Pular para o conteúdo

FAQ & Troubleshooting

Perguntas gerais

A API do FazNota tem ambiente de sandbox/homologação?

Não há sandbox dedicado. A especificação lista um único servidor, o de produção (https://api.mysebr.com.br/nfemyse-v3/rest). O ambiente em que os documentos são transmitidos (homologação ou produção) não é escolhido pela URL: ele vem do cadastro da empresa no FazNota (como descrito, por exemplo, no CIOT). Para conferir como a sua empresa está configurada, fale com o suporte.

Como recebo o resultado de uma emissão?

Consultando o recibo (polling). Toda emissão devolve um recibo, e o resultado final sai na consulta desse recibo (ex.: GET /nfe/nota/{recibo}). Veja Fluxo assíncrono.

Posso ter mais de um Token por empresa?

Atualmente cada empresa tem um Token único de integração, gerado no Painel FazNota. Para isolar integrações distintas (ex.: ERP vs e-commerce), você pode usar tokens de empresas vinculadas (se acessível via Painel de Gestão de Contas).

A API é versionada?

Sim. A versão atual é a v3, expressa no path (/nfemyse-v3/rest/...), e a versão exata corrente é a 3.20.0 (SemVer). Toda resposta informa a versão que respondeu no header X-API-Version e no campo meta.api_version. Quebra de contrato não entra na v3: vira /nfemyse-v4/, com as duas versões em paralelo e no mínimo 90 dias de comunicação prévia. Veja o Changelog.

Por que a API sempre retorna HTTP 200?

É uma convenção intencional de canal único de status: a aplicação responde em HTTP 200 sempre que processou a requisição, e o resultado real está em body.status. Apenas falhas estruturais (auth, rate limit, URL errada) retornam HTTP ≠ 200.

Os principais motivos da convenção:

  • Resposta sempre lida pelo cliente — bibliotecas como axios lançam exception em 4xx/5xx por padrão; com 200 + body.status, o cliente sempre acessa o body sem try/catch obrigatório para erros de negócio.
  • Validação não é erro de servidor — um CFOP inválido é resposta de negócio, não 5xx. Mistura com 5xx polui métricas de SRE.
  • Duplicidade (050) é resposta válida — retornar o recibo original é o comportamento correto.

Veja Estrutura de resposta para o padrão completo de tratamento.

Posso usar a API de um frontend (browser)?

Tecnicamente o CORS está aberto. Mas não é recomendado: o Token é credencial sensível e não deve ser exposto ao browser. Sempre faça as chamadas a partir do seu backend.

Autenticação

Recebo HTTP 401 mesmo com Token correto

  • Verifique se o header é Authorization: Token <valor>. Token é o formato canônico; o prefixo Bearer também é aceito como alias tolerado, mas prefira Token.
  • Confirme se o Token não foi trocado no painel — o Token é único por empresa, e o antigo deixa de valer.
  • Verifique se há espaços extras ou quebras de linha no Token.

Recebo HTTP 403 "contrato inapto"

Contrato da empresa precisa ser regularizado. Entre em contato com o suporte ou o time comercial do FazNota.

Recebo HTTP 429

Você atingiu o limite de consumo da janela atual. Veja X-RateLimit-Reset para saber quando retomar. Reduza o ritmo de envio e implemente backoff exponencial.

Emissão de notas

Recebi status: "001" mas a consulta retorna status: "002" há muito tempo

Esperado durante o processamento (alguns segundos a minutos). Continue o polling com intervalo de 2s+ e backoff. Se passar de 5 minutos, acione o suporte com o meta.request_id e o recibo.

Recebi status: "050" (duplicidade)

Não é erro. Você está enviando o mesmo numero-origem de uma emissão anterior. A API retorna o recibo da emissão original para você consultar. Veja Idempotência.

Recebi status: "900" (rejeição SEFAZ)

Antes de qualquer coisa, verifique data.sefaz.codigo. Se for 217 ou 105, não é uma rejeição — é a SEFAZ ainda processando a nota (lenta/instável). Continue consultando o mesmo recibo; o resultado se resolve sozinho em minutos (reconciliação automática, janela de até 3h). Não reemita — isso duplica o documento fiscal. Veja SEFAZ lenta ou instável para o detalhe completo.

120 e 150 nunca chegam com 900: são códigos de autorização (com alerta e fora de prazo) e saem com status: "004" — veja Autorizada com alerta.

Para qualquer outro data.sefaz.codigo, aí sim é rejeição definitiva. Algumas mensagens comuns:

Código aprox.Significado
Rejeição 539Duplicidade na SEFAZ (chave já existe lá)
Rejeição 539/610Numeração já utilizada
Rejeição 538/611NCM inválido
Rejeição 778CFOP incompatível com operação
Rejeição 233/237Inscrição estadual do destinatário inválida

Corrija o dado indicado na mensagem e emita uma nova nota (não é o caso de retentar a mesma).

Campo nfe@chave deve ter 44 caracteres.

A chave de acesso da NFe tem exatamente 44 dígitos numéricos. Não inclua prefixos como NFe, espaços ou hífens — apenas os 44 dígitos.

Campo nfe@motivo deve ter entre 15 e 255 caracteres.

No cancelamento (NF-e, NFC-e e NFS-e), o motivo precisa ter entre 15 e 255 caracteres. Na carta de correção (POST /nfe/correcao), o motivo é o texto da correção e aceita de 15 a 1.000 caracteres (desde a 3.15.1). Mensagens curtas como "Cancelar" ou "Teste" são rejeitadas.

Campo nfe@cliente documento não pertence a um cliente cadastrado.

O CPF/CNPJ informado em cliente (como string) não está cadastrado. Soluções:

  1. Cadastrar o cliente antes via POST /clientes.
  2. Enviar o cliente inline como objeto no body da emissão.

Campo nfe@transporte@placa-veiculo inválido.

A placa precisa estar no formato AAA-9999 (antigo) ou AAA-9A99 (Mercosul). Tudo maiúsculo. Exemplo válido: ABC-1234 ou ABC-1D23.

Consultas e listagens

Listagem retorna sempre os mesmos 100 (ou 50) registros

Você não está paginando. Adicione ?page=1&page_size=20 (e iterations subsequentes). Veja Paginação.

page_size=10000 retorna só 500

O limite é capado em 500 por chamada (1000 em clientes/produtos). Use loops com páginas menores.

Como saber quantas páginas tem no total?

A API não retorna o total. Pare quando uma página vier com menos itens que o page_size solicitado.

Performance

As consultas estão lentas

  • Verifique se você está usando a consulta completa quando bastaria a simples: /nfe/nota/{recibo}/completa em vez de /nfe/nota/{recibo} (NF-e), ou /nfce/cupom/{recibo}/completa em vez de /nfce/cupom/{recibo} (NFC-e).
  • Cache localmente listagens de clientes/produtos.
  • Evite consultar uma listagem grande para depois filtrar localmente — use os endpoints específicos (/clientes/{doc}, /produtos/{ref}).

Como melhorar performance de polling?

Use backoff exponencial. Após 004/010/999, pare. Para 900, confira data.sefaz.codigo antes de parar — veja SEFAZ lenta ou instável.

let wait = 2000;
const TERM = ['004', '010', '999'];
const SEFAZ_TRANSITORIO = ['217', '105'];
while (true) {
const json = await fetch(...).then(r => r.json());
const codigoSefaz = json.data?.sefaz?.codigo;
const parar = TERM.includes(json.status)
|| (json.status === '900' && !SEFAZ_TRANSITORIO.includes(codigoSefaz));
if (parar) break;
await sleep(wait);
wait = Math.min(wait * 1.5, 30_000);
}

Suporte

Como abrir um ticket?

Envie para [email protected] com:

  1. Descrição clara do problema.
  2. meta.request_id (ou X-Request-Id) de pelo menos uma requisição com falha.
  3. Horário aproximado do ocorrido.
  4. Trecho do payload enviado (omita o Token).
  5. Resposta recebida (status interno + descricao + data.erro).

O que NÃO incluir no ticket

  • ❌ Seu Token completo (envie apenas primeiros e últimos 6 caracteres se precisar)
  • ❌ Senhas do Painel FazNota
  • ❌ Dados pessoais de clientes/produtos não relacionados ao problema