# Índice 1. [Quando usar a API assíncrona](#quando-usar) 2. [Criação de um pedido](#criacao-pedido) 3. [Parâmetros de configuração](#parametros-configuracao) 4. [Exemplos ultilizando a consulta Receita Federal / CNPJ](#exemplo-receita-federal-cnpj) 5. [Obtenção de uma resposta](#obtencao-resposta) 6. [Callback de resposta](#callback) 7. [Prazo de armazenamento](#armazenamento) ## [Quando usar a API assíncrona](#quando-usar) A API assíncrona permite que você solicite a automação de uma consulta sem aguardar pelo retorno dela com uma conexão HTTP ativa. Cenários em que você pode considerar a integração com a API assíncrona: - Processamentos de lotes; - Processamentos ou monitoramentos automáticos diários; - Consultas que não precisam ser processadas imediatamente; - Quando tenta fazer uma consulta diversas vezes até ter sucesso. > Este endpoint não tem custo. ## [Criação de um pedido](#criacao-pedido) | | | | ------------------ | ------------------------------------------------ | | Método HTTP | POST | | URL | https://api.infosimples.com/api-async/v2/servico | | Formato do retorno | JSON | Substitua `servico` pelo serviço que será consultado, por exemplo `receita-federal/cnpj`. Você encontra o `servico` na [documentação específica](https://api.infosimples.com/consultas/docs/pt-BR.md#servicos) da respectiva API.

## [Parâmetros de configuração](#parametros-configuracao) Além desses parâmetros, é necessário passar os parâmetros específicos das fontes solicitadas. Você pode localizar esses parâmetros específicos nas [documentações específicas](https://api.infosimples.com/consultas/docs/pt-BR.md#servicos) de cada fonte. `*`: Parâmetro obrigatório | Parâmetro | Descrição | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | token* | Chave de autenticação da API. É com o token que a API reconhece e autoriza quem está fazendo a consulta. | | time_limit | Horário máximo aceitável para realizar a consulta. Valor mínimo: **horário atual + 600 segundos**. Não há limite para o valor máximo a ser informado. O valor deve ser informado como uma `String` no formato ISO 8601, por exemplo **"2026-05-10T07:00:00-03:00"**. | | timeout | Duração máxima aceitável para realizar a consulta, em segundos. Valor mínimo: **600**. Não há limite para o valor máximo a ser informado. | | callback_url | URL do seu servidor web que receberá uma requisição GET com o identificador do pedido (parâmetro `request_id`) junto com o parâmetro `callback_secret` ([você encontra o valor dele neste link](https://api.infosimples.com/administracao/conta?lang=pt-BR#callback_secret)) quando o pedido for finalizado. O `callback_secret` serve para você confirmar que foi a Infosimples que enviou a requisição para o seu servidor web. | | context | É um texto de até **1.000** caracteres que, se informado, será retornado junto com a consulta. Esse texto pode ser usado em sua aplicação para restaurar o contexto de execução do seu código. Por exemplo, ele pode conter um conjunto de variáveis ou um identificador de um registro da sua aplicação. Sugerimos que você sempre codifique esse campo em `Base64` e aplique criptografia simétrica quando o conteúdo possuir dados sensíveis. | ## [Exemplos ultilizando a consulta Receita Federal / CNPJ](#exemplo-receita-federal-cnpj) Por exemplo, para a consulta **Receita Federal / CNPJ** é necessário informar o parâmetro `cnpj`. ### Exemplo de requisição #### Python ```python # Testado com: Python 3.10.19, Python 3.14.0 import requests import base64 url = "https://api.infosimples.com/api-async/v2/receita-federal/cnpj" args = { "token": "VALOR_DO_PARAMETRO_TOKEN", "callback_url": "VALOR_DO_PARAMETRO_CALLBACK_URL", "context": base64.b64encode("VALOR_DO_PARAMETRO_CONTEXT".encode("ascii")), "cnpj": "VALOR_DO_PARAMETRO_CNPJ" } response = requests.post(url, args) response_json = response.json() response.close() print(response_json) ``` ### Exemplo de resposta #### Sucesso ```json { "request_id": "012d3642-297b-42ce-9dfd-27c44f4c321a", "status": "pending", "message": "", "client_name": "Infosimples", "token_name": "infosimples-producao", "api_version": "v2", "service": "receita-federal/cnpj", "time_limit": "2020-04-24T10:55:04.000-03:00", "timeout": 10800, "callback_url": "https://www.minhaempresa.com/infosimples/callback", "context": "ID_DO_PEDIDO_NA_MINHA_APLICACAO_19929818829", "parameters": {"cnpj":"00000000000191"}, "requested_at": "2020-04-23T10:55:04.000-03:00", "finished_at": null, "response": null } ``` #### Erro ```json { "status":"error", "message":"Serviço (servico) não é válido" } ``` Os retornos possíveis são de sucesso ou de erro. Em caso de erro, haverá também uma mensagem que permitirá entender o que aconteceu. **Importante: não haverá cobrança nos casos em que o valor de `status` for igual a `error`**. ## [Estrutura da resposta](#estrutura-da-resposta) Uma resposta da API assíncrona possui os seguintes campos: | Campo | Tipo | Descrição | | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | request_id | string | Identificador do pedido gerado pela Infosimples. É um UUID com **36** caracteres. | | status | string | Situação do pedido. Pode assumir um dos seguintes valores: **pending** : pedido criado com sucesso e em processamento. **finished** : pedido finalizado (é possível que a consulta tenha falhado com algum erro e por isso o campo `response` sempre deve ser verificado). **error** : um erro ocorreu e impediu a finalização do pedido. O campo `message` tem detalhes do erro. Uma vez que o status se tornar **finished** ou **error** , o pedido assíncrono não será mais atualizado. | | message | string | Em caso de status **error** , este campo apresenta uma mensagem com detalhes do erro. | | client_name | string | Nome do cliente por extenso. | | token_name | string | Nome da chave de acesso usada na requisição. | | api_version | string | Versão da API utilizada na requisição. | | service | string | Serviço solicitado. | | timeout | number | Valor utilizado para o tempo máximo de processamento. | | time_limit | string | Data e hora limite para processamento. | | callback_url | string | URL do seu servidor que receberá um request com o parâmetro `request_id` quando o pedido estiver finalizado. | | context | string | Texto informado na requisição do pedido assíncrono. | | parameters | object | Parâmetros específicos do serviço enviado na requisição. | | requested_at | string | Data e hora da requisição. | | finished_at | string | Data e hora do fim do processamento. Pode ser `null`. | | response | object | Quando o processamento estiver finalizado, retornará a resposta que normalmente seria retornada pela API padrão (síncrona) da Infosimples. Pode ser `null`. | ## [Obtenção de uma resposta](#obtencao-resposta) | | | | ------------------ | --------------------------------------------- | | Método HTTP | GET | | URL do endpoint | https://api.infosimples.com/api-async/v2/show | | Formato do retorno | JSON | ### Parâmetros da requisição `*`: Parâmetro obrigatório | Parâmetro | Descrição | | ----------- | -------------------------------------------------------------------------------------------------------- | | token* | Chave de autenticação da API. É com o token que a API reconhece e autoriza quem está fazendo a consulta. | | request_id* | Identificador do pedido gerado pela Infosimples. | ### Exemplo de requisição #### Python ```python # Testado com: Python 3.10.19, Python 3.14.0 import requests url = "https://api.infosimples.com/api-async/v2/show" args = { "token": "VALOR_DO_PARAMETRO_TOKEN", "request_id": "VALOR_DO_PARAMETRO_REQUEST_ID", } response = requests.get(url, args) response_json = response.json() response.close() print(response_json) ``` ### Exemplo de resposta #### Finalizado ```json { "request_id": "012d3642-297b-42ce-9dfd-27c44f4c321a", "status": "finished", "message": "", "client_name": "Infosimples", "token_name": "infosimples-producao", "api_version": "v2", "service": "receita-federal/cnpj", "time_limit": "2020-04-24T10:55:04.000-03:00", "timeout": 10800, "callback_url": "https://www.minhaempresa.com/infosimples/callback", "context": "ID_DO_PEDIDO_NA_MINHA_APLICACAO_19929818829", "parameters": {"cnpj":"00000000000191"}, "requested_at": "2020-04-23T10:55:04.020-03:00", "finished_at": "2020-04-23T10:55:06.161-03:00", "response": { ... } // #{t('docs.v2.assincrona.response_comment_1')} // #{t('docs.v2.assincrona.response_comment_2')} // #{t('docs.v2.assincrona.response_comment_3')} } ``` #### Pendente ```json { "request_id": "012d3642-297b-42ce-9dfd-27c44f4c321a", "status": "pending", "message": "", "client_name": "Infosimples", "token_name": "infosimples-producao", "api_version": "v2", "service": "receita-federal/cnpj", "time_limit": "2020-04-24T10:55:04.000-03:00", "timeout": 10800, "callback_url": "https://www.minhaempresa.com/infosimples/callback", "context": "ID_DO_PEDIDO_NA_MINHA_APLICACAO_19929818829", "parameters": {"cnpj":"00000000000191"}, "requested_at": "2020-04-23T10:55:04.000-03:00", "finished_at": null, "response": null } ``` ## [Callback de resposta](#callback) Sugerimos que faça sua integração com o parâmetro `callback_url`. Neste caso, você receberá uma requisição GET via HTTP com o `request_id` de cada pedido finalizado em seu servidor e com esse `request_id` poderá obter a respectiva resposta. Você também receberá o parâmetro `callback_secret` ([encontrado neste link](https://api.infosimples.com/administracao/conta?lang=pt-BR#callback_secret)) que pode ser usado por você para validar que a requisição veio genuinamente da API da Infosimples. Exemplo de um pseudocódigo do recebimento do callback: ```python if params["callback_secret"] == "__VALOR_DO_CALLBACK_SECRET_DA_MINHA_CONTA__" request_id = params["request_id"] // ... // continua processamento para obtenção dos dados do pedido // ... else // ignora a requisição porque não foi enviada pela Infosimples end ``` Caso opte por não informar o parâmetro `callback_url` no pedido **(NÃO RECOMENDADO)**, uma sugestão é chamar o serviço de obtenção de pedido em intervalos de 30 segundos para verificar se ele já foi finalizado. Caso você tenha usado o parâmetro `callback_url` e após o período de `timeout` não receba uma requisição da Infosimples em seu servidor web, recomendamos que faça uma requisição para obtenção de pedido. Uma sugestão é agendar um processo em sua aplicação que depois de 3 segundos do `timeout` expirar faz uma requisição para obtenção de pedido. As requisições de callback enviadas pela Infosimples serão originadas a partir de um dos endereços IPs a seguir: ``` 3.221.156.169 34.171.31.113 ``` ## [Prazo de armazenamento do pedido](#armazenamento) A Infosimples armazena o pedido de requisição assíncrona por 7 dias corridos. Após esse período, o pedido será excluído automaticamente e não será possível obter seus dados chamando o web service de obtenção de pedido. ## Precisa de ajuda? Ainda tem alguma dúvida ou precisa de ajuda na sua integração? Entre em contato em [suporte@infosimples.com.br](mailto:suporte@infosimples.com.br) e receba ajuda da nossa equipe técnica altamente qualificada.