Solicitar token

Informações importantes antes da sua integração

tags: documentação, API, desenvolvedores, token

Atualizado há mais de um anoLidia

Converse com nosso time pelo chat.

Segurança do Token

Recomendamos aplicar as seguintes medidas para maior segurança do token:

• Restringir o acesso apenas para determinados endereços de IP

• Restringir o acesso apenas a determinadas fontes de consultas

• Limitar o número de chamadas por hora

• Limitar o número de chamadas por dia

• Limitar o número de chamadas por semana

• Limitar o número de chamadas por mês

Restringir o acesso apenas para determinados endereços de IP

Restringir o acesso apenas a determinadas fontes de consultas

Limitar o número de chamadas por hora

Limitar o número de chamadas por dia

Limitar o número de chamadas por semana

Limitar o número de chamadas por mês

Modelo de autenticação das APIs

Seguimos o mesmo modelo do Twilio e da Amazon.

Geramos um token de autenticação que deve ser informado em todas as chamadas. Este token é um segredo e deve ser tratado exatamente como uma senha.

Só são possíveis chamadas via SSL (TLS 1.2).

Autenticação por certificado digital

Opcionalmente, podemos configurar a autenticação por certificado digital, mas isto exige um endpoint dedicado ao cliente.

Resultado em JSON ou XML

Para qualquer API, caso queira o output em json ou xml, basta incluir ao final &format=json (ou xml)

Chamada assíncrona (ASYNC)

As APIs também funcionam de forma assíncrona, basta informar no final da URL os parâmetros: &options={async:true, async_run_persistent:true} e depois utilizar o UID retornado para obter o resultado da chamada.

Parâmetro async: Indica se deve executar a transação de forma assíncrona (false por padrão).

Valores:

• true

• false

true

false

Exemplo de uso: &options={async:true}

Exemplo com Sintegra Unificada:

• Primeira chamada:
  ​https://api.exato.digital/sintegra/unificada?uf={uf}&cpf={cpf}&token={token}&options={async:true}

  Retorno esperado: Execução em andamento. Execução assíncrona em andamento...

• Segunda chamada:
  ​https://api.exato.digital/sintegra/unificada?uid={uid}&token={token}
  Parâmetro uid: primeiro campo retornando na primeira chamada: “UniqueIdentifier”

  Retorno esperado: A mensagem vai ser: "Execução em andamento." até a consulta completar.

Primeira chamada:
​https://api.exato.digital/sintegra/unificada?uf={uf}&cpf={cpf}&token={token}&options={async:true}

Retorno esperado: Execução em andamento. Execução assíncrona em andamento...

Segunda chamada:
​https://api.exato.digital/sintegra/unificada?uid={uid}&token={token}
Parâmetro uid: primeiro campo retornando na primeira chamada: “UniqueIdentifier”

Retorno esperado: A mensagem vai ser: "Execução em andamento." até a consulta completar.

Chamadas aos relatórios

Para os relatórios, é recomendado usar a chamada no modelo assíncrono, desta forma, a primeira chamada (https://api.exato.digital/exec-datasource?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&consulta_tipo_id=5025&parametros=12387530000113&options={async:true}) vai retornar um identificador único (UID) que deve ser passado como parâmetro no segundo endpoint: https://api.exato.digital/exec-datasource?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&consulta_tipo_id=5025&uid=[UID]

O segundo endpoint vai retornar código 12 (em execução) enquanto a consulta estiver sendo processada. Ao ser finalizada, este código deve mudar para 1 (sucesso) ou alguma outra situação.

Options

exec_mode: Modo de execução da consulta. (por padrão o modo é normal).

Tipo aceito: número inteiro

Valores:

• 1 = execute - Execução normal.

• 2 = test - Execução de teste, com dados simulados.

• 3 = status - Retorna apenas a situação da execução.

• 4 = result - Retorna o resultado de uma transação.

• 5 = params_and_price_check - Checa os parâmetros e o preço.

• 6 = balance - Retorna o saldo.

• 7 = statistics - Retorna estatísticas gerais da fonte (como tempo de acesso)

1 = execute - Execução normal.

2 = test - Execução de teste, com dados simulados.

3 = status - Retorna apenas a situação da execução.

4 = result - Retorna o resultado de uma transação.

5 = params_and_price_check - Checa os parâmetros e o preço.

6 = balance - Retorna o saldo.

7 = statistics - Retorna estatísticas gerais da fonte (como tempo de acesso)

Exemplo: &options={exec_mode:1}

async: Indica se deve executar a transação de forma assíncrona (false por padrão).

Tipo aceito: booleano

Valores:

• true

• false

true

false

Exemplo: &options={async:true}

async_run_persistent: Indica se deve executar uma transação assíncrona até obter um resultado final (false por padrão).

Tipo aceito: booleano

Valores:

• true

• false

true

false

Exemplo: &options={async_run_persistent:true}

cache_limit_in_hours: Limite, em horas, que uma consulta é aceita do cache. Caso informado, o sistema tenta buscar a consulta com a mesma chave de entrada no cache interno, retornando os dados caso encontre no período informado. Atenção: Quando a consulta é lida do cache, a velocidade é bem superior a online pois vem direto da base de dados, porém, o dado não será online, e sim da data encontrada no cache. (null por padrão).

Tipo aceito: número inteiro

Valores:

• null - Usa o tempo padrão da consulta

• 0 - desabilita

• número inteiro - limite em horas

null - Usa o tempo padrão da consulta

0 - desabilita

número inteiro - limite em horas

Exemplo: &options={cache_limit_in_hours:1}

cache_include_not_found: Indica se deve incluir resultados "Entidade não encontrada" na busca em cache (null por padrão).

Tipo aceito: booleano

Valores:

• true

• false

true

false

Exemplo: &options={cache_include_not_found:true}

generate_result_pdf: Indica que se a fonte de dados possuir comprovante em PDF, ele deve ser obrigatoriamente retornado. Caso esta opção seja especificada como 'enable' e haja falha na geração do comprovante em PDF, a consulta apresentará erros. (null por padrão).

Tipo aceito: número inteiro

Valores:

• null - Usa as configurações do cadastro do cliente

• 0 = default - Tenta gerar o PDF, mas não interrompe a transação/consulta caso ocorra erro

• 1 = enable - Exige o PDF para que a transação/consulta seja considerada sucesso.

• 2 = disable - Desabilita a geração de PDFs, geralmente para melhor performance.

null - Usa as configurações do cadastro do cliente

0 = default - Tenta gerar o PDF, mas não interrompe a transação/consulta caso ocorra erro

1 = enable - Exige o PDF para que a transação/consulta seja considerada sucesso.

2 = disable - Desabilita a geração de PDFs, geralmente para melhor performance.

Exemplo: &options={generate_result_pdf:true}

generate_pdf_sync: Indica se deve gerar o PDF de forma síncrona (false por padrão).

Tipo aceito: booleano

Valores:

• true

• false

true

false

Exemplo: &options={generate_pdf_sync:true}

allow_outdated_result: Indica se deve aceitar resultado desatualizado para alguns tipos de retorno, caso não seja possível realizar a consulta on-line ou do cache. (null por padrão)

Tipo aceito: número inteiro

Valores:

• 0 = default - Usa configurações do cadastro do cliente

• 1 = enable - Habilita resultado desatualizado

• 2 = disable - Desabilita resultado desatualizado

0 = default - Usa configurações do cadastro do cliente

1 = enable - Habilita resultado desatualizado

2 = disable - Desabilita resultado desatualizado

Exemplo: &options={allow_outdated_result:1}

timeout_ms: Indica o timeout da transação. O valor especificado pode ou não ser respeitado de acordo com os termos do contrato com o cliente (null por padrão).

Tipo aceito: número inteiro (em milisegundos)

Exemplo: &options={timeout_ms:60000}

read_from_cache: Indica que a chamada aceita leitura de resultados do cache (se existir). Por padrão, a consulta é executada usando o cache diário, ou seja, se a mesma consulta para a mesma entrada foi efetuada no mesmo dia com sucesso anteriormente, o resultado retornado será oriundo do cache.

Tipo aceito: número inteiro

Valores:

• default = 0

• enable = 1

• disable = 2

default = 0

enable = 1

disable = 2

Exemplo: &options={read_from_cache:10}

outdated_result_limit_in_hours: Tempo (em horas) que o sistema deve buscar a consulta no cache em caso de aceite de resultados antigos (datados). Este parâmetro só funciona caso o parâmetro 'allow_outdated_result' seja passado como enable.

Tipo aceito: número inteiro (valor em horas)

Exemplo: &options={outdated_result_limit_in_hours:10}

custom_parameters: Parâmetros customizados específicos para seu token de acesso.

Tipo aceito: string

Exemplo: &options={custom_parameters:’parametro_teste:1’}

callback_url: URL de callback de resultado da chamada (webhook). Ao ser informado, o resultado da consulta será postado (POST) para a URL informada.

Tipo aceito: string

Exemplo: &options={callback_url:url_de_callback}

result_html: Indica que deve retornar o bloco de informações em formato html. Utilizado para exibição do resultado da consulta direto em tela. (campo ResultHtml) (false por padrão).

Tipo aceito: boolean

Valores:

• true = retorna o bloco de informações em formato HTML

• false = não retorna o bloco (padrão)

true = retorna o bloco de informações em formato HTML

false = não retorna o bloco (padrão)

Exemplo: &options={result_html:true}

Lentidão na chamada das APIs

Como automatizamos consultas diretamente das fontes oficiais de dados, algumas chamadas podem demorar algum tempo para retornar ou até mesmo passarem por períodos de indisponibilidade. Caso ocorra lentidão, aguarde alguns minutos e tente executar novamente. Caso o erro persista, entre em contato com o [email protected]

Isto respondeu à sua pergunta?😞😐😃