Índice

1. Objetivo
2. Histórico de versão
3. Pré-requisitos
4. Processamento assíncrono e fluxo da solicitação
5. Status de processamento e comportamento do webhook
6. Endpoint da api
7. Restrições

Regras Comuns de Solicitação e Retorno das APIs assíncronas

1. Objetivo

Descreve o fluxo comum de integração para apis assíncronas da apuração de CBS.

2. Histórico de versão

3. Pré-requisitos

Para consumir as API assincronas é necessário:

1. Credenciais válidas para o estabelecimento matriz;
2. Token obtido por meio da API de autenticação;
3. Webhook válido e acessível publicamente para receber o retorno da API.

O manual com orientações para geração de credenciais e obtenção do token de acesso pode ser obtido em:
https://arquivos.receitafederal.gov.br → Documentos > Técnicos > Receita Integra.

4. Processamento assíncrono e fluxo da solicitação

Como as apis deste conjunto operam em modo assíncrono, a chamada não retorna o arquivo final na mesma requisição.

Como funciona

1. O cliente envia o POST da api específica informando a urlRetorno (do webhook).
2. A api valida a urlRetorno do webhook com método HEAD. Se o webhook não responder, a solicitação é cancelada com erro.
3. Em caso de sucesso (Código http 201), a api retorna o payload com tiqueteSolicitacao.
4. A api processa a solicitação de forma assíncrona.
5. Ao concluir o processamento, a api chama a urlRetorno (do webhook).
6. O payload que é enviado para urlRetorno do webhook:
   • Sucesso: retorna tiqueteSolicitacao, urlAssinada e urlAssinadaExpiraEm.
   • Erro: retorna codigoErro e mensagemErro.
7. A situação da solicitação pode ser consultada no endpoint a seguir, informando o tiqueteSolicitacao: Consultar a situação da solicitação

5. Status de processamento e comportamento do webhook

Enquanto estiver em processamento:

• o arquivo final ainda não estará disponível para download;
• o cliente deve aguardar o aviso no webhook (urlRetorno) ou consultar o endpoint de status.

Tempo esperado de processamento

• Tempo limite de processamento: até 240 minutos (4 horas).
  Se esse limite for excedido, a solicitação passará para o status de erro.

Comportamento do webhook (urlRetorno)

• O webhook é acionado quando o processamento for concluído (sucesso ou erro).
• Em caso de sucesso, o payload inclui tiqueteSolicitacao, urlAssinada e urlAssinadaExpiraEm.
• Em caso de erro, o payload inclui codigoErro e mensagemErro.

5.1 Recomendações de segurança para webhook

Para reduzir o risco de interceptação, falsificação e processamento indevido das notificações, o cliente deve:

1. Usar HTTPS: disponibilizar a urlRetorno exclusivamente com HTTPS. Não desabilitar a validação do certificado TLS.
2. Restringir o endpoint: utilizar uma rota dedicada ao recebimento das notificações, sem expor outras funções administrativas no mesmo endereço.
3. Proteger a urlAssinada: tratar a URL Assinada como um segredo temporário, pois ela autoriza o download durante o período de validade de 48 horas. Não gravá-la em logs, mensagens de erro, métricas, histórico do navegador ou ferramentas de rastreamento; transmiti-la e armazená-la somente em canais protegidos.
4. Validar a expiração: conferir urlAssinadaExpiraEm, quando presente, antes do download. Baixar o arquivo somente quando a notificação indicar sucesso e descartar a URL após o uso ou a expiração.
5. Controlar disponibilidade e abuso: aplicar limite de requisições, proteção contra repetição e monitoramento de falhas. A resposta deve ser um status HTTP 2xx somente depois que o recebimento tiver sido aceito; nos demais casos, usar um status não 2xx para permitir nova tentativa conforme o mecanismo de notificações.
6. Manter auditoria sem dados sensíveis: registrar, no mínimo, o tiqueteSolicitacao, o horário, o resultado do processamento e um identificador de correlação. Mascarar tokens, URLs pré-assinadas, credenciais e dados pessoais nos logs.

O cliente também deve manter o endpoint disponível durante o período esperado de processamento e tratar a consulta ao endpoint de status como mecanismo de recuperação caso a notificação não seja recebida. A validação do HEAD realizada na abertura da solicitação confirma apenas que o endereço está acessível; ela não substitui a autenticação nem a validação do conteúdo do POST.

6. Endpoint da API

6.1 Obter token OAuth2

Esta api utiliza protocolo de segurança TLS, OAuth 2.0 no fluxo Client Credentials.

Como funciona:

1. A aplicação cliente envia Client Id e Client Secret no endpoint de token.
2. O serviço retorna um access_token.
3. O token é enviado nas chamadas da api no header Authorization.

O manual com orientações para geração de credenciais e obtenção do token de acesso pode ser obtido em:
https://arquivos.receitafederal.gov.br → Documentos > Técnicos > Receita Integra.

6.2 Extrair, preparar o token para uso e acionar o endpoint da api

Após obter o token no passo anterior:

1. Substitua $TOKEN pelo valor de access_token. Este valor deve ser utilizado no cabeçalho das requisições para autenticação.
2. Substitua {cnpj} pelo CNPJ base com 8 dígitos.
3. Informe no corpo uma urlRetorno HTTPS válida para receber o payload com o link do arquivo de retorno.

6.3 Receber retorno assíncrono e baixar arquivo

Após receber a urlAssinada no webhook (urlRetorno), o arquivo pode ser baixado quantas vezes for necessário dentro do prazo de disponibilidade de 48 horas. Após esse prazo, a URL expira e deixa de permitir download.

7. Restrições

1. Limite de consumo do endpoint de abertura: 4 chamadas por dia.
2. O arquivo de retorno fica disponível por 48 horas após o aviso de pronto.