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

Migrar para a v3

O que não muda

  • Fluxo assíncrono: emissão → recibo → polling. Idêntico.
  • Nomes dos campos de payload de emissão (serie, cfop, cliente, itens, numero_origem, transporte, faturas, …). Praticamente iguais.
  • Autenticação: header Authorization: Token SEU_TOKEN. Igual.
  • Idempotência: continue enviando numero_origem (a v3 também aceita numero-origem com hífen).

O que muda

  1. URL base — troque o caminho da v2 pelo da v3:

    Base
    v2https://api.mysebr.com.br/nfemyse/rest
    v3https://api.mysebr.com.br/nfemyse-v3/rest

  2. Envelope de resposta — este é o principal ajuste. A v2 devolve JSON ad-hoc por endpoint; a v3 devolve sempre o mesmo envelope:

    {
      "status": "001",
      "descricao": "Nota registrada com sucesso.",
      "data": { "recibo": "rec_abc123" },
      "meta": { "request_id": "req_...", "timestamp": "..." }
    }

    Adapte seu parser para ler o resultado em data.* (ex.: data.recibo, data.sefaz.chave) e o status em status/descricao. Veja Estrutura de resposta (v3) e Códigos de status (v3).

  3. Erros unificados — na v3, erros de negócio e de framework usam o mesmo envelope (status/descricao + data.erro), em vez da mistura erro/error da v2.

  4. Aproveite os novos recursos (opcional, mas recomendado):

    • meta.request_id e header X-Request-Id — guarde-os nos seus logs; agilizam muito o suporte.
    • Headers X-RateLimit-* — para se auto-regular antes de tomar 429.
    • Paginação por query string ?page=&page_size= — mais simples que o path.
    • /nffornecedor — reconhecimento de nota de fornecedor (novo).
    • NFSe completa — listagem, consulta, edição e cancelamento (na v2 só havia emissão).

Checklist de migração

  • Trocar a base …/nfemyse/rest → …/nfemyse-v3/rest.
  • Adaptar o parser de resposta para o envelope { status, descricao, data, meta }.
  • Ler o recibo em data.recibo (era recibo na raiz).
  • Ler o resultado da SEFAZ em data.sefaz.*.
  • Unificar o tratamento de erro para data.erro + status.
  • (Recomendado) Persistir meta.request_id nos logs.
  • (Recomendado) Monitorar X-RateLimit-Remaining.
  • Testar emissão, consulta por recibo, cancelamento e listagens na v3.

Próximos passos