Skip to content

Enriquecer empresa (síncrono, sem webhook)

Request

Enriquece uma empresa e devolve o resultado na própria resposta, sem webhook e sem polling.

É o mesmo enriquecimento de /b2b/companies/enrich — mesma base, mesma cascata de fornecedores, mesmo custo e mesmo formato de retorno. A única diferença é que a resposta vem no corpo em vez de chegar depois.

Quando usar: quando você não tem (ou não quer manter) um endereço público para receber webhook. Para volume, continue usando /b2b/companies/enrich/bulk, que é assíncrono por desenho.

Uma empresa por chamada. O endpoint aceita exatamente um; para vários, use o /bulk.

Custo: 1 crédito por registro, debitado na entrada e estornado automaticamente quando o registro não retorna dado — igual ao caminho assíncrono.

Três desfechos possíveis

HTTPSignificadoO que fazer
200Concluído. O corpo traz o registro enriquecido.Usar o resultado.
202Não concluiu a tempo e segue processando.Consultar GET /b2b/status/{id_processamento} (o header Location já traz o caminho).
429Sem vaga para execução síncrona neste momento. Nenhum crédito é debitado.Repetir depois do Retry-After (5s) ou usar o endpoint assíncrono.

O 429 é controle de carga, não limite de plano nem de requisições: a execução síncrona mantém a conexão aberta enquanto consulta os fornecedores, então há um teto de chamadas simultâneas. Ele protege o tempo de resposta de quem já está sendo atendido. O endpoint assíncrono (POST /b2b/persons/enrich) não tem esse teto — em cargas grandes, prefira ele, que aceita até 10.000 contatos por chamada.

O 202 não é erro e não significa trabalho perdido: o crédito continua debitado, o enriquecimento continua rodando e o resultado fica disponível no status — exatamente como no caminho assíncrono. Ele acontece quando a empresa precisa da cascata completa de fornecedores, que pode levar mais tempo do que uma requisição HTTP deve ficar aberta.

Empresa que já existe enriquecida na base responde em poucos segundos.

Idempotência (recomendado)

Envie o header Idempotency-Key com um valor único por tentativa de negócio (um UUID, por exemplo). Se a chamada já tiver respondido e você repetir com a mesma chave, recebe a resposta original — mesmo corpo, mesmo status — sem ser cobrado de novo. A resposta repetida vem com o header Idempotency-Replayed: true.

A chave vale por 24 horas e é isolada por conta. Três limites que valem conhecer antes de desenhar o retry:

  • A chave é guardada quando a resposta sai, não quando a chamada entra. Reenviar enquanto a primeira ainda está em curso executa (e cobra) de novo. Como o servidor pode segurar a chamada por até 50 segundos, use um timeout de cliente maior que isso e, num 202, espere o Retry-After em vez de reenviar.

  • A chave não é ligada ao corpo nem ao endpoint — só à sua conta. Reutilizar a mesma chave em uma chamada diferente devolve a resposta da anterior, não a nova. Gere uma chave por chamada.

  • Chaves são truncadas em 200 caracteres. Duas chaves que só diferem depois do caractere 200 são tratadas como a mesma.

Sem esse header, cada chamada é uma execução nova e um débito novo.

Exemplo


curl -X POST https://api.datastone.com.br/v1/b2b/companies/enrich/sync \
  -H "Authorization: Token SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3d9a7f10-4c2b-4e8f-9a61-0b7c5e2d4a83" \
  -d '{"cnpj": "29128179000149"}'
Security
ApiKeyAuth
Headers
Idempotency-Keystring, <= 200 characters

Chave única da tentativa, isolada por conta e válida por 24h. Repetir a chamada com a mesma chave devolve a resposta original sem cobrar de novo, desde que a primeira já tenha respondido. Acima de 200 caracteres a chave é truncada, não recusada.

Example:6f1c0b2e-6a1e-4a5e-9d3a-2b8f5c1d7e42
Bodyapplication/jsonrequired

Informe pelo menos um identificador. Aceita os campos direto na raiz ou dentro de contato (contact também é aceito).

Use exatamente os nomes abaixo. Um campo com nome diferente é descartado em silêncio, não recusado: {"cnpj": "...", "company_id": 123} responde 200 usando só o CNPJ, e cobra o crédito. Se o nome errado for o único identificador, a resposta é 400. Em particular, linkedin_url e company_id não são aceitos — os nomes válidos são url_linkedin e id_empresa. (cnpj se escreve igual nos dois idiomas.)

Empresa não é enriquecida por e-mail. Não há campo email aqui: se enviado, é ignorado — a chamada segue pelos outros campos, ou volta 400 se não houver nenhum.

cnpjstring
Example:"29128179000149"
url_linkedinstring
Example:"https://www.linkedin.com/company/datastone"
id_empresainteger
Example:46165660
curl -i -X POST \
  https://api.datastone.com.br/v1/b2b/companies/enrich/sync \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 6f1c0b2e-6a1e-4a5e-9d3a-2b8f5c1d7e42' \
  -d '{
    "cnpj": "29128179000149"
  }'

Responses

Enriquecimento fechado dentro da requisição. 200 não significa que o registro foi enriquecido com sucesso — significa que o lote fechou. Um registro que falhou vem com contatos[0].status = "failed" e um erro, enquanto o status da raiz continua completed. Leia sempre contatos[].status.

Headers
Locationstring

Caminho do processamento, /b2b/status/{id}.

Cache-Controlstring

Sempre no-store — a resposta contém dado pessoal.

Idempotency-Replayedstring

true quando a resposta é a repetição de uma chamada anterior.

Bodyapplication/json
id_processamentostring
concluidoboolean
Example:true
statusstring
Example:"completed"
total_registrosinteger
sucessointeger
falhouinteger
aguardou_segundosnumber

Quanto o servidor esperou o enriquecimento fechar.

timestampnumber

Epoch em que o lote fechou.

rotaobject

Por onde o registro foi resolvido. Presente só quando há contagem de rota.

contatosArray of objects

Mesmo formato dos itens do webhook e de /b2b/status/{id_processamento}. status aqui é o do REGISTRO; o status da raiz é do lote e vale completed mesmo quando o único registro falhou.

Response
{
  "id_processamento": "string",
  "concluido": true,
  "status": "completed",
  "total_registros": 0,
  "sucesso": 0,
  "falhou": 0,
  "aguardou_segundos": 0,
  "timestamp": 0,
  "rota": {
    "enriched": 0,
    "already_complete": 0
  },
  "contatos": [
    { … }
  ]
}