Requisição

A API de Chamadas Assíncronas serve como uma camada externa às APIs da Plataforma de Dados (people, companies, validations, etc), que viabiliza a realização de chamadas assíncronas. Quando um usuário faz uma consulta nessa API, ele imediatamente recebe como retorno uma mensagem de reconhecimento, que contém o identificador da consulta (QueryId). Uma vez que o resultado estiver pronto, o mesmo vai ser postado na URL especificada pelo usuário nos parâmetros da consulta, sem que o usuário tenha que ficar esperando pelo retorno. Recomendamos fortemente o uso do QueryId informado na requisição incial para a validação do retorno da consulta que for postado na URL especificada.

O modelo de resposta é exatamente o mesmo utilizado nas APIs individuais, ou seja, o mesmo tratamento de dados utilizado no processo síncrono pode ser utilizado no processo assíncrono, sem qualquer necessidade de alteração.

Funcionamento

As chamadas na API de Hooks seguem exatamente a mesma estrutura das requisições das outras APIs, com dois campos adicionais obrigatórios: API e Hooks. Uma vez que a requisição for disparada, a API de hooks vai registrar o pedido e retornar um acknowledgement: uma resposta contendo o QueryId do pedido. Quando a requisição terminar de ser executada, o resultado será enviado através de um POST na URL fornecida como parte do parâmetro hooks.

O campo api deve receber o nome da API que possui o dataset especificado, os possíveis valores são: addresses, companies, lawsuits, marketplace, ondemand, people, products, validations e vehicles;

O campo hooks deve seguir o formato "web{[sua url que vai receber o retorno]}", aonde "[sua url que vai receber o retorno]" é um endereço http ou https válido aonde a Plataforma de Dados vai realizar uma chamada POST para enviar os resultados. Não é necessário que a sua URL retorne qualquer tipo de mensagem para a Plataforma de Dados. Se for configurada uma URL inválida, o retorno será perdido, e só poderá ser recuperado através de uma consulta no Log.

Exemplos

Imagine que você quer chamar o dataset de Dados Básicos da API de Pessoas (people) de forma assíncrona. Para fazer isso, basta preencher exatamente o mesmo corpo de requisição que você preencheria para a API de People, e incluir os parâmetros de "api" e "hooks", conforme descrito acima. Segue o exemplo de requisição:

Post:

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

O mesmo modelo serve para consultas a API de Empresas (companies):

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

Assim, qualquer chamada pode rapidamente transformada em uma chamada assíncrona, sem a necessidade de grandes alterações de código.

Parâmetro Adicional - PostBackSecret

É possível passar uma chave secreta que não é logada nos servidores e é repassada na requisição de POST. Pode ser usado para garantir a autenticidade da requisição recebida.

Exemplo:

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

Exemplo de resposta:

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

É possível passar um par de chaves de Authorization no header do POST da callback, para isso basta incluir no corpo da request os campos Authorization Key e Authorization Token, conforme o exemplo abaixo. Isso pode ser usado para garantir a autenticidade da requisição recebida. As chaves de Authorization não são logadas nos servidores e é repassada somente na callback.

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

Exemplo de resposta:

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 faz as mesmas validações que as APIs de enriquecimento fazem no processamento da requisição. Sendo assim, qualquer erro de validação da requisição que as APIs de enriquecimento possam emitir, a API de Hooks também pode - e.g. requisição mal formada, token de acesso inválido, view/dataset inválidos, etc. Em adição à essas validações, a API de Hooks também garante que o parâmetro de hooks passado está correto e sintaticamente válido e, caso contrário, emite um erro adequado.

Caso a requisição seja bem formada - ou seja, tenha passado por todas as validações mencionadas acima - a API vai gerar um QueryId e retornar o mesmo para o usuário. Além disso, esse QueryId vai ser persistido para as APIs de enriquecimento, que por sua vez vão retornar a informação para "o meio de recebimento da informação" estipulado pelo usuário utilizando o mesmo QueryId para a identificação da resposta emitida.

Exemplo de resposta bem sucedida:

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

Exemplo de resposta com erro:

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

ou

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