Fiscal Contora
Fiscal Contora Infraestrutura fiscal
Documentação / MDF-e v1
Quickstart OpenAPI IA Health
API REST fiscal

MDF-e para manifesto e encerramento operacional, integrado ao ecossistema de transporte da plataforma.

Esta documentação descreve a versão pública atual da API fiscal da Contora, com base compartilhada de empresas, certificados, chaves, filas, webhooks e artefatos para NF-e, NFC-e, NFS-e, CT-e e MDF-e. NF-e, NFC-e e NFS-e operam em produção regular; CT-e e MDF-e em produção assistida e controlada.

Atualizado em .

Status atual

Status da API Homologação Controlada Os endpoints públicos de MDF-e e geração de DAMDFE já estão expostos e operam em homologação controlada, com validação operacional real por viagem; a abertura em produção é gradual.
Superfície técnica O contrato público já cobre MDF-e 3.00 rodoviário com autorização, cancelamento, encerramento, artefatos e PDF, mas a abertura ampla ainda depende de cenários reais de transporte.

Ciclo de Vida do MDF-e

O MDF-e (Manifesto Eletrônico de Documentos Fiscais) é tratado como domínio próprio, conectado ao contexto de transporte da conta. A integração reaproveita empresas, certificados, ambiente, webhook, billing e histórico operacional da API Fiscal Contora.

Leitura prática: nesta etapa, MDF-e deve ser usado primeiro em homologação. Antes de liberar produção real por cliente, valide certificado, UF, cenário de transporte, autorização, cancelamento e encerramento com dados reais de operação.
Formatos de Endpoints Suportados:

• Global / Flat (Recomendado): /api/v1/mdfe/drafts... (a empresa é identificada dinamicamente pelo token de API).
• Hierárquico (Multi-empresa): /api/v1/companies/{company_id}/mdfe/drafts... (caso o token gerencie múltiplos emissores e você queira isolá-los na URL).

1. Criar Rascunho de MDF-e

Envie os dados do manifesto, incluindo UF de início/fim, municípios, documentos vinculados, veículo, condutores e totais de carga:

curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "homologacao",
    "payload": {
      "uf_ini": "MG",
      "uf_fim": "SP",
      "tp_emit": "2",
      "modal": "01",
      "rntrc": "12345678",
      "inf_lotacao": {
        "local_carrega": { "cep": "30140071" },
        "local_descarrega": { "cep": "01001000" }
      },
      "municipios_carregamento": [
        { "codigo": "3106200", "nome": "Belo Horizonte" }
      ],
      "municipios_descarga": [
        {
          "codigo": "3550308",
          "nome": "Sao Paulo",
          "nfe_keys": ["35260700000000000100550010000000011000000010"],
          "cte_keys": []
        }
      ],
      "veiculo": {
        "placa": "AAA1A23",
        "tara_kg": 7000,
        "tipo_rodado": "06",
        "tipo_carroceria": "01",
        "uf_licenciamento": "MG"
      },
      "condutores": [
        { "nome": "Joao da Silva", "cpf": "12345678909" }
      ],
      "produto_predominante": "CARGA GERAL",
      "tipo_carga": "05",
      "valor_carga": 5000.00,
      "unidade_peso": "01",
      "peso_carga": 1000.0
    }
  }' \
  https://fiscal.contora.com.br/api/v1/mdfe/drafts

Se o MDF-e rodoviário tiver apenas um único documento vinculado, envie também inf_lotacao com o local de carga e o local de descarga por CEP ou latitude/longitude.

Para carga própria com NF-e do próprio emitente, use tp_emit = "2". Nesse fluxo, o RNTRC pode ficar ausente e a exigência de inf_lotacao para documento único deixa de ser obrigatória no MVP atual.

2. Gerar XML sem Assinatura

Use este passo para validar estrutura, campos obrigatórios e chave de acesso antes de autorizar:

curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "sign": false }' \
  https://fiscal.contora.com.br/api/v1/mdfe/drafts/{draft_id}/build

3. Enfileirar Autorização

A autorização é processada pela fila fiscal para evitar travar a aplicação integradora quando a SEFAZ estiver lenta ou instável:

curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "action": "authorize" }' \
  https://fiscal.contora.com.br/api/v1/mdfe/drafts/{draft_id}/dispatch

4. Consultar Status e Artefatos

Consulte o estado consolidado do manifesto ou baixe os XMLs e o DAMDFE em PDF quando estiverem disponíveis:

# Consultar status
curl -H "Authorization: Bearer {token}" \
  https://fiscal.contora.com.br/api/v1/mdfe/drafts/{draft_id}/status

# Listar artefatos
curl -H "Authorization: Bearer {token}" \
  https://fiscal.contora.com.br/api/v1/mdfe/drafts/{draft_id}/artifacts

# Baixar XML autorizado, quando disponível
curl -H "Authorization: Bearer {token}" -OJ \
  https://fiscal.contora.com.br/api/v1/mdfe/drafts/{draft_id}/artifacts/xml_authorized

# Baixar DAMDFE em PDF
curl -H "Authorization: Bearer {token}" -OJ \
  https://fiscal.contora.com.br/api/v1/mdfe/drafts/{draft_id}/artifacts/pdf_danfe

5. Cancelamento e Encerramento

O encerramento informa o fim da operação de transporte. O cancelamento exige justificativa conforme regra fiscal aplicável:

# Cancelar MDF-e
curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Cancelamento por erro operacional no manifesto." }' \
  https://fiscal.contora.com.br/api/v1/mdfe/drafts/{draft_id}/cancel

# Encerrar MDF-e
curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "city_code": "3550308", "state_code": "SP", "closed_at": "2026-07-02" }' \
  https://fiscal.contora.com.br/api/v1/mdfe/drafts/{draft_id}/close