FAQ

Quais cidades são atendidas?

Para dúvidas se uma cidade é atendida na NFS-e, utilize o endpoint ConsultarMetadados. Ele retorna os metadados disponíveis para a cidade consultada e deve ser usado como fonte atualizada para validar atendimento e características do provedor.

Para saber se a cidade utiliza provedor padrão da prefeitura ou o padrão nacional, consulte o campo provedor retornado pelo endpoint. Quando o valor for PadraoNacional, a cidade utiliza o padrão nacional. Quando vier outro nome, como Fiorilli, Betha, Ginfes ou outro provedor, a cidade utiliza o provedor indicado.

Na emissão de NFS-e, o campo provedor do payload usa o enum:

• padrao: provedor padrão da prefeitura;
• nacional: Ambiente de Dados Nacional (ADN) do Sistema Nacional NFS-e.

O valor padrão é padrao. Use nacional quando os metadados da cidade indicarem PadraoNacional.

Exemplo de cidade atendida por provedor padrão:

{
  "codigo_ibge": "5008305",
  "uf": "MS",
  "municipio": "Tres Lagoas",
  "provedor": "Fiorilli",
  "ambientes": [
    "producao",
    "homologacao"
  ],
  "credenciais": [
    "certificado",
    "login_senha"
  ]
}

Exemplo de cidade atendida pelo padrão nacional:

{
  "codigo_ibge": "4115200",
  "uf": "PR",
  "municipio": "Maringa",
  "provedor": "PadraoNacional",
  "ambientes": [
    "producao",
    "homologacao"
  ],
  "credenciais": [
    "certificado"
  ]
}

Erros de RateLimit

Quando o limite de requisições for excedido, a API retorna:

HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-Retry-In: 1.003928397s

Ao receber 429, aguarde o tempo indicado nos headers Retry-After e X-Retry-In antes de tentar novamente. Para entender o funcionamento completo, consulte Limites e cotas.

Erros de falta de crédito

Quando não houver créditos suficientes para processar a operação, a API retorna:

HTTP/1.1 402 Payment Required

Código de erro:

• InsufficientCredits

Mensagem:

• Créditos insuficientes para concluir a operação. Adquira uma nova franquia para continuar.

Quando a requisição ultrapassar o limite permitido para a cota, a API também retorna 402, com o código:

• QuotaExceeded

Mensagem:

• A requisição ultrapassa o limite de {limite} operações para a cota "{nome-da-cota}".

Para consultar como a cota é consumida, quais headers observar e como tratar esses retornos, veja Limites e cotas.

Como saber como a cota é usada?

Consulte Limites e cotas. Essa página explica o consumo da cota prepago-creditos, os headers x-quota-name, x-quota-used e x-quota-limit, o endpoint de consulta da cota pré-paga e os comportamentos dos erros 402 e 429.

Erro X999 na emissão em homologação de NFS-e

Mensagem:

• X999: Erro de Conexão: Não informado a URL de Homologação, favor entrar em contato com a Prefeitura ou Provedor.

Para emitir NFS-e em ambiente de homologação, a prefeitura ou o provedor precisa disponibilizar uma URL de homologação. Nem todas as prefeituras possuem esse ambiente disponível.

Quando a prefeitura ou o provedor não disponibiliza ambiente de homologação, é necessário utilizar o ambiente de produção.

O que fazer em erros 400 a 499 ou internal error?

Se ocorrer erro HTTP entre 400 e 499, ou se a API retornar uma mensagem de internal error, abra um tópico em Dúvidas Privadas ACBr API com as evidências descritas em Onboard Integração, caso não for nenhuma das exceções tratadas abaixo.

Abrir fluxo em tela cheia

Para 401, verifique se o client_id e o client_secret pertencem ao ambiente usado, se o token foi gerado pelo fluxo OAuth 2 client_credentials e se a requisição está enviando o header Authorization: Bearer <access_token>.

Para 403, verifique se o token possui os scopes necessários para o endpoint chamado. Gere um novo token com os scopes corretos e envie a requisição novamente.

Para erros entre 400 e 499, revise primeiro os dados enviados. Confira payload, parâmetros, ambiente, CPF/CNPJ, IDs informados, scopes e endpoint utilizado. Se encontrar erro nos dados, corrija e envie a requisição novamente. Se os dados já foram conferidos e o erro persistir, separe as evidências para análise.

Inclua o corpo da resposta, ID da resposta ou da requisição quando disponível, client_id, ambiente, URL chamada, horário aproximado, endpoint usado e payloads/debug quando forem necessários para análise. Não envie segredos como client_secret, token de acesso, certificado digital ou senha do certificado.