A integração fiscal não termina quando o sistema envia uma requisição. Nas APIs assíncronas da apuração da Contribuição sobre Bens e Serviços (CBS), a abertura de uma consulta inicia um processo que pode ser concluído mais tarde, com um arquivo de retorno obtido em etapa própria. Essa distinção é importante para quem mantém ERPs em Delphi e para profissionais contábeis que dependem da consistência dos dados recebidos pelo sistema.
Em 14 de outubro de 2026, a Receita Federal registrou a versão 1.1 das Regras Comuns de Solicitação e Retorno das APIs assíncronas. A revisão atualizou o conteúdo da notificação enviada ao webhook e o fluxo de obtenção e download do arquivo de retorno por meio de urlAssinada. Não se trata, portanto, de apenas trocar uma URL: a implementação precisa separar claramente a abertura, o acompanhamento, a autorização temporária de download e a leitura do arquivo.
Este artigo percorre o fluxo confirmado na documentação oficial, explica seus efeitos operacionais, delimita o que vale especificamente para débitos e créditos e propõe um roteiro de implementação e testes. Também aponta divergências entre páginas oficiais que merecem tratamento defensivo no código.
Este roteiro complementa o guia de integração da apuração assistida ao ERP. Para contextualizar a evolução dos ambientes, consulte também o anúncio inicial das APIs da CBS; os contratos a implementar são os da documentação oficial atual, não os de versões anteriores.
O que a revisão de outubro efetivamente mudou
É útil separar dois momentos da documentação. Em 14 de setembro de 2026, a Receita Federal anunciou novas APIs de apuração da CBS e a adoção de consultas incrementais, com oferta gradual dos serviços. Já a mudança específica do retorno assíncrono está registrada em 14 de outubro, na versão 1.1 do guia comum. Essa distinção evita atribuir ao anúncio de setembro detalhes técnicos que foram documentados na revisão posterior.
A versão 1.1 passou a prever que, depois de uma solicitação atingir a situação CONCLUIDA, o consumidor consulte um serviço autenticado de download usando o tíquete da solicitação. A resposta desse serviço entrega uma urlAssinada, isto é, um endereço temporário para obter o arquivo de retorno. O download do arquivo é feito com GET diretamente nessa URL, sem Bearer Token e sem cabeçalhos adicionais, conforme a documentação do serviço de download.
A consequência prática é direta: o webhook não entrega o arquivo e não deve ser projetado como se entregasse. Ele passa a sinalizar o desfecho do processamento. Em caso de sucesso, a notificação contém tiqueteSolicitacao e situacao; em caso de erro, contém codigoErro e mensagemErro. Cabe ao ERP, ao receber uma conclusão, executar a próxima etapa autenticada para obter o link temporário e, só então, baixar e processar o JSON.
O serviço de consulta do link temporário teve versão inicial registrada em 13 de outubro de 2026. Isso reforça que a URL assinada é uma fase própria do contrato de integração, não um campo eventualmente anexado à resposta de abertura ou à notificação.
O fluxo assíncrono ponta a ponta
A maneira mais segura de entender a integração é tratá-la como uma máquina de estados controlada pelo tíquete. Esse tíquete é a chave de correlação entre a abertura da solicitação, a notificação, as consultas de situação e o download.
1. Abertura da solicitação e persistência do tíquete
A API específica é acionada por uma requisição POST. Se a abertura for aceita, a resposta é HTTP 201 e contém tiqueteSolicitacao. Nas APIs de débitos e créditos, a resposta pode trazer também tEASegundos, a estimativa de atendimento em segundos; o valor -1 indica que uma estimativa não pôde ser obtida.
Para o ERP, o ponto essencial é persistir o tíquete imediatamente, junto com informações de correlação internas: contribuinte consultado, tipo de serviço, data e hora da abertura, estado inicial, identificador do usuário ou rotina que iniciou o processo e eventuais códigos de erro. Sem esse registro, uma notificação posterior fica difícil de relacionar à tarefa contábil que a originou.
O aceite de abertura não significa que o arquivo esteja pronto. Ele representa apenas o ingresso da solicitação no fluxo assíncrono. Por isso, a rotina não deve bloquear a tela do usuário nem pressupor que haverá resultado imediato.
2. Webhook opcional ou acompanhamento por consulta de situação
O campo urlRetorno é opcional. Com webhook, o cliente informa uma URL de retorno e a API realiza uma chamada HEAD para validar a disponibilidade do endereço antes de prosseguir. A validação comprova que o endpoint está acessível, mas, como a própria Receita ressalta no guia, não substitui autenticação nem validação do conteúdo posteriormente enviado por POST.
Sem webhook, a orientação é enviar urlRetorno como string vazia e acompanhar o processamento pela API de situação. A consulta de situação também é o mecanismo de contingência quando existe webhook, mas a notificação não chega. Portanto, webhook é um acelerador de reação; não elimina a necessidade de uma rotina de reconciliação.
A API de situação documenta os estados PENDENTE, EM_PROCESSAMENTO, CONCLUIDA, ERRO e EXPIRADA. Ao identificar CONCLUIDA, o sistema pode avançar para a consulta do link de download. Em ERRO ou EXPIRADA, a resposta inclui codigoErro e mensagemErro, que devem ser preservados para suporte e auditoria.
3. Obtenção autenticada da URL assinada
Após CONCLUIDA, o ERP consulta o endpoint de download com o tíquete e autenticação Bearer. A resposta HTTP 200 contém urlAssinada e, quando disponível, urlAssinadaExpiraEm. Esse ponto merece uma separação arquitetural importante: a autenticação usada para solicitar o link não é reutilizada no download do arquivo.
A URL assinada deve ser tratada como uma credencial temporária. Quem a possuir durante sua validade pode baixar o arquivo. Por isso, ela não deve aparecer em logs, mensagens de exceção, métricas, históricos de navegador ou sistemas de rastreamento. O guia oficial recomenda também mascarar tokens, credenciais, URLs pré-assinadas e dados pessoais nos registros operacionais.
Se o link expirar, a documentação orienta consultar novamente o endpoint de download para gerar outro, desde que o arquivo ainda esteja disponível. Não é necessário — nem indicado — repetir a abertura da consulta apenas porque a URL assinada venceu.
4. Download e processamento do arquivo de retorno
O arquivo é obtido por GET na URL assinada, sem Bearer Token e sem cabeçalhos adicionais. No desenho de um cliente Delphi, vale separar essa chamada da camada habitual que injeta automaticamente Authorization em todas as requisições. Reaproveitar o token nesse GET contraria o contrato documentado e pode produzir comportamento inadequado.
Depois do download, a aplicação deve validar e processar o JSON conforme a especificação do serviço consumido. O processamento precisa ser idempotente do ponto de vista interno: se uma rotina for retomada após falha local, o ERP não pode duplicar lançamentos, eventos ou controles apenas porque o mesmo arquivo foi reavaliado. Uma estratégia possível é registrar o tíquete, o momento da leitura e uma identificação do conteúdo processado, usando isso para impedir uma segunda aplicação do mesmo retorno.
Limites operacionais e consultas incrementais
O guia comum estabelece três condições de planejamento relevantes: até quatro chamadas diárias de abertura por API, prazo máximo de processamento de 240 minutos e disponibilidade do arquivo por 48 horas após o aviso de que está pronto. Esses parâmetros devem orientar o agendamento de jobs e a rotina de monitoramento.
O limite de quatro chamadas é relativo à abertura, não uma autorização para disparar consultas em excesso até encontrar uma resposta desejada. Em sistemas multiempresa, a equipe deve mapear com precisão em que nível controla esse consumo por API e organizar uma fila que evite desperdício de chamadas.
Já a disponibilidade de 48 horas exige reação operacional. Não é prudente aguardar a próxima manutenção manual para buscar um arquivo concluído. Um webhook recebido ou um polling que encontre CONCLUIDA deve colocar o download em uma fila de alta prioridade, com registro claro de sucesso ou falha.
Para débitos e créditos, a documentação prevê retorno incremental: são consideradas inclusões e atualizações desde a data de atualização da última solicitação concluída mais recente, limitadas aos últimos oito dias, desde que tenha havido consulta concluída nos três meses anteriores. Se não houver consulta concluída nesse período, a busca começa no primeiro dia do mês corrente. Essa regra está explicitamente documentada para esses dois serviços; não deve ser generalizada automaticamente para outras APIs sem conferência da especificação correspondente.
A implicação contábil é que a regularidade das consultas influencia o recorte de dados retornados. Para conciliações, o ERP precisa armazenar a data e a situação das consultas concluídas, em vez de usar apenas a data da tentativa de abertura. Uma tentativa que falhou ou expirou não equivale, pelo texto da regra, a uma consulta concluída.
Segurança, observabilidade e pontos que exigem cautela
O guia comum orienta que a URL de webhook seja disponibilizada exclusivamente por HTTPS, com validação de certificado TLS mantida. Também recomenda rota dedicada ao recebimento das notificações e, como camada adicional, restrição de origens por faixas oficiais de IP quando aplicável ao ambiente emissor.
Há, porém, uma limitação documental relevante. As páginas de débitos e créditos ainda trazem um trecho que menciona urlRetorno acessível por HTTP ou HTTPS, enquanto o guia comum exige HTTPS. As fontes não demonstram uma harmonização formal entre esses textos. A escolha prudencial é seguir a regra mais restritiva — HTTPS —, não porque exista confirmação de que a referência a HTTP já tenha sido removida de todos os serviços, mas porque essa é a orientação do guia comum e de seu capítulo de segurança.
Outro cuidado envolve o fim do processamento. O guia comum informa que, se o limite de 240 minutos for excedido, a solicitação passa para status de erro. A página de situação, por sua vez, exemplifica esse caso com situacao=EXPIRADA. Em vez de codificar uma única expectativa, o cliente deve tratar ERRO e EXPIRADA como estados terminais, persistir o código e a mensagem recebidos e encaminhar a ocorrência para uma fila de análise ou nova ação controlada.
No endpoint de download, a documentação prevê HTTP 401 para token, tíquete ou identificação do consumidor inválidos; HTTP 404 para solicitação inexistente ou arquivo indisponível — inclusive enquanto o processamento não terminou ou quando o download já foi realizado —; e HTTP 500 para erro interno. Um 404, portanto, não deve ser automaticamente interpretado como ausência definitiva de dados. O sistema precisa considerar a situação conhecida do tíquete, o horário e as tentativas já realizadas antes de definir uma ação.
Aplicação prática
A adaptação pode ser organizada como uma entrega técnica curta, mas disciplinada, envolvendo desenvolvimento, infraestrutura e operação contábil.
Modele uma tabela de controle de solicitações
Crie uma entidade própria para a solicitação assíncrona. Ela deve guardar, no mínimo, o tipo de API, o contribuinte relacionado, o tiqueteSolicitacao, o horário de abertura, a situação atual, os horários de notificação, consulta de situação e download, além de codigoErro e mensagemErro quando existirem. Registre também um identificador de correlação interno, mas não armazene URL assinada ou token em texto aberto nos logs.
Essa estrutura permite responder perguntas operacionais objetivas: qual solicitação ainda está em processamento, qual arquivo foi baixado dentro da janela de disponibilidade e qual erro precisa ser tratado pelo suporte ou pela área contábil.
Implemente webhook e polling como mecanismos complementares
Se houver webhook, disponibilize uma rota exclusiva em HTTPS e prepare-a para responder ao HEAD de validação antes da abertura. Ao receber o POST, valide a estrutura mínima esperada, relacione o tíquete à solicitação persistida e coloque a próxima ação em fila. O receptor do webhook deve ser rápido: receber, validar, registrar e delegar o trabalho pesado ao processamento assíncrono interno.
Em paralelo, mantenha um job de polling da situação. Ele é obrigatório quando urlRetorno estiver vazia e útil como contingência quando houver webhook. Use intervalos progressivos, evitando consultar sem necessidade. O limite de quatro chamadas diárias informado no guia se refere ao endpoint de abertura; ainda assim, o polling deve ser moderado, rastreável e baseado no estado atual, sem gerar tráfego desnecessário.
Separe os clientes HTTP no projeto Delphi
Na implementação, trate três tipos de chamada: abertura e situação autenticadas; obtenção do link também autenticada; e download pela URL assinada sem Bearer Token ou cabeçalhos adicionais. Essa separação reduz o risco de um interceptor global acrescentar credenciais no GET final.
Teste explicitamente o comportamento de expiração. Quando urlAssinadaExpiraEm vier na resposta, use-o como dado de controle. Se o download não ocorrer a tempo, solicite novo link, desde que ainda esteja dentro da disponibilidade do arquivo. Após concluir a leitura, descarte a URL da memória e não a replique em notificações internas.
Monte uma matriz de testes antes de liberar
A validação não deve cobrir apenas o caminho feliz. Teste abertura aceita com retorno HTTP 201; webhook de sucesso; webhook de erro; ausência de webhook com acompanhamento por situação; CONCLUIDA seguida de download HTTP 200; e falhas 401, 404 e 500 na consulta do link.
Inclua ainda casos terminais ERRO e EXPIRADA, justamente pela divergência de redação sobre o prazo de 240 minutos. Verifique que o ERP não baixa arquivo antes da conclusão, que não reenvia a abertura por simples expiração do link e que impede duplicidade no processamento do JSON. Para débitos e créditos, simule consultas concluídas recentes e ausência de conclusão nos três meses anteriores para avaliar a regra incremental documentada.
Alinhe desenvolvimento e contabilidade
A equipe contábil deve conseguir identificar, na interface do ERP, se uma consulta foi aberta, está processando, foi concluída e baixada, ou terminou em erro/expiração. Isso não significa interpretar tecnicamente cada código, mas oferecer evidência operacional suficiente para a conciliação e para o acionamento da equipe responsável.
Os marcos divulgados pela Receita para disponibilização gradual — débitos e créditos no início de outubro, pagamentos e recolhimentos no início de novembro, e DARFs RAD e PCONT ao final de novembro de 2026 — são cronograma de oferta de serviços, conforme a notícia oficial. Eles não foram apresentados, nas fontes consultadas, como prazo geral obrigatório de adaptação para empresas ou desenvolvedores.
Conclusão
A revisão das APIs assíncronas da CBS formaliza um fluxo em quatro etapas: abrir a solicitação e guardar o tíquete; acompanhar a situação por webhook ou consulta; obter uma URL assinada em endpoint autenticado após a conclusão; e baixar o arquivo por GET sem token adicional. Para um ERP, esse desenho pede controle de estados, filas de processamento, observabilidade sem exposição de segredos e uma rotina confiável de contingência.
O ponto central para desenvolvedores Delphi é não reduzir a mudança a um detalhe de transporte. O tíquete deve se tornar o eixo da integração, e o arquivo deve ser processado com idempotência. Para a área contábil, a disciplina de acompanhamento ajuda a distinguir uma consulta concluída de uma tentativa ainda pendente ou encerrada com falha, especialmente nas regras incrementais de débitos e créditos.
Persistem limites documentais: há divergência entre ERRO e EXPIRADA para o estouro de 240 minutos e entre a exigência de HTTPS no guia comum e a menção a HTTP ou HTTPS em páginas específicas. Enquanto não houver harmonização expressa, tratar ambos os estados como terminais e adotar HTTPS representa uma implementação defensiva baseada no conjunto das evidências oficiais, sem supor obrigações ou disponibilidades além do que foi publicado.
Referências
RECEITA FEDERAL DO BRASIL. Consultar créditos em operações de consumo (CBS). 2026. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/credito.html. Acesso em: 19 out. 2026.
RECEITA FEDERAL DO BRASIL. Consultar débitos em operações de consumo (CBS). 2026. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/debito.html. Acesso em: 19 out. 2026.
RECEITA FEDERAL DO BRASIL. Consultar link para download do arquivo de retorno. 2026. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/download.html. Acesso em: 19 out. 2026.
RECEITA FEDERAL DO BRASIL. Consultar situação da solicitação. 2026. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/situacao-solicitacao.html. Acesso em: 19 out. 2026.
RECEITA FEDERAL DO BRASIL. Receita Federal publica nova documentação técnica das APIs de apuração da CBS. 2026. Disponível em: https://www.gov.br/receitafederal/pt-br/assuntos/noticias/2026/setembro/receita-federal-publica-nova-documentacao-tecnica-das-apis-de-apuracao-de-cbs. Acesso em: 19 out. 2026.
RECEITA FEDERAL DO BRASIL. Regras Comuns de Solicitação e Retorno das APIs assíncronas. 2026. Disponível em: https://docs.receitafederal.gov.br/apuracao-cbs/guiaapiassincrona.html. Acesso em: 19 out. 2026.
0 comentário(s)