--- title: "Guia de Solução de Problemas - Erros Comuns da API (RTC)" description: "Um guia para ajudar a diagnosticar e resolver erros comuns ao integrar com a API de emissão de NFS-e usando o layout RTC." source_url: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/guia-solucao-problemas-nfse-rtc last_updated: 2026-06-25 --- # 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. :::info * Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de [Perguntas e Respostas sobre a Reforma Tributária](/documentacao/reforma-tributaria/perguntas-e-respostas). Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas. * Se você quer uma **visão geral rápida**, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página [Visão geral da Reforma Tributária na NFE.io](/documentacao/reforma-tributaria) ::: ## 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 a especificação OpenAPI da API de NFS-e (RTC) 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 a especificação OpenAPI da API de NFS-e (RTC) 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.