Guia de Solução de Problemas: Erros Comuns da API (Layout RTC)

Introdução

Este guia foi projetado para ajudar desenvolvedores a diagnosticar e resolver erros comuns encontrados ao integrar com a API de emissão de NFS-e. Ele abrange erros de validação, rejeições de regras de negócio e problemas de fluxo de integração, fornecendo passos práticos para que sua integração funcione sem problemas.

---

Passos Gerais para Depuração

Antes de mergulhar em tipos de erro específicos, sempre siga estes passos iniciais:

1. Verifique a Resposta Completa da API: Nossa API retorna mensagens de erro estruturadas na resposta JSON. Essas mensagens frequentemente incluem um código de erro, uma descrição e o campo específico que causou o problema. Sempre registre (log) o corpo completo da resposta, pois é a informação mais crítica para a depuração.

2. Valide Contra o Schema: Muitos erros ocorrem porque o payload JSON não está em conformidade com a estrutura exigida. Antes de enviar uma requisição, valide seu payload contra o nfse-request-schema-rtc-pt-br.json para identificar problemas estruturais, tipos de dados incorretos ou formatos inválidos antecipadamente.

3. Utilize o Ambiente de Homologação: O Fluxo de Validação (Mockup) do ambiente de homologação é seu melhor amigo. Ele permite testar a estrutura e as regras de negócio da sua requisição sem de fato emitir um documento fiscal, fornecendo feedback instantâneo sobre o que precisa ser corrigido.

4. Aproveite os Logs Detalhados: Lembre-se de que nosso sistema mantém um histórico detalhado de todas as requisições e respostas. Se precisar contatar o suporte, ter o externalId ou o timestamp exato da sua requisição permitirá que nossa equipe encontre rapidamente os logs e diagnostique o problema.

---

Cenários de Erros Comuns e Soluções

1. Erros de Validação (HTTP 400 - Bad Request)

Estes são os erros mais comuns durante a integração inicial. Eles ocorrem quando o payload da requisição está malformado ou faltam informações obrigatórias.

Sintoma:

Uma resposta imediata da API com um status HTTP 400. O corpo da resposta conterá detalhes sobre a falha de validação.

Causas Comuns e Soluções:

• Campos Obrigatórios Ausentes:

  • Problema: Um campo ou objeto obrigatório está faltando. Por exemplo, deixar de enviar o objeto borrower, o servicesAmount ou todo o grupo IbsCbs.
  • Solução: Revise o nfse-request-schema-rtc-pt-br.json e a documentação funcional para garantir que todos os campos marcados como obrigatórios (ou required no schema) estejam presentes no seu payload JSON. Preste atenção especial ao grupo IbsCbs, que é sempre obrigatório.

• Formatos de Dados Inválidos:

  • Problema: Um campo é enviado no formato errado. Exemplos comuns incluem enviar uma data como DD/MM/AAAA em vez de YYYY-MM-DD, ou um número como string (ex: "100.00" em vez de 100.00).
  • Solução: Verifique os requisitos de tipo de dado e formato para cada campo na documentação. Datas e data-horas devem seguir os padrões ISO 8601 (YYYY-MM-DD e YYYY-MM-DDTHH:MM:SS-03:00).

• Valores de Enum/Código Inválidos:

  • Problema: Um campo que espera um conjunto específico de valores recebe um valor inválido. Por exemplo, enviar um taxationType incorreto ou um operationIndicator desatualizado.
  • Solução: Consulte as tabelas de referência na documentação funcional para os valores corretos de campos como taxationType, operationIndicator e classCode. Não fixe esses valores no código (hardcode) se eles puderem mudar com base na operação.

2. Erros de Regra de Negócio e Lógica

Esses erros ocorrem após a validação inicial ser aprovada, mas os dados violam uma regra de negócio específica aplicada pelo nosso sistema ou pelas autoridades fiscais.

Sintoma:

A requisição é aceita (HTTP 200/202), mas o status final recebido via webhook indica uma falha. A mensagem de erro descreverá a regra de negócio que foi violada.

Causas Comuns e Soluções:

• Códigos de Tributação Incorretos para a Operação:

  • Problema: A combinação de operationIndicator e classCode no grupo IbsCbs é inválida ou não corresponde ao serviço prestado. Esta é a parte mais crítica do novo layout.
  • Solução: Revise cuidadosamente a finalidade do operationIndicator (define o local de incidência do imposto) e do classCode (define o tratamento tributário). Garanta que você está usando os códigos corretos para o serviço, local e regimes tributários dos participantes específicos.

• Dados de Participantes Inválidos (CNPJ/CPF/Endereço):

  • Problema: O federalTaxNumber (CNPJ/CPF) do prestador ou tomador é inválido, inativo ou não corresponde aos seus dados cadastrais. Da mesma forma, um endereço incorreto (especialmente CEP ou código da cidade) pode causar rejeição.
  • Solução: Conforme recomendado nas boas práticas, utilize nossas APIs de consulta para validar dados cadastrais (CNPJ/CPF, Inscrição Estadual) e endereços (CEP) antes de enviar a requisição de emissão. Este passo de pré-validação reduz significativamente as rejeições.

• Erros de Campos Condicionais:

  • Problema: Um campo que é obrigatório apenas sob certas condições está ausente. Por exemplo, enviar taxationType: "Immune" sem fornecer o immunityType correspondente.
  • Solução: Leia a documentação para campos que possuem lógica condicional. O campo immunityType, por exemplo, só é obrigatório quando taxationType é Immune. Outro exemplo é o objeto recipient, que se torna obrigatório se destinationIndicator for DifferentFromBuyer.

3. Erros de Fluxo de Integração e Processamento Assíncrono

Esses problemas estão relacionados ao fluxo geral de comunicação com a API, em vez do payload de dados em si.

Sintoma:

Comportamento inesperado, como notas fiscais duplicadas ou nunca receber uma atualização de status final.

Causas Comuns e Soluções:

• Emissão de Nota Fiscal Duplicada:

  • Problema: Seu sistema envia a mesma requisição de emissão várias vezes, muitas vezes devido a timeouts de rede ou falta de confirmação de resposta, resultando em notas duplicadas.
  • Solução: Sempre utilize o campo externalId. Forneça um identificador único do seu sistema para cada requisição. Se nossa API receber uma requisição com um externalId que já foi processado com sucesso, ela não criará uma nova nota e, em vez disso, retornará os dados da original, garantindo a idempotência.

• Não Recebimento do Status Final (Problemas de Webhook):

  • Problema: Você envia uma requisição com sucesso, mas nunca recebe a notificação final de sucesso ou falha na sua URL de webhook.
  • Solução:
    1. Verifique sua URL de Webhook: Garanta que a URL de webhook configurada em nosso sistema está correta, acessível publicamente e pode receber requisições POST.
    2. Verifique seu Firewall/Rede: Certifique-se de que nossos servidores não estão sendo bloqueados pelo seu firewall.
    3. Inspecione os Logs do Servidor: Verifique os logs do seu servidor no momento da requisição para ver se a chamada do webhook foi recebida e se resultou em um erro do seu lado (ex: 500 Internal Server Error).

• Mecanismo de Retentativa Automático:

  • Informação: Para erros temporários de rede ou instabilidade por parte da autoridade fiscal (como timeouts ou erros 5xx), nosso sistema possui um mecanismo de retentativa com exponential backoff integrado. Você não precisa implementar sua própria lógica de retentativa para esses casos; nossa API gerencia isso automaticamente.

---

Seguindo este guia, você pode identificar e corrigir eficientemente os problemas mais comuns, levando a uma integração mais rápida e confiável.