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
axioslançam exception em 4xx/5xx por padrão; com200 + body.status, o cliente sempre acessa o body semtry/catchobrigató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 prefixoBearertambém é aceito como alias tolerado, mas prefiraToken. - 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 539 | Duplicidade na SEFAZ (chave já existe lá) |
| Rejeição 539/610 | Numeração já utilizada |
| Rejeição 538/611 | NCM inválido |
| Rejeição 778 | CFOP incompatível com operação |
| Rejeição 233/237 | Inscriçã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:
- Cadastrar o cliente antes via
POST /clientes. - 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}/completaem vez de/nfe/nota/{recibo}(NF-e), ou/nfce/cupom/{recibo}/completaem 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:
- Descrição clara do problema.
meta.request_id(ouX-Request-Id) de pelo menos uma requisição com falha.- Horário aproximado do ocorrido.
- Trecho do payload enviado (omita o Token).
- 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