Documentação da API de integração

Introdução

A API de integração deixa o sistema da sua empresa cadastrar, consultar, atualizar e remover documentos da base monitorada do Datarich, e os webhooks avisam o seu sistema quando algo importante acontece.

Quem libera o acesso é o Administrador da sua conta, na tela Integrações do app: ele cria um sistema integrado, escolhe o que ele pode fazer e recebe a chave. A mesma regra da tela vale para a API — o que a tela recusa (documento inválido, fonte não habilitada, conta bloqueada), a API recusa igual.

Endereço base: https://api.datarich.com.br /api/v1/public/integration/v1

Autenticação

Chave de API

Envie a chave no cabeçalho X-Api-Key (ou Authorization: Bearer <chave>) em toda chamada. O formato é drk_<id>_<segredo>.

A chave aparece uma única vez, ao ser criada ou rotacionada: guarde-a no cofre do seu sistema. O Datarich guarda só um resumo (hash) dela; se você perder, gere outra — a antiga deixa de valer na hora. Revogar é definitivo.

A chave é sua e só sua: nunca coloque em código de navegador ou de aplicativo distribuído, e nunca em repositório.

A conta vem da chave

Você não informa conta nem usuário: a conta é sempre a da chave. Cada chave só enxerga os documentos que ela mesma cadastrou (ou que apresentou já existindo na base); qualquer outro documento responde 404, como se não existisse.

Opcionalmente o Administrador limita a chave a uma lista de endereços IP (ou faixas CIDR) e define uma data de expiração.

Acessos (escopos)

Rotas

• GET /sources — Lista as fontes habilitadas na sua conta, com o preço final por consulta.
• POST /entities — Cadastra documentos em lote e agenda a primeira consulta.
• GET /entities — Lista os documentos da chave, com a situação e o último resultado de cada fonte.
• GET /entities/{id} — Situação do monitoramento e resultado atual de cada fonte.
• PATCH /entities/{id} — Pausa ou retoma o monitoramento, muda a frequência ou a referência externa.
• DELETE /entities/{id} — Remove o documento e todo o seu histórico (definitivo).

curl -X GET 'https://api.datarich.com.br/api/v1/public/integration/v1/sources' \
  -H 'X-Api-Key: <sua chave>'

[
  { "id": "3f1c0c8e-0000-4000-8000-000000000001", "code": "EXEMPLO_CNPJ", "name": "Dados cadastrais de CNPJ", "tipo_entidade": "empresa", "preco": 0.25 }
]

curl -X POST 'https://api.datarich.com.br/api/v1/public/integration/v1/entities' \
  -H 'X-Api-Key: <sua chave>' \
  -H 'Content-Type: application/json' \
  -d '{ "items": [ { "tipo_entidade": "empresa", "documento": "11.222.333/0001-81", "referencia_externa": "cliente-42", "id_data_sources": ["3f1c0c8e-0000-4000-8000-000000000001"], "monitorado": true, "frequencia_dias": 30 }, { "tipo_entidade": "pessoa", "documento": "529.982.247-25", "data_nascimento": "1980-05-17", "referencia_externa": "cliente-43", "id_data_sources": ["3f1c0c8e-0000-4000-8000-000000000002"] } ] }'

{
  "criados": 2,
  "ja_existentes": 0,
  "invalidos": 0,
  "itens": [
    { "indice": 0, "id": "9b2f6c40-0000-4000-8000-0000000000a1", "referencia_externa": "cliente-42", "aceito": true },
    { "indice": 1, "id": "9b2f6c40-0000-4000-8000-0000000000a2", "referencia_externa": "cliente-43", "aceito": true }
  ]
}

curl -X GET 'https://api.datarich.com.br/api/v1/public/integration/v1/entities' \
  -H 'X-Api-Key: <sua chave>'

{
  "items": [ { "id": "9b2f6c40-0000-4000-8000-0000000000a1", "tipo_entidade": "empresa", "referencia_externa": "cliente-42", "monitorado": true, "frequencia_dias": 30, "resultados": [] } ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

curl -X GET 'https://api.datarich.com.br/api/v1/public/integration/v1/entities/{id}' \
  -H 'X-Api-Key: <sua chave>'

{
  "id": "9b2f6c40-0000-4000-8000-0000000000a1",
  "tipo_entidade": "empresa",
  "referencia_externa": "cliente-42",
  "monitorado": true,
  "motivo_pausado": null,
  "frequencia_dias": 30,
  "proxima_reconsulta": "2026-11-07T12:00:00Z",
  "resultados": [
    {
      "id_data_source": "3f1c0c8e-0000-4000-8000-000000000001",
      "fonte": "Dados cadastrais de CNPJ",
      "classificacao": "Ativa",
      "tom": "info",
      "atualizado_em": "2026-10-08T12:00:00Z",
      "valido_ate": "2026-11-07T12:00:00Z"
    }
  ]
}

curl -X PATCH 'https://api.datarich.com.br/api/v1/public/integration/v1/entities/{id}' \
  -H 'X-Api-Key: <sua chave>' \
  -H 'Content-Type: application/json' \
  -d '{ "monitorado": false, "motivo": "cliente encerrou o contrato", "frequencia_dias": 90 }'

{
  "id": "9b2f6c40-0000-4000-8000-0000000000a1",
  "tipo_entidade": "empresa",
  "referencia_externa": "cliente-42",
  "monitorado": true,
  "motivo_pausado": null,
  "frequencia_dias": 30,
  "proxima_reconsulta": "2026-11-07T12:00:00Z",
  "resultados": [
    {
      "id_data_source": "3f1c0c8e-0000-4000-8000-000000000001",
      "fonte": "Dados cadastrais de CNPJ",
      "classificacao": "Ativa",
      "tom": "info",
      "atualizado_em": "2026-10-08T12:00:00Z",
      "valido_ate": "2026-11-07T12:00:00Z"
    }
  ]
}

curl -X DELETE 'https://api.datarich.com.br/api/v1/public/integration/v1/entities/{id}' \
  -H 'X-Api-Key: <sua chave>'

Erros e limites

• Cada chave tem um limite de requisições por minuto, definido pela plataforma; ao excedê-lo a API responde 429 com Retry-After.
• Há também um limite por endereço de origem, aplicado antes mesmo da chave.
• Os erros vêm no formato { "ErrorMessage": "...", "StatusCode": 400 }.

Webhooks

Um webhook é uma URL do seu sistema que o Datarich chama (POST, JSON) quando um evento acontece. O Administrador cadastra a URL em Integrações, escolhe os eventos e recebe o segredo de assinatura (whsec_...), mostrado uma única vez.

O corpo nunca leva documento, nome nem data de nascimento: só identificadores, a fonte e a classificação. Para o detalhe, consulte a API com o id_monitored_entity.

Um webhook pode ser ligado a uma chave: então recebe só os eventos dos documentos dela, e data.referencia_externa traz a referência do seu sistema.

Eventos

Corpo

{
  "id": "4c7d1e22-0000-4000-8000-0000000000b1",
  "evento": "monitoring.result_changed",
  "ocorrido_em": "2026-10-08T12:00:00.0000000Z",
  "data": {
    "id_monitored_entity": "9b2f6c40-0000-4000-8000-0000000000a1",
    "tipo_entidade": "empresa",
    "referencia_externa": "cliente-42",
    "detalhe": {
      "fonte": "EXEMPLO_CNPJ",
      "classificacao_anterior": "Ativa",
      "classificacao": "Baixada",
      "tom": "critical"
    }
  }
}

Cabeçalhos

Como verificar a assinatura

1. Calcule HMAC-SHA256(segredo, "<timestamp>.<corpo exato recebido>") em hexadecimal, prefixe com v1= e compare com X-Datarich-Signature em tempo constante.
2. Use o corpo bruto, antes de converter para objeto: qualquer espaço ou ordem de campos diferente muda a assinatura.
3. Recuse timestamps muito antigos (sugestão: mais de 5 minutos) para impedir a repetição de uma mensagem capturada.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

// `rawBody` = o corpo EXATAMENTE como chegou (string), antes de qualquer JSON.parse.
export function isValid(secret, headers, rawBody, toleranceSeconds = 300) {
  const timestamp = Number(headers['x-datarich-timestamp']);
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = 'v1=' + createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const received = String(headers['x-datarich-signature'] ?? '');
  return expected.length === received.length && timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

C#

using System.Security.Cryptography;
using System.Text;

// rawBody = o corpo EXATAMENTE como chegou, antes de desserializar.
static bool IsValid(string secret, string timestampHeader, string signatureHeader, string rawBody, int toleranceSeconds = 300) {
  if (!long.TryParse(timestampHeader, out var timestamp)) return false;
  if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - timestamp) > toleranceSeconds) return false;
  using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
  var expected = "v1=" + Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes($"{timestamp}.{rawBody}"))).ToLowerInvariant();
  return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(signatureHeader));
}

Python

import hashlib, hmac, time

def is_valid(secret: str, timestamp_header: str, signature_header: str, raw_body: str, tolerance_seconds: int = 300) -> bool:
    # raw_body = o corpo EXATAMENTE como chegou, antes de json.loads.
    try:
        timestamp = int(timestamp_header)
    except ValueError:
        return False
    if abs(time.time() - timestamp) > tolerance_seconds:
        return False
    digest = hmac.new(secret.encode(), f"{timestamp}.{raw_body}".encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest("v1=" + digest, signature_header)

Entrega e novas tentativas

• Responda com qualquer status 2xx dentro do tempo máximo definido pela plataforma. Outra resposta, ou falha de conexão, agenda nova tentativa em intervalos crescentes.
• Esgotadas as tentativas, a entrega fica como falhou e o Administrador pode reenviá-la na tela Integrações. O histórico de entregas fica disponível por um período limitado.
• A URL precisa ser https, na porta padrão, com endereço público. O endereço é conferido a cada envio; redirecionamentos não são seguidos.