Pular para o conteúdo
API de emissão de notas do FazNota

FAQ & Troubleshooting

Perguntas gerais

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

A documentação atual descreve o ambiente de produção (api.mysebr.com.br). Para testes sem efeito fiscal, entre em contato com o suporte sobre disponibilidade de ambiente de homologação.

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 é v3, expressa no path (/nfemyse-v3/rest/...). Mudanças significativas de contrato seguem comunicação prévia.

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 é exatamente Authorization: Token <valor> (não Bearer).
  • Confirme se o Token foi rotacionado no painel — o antigo é revogado.
  • 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.

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.

Para cancelamentos e cartas de correção, o motivo precisa ter entre 15 e 255 caracteres. 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 /nota/{recibo}/completa quando bastaria /nota/{recibo} (versão simples).
  • 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