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).
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 responde422 MDFE_INACTIVE. - Série e próximo número do MDF-e, padrão série
1e número1. - Assinatura com direito a emitir (mesmo limite mensal de notas)
- Recurso
features.mdfeEmissionhabilitado 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).
# 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 |
|---|---|
ufStart | ide/UFIni |
ufEnd | ide/UFFim |
municipalityStartIbge | ide/infMunCarrega/cMunCarrega |
issueDate | ide/dhEmi |
modal.kind | ide/modal (1 rodoviário) |
modal.rntrc | infModal/rodo/infANTT/RNTRC |
modal.vehicle | infModal/rodo/veicTracao |
modal.trailers[] | infModal/rodo/reboque |
drivers[] / modal.drivers[] | infModal/rodo/condutor |
documents[].cityCode | infDoc/infMunDescarga/cMunDescarga |
documents[].nfeAccessKeys[] | infDoc/infNFe/chNFe |
documents[].cteAccessKeys[] | infDoc/infCTe/chCTe |
documents[].mdfeAccessKeys[] | infDoc/infMDFeTransp/chMDFe |
cargoTotalAmount | tot/vCarga |
cargoQuantity | tot/qCarga |
cargoUnit | tot/cUnid (default KG → 01) |
insurance[] | seg |
predominantProduct | prodPred |
seals[] | lacres |
autXml[] | autXML |
additional | infAdic |
techResponsible | infRespTec |
payments[] | infPag |
| (empresa cadastrada) | emit, enderEmit |