Docs/MDF-e

MDF-e — Manifesto Eletrônico de Documentos Fiscais

API-first para emissão, consulta, cancelamento, encerramento e eventos de MDF-e (modelo 58). Não passa por venda nem por invoice de produto/serviço. A emissão é sempre em produção (SEFAZ tpAmb=1).

Ver requisitos de autenticação

Pré-requisitos

  • Certificado digital A1 válido na empresa
  • MDF-e ativo na empresa. Toda empresa nasce com o MDF-e desativado. O MDF-e não aparece no painel: a ativação e a configuração são só pela API, em PATCH /v1/companies/{companyId}/mdfe/settings (veja abaixo). Desativado, a emissão responde 422 MDFE_INACTIVE.
  • Série e próximo número do MDF-e, padrão série 1 e número 1.
  • Assinatura com direito a emitir (mesmo limite mensal de notas)
  • Recurso features.mdfeEmission habilitado na conta

Ativar e configurar pela API

Não há configuração de MDF-e no painel. Use GET para ler e PATCH para ligar, desligar ou ajustar a numeração. Campos ausentes ficam como estão; campo desconhecido responde 422. Só o titular ou um administrador da empresa pode alterar (403 COMPANY_SETTINGS_FORBIDDEN).

Shell
# Ativar e configurar
curl -X PATCH "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/mdfe/settings" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Api-Secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"active": true, "series": 1, "number": 1}'

# Desativar
curl -X PATCH "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/mdfe/settings" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Api-Secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

O próximo número só sobe. Número menor que o atual na mesma série responde 409 MDFE_NUMBER_REGRESSION; para voltar mesmo assim, repita com ?confirmNumber=1. Série nova grava o número informado. Para parar de emitir, envie {"active": false}.

Fluxo assíncrono

POST /v1/companies/{companyId}/mdfe cria o documento e enfileira a transmissão à SEFAZ. A resposta imediata traz status: processing (ou pending se ainda não enfileirado). O desfecho chega por webhook (mdfe.authorized / mdfe.rejected) ou por GET /v1/companies/{companyId}/mdfe/{id}.

Após autorizado, use POST .../close para encerrar o manifesto, POST .../drivers, POST .../documents ou POST .../payments para eventos complementares, e DELETE .../mdfe/{id} para cancelamento (com justificativa).

Idempotência

Informe Idempotency-Key (header) ou externalId no body. A chave é única por empresa na coleção mdfes.

Campos Zod ↔ tag XML

Campo (API)Tag / grupo XSD
ufStartide/UFIni
ufEndide/UFFim
municipalityStartIbgeide/infMunCarrega/cMunCarrega
issueDateide/dhEmi
modal.kindide/modal (1 rodoviário)
modal.rntrcinfModal/rodo/infANTT/RNTRC
modal.vehicleinfModal/rodo/veicTracao
modal.trailers[]infModal/rodo/reboque
drivers[] / modal.drivers[]infModal/rodo/condutor
documents[].cityCodeinfDoc/infMunDescarga/cMunDescarga
documents[].nfeAccessKeys[]infDoc/infNFe/chNFe
documents[].cteAccessKeys[]infDoc/infCTe/chCTe
documents[].mdfeAccessKeys[]infDoc/infMDFeTransp/chMDFe
cargoTotalAmounttot/vCarga
cargoQuantitytot/qCarga
cargoUnittot/cUnid (default KG → 01)
insurance[]seg
predominantProductprodPred
seals[]lacres
autXml[]autXML
additionalinfAdic
techResponsibleinfRespTec
payments[]infPag
(empresa cadastrada)emit, enderEmit