Como ligar o seu ERP à Apuração Assistida do IBS sem improviso

O CGIBS publicou as respostas sobre arquivos, notificação e credenciais. Reunimos o que cada uma exige de quem vai construir.

1. Por que essa FAQ importa para quem desenvolve

O Comitê Gestor do IBS publicou uma lista de perguntas frequentes sobre a Apuração Assistida do IBS, na Central de Conteúdo do portal de serviços. São 21 perguntas, e elas respondem justamente o que o manual deixava em aberto.

O documento não é sobre o conceito da apuração assistida, que o blog já cobriu em Apuração Assistida: agora o Fisco calcula o seu imposto primeiro. É sobre a mecânica: que arquivos existem, como o seu sistema é avisado, que credenciais usar e o que acontece quando algo falha.

Reunimos abaixo o que mais muda decisão de arquitetura, agrupado por assunto, com uma linha de consequência prática onde ela existe. A redação oficial está na FAQ do CGIBS, e vale a leitura direta.

2. Os arquivos

O que é a Apuração Assistida do IBS?
É a sistemática pela qual as informações das operações e dos demais eventos com efeito na apuração do IBS são processadas, gerando os lançamentos correspondentes. O resultado fica disponível ao contribuinte para acompanhamento e para integração com os sistemas dele.

Que tipos de arquivo o sistema entrega?
Dois. O Arquivo Diferencial sai do Processamento Diário e traz as operações e os lançamentos daquele ciclo. O Arquivo Manual é gerado quando o contribuinte pede, e reúne as informações do período solicitado.

O Arquivo Diferencial mostra o saldo acumulado?
Não. Ele não é uma fotografia da apuração nem o saldo do momento. Traz apenas o que foi processado naquele ciclo, com as movimentações financeiras correspondentes. Para quem desenvolve, isso define o modelo. O arquivo é um fluxo de eventos para aplicar sobre o estado que você mantém, e não um estado pronto para substituir o seu.

As operações do Diferencial são sempre do dia anterior?
Não. O que coloca uma operação no arquivo é existir lançamento dela processado naquele ciclo, e não a data do fornecimento ou da emissão do documento. Uma operação antiga reaparece quando ganha um lançamento novo. Indexar pela data de emissão, portanto, não funciona.

Preciso baixar tudo de novo para manter os dados em dia?
Não. Os Arquivos Diferenciais sucessivos mantêm a base atualizada, sem exigir uma carga completa por dia.

Qual a diferença entre os dois, em uma frase?
O período de referência. O Diferencial corresponde a um Processamento Diário, e o Manual ao intervalo que o contribuinte solicitar.

3. A notificação

Como meu sistema fica sabendo que há arquivo novo?
Depois de gerar os arquivos, a Apuração Assistida chama um endereço HTTPS que você cadastra, o webhook, avisando que há material disponível. O webhook apenas notifica. Ele não transporta o arquivo, que continua sendo buscado pelas APIs.

E se o meu endpoint estiver fora do ar na hora?
O sistema tenta de novo. São cinco tentativas no total: a inicial e mais quatro, depois de 30 minutos, 2 horas, 6 horas e 12 horas. Insistindo o insucesso, o CGIBS manda um e-mail para o endereço cadastrado. Na prática, a última rede de proteção é uma pessoa lendo caixa de entrada, e não o seu sistema.

O webhook de teste usa dados reais?
Nesta versão, não. A função de teste do Portal dispara dados fixos, para você validar o recebimento e o tratamento da notificação. Ela simula o aviso, e não o resultado de um Processamento Diário.

4. As credenciais e os limites

O Client ID e o Client Secret expiram?
Não têm prazo de validade. Mas há um detalhe que derruba integração em produção: gerar um par novo invalida o par anterior imediatamente, sem período de convivência. Rotação de credencial, aqui, é corte seco, e precisa de janela combinada.

Os limites do Portal e da API são contados separado?
Não. Os limites são compartilhados entre o Portal do Contribuinte e a API. Uma pessoa baixando arquivos pela tela consome a mesma cota da sua automação, e isso costuma aparecer como erro intermitente sem causa aparente.

Por quanto tempo os arquivos ficam disponíveis?
Até 7 dias. Depois disso eles são removidos e a solicitação passa para a situação Expirada. Precisando do conteúdo de novo, só com nova solicitação. Uma integração que fique parada por um fim de semana prolongado já entra na zona de risco.

Se a sua equipe está dimensionando esse trabalho agora, vale ver antes de construir. A Migrate participa do piloto da Apuração Assistida do IBS desde o começo e pode mostrar a integração funcionando.

5. A operação no dia a dia

Dá para alterar ou excluir um lançamento já publicado?
Não. Lançamento publicado não se altera nem se apaga. A correção vem como um novo lançamento, que produz o efeito sem mexer no original, preservando o histórico. Para o seu banco de dados, isso significa tabela append-only, sem update e sem delete, com o saldo saindo da soma dos eventos.

Achei um arquivo ausente ou corrompido. E agora?
Você faz uma solicitação manual do período correspondente. O novo processamento gera o conjunto outra vez, e o conjunto anterior deve ser substituído pelo novo, e não complementado.

E quando o próprio Processamento Diário falha?
O caminho é o mesmo: solicitação manual do período afetado, para recuperar o que não chegou. Vale notar o que isso implica. O seu sistema precisa perceber a ausência, porque ninguém avisa que o arquivo que deveria existir não existe.

Como desligo a integração?
Pelo Portal do Contribuinte, com efeito imediato. Desabilitada, você para de receber Arquivos Diferenciais e não consegue fazer novas solicitações pela integração.

6. A conta que a integração cobra

Preciso de um ERP específico?
Não. O CGIBS não exige ERP determinado. Exige um sistema que implemente os requisitos, formatos e procedimentos do Manual de Orientação ao Contribuinte, e o credenciamento previsto nele.

Essa resposta é tecnicamente simples e operacionalmente pesada, porque a liberdade vem acompanhada da lista inteira. Vale enxergá-la junta, em vez de item a item.

Um endpoint HTTPS disponível o ano todo, porque a entrega tem cinco tentativas e depois vira e-mail. Processamento idempotente, porque a mesma notificação pode chegar mais de uma vez. Um modelo append-only para os lançamentos. Indexação por ciclo de processamento, e não por data de emissão. Detecção de ausência, porque arquivo que não veio não gera aviso. Reprocessamento por solicitação manual, com substituição do conjunto anterior. Controle da janela de 7 dias. Cota compartilhada com o uso humano do Portal. E rotação de credencial sem convivência entre pares.

Nenhum desses itens é difícil isolado. Somados, são um produto, com plantão, monitoração e evolução a cada versão do manual. A pergunta útil não é se o seu time dá conta, porque dá. É se essa é a camada que você quer manter e versionar pelos próximos anos, enquanto a Reforma segue mudando. O raciocínio de construir ou terceirizar está em Construir ou terceirizar o cálculo da Reforma.

E há a parte que nenhuma API entrega: conferir se o cálculo do Fisco está certo. Os arquivos chegam, o seu sistema os guarda, e alguém ainda precisa ler o resultado e discordar quando for o caso, dentro do prazo. Isso está em como ler o demonstrativo e em como contestar.

7. Perguntas frequentes

Se eu já baixo os arquivos pelo Portal, preciso integrar?
Depende do volume e da disciplina do processo. O download manual funciona, mas consome a mesma cota da API e depende de alguém lembrar dentro da janela de 7 dias. Operações com poucos documentos convivem bem com o Portal. Acima disso, a ausência de um dia costuma só aparecer no fechamento.

Perdi uma notificação e só percebi depois de uma semana. Recupero?
O arquivo original provavelmente expirou, porque a disponibilidade é de até 7 dias. O caminho é a solicitação manual do período, que gera o conjunto de novo. O conteúdo não se perde, o que se perde é a automação daquele intervalo, e o trabalho de reconciliar.

Posso implementar só o webhook agora e o resto depois?
O webhook sozinho avisa que existe arquivo, e nada mais, porque ele não transporta conteúdo. Sem o consumo pelas APIs e sem o tratamento dos lançamentos, você recebe o aviso e não tem o que fazer com ele. É uma entrega que parece progresso e não move o fechamento.

A Migrate substitui o meu ERP?
Não. O ERP continua sendo o seu, com as suas regras e a sua base. A Migrate atua na camada entre o Fisco e o seu sistema, que é onde moram o credenciamento, a notificação, o consumo dos arquivos e o acompanhamento da apuração. Vale conversar olhando o seu desenho atual, e não um genérico.

Onde encontro a redação oficial dessas respostas?
Na Central de Conteúdo do portal de serviços do CGIBS, na seção de perguntas frequentes sobre a Apuração Assistida do IBS. O mesmo catálogo reúne o Manual de Orientação ao Contribuinte e o manual específico da API de integração, que são a referência normativa para implementar.

Migrate ao seu lado na integração com a Apuração Assistida

A FAQ do CGIBS deixa claro que a integração não é um endpoint. É um conjunto de comportamentos combinados, cada um com a sua regra de falha, e todos precisam estar de pé no mesmo dia em que a apuração começa a valer.

A Migrate trabalha com documento fiscal eletrônico há mais de 20 anos, em cinco países, e foi habilitada no projeto piloto da Apuração Assistida do IBS. A solução já cobre o credenciamento, a notificação, o consumo dos arquivos e o acompanhamento, com a segurança de quem acompanha cada versão do manual desde a primeira.

Se a sua equipe está decidindo o que construir e o que integrar, vale ver funcionando antes de decidir. Agende uma demonstração da Apuração Assistida.

Referências

BRASIL. Comitê Gestor do IBS. Perguntas frequentes sobre a Apuração Assistida do IBS. Central de Conteúdo do Portal de Serviços do CGIBS. https://www.servicos.cgibs.gov.br/catalogo/469C76ED8FCC8C27E06338CC17ACC834/2

BRASIL. Comitê Gestor do IBS. Manual de Orientações do Contribuinte Usuário do Sistema de Apuração Assistida do IBS (MOC-IBS). Portal de Serviços do CGIBS. https://www.servicos.cgibs.gov.br/catalogo/469C76ED8FCC8C27E06338CC17ACC834/2

BRASIL. Comitê Gestor do IBS. API de Integração com a Apuração Assistida: Manual de Orientação ao Contribuinte. Portal de Serviços do CGIBS. https://www.servicos.cgibs.gov.br/catalogo/469C76ED8FCC8C27E06338CC17ACC834/2