Pular para o conteúdo

Código de Exemplo — Visão geral

Esta seção traz implementações completas e prontas para produção em várias linguagens. Cada exemplo cobre o ciclo completo:

  • Carregamento do Token a partir de variável de ambiente
  • Cliente HTTP centralizado com headers padrão e timeout
  • Idempotência via numero-origem
  • Polling com backoff exponencial
  • Retry em erros transitórios
  • Tratamento de status: "050", "900", "999"
  • Captura do X-Request-Id para logs

Em cada uma das 9 linguagens (cURL, PHP, JavaScript, TypeScript, Python, Java, C#, Go e Ruby), os exemplos cobrem as 81 operações listadas na matriz abaixo: NF-e, NFC-e e NFS-e (emitir, consultar, alterar, cancelar e listar; consulta completa na NF-e e na NFC-e; carta de correção na NF-e), inutilização de numeração, notas de fornecedor (MD-e), XML em lote por período, resumo diário, classificação fiscal, rotinas de NFS-e, certificado digital A1, CIOT, RENAVE, clientes, produtos e status (health check).

Linguagens disponíveis

Padrão dos exemplos

Cada página segue a mesma estrutura:

  1. Setup — instalação de dependências e variáveis de ambiente.
  2. Cliente HTTP centralizado — com captura de X-Request-Id e tratamento de erro.
  3. Helper de polling reutilizável — chamado por todos os cenários assíncronos.
  4. Cenários por documento fiscal:
    • Emitir NFC-e (com polling)
    • Emitir NF-e (com transporte completo, faturas)
    • Emitir NFS-e (Nota Fiscal de Serviço)
    • Cancelar NF-e, NFC-e, NFS-e
    • Lançar carta de correção (CC-e)
    • Inutilizar numeração (NF-e e NFC-e)
    • Reconhecer nota de fornecedor (MD-e)
    • CIOT (emissão e eventos) e RENAVE (registros e cancelamentos)
    • Classificação fiscal, rotinas de NFS-e e certificado digital A1
    • Resumo diário e XML em lote por período
  5. Retry com backoff — apenas em erros transitórios.
  6. Listar com paginação — loop completo.
  7. Tratamento de erros — captura de X-Request-Id e propagação adequada.

Matriz de cobertura (81 operações)

Cada linha é uma operação da Referência da API. A coluna JS/TS vale para JavaScript e TypeScript (mesma página).

NF-e (12)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
GET /nfe — Listar NFes✅✅✅✅✅✅✅✅
GET /nfe/paginacao/{pagina}/{quantidade} — Listar NFes (paginação por path — legado)✅✅✅✅✅✅✅✅
GET /nfe/nota/{recibo} — Consultar NFe pelo recibo✅✅✅✅✅✅✅✅
GET /nfe/nota/{recibo}/completa — Consultar NFe completa pelo recibo✅✅✅✅✅✅✅✅
GET /nfe/correcao/{recibo} — Consultar carta de correção (CC-e) pelo recibo✅✅✅✅✅✅✅✅
GET /nfe/cancelamento/{recibo} — Consultar cancelamento pelo recibo✅✅✅✅✅✅✅✅
POST /nfe/emissao — Emitir NFe✅✅✅✅✅✅✅✅
PUT /nfe/{id} — Alterar NFe não emitida✅✅✅✅✅✅✅✅
POST /nfe/correcao — Lançar carta de correção (CC-e)✅✅✅✅✅✅✅✅
POST /nfe/cancelamento — Cancelar NFe✅✅✅✅✅✅✅✅
POST /nfe/inutilizacao — Inutilizar numeração de NFe✅✅✅✅✅✅✅✅
GET /nfe/inutilizacao/{recibo} — Consultar inutilização de NFe pelo recibo✅✅✅✅✅✅✅✅

NFC-e (10)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
GET /nfce — Listar NFCes✅✅✅✅✅✅✅✅
GET /nfce/paginacao/{pagina}/{quantidade} — Listar NFCes (paginação por path — legado)✅✅✅✅✅✅✅✅
GET /nfce/cupom/{recibo} — Consultar NFCe pelo recibo✅✅✅✅✅✅✅✅
GET /nfce/cupom/{recibo}/completa — Consultar NFCe completa pelo recibo✅✅✅✅✅✅✅✅
GET /nfce/cancelamento/{recibo} — Consultar cancelamento de NFCe pelo recibo✅✅✅✅✅✅✅✅
POST /nfce/emissao — Emitir NFCe✅✅✅✅✅✅✅✅
PUT /nfce/{id} — Alterar NFCe não emitida✅✅✅✅✅✅✅✅
POST /nfce/cancelamento — Cancelar NFCe✅✅✅✅✅✅✅✅
POST /nfce/inutilizacao — Inutilizar numeração de NFCe✅✅✅✅✅✅✅✅
GET /nfce/inutilizacao/{recibo} — Consultar inutilização de NFCe pelo recibo✅✅✅✅✅✅✅✅

NFS-e (6)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
GET /nfse — Listar NFSes✅✅✅✅✅✅✅✅
GET /nfse/nota/{recibo} — Consultar NFSe pelo recibo✅✅✅✅✅✅✅✅
POST /nfse/emissao — Emitir NFSe✅✅✅✅✅✅✅✅
PUT /nfse/{id} — Alterar NFSe não emitida✅✅✅✅✅✅✅✅
POST /nfse/cancelamento — Cancelar NFSe✅✅✅✅✅✅✅✅
POST /nfse/cancelar — Cancelar NFSe (alias legado)✅✅✅✅✅✅✅✅

RENAVE (6)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
POST /renave/nota-fiscal/entrada — Entrada de veículo no estoque (compra)✅✅✅✅✅✅✅✅
POST /renave/nota-fiscal/saida — Saída de veículo do estoque (venda)✅✅✅✅✅✅✅✅
POST /renave/estoque/entrada-veiculo-proprio — Entrada de veículo próprio no estoque✅✅✅✅✅✅✅✅
POST /renave/estoque/cancelamento-entrada — Cancelar entrada no estoque✅✅✅✅✅✅✅✅
POST /renave/estoque/cancelamento-saida — Cancelar saída do estoque✅✅✅✅✅✅✅✅
GET /renave/{recibo} — Consultar operação RENAVE pelo recibo✅✅✅✅✅✅✅✅

CIOT (5)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
POST /ciot/emissao — Emitir CIOT✅✅✅✅✅✅✅✅
POST /ciot/cancelamento — Cancelar CIOT✅✅✅✅✅✅✅✅
POST /ciot/retificacao — Retificar CIOT✅✅✅✅✅✅✅✅
POST /ciot/encerramento — Encerrar CIOT✅✅✅✅✅✅✅✅
GET /ciot/{recibo} — Consultar operação de CIOT pelo recibo✅✅✅✅✅✅✅✅

Classificação fiscal (2)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
POST /classificacao-fiscal — Classificar um produto ou serviço✅✅✅✅✅✅✅✅
POST /classificacao-fiscal/lote — Classificar de 1 a 10 produtos✅✅✅✅✅✅✅✅

Rotinas de NFS-e (16)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
GET /rotinas — Listar as rotinas da empresa✅✅✅✅✅✅✅✅
POST /rotinas — Criar uma rotina✅✅✅✅✅✅✅✅
GET /rotinas/modelos — Modelos de rotina e os campos de cada um✅✅✅✅✅✅✅✅
GET /rotinas/clientes — Buscar cliente para o campo de cliente✅✅✅✅✅✅✅✅
GET /rotinas/servicos — Serviços para o campo de serviço✅✅✅✅✅✅✅✅
POST /rotinas/validar — Conferir uma rotina sem gravar✅✅✅✅✅✅✅✅
GET /rotinas/{id} — Detalhe da rotina✅✅✅✅✅✅✅✅
PUT /rotinas/{id} — Alterar a rotina✅✅✅✅✅✅✅✅
DELETE /rotinas/{id} — Excluir a rotina✅✅✅✅✅✅✅✅
GET /rotinas/{id}/execucoes — Histórico de emissões da rotina✅✅✅✅✅✅✅✅
POST /rotinas/{id}/pausar — Pausar a rotina✅✅✅✅✅✅✅✅
POST /rotinas/{id}/retomar — Retomar a rotina✅✅✅✅✅✅✅✅
POST /rotinas/{id}/emitir-agora — Emitir uma competência agora✅✅✅✅✅✅✅✅
GET /rotinas/{id}/extras — Valores extras da rotina✅✅✅✅✅✅✅✅
PUT /rotinas/{id}/extras/{competencia} — Lançar valor extra em um mês✅✅✅✅✅✅✅✅
DELETE /rotinas/{id}/extras/{competencia} — Remover o valor extra de um mês✅✅✅✅✅✅✅✅

Certificado digital A1 (2)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
GET /certificado — Situação e validade do certificado digital✅✅✅✅✅✅✅✅
POST /certificado/a1 — Instalar (ou trocar) o certificado digital A1✅✅✅✅✅✅✅✅

Relatórios (3)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
GET /resumo — Resumo diário de emissões✅✅✅✅✅✅✅✅
POST /xml/solicitacao — Solicitar XMLs por período✅✅✅✅✅✅✅✅
GET /xml/solicitacao/{protocolo} — Consultar solicitação de XML✅✅✅✅✅✅✅✅

Fornecedor (MD-e) (3)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
GET /nffornecedor — Listar notas de fornecedor✅✅✅✅✅✅✅✅
GET /nffornecedor/{recibo} — Consultar nota de fornecedor pelo recibo✅✅✅✅✅✅✅✅
POST /nffornecedor/reconhecimento — Reconhecer nota de fornecedor✅✅✅✅✅✅✅✅

Clientes (6)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
GET /clientes — Listar clientes✅✅✅✅✅✅✅✅
POST /clientes — Cadastrar cliente✅✅✅✅✅✅✅✅
GET /clientes/{doc} — Consultar cliente por documento (CPF/CNPJ)✅✅✅✅✅✅✅✅
PUT /clientes/{doc} — Atualizar cliente por documento✅✅✅✅✅✅✅✅
DELETE /clientes/{doc} — Excluir cliente por documento✅✅✅✅✅✅✅✅
GET /clientes/busca/{nome} — Buscar cliente por nome✅✅✅✅✅✅✅✅

Produtos (7)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
GET /produtos — Listar produtos✅✅✅✅✅✅✅✅
POST /produtos — Cadastrar produto✅✅✅✅✅✅✅✅
GET /produtos/{ref} — Consultar produto por referência✅✅✅✅✅✅✅✅
PUT /produtos/{ref} — Atualizar produto por referência✅✅✅✅✅✅✅✅
DELETE /produtos/{ref} — Excluir produto por referência✅✅✅✅✅✅✅✅
GET /produtos/nome/{nome} — Buscar produto por nome✅✅✅✅✅✅✅✅
GET /produtos/paginacao/{pagina}/{quantidade}/{busca} — Listar produtos paginado com busca (legado)✅✅✅✅✅✅✅✅

Status (3)

OperaçãocURLJS/TSPythonPHPJavaC#GoRuby
GET /health — Health check✅✅✅✅✅✅✅✅
GET /health/deep — Health check profundo (banco + pool de conexões)✅✅✅✅✅✅✅✅
GET /health/pool — Métricas do pool de conexões✅✅✅✅✅✅✅✅

Infraestrutura e padrões

CenáriocURLJS/TSPythonPHPJavaC#GoRuby
Health check (sem auth)✅✅✅✅✅✅✅✅
Cliente HTTP centralizado✅✅✅✅✅✅✅✅
Helper de polling reutilizável✅✅✅✅✅✅✅✅
Retry com backoff✅✅✅✅✅✅✅✅
Captura X-Request-Id✅✅✅✅✅✅✅✅
Tratamento estruturado de erros✅✅✅✅✅✅✅✅

Variáveis de ambiente comuns

Todos os exemplos esperam:

Terminal window
export MYSE_API_BASE="https://api.mysebr.com.br/nfemyse-v3/rest"
export MYSE_API_TOKEN="seu_token_aqui"