Documentação Técnica

Requisição

post https://plataforma.bigdatacorp.com.br/chamadasassincronas/

A API de Chamadas Assíncronas oferece uma camada externa às APIs da Plataforma de Dados (como people, companies, validations, entre outras), permitindo a realização de chamadas assíncronas. Quando um usuário faz uma consulta utilizando essa API, ele recebe imediatamente uma mensagem de reconhecimento contendo um identificador da consulta (QueryId). Posteriormente, quando o resultado estiver pronto, ele será enviado automaticamente para a URL especificada pelo usuário nos parâmetros da consulta, eliminando a necessidade de o usuário aguardar a resposta.

Recomendamos o uso do QueryId fornecido na requisição inicial para validar o retorno enviado à URL especificada.

O modelo de resposta segue o padrão das APIs individuais, permitindo que o mesmo tratamento de dados utilizado para chamadas síncronas seja aplicado sem modificações.

Funcionamento

As chamadas à API de Hooks seguem a mesma estrutura das requisições feitas para as APIs de Enriquecimento, mas com dois campos adicionais obrigatórios: api e hooks. Uma vez disparada, a API registra a solicitação e retorna uma resposta de confirmação contendo o QueryId do pedido. Quando a execução é concluída, o resultado é enviado via POST para a URL fornecida no parâmetro hooks.

  • Campo api: Indica o nome da API correspondente ao dataset solicitado. Valores válidos incluem: addresses, companies, lawsuits, marketplace, ondemand, people, products, validations e vehicles.

  • Campo hooks: Deve seguir o formato web{[sua url de retorno]}, onde [sua url de retorno] é um endereço HTTP ou HTTPS válido para onde a Plataforma de Dados enviará os resultados.

Observação: Caso uma URL inválida seja fornecida, o retorno será perdido e só poderá ser recuperado através de uma consulta na API de Eventos.

Exemplos de Requisição

Para obter os dados do dataset Dados Cadastrais Básicos da API de Pessoas (people) de forma assíncrona, basta preencher o corpo da requisição conforme faria para a API de Pessoas e incluir os parâmetros api e hooks. A seguir estão alguns exemplos de requisição:

POST: https://plataforma.bigdatacorp.com.br/chamadasassincronas/

{
    "Datasets": "basic_data",
    "q": "doc{xxxxxxxxxxx}",
    "api": "people",
    "hooks": "web{[seu endereço de postback]}"
}

{
    "Datasets": "processes",
    "q": "doc{xxxxxxxxxxx}",
    "api": "people",
    "hooks": "email{[seu endereço de email]}"
}

{
    "Datasets": "basic_data",
    "q": "doc{xxxxxxxxxxx}",
    "api": "companies",
    "hooks": "web{[seu endereço de postback]}"
}

Qualquer chamada pode ser transformada em uma chamada assíncrona com essas alterações simples.

Parâmetro Adicional - PostBackSecret

Você pode incluir uma chave secreta (PostBackSecret) que não é registrada nos servidores e é repassada na requisição POST. Isso ajuda a garantir a autenticidade da requisição recebida.

{
    "Api": "validations",
    "Datasets": "ondemand_phone_operator",
    "q": "phone{XXXXXXXXXXX}",
    "Hooks": "web{SEU_WEB_SERVER}, postbacksecret{SUA_SECRET}"
}

Postbacksecret: SUA_SECRET
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/535.1 (KHTML, like Gecko) Chrome/13.0.782.107 Safari/535.1
Content-Type: application/x-www-form-urlencoded; charset=iso-8859-1
Host: 7a90c208.ngrok.io
Content-Length: 508
Accept-Encoding: gzip, deflate
Connection: Close
X-Forwarded-For: 184.72.90.61

Parâmetros Adicionais - Authorization

Para maior segurança, é possível incluir um par de chaves de Authorization no header da callback. Basta adicionar os campos Authorization Key e Authorization Token no corpo da requisição.

{
    "Api": "validations",
    "Datasets": "ondemand_phone_operator",
    "q": "phone{XXXXXXXXXXX}",
    "Hooks": "web{SEU_WEB_SERVER}, authorizationkey{key}, authorizationtoken{token}"
}

AuthorizationKey: [key]
Authorization: Bearer [token]
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/535.1 (KHTML, like Gecko) Chrome/13.0.782.107 Safari/535.1
Content-Type: application/x-www-form-urlencoded; charset=iso-8859-1
Host: 7a90c208.ngrok.io
Content-Length: 508
Accept-Encoding: gzip, deflate
Connection: Close
X-Forwarded-For: 184.72.90.61

Validação e Retornos

A API de Hooks realiza as mesmas validações feitas pelas APIs de enriquecimento, como:

  • Verificação de estrutura da requisição;
  • Validação do token de acesso;
  • Parâmetros de views ou datasets inválidos.

Caso uma requisição seja bem formada e validada, a API retorna um QueryId para rastrear o processamento. O resultado é posteriormente enviado para a URL especificada, utilizando o mesmo QueryId para identificação.

{
    "QueryId": "7cfe93e7-9d7e-4458-90eb-feaa6d9b5dee",
    "ElapsedMilliseconds": 3456.0,
    "Status": {
        "api": [
            {
                "Code": 0,
                "Message": "OK"
            }
        ]
    }
}

{
    "QueryId": "49f6ab63-7963-4bc2-af5d-baf89244ace8",
    "ElapsedMilliseconds": 5.0,
    "Status": {
        "api": [
            {
                "Code": -131,
                "Message": "INVALID API PARAMETER"
            }
        ]
    }
}

{
    "QueryId": "06c4de35-1271-45c4-af68-3dac02504c79",
    "ElapsedMilliseconds": 1984.0,
    "Status": {
        "api": [
            {
                "Code": -111,
                "Message": "INVALID ACCESS TOKEN"
            }
        ]
    }
}

Problemas com Envio dos Dados

Alguns retornos das APIs de Enriquecimento podem ter mais de 100Mb de dados em uma única requisição. Casos como estes podem gerar erros no recebimento nas APIs de Webhooks. Os erros mais comuns são:

  1. Timeout: Ocorre quando a API não responde dentro de um tempo predeterminado (por padrão 60 segundos), após uma série de tentativas de envio. Quando isso ocorrer, enviaremos uma mensagem com o status de erro -1212 (TIMEOUT EXCEEDED FOR THIS QUERY. IF THIS ERROR PERSISTS, PLEASE CONTACT OUR SUPPORT TEAM).
  2. Payload too large: Este erro é referente a limitições do payload de entrada da API de Webhooks que está recebendo os dados. Caso erros como este sejam recebidos, é necessário configurar o servidor para permitir entrada de dados maiores. Neste casos, iremos enviar uma mensagem com o status -169 (FAILED TO SEND RESULT USING WEBHOOKS. YOUR API MAY NOT SUPPORT LARGE PAYLOADS. CHECK SIZE LIMITS AND API SETTINGS, OR USE OUR EVENTS API TO RETRIEVE THE RESULT.).

A seguir estão alguns exemplos de mensagens de erro enviadas pela API de Hooks:

{
    "Result": [],
    "QueryId": "5d6bfe34-026d-4d08-a518-9a7f0de3e392",
    "ElapsedMilliseconds": 21822,
    "QueryDate": "2025-01-15T13:51:36.5628313Z",
    "Status": {
    "hooks": [
            {
                "Code": -1212,
                "Message": "TIMEOUT EXCEEDED FOR THIS QUERY. IF THIS ERROR PERSISTS, PLEASE CONTACT OUR SUPPORT TEAM"
            }
        ]
    }
}
```json Erro por tamanho de payload
{
    "Result": [],
    "QueryId": "bdabfe34-026d-4d08-a518-9a7f0de3e39d",
    "ElapsedMilliseconds": 21822,
    "QueryDate": "2025-01-15T13:51:36.5628313Z",
    "Status": {
    "hooks": [
            {
                "Code": -169,
                "Message": "FAILED TO SEND RESULT USING WEBHOOKS. YOUR API MAY NOT SUPPORT LARGE PAYLOADS. CHECK SIZE LIMITS AND API SETTINGS, OR USE OUR EVENTS API TO RETRIEVE THE RESULT."
            }
        ]
    }
}

O QueryId enviado na mensagem de erro é o mesmo que o da requisição original. Use-o para obter os dados completos da requisição através da API de Eventos.

Language
Credentials
Click Try It! to start a request and see the response here!