Pular para o conteúdo principal
Version: 1.2.0

API de vínculos societários

Descubra de que empresas uma pessoa é sócia (busca reversa de vínculo societário), por HTTP e JSON.

Como funciona​

  1. Inicie a busca com POST /party/v1/companies-of, informando o party_id de uma pessoa já cadastrada no seu workspace.
  2. Receba o resultado de um destes modos, escolhido pelo parâmetro wait:
    • async (padrão): a resposta é 202 com um execution_id, e você acompanha com GET /party/v1/companies-of/{execution_id};
    • sync: a requisição espera até wait_timeout_s (de 1 a 20 segundos). Se a busca terminar a tempo, a resposta é 200 com o resultado; se não, é o mesmo 202 do modo assíncrono, e a busca continua. Esperar não é um erro nem um bloqueio: o execution_id sempre pode ser consultado depois.

Os vínculos devolvidos são candidatos: o CPF da base de sócios é mascarado, então pode haver homônimos. Trate match_score como ordenação, e não como confirmação de que a pessoa é sócia.

Autenticação​

Todas as rotas, exceto a de saúde do serviço, exigem o header x-api-key. A chave precisa ter permissão para a busca reversa; sem ela, a resposta é 403 forbidden. Revogar uma chave pode levar até 300 segundos para valer.

Restrição por IP de origem (opcional)​

Cada chave pode ter uma lista de IPs ou faixas (CIDR) de origem permitidos. Sem lista, a chave vale de qualquer origem; com lista, requisições vindas de fora dela recebem 403 ip_not_allowed. Configure a lista na tela de Chaves de API, ao gerar a chave ou depois.

  • As alterações valem em até 5 minutos.
  • A Zabit considera o IP de origem visto pelo balanceador. Um X-Forwarded-For enviado por você é ignorado.
  • A verificação vem antes de qualquer outra regra: com a origem não autorizada, a resposta é sempre 403, mesmo que o corpo da requisição esteja inválido.

Limites​

Não há cota diária por chave nesta API. O limite é operacional: se a fila de buscas do workspace estiver cheia, a resposta é 429 backlog_exceeded, com o header Retry-After (em segundos), e a busca não é enfileirada. Tente de novo depois desse prazo. Consultar o resultado não tem custo.

Repetir um pedido com segurança​

O header opcional Idempotency-Key (16 a 128 caracteres) evita iniciar duas buscas quando você precisa repetir um pedido. Veja os detalhes na operação Buscar empresas de uma pessoa.

Erros​

Os erros seguem o formato {"error": {"code": "...", "message": "..."}}. Use code para decidir o que fazer; message é para leitura humana e pode mudar.

Authentication​

Chave de API do workspace, enviada no header x-api-key. O valor completo aparece uma única vez, na criação; se perder o valor, gere outra chave. A chave precisa ter permissão para a busca reversa. Revogar uma chave pode levar até 300 segundos para valer.

Security Scheme Type:

apiKey

Header parameter name:

x-api-key