Pular para o conteúdo

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 (menos /health*) -> Authorization: Token <TOKEN_DA_EMPRESA>
(Token é o formato canônico; "Bearer <TOKEN>" é aceito como alias tolerado).
- 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": "...", "api_version": "3.20.0" } }
- Guarde meta.request_id (e o header X-Request-Id) nos seus logs — agiliza o suporte.
- meta.api_version / header X-API-Version = versao SemVer da API (MAJOR no path: v3).
Campo novo em meta ou data NAO e erro: o contrato e aditivo, ignore chave desconhecida.
- 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 sem-notas | 007 falha: só na consulta de XML em lote (GET /xml/solicitacao/{protocolo}), 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} (não emitida) |
POST /nfe/cancelamento {chave, motivo(15-255)} -> GET /nfe/cancelamento/{recibo} |
POST /nfe/correcao {chave, motivo(15-1000)} -> GET /nfe/correcao/{recibo} |
GET /nfe (lista, ?page&page_size) | GET /nfe/paginacao/{pagina}/{quantidade} (legado) |
POST /nfe/inutilizacao -> GET /nfe/inutilizacao/{recibo}
- NFCe: POST /nfce/emissao | GET /nfce/cupom/{recibo}[/completa] | PUT /nfce/{id} (não emitida) |
POST /nfce/cancelamento {chave, motivo(15-255)} -> GET /nfce/cancelamento/{recibo} |
GET /nfce (lista, ?page&page_size) | GET /nfce/paginacao/{pagina}/{quantidade} (legado) |
POST /nfce/inutilizacao -> GET /nfce/inutilizacao/{recibo}
- inutilizacao (NFe/NFCe, assíncrona): {serie, numero-inicial, numero-final, justificativa(15-255),
ano?(AA ou AAAA)} -> recibo; consulta 004 homologada (sefaz.codigo 102) | 900 SEFAZ recusou
| 002 na fila. Recusa na hora (400): nota autorizada/em processamento na faixa, faixa já
inutilizada ou já na fila, certificado A3, emitente sem CNPJ.
- NFSe: POST /nfse/emissao | GET /nfse/nota/{recibo} | PUT /nfse/{id} (não emitida) |
GET /nfse (lista, ?page&page_size) | POST /nfse/cancelamento {chave, motivo(15-255)}
(POST /nfse/cancelar = alias legado do mesmo handler)
- CIOT (ANTT, ETC frota própria, TipoOperacao 1 lotação | 2 fracionada): POST /ciot/emissao
(campos do leiaute PEF: CpfCnpjContratante, CpfCnpjDestinatario, ValorFrete, Veiculos[1],
OrigemDestino[], DadosCarga, InfPagamento[], InfIndicadoresOperacionais na lotação; NÃO enviar
CpfCnpjContratado/RNTRCContratado/IdOperacaoTransporte) | POST /ciot/cancelamento {ciot|recibo, motivo}
| POST /ciot/retificacao {ciot|recibo, ValorFrete?...} (só fracionada) | POST /ciot/encerramento
{ciot|recibo} -> recibo; GET /ciot/{recibo}: 004 emitido (data.ciot, codigo-verificador, protocolo)
| 010 cancelado | 900 recusado | 002 na fila. Exige certificado A1 e RNTRC da ETC no cadastro.
- CT-e (57) / CT-e OS (67), MDF-e (58), BP-e (63) — 3.21.0, assíncronos como a NF-e: POST -> 001 recibo;
GET /cte/{recibo} | /cte-os/{recibo} | /mdfe/{recibo} | /bpe/{recibo}: 002/003 fila | 004 autorizado
(chave, protocolo) ou evento registrado | 010 cancelado | 900 recusado (c-stat, x-motivo; corrigir e
reenviar com o MESMO numero-origem) | 999 técnico/indeterminado (reenviar o mesmo pedido; o documento
já numerado é consultado na SEFAZ antes, nunca duplica) | 500 recibo inexistente/de outra empresa/outro
modelo. numero-origem obrigatório na emissão. Eventos aceitam chave ou recibo da emissão (protocolo e
sequência resolvidos pela API). Contrato completo de cada rota: guias emitir-cte, emitir-mdfe,
emitir-bpe e a referência OpenAPI. MDF-e montado pelo corpo (veículo por placa, condutor por CPF,
municípios por IBGE, documentos por chave). Exige certificado A1.
- RENAVE (estoque de veículos, SERPRO): POST /renave/nota-fiscal/entrada {chaveNFe, cpfOperadorResponsavel,
dataCompra, valorCompra, emailVendedor, veiculo{placa,numeroCrv,renavam,...}} | POST
/renave/nota-fiscal/saida {... dataVenda, valorVenda, comprador{nome,email,endereco{...}}} | POST
/renave/estoque/entrada-veiculo-proprio | POST /renave/estoque/cancelamento-entrada|cancelamento-saida
{id-renave|recibo} -> recibo; GET /renave/{recibo}: 004 registrado (data.id-renave) | 010 cancelado
| 900 recusado (data.mensagem) | 999 técnico (reenviar o mesmo pedido reaproveita o registro).
- nffornecedor: POST /nffornecedor/reconhecimento | GET /nffornecedor/{recibo} |
GET /nffornecedor (lista, ?page&page_size)
- clientes: GET/POST /clientes | GET/PUT/DELETE /clientes/{doc} | GET /clientes/busca/{nome}
- produtos: GET/POST /produtos | GET/PUT/DELETE /produtos/{ref} | GET /produtos/nome/{nome} |
GET /produtos/paginacao/{pagina}/{quantidade}/{busca} (legado)
- 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.
- classificação fiscal (SÍNCRONA, sem recibo; só consulta, não grava nada; 3.16.0):
POST /classificacao-fiscal {nome (obrig., até 150), natureza?(mercadoria|servico),
descricao?, ncm?(8 díg., só mercadoria), item-lc116?(1.07, só serviço), nbs?(9 díg.),
documento?(nfe|nfce|nfse), operacao?, finalidade?, destinatario?, destino?
(interna|interestadual|exterior), data-referencia?(AAAA-MM-DD), respostas?{id:valor},
referencia?} -> 005 data.pacote (snake_case: identidade, icms|iss, pis_cofins, ipi,
ibs_cbs, imposto_seletivo, simples, perguntas_pendentes[], validacao.achados[],
metadados). Cada campo: {valor, fundamento, fonte, confianca, requer_revisao?}.
perguntas_pendentes -> reenviar o MESMO produto com respostas {id: valor}.
POST /classificacao-fiscal/lote {produtos:[...1 a 10]} -> 005 data{total, sucesso,
falhas, resultados[{indice, referencia?, status, descricao, pacote?|campo?}]}.
400 formato/recusa (data.campo) | 999 indisponível (tentar de novo). Empresa (CRT/UF)
vem da chave. Informar ncm acelera. Sugestão: conferir com contador (CRC).
- rotinas (NFS-e que se emite sozinha na agenda; 3.17.0; chave com permissão FISCAL; empresa da chave):
GET /rotinas | GET /rotinas/modelos (codigo, parametros[{nome, rotulo, tipo, obrigatorio,
ajuda?, depende-de?, depende-valor?, opcoes?}]) | GET /rotinas/clientes?busca= (2 a 60) |
GET /rotinas/servicos | POST /rotinas/validar -> 005 {pode-ativar, pendencias[]} |
POST /rotinas {modelo (NFSE_RECORRENTE|NFSE_ALUGUEL|NFSE_CONDOMINIO), nome, periodicidade?
(mensal|bimestral|trimestral|semestral|anual), dia (1-31), inicio (AAAA-MM-DD), fim?,
ativar? (padrão true; false = rascunho), parametros {id_clifor, id_produto, vl_servico...}}
| GET/PUT/DELETE /rotinas/{id} (PUT parcial nos parametros; modelo não muda; ativar
padrão true, mas false em rotina PAUSADA, que não religa; ativar=false em ATIVA = 400)
| GET /rotinas/{id}/execucoes | POST /rotinas/{id}/pausar |
/retomar | /emitir-agora {competencia?: AAAA-MM, vazio = mês atual} -> 001 {numero-origem
ROT-<id>-<AAAA-MM>} | GET /rotinas/{id}/extras | PUT|DELETE /rotinas/{id}/extras/{AAAA-MM}
{valor, motivo}. Chaves em kebab-case, MENOS dentro de parametros/rotulos (nomes do modelo,
snake_case). Valores: 3500.5 ou "3.500,50". situacao: ativa|rascunho|pausada|
pausada_por_falha|encerrada. Detalhe traz pendencias[], diagnostico (texto) e execucoes
[{competencia, situacao E|F|P|C, recibo, retorno}]; desfecho da nota em GET
/nfse/nota/{recibo}. Agenda: emite às 08:00 (cron a cada 15 min); 29-31 = último dia;
1ª emissão sempre no futuro (mês atual: emitir-agora); falha re-tenta no dia seguinte, 3ª
seguida pausa; competência emitida não repete. 005 leitura | 001 gravação/ação | 400
(data.campo, data.pendencias) | 500 rotina não encontrada | 999 interno.
- certificado digital (SÍNCRONO, sem recibo; 3.20.0; empresa da chave):
GET /certificado -> 005 {tipo A1|A3, titular, cnpj, dt-validade, dias-para-vencer,
situacao VALIDO|A_VENCER|VENCIDO|NAO_INSTALADO|INDISPONIVEL, instalado} |
POST /certificado/a1 {arquivo (o .pfx em base64, até 50 KB), senha} -> 001 {tipo,
titular, documento, tipo-documento CNPJ|CPF, valido-ate (= dt-validade), dias-para-vencer, situacao}:
já em uso na próxima emissão. Confere senha, chave privada, ICP-Brasil, validade,
titular (mesma raiz de CNPJ ou mesmo CPF da empresa) e não troca certificado válido por
um que vence antes. 400 (data.campo arquivo|senha; descricao diz o motivo) | 999 interno
ou limite por minuto. Só campos arquivo e senha. Nunca logar a senha nem o arquivo.
- status (sem token): GET /health | GET /health/deep (banco + pool) | GET /health/pool (métricas)
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"}] }'