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

Integração com IA / LLMs

Vai gerar a integração com a ajuda de um assistente de IA (Claude, ChatGPT, Copilot, Cursor…)? Esta página reúne o material pronto para o modelo entender a API v3 e produzir código correto de primeira.

Arquivos prontos para IA

llms.txt (índice)

Índice curado de toda a documentação v3, em Markdown, no padrão llmstxt.org. Aponte seu agente para ele.
https://faznota.com.br/api/llms.txt

llms-full.txt (contexto completo)

Toda a documentação v3 concatenada em um único Markdown. Cole no seu assistente para dar contexto total de uma vez.
https://faznota.com.br/api/llms-full.txt

Como usar

  1. Contexto rápido: cole a URL do llms-full.txt (ou o conteúdo dele) no seu assistente e peça: “Com base nesta documentação, gere a integração de emissão de NFe em <sua linguagem>.”
  2. Bloco mínimo: se preferir algo curto, copie o bloco de contexto abaixo — é o essencial e estável da API.

Bloco de contexto (copie e cole no seu LLM)

Você vai integrar com a API de Nota Fiscal do FazNota (v3). Regras essenciais:


BASE E AUTENTICAÇÃO
- Base URL: https://api.mysebr.com.br/nfemyse-v3/rest
- Auth: header em TODAS as requisições -> Authorization: Token <TOKEN_DA_EMPRESA>
- O TOKEN é a chave de integração da empresa (não expor no frontend; chamar do backend).


MODELO ASSÍNCRONO (emissão -> recibo -> polling)
1) POST /nfe/emissao (ou /nfce/emissao, /nfse/emissao) devolve um "recibo".
2) Consultar o resultado por polling em GET /nfe/nota/{recibo} (NFCe: /nfce/cupom/{recibo}).
3) Intervalo mínimo 2s entre consultas, com backoff exponencial (2s,3s,4.5s,...ate 30s).
   Parar em estado terminal. Timeout total ~5 min.


ENVELOPE DE RESPOSTA (sempre HTTP 200 nos endpoints de negócio)
{ "status": "<codigo>", "descricao": "<texto>", "data": { ... },
  "meta": { "request_id": "...", "timestamp": "..." } }
- Guarde meta.request_id (e o header X-Request-Id) nos seus logs — agiliza o suporte.
- Headers X-RateLimit-Limit/Remaining/Reset indicam o consumo permitido.


STATUS DE EMISSÃO (campo status; decida pelo data.sefaz.codigo quando houver)
- 001 registrada (recibo gerado) | 002/003 em processamento | 004 autorizada
- 010 cancelada | 050 duplicidade (mesmo numero-origem -> retorna o recibo original)
- 006 processado sem resultado | 007 falha no processamento assíncrono (ambos finais)
- 400 parâmetro inválido (erro do chamador — repetir a requisição não resolve)
- 900 rejeição da SEFAZ (corrigir e reemitir). IMPORTANTE: se vier 900 com
  data.sefaz.codigo 217 ou 105, NÃO é rejeição — a SEFAZ ainda está processando;
  continue consultando o mesmo recibo e NÃO reemita (duplica documento fiscal).


IDEMPOTÊNCIA
- Envie sempre "numero-origem" (seu id único da venda). Reenvio com o mesmo valor
  NÃO gera outra nota — retorna o recibo da emissão original.


PAYLOAD DE EMISSÃO DE NFe (POST /nfe/emissao) — campos principais
{
  "serie": "1",                         // obrigatório
  "cfop": "5102",                       // obrigatório na prática
  "numero-origem": "PED-2026-0001",     // recomendado (idempotência)
  "tipo": "S",                          // S saída (default) | E entrada
  "finalidade": "N",                    // N normal | C complementar | A ajuste | D devolução
  "cliente": "12345678000199",          // CPF/CNPJ de cliente cadastrado OU objeto com dados
  "itens": [                            // obrigatório, >=1
    { "produto": "SKU-001", "quantidade": "2", "valor-unitario": "89.90" }
    // "produto" pode ser objeto com referencia + configuracoes-fiscais (ipi, pis-cofins,
    //  cbs-ibs (IBS/CBS reforma tributária), icms.estados[].aliquotas...)
  ],
  "transporte": { "modalidade": "9" },  // 9 = sem frete (default)
  "faturas": [ { "valor": "179.80", "data": "2026-08-15" } ]  // opcional
}
Cliente inline exige endereço completo (no mínimo cidade e estado/UF).


ENDPOINTS PRINCIPAIS
- NFe:  POST /nfe/emissao | GET /nfe/nota/{recibo}[/completa] | PUT /nfe/{id} |
        POST /nfe/cancelamento | POST /nfe/correcao | GET /nfe (lista, ?page&page_size)
- NFCe: POST /nfce/emissao | GET /nfce/cupom/{recibo}[/completa] | POST /nfce/cancelamento
- NFSe: POST /nfse/emissao | GET /nfse/nota/{recibo} | POST /nfse/cancelamento
- nffornecedor: POST /nffornecedor/reconhecimento | GET /nffornecedor/{recibo}
- clientes: GET/POST /clientes | GET/PUT/DELETE /clientes/{doc} | GET /clientes/busca/{nome}
- produtos: GET/POST /produtos | GET/PUT/DELETE /produtos/{ref}
- resumo:  GET /resumo?data-inicial=AAAA-MM-DD&data-final=AAAA-MM-DD (máx 92 dias)
           totais/dia de NFe e NFCe emitidas/canceladas/denegadas + falhas.
           ATENÇÃO: canceladas é SUBCONJUNTO de emitidas — não some os dois.
- xml em lote (assíncrono): POST /xml/solicitacao {tipo:NFe|NFCe, data-inicial,
           data-final, email?} -> data.protocolo; depois GET /xml/solicitacao/{protocolo}
           -> 002 processando | 005 disponivel (data.url-download, expira em 7 dias)
           | 006 sem-notas (final) | 007 falha (final). A url-download só aceita GET.


ERROS
- Erro de negócio vem em data.erro (texto claro e acionável). HTTP != 200 só em auth
  (401/403), rate limit (429) e URL inválida.


EXEMPLO cURL (emissão)
curl -X POST https://api.mysebr.com.br/nfemyse-v3/rest/nfe/emissao \
  -H "Authorization: Token SEU_TOKEN" -H "Content-Type: application/json" \
  -d '{ "serie":"1","cfop":"5102","numero-origem":"PED-1","cliente":"12345678000199",
        "itens":[{"produto":"SKU-001","quantidade":"1","valor-unitario":"10.00"}] }'