# Index 1. [When to use the asynchronous API](#quando-usar) 2. [Creating a request](#criacao-pedido) 3. [Configuration parameters](#parametros-configuracao) 4. [Example (Receita Federal / CNPJ)](#exemplo-receita-federal-cnpj) 5. [Getting a response](#obtencao-resposta) 6. [Response callback](#callback) 7. [Retention period](#armazenamento) ## [When to use the asynchronous API](#quando-usar) The asynchronous API enables you to request an automation without keeping an open HTTP connection while waiting for the result. Scenarios in which you might consider the asynchronous API: - Batch processing; - Daily automatic processing or monitoring; - Queries that don't need to be processed immediately; - When trying to make a query multiple times until success. > This endpoint has no cost. ## [Creating a request](#criacao-pedido) | | | | --------------- | ------------------------------------------------ | | HTTP Method | POST | | URL | https://api.infosimples.com/api-async/v2/servico | | Response Format | JSON | Replace `service` with the chosen service, such as `receita-federal/cnpj`. You can find out the possible values in the [service specific documentation](https://api.infosimples.com/consultas/docs/en.md#servicos).

## [Configuration parameters](#parametros-configuracao) In addition to these parameters, you must also provide the service-specific parameters. You can find those in the [services documentation](https://api.infosimples.com/consultas/docs/en.md#servicos). `*`: Required parameter | Parameter | Description | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | token* | The token that will authenticate and authorize the request. | | time_limit | Maximum acceptable time to process the query. Minimum value: **current time + 600 seconds**. No maximum limit. The value must be a `String` in ISO 8601 format, e.g. `'2026-05-10T07:00:00-03:00'`. | | timeout | How long (in seconds) a request is allowed to take. Minimum value: **600**. No maximum limit. | | callback_url | A URL pointing to your application that will be invoked via GET when the request completes, sending you the `request_id` and the `callback_secret`. Your account's callback secret can be found in the [account settings](https://api.infosimples.com/administracao/conta?lang=en#callback_secret) and it allows you to confirm whether or not the data came from Infosimples' servers. | | context | A text of up to **1,000** characters that, if provided, will be returned together with the query. Can contain variables or identifiers from your application. We recommend encoding in `Base64` and applying encryption when the content contains sensitive data. | ## [Examples using service Receita Federal / CNPJ](#exemplo-receita-federal-cnpj) The example below shows a request and response for the **Receita Federal / CNPJ** service. It is required to inform the `cnpj` parameter. ### Request examples #### Python ```python # Tested with: 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": "VALUE_OF_PARAMETER_TOKEN", "callback_url": "VALUE_OF_PARAMETER_CALLBACK_URL", "context": base64.b64encode("VALUE_OF_PARAMETER_CONTEXT".encode("ascii")), "cnpj": "VALUE_OF_PARAMETER_CNPJ" } response = requests.post(url, args) response_json = response.json() response.close() print(response_json) ``` ### Response example #### Success ```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 } ``` #### Error ```json { "status":"error", "message":"Serviço (servico) não é válido" } ``` The possible resposnes are success or error. In case of an error, there will be also a message present that will allow you to understando what happened. **Important: requests for which `status` is `error` will not be billed.** ## [Response structure](#estrutura-da-resposta) An asynchronous API response has the following fields: | Field | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | request_id | string | Request identifier generated by Infosimples. It is a UUID with **36** characters. | | status | string | Request status: `pending` (created and being processed), `finished` (completed - always check the `response` field), `error` (an error prevented completion - details in `message`). Once `finished` or `error`, the request will no longer be updated. | | message | string | When status is **error** , this field contains details about the error. | | client_name | string | Account holder's full name. | | token_name | string | Name of the access key used in the request. | | api_version | string | API version used in the request. | | service | string | Requested service. | | timeout | number | Maximum processing time used. | | time_limit | string | Deadline date and time for processing. | | callback_url | string | URL of the server that will receive the `request_id` when the request is completed. | | context | string | Text provided in the asynchronous request. | | parameters | object | Service-specific parameters sent in the request. | | requested_at | string | Date and time of the request. | | finished_at | string | Date and time when processing completed. Can be `null`. | | response | object | When processing is complete, this contains the response that would normally be returned by the standard (synchronous) Infosimples API. Can be `null`. | ## [Getting a response](#obtencao-resposta) | | | | --------------- | --------------------------------------------- | | HTTP Method | GET | | Endpoint URL | https://api.infosimples.com/api-async/v2/show | | Response Format | JSON | ### Request parameters `*`: Required parameter | Parameter | Description | | ----------- | ----------------------------------------------------------- | | token* | The token that will authenticate and authorize the request. | | request_id* | Request identifier generated by Infosimples. | ### Request examples #### Python ```python # Tested with: Python 3.10.19, Python 3.14.0 import requests url = "https://api.infosimples.com/api-async/v2/show" args = { "token": "VALUE_OF_PARAMETER_TOKEN", "request_id": "VALUE_OF_PARAMETER_REQUEST_ID", } response = requests.get(url, args) response_json = response.json() response.close() print(response_json) ``` ### Response example #### Finished ```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')} } ``` #### Pending ```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 } ``` ## [Response callback](#callback) We suggest that you integrate using the `callback_url` parameter. In this case, you will receive an HTTP GET request on your server with the `request_id` of each completed request, and with this `request_id` you will be able to obtain the respective response. You will also receive the `callback_secret` parameter ([found here](https://api.infosimples.com/administracao/conta?lang=en#callback_secret)), which you can use to validate that the request genuinely came from the Infosimples API. Pseudocode for receiving a callback: ```python if params["callback_secret"] == "__MY_ACCOUNT_CALLBACK_SECRET_VALUE__" request_id = params["request_id"] // ... // continue processing to get the request data // ... else // ignore the request because it was not sent by Infosimples end ``` Although recommended, the `callback_url` is optional. If you end up not using it, you can call the endpoint that retrieves the response every 30 seconds to check if it has already completed. If you used the `callback_url` and did not receive a callback after the `timeout`, you can try to retrieve the response directly. One way to do this is to schedule a process on your application that tries to retrieve the response 3 seconds after the timeout expiration. Infosimples will send callback requests from the following IP addresses: ``` 3.221.156.169 34.171.31.113 ``` ## [Request retention period](#armazenamento) Infosimples retains asynchronous requests for 7 calendar days. After this period, the request is automatically deleted and its data can no longer be retrieved via the request retrieval endpoint. ## We're here to help Do you still need to figure something out? Reach us at [suporte@infosimples.com.br](mailto:suporte@infosimples.com.br) and our highly qualified support team will be happy to help.