Receita Federal · Documentação oficial

Guia API Assíncrona

Fluxo comum, webhook, segurança e restrições das APIs assíncronas de Apuração CBS.

docs.receitafederal.gov.br/apuracao-cbs/ Versão 1.1 · set/2026 · Receita Federal do Brasil

Pré-requisitos

01
Credenciais válidas para o estabelecimento matriz

Client Id e Client Secret obtidos junto à Receita Federal para o CNPJ raiz (8 dígitos).

02
Token obtido via API de autenticação

Token OAuth2 (Client Credentials) válido, incluído no header Authorization: Bearer <token>.

03
Webhook válido e acessível publicamente

URL HTTPS de retorno que aceite requisições HEAD (validação) e POST (notificação de conclusão).

Documentação sobre credenciais: arquivos.receitafederal.gov.br Documentos > Técnicos > Receita Integra

Fluxo assíncrono

1
Cliente envia POST com urlRetorno

Requisição para o endpoint correspondente (débitos, créditos, pagamentos ou recolhimentos) com a URL do webhook no corpo.

2
API valida webhook via HEAD

A API faz uma requisição HEAD para o urlRetorno. Se o webhook estiver indisponível, a solicitação é cancelada.

3
Sucesso (HTTP 201) retorna tiqueteSolicitacao

Resposta imediata com o tíquete identificador da solicitação assíncrona e o tempo estimado de processamento em segundos.

4
Processamento assíncrono iniciado

A Receita Federal processa a consulta de forma assíncrona. O tempo máximo de processamento é de 240 minutos.

5
Conclusão dispara chamada ao webhook

Ao final do processamento, a API notifica o cliente com POST para o urlRetorno informado.

6
Payloads do webhook
Sucesso
  • tiqueteSolicitacao
  • urlAssinada
  • urlAssinadaExpiraEm
Erro
  • codigoErro
  • mensagemErro
Limite temporal: o processamento assíncrono tem tempo máximo de 240 minutos (4 horas). Solicitações que ultrapassarem esse limite serão encerradas com erro APURACAO-408.

Recomendações de segurança

1

HTTPS obrigatório

Usar exclusivamente HTTPS com validação TLS. Nunca expor endpoints de webhook via HTTP.

2

Endpoint dedicado

Criar rota separada para o webhook, sem funções administrativas expostas no mesmo caminho.

3

Proteção da URL assinada

Tratar a urlAssinada como segredo temporário (válida por 48h). Não registrar em logs nem no histórico do navegador.

4

Validação de expiração

Verificar o campo urlAssinadaExpiraEm antes de realizar o download do arquivo de resultado.

5

Controle de disponibilidade

Implementar limites de requisição e proteção contra repetição. Responder HTTP 2xx apenas após aceitar e processar com sucesso a notificação.

6

Auditoria mascarada

Registrar em logs: tiqueteSolicitacao, horário e resultado. Mascarar tokens, URLs assinadas e credenciais.

Autenticação OAuth2 (Client Credentials)

1. Enviar
Client Id + Client Secret
→
2. Receber
access_token
→
3. Usar
Authorization: Bearer <token>

Exemplo de chamada

curl --location --request POST \
  'https://api.receitafederal.gov.br/apuracao-cbs/v2/{endpoint}/{cnpj}' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{ "urlRetorno": "https://cliente.exemplo.com/webhooks/apuracao-cbs" }'

Restrições

Restrição Limite
Chamadas ao endpoint de abertura 4 por dia
Disponibilidade do arquivo (URL assinada) 48 horas