O manifesto e os documentos da viagem
O MDF-e reúne informações dos documentos fiscais transportados e da operação de transporte. Ele não substitui a NF-e da mercadoria nem o CT-e da prestação de serviço. A obrigatoriedade e o preenchimento dependem da operação; valide com a equipe fiscal os documentos que devem acompanhar a carga e a habilitação do estabelecimento.
Na integração, confira o tipo de emitente, as UFs e os municípios de carregamento e descarregamento, o veículo de tração, o condutor e os documentos referenciados. Os demais grupos do modal rodoviário, como informações de contratação e pagamento, devem ser preenchidos quando exigidos pela operação e pelo schema vigente. O OpenAPI detalha os campos aceitos; os dados de exemplo são fictícios.
- Use documentos referenciados e cadastros que pertençam à operação e ao contexto autorizado.
- Confira o trajeto, os municípios e os dados de veículo e condutor antes da transmissão.
- Use uma referência externa estável e a mesma chave de idempotência para repetir a mesma solicitação.
- Mantenha um fluxo de conferência para autorização, início da viagem e encerramento fiscal.
Encerrar não é cancelar o MDF-e
Encerramento e cancelamento possuem finalidades distintas. Quando a operação termina, o encerramento informa o término do manifesto conforme as condições do Fisco. O cancelamento desfaz um documento nas hipóteses em que isso é permitido. A sua aplicação precisa tratar cada ação separadamente e acompanhar o protocolo do evento.
O endpoint de encerramento recebe os dados exigidos no contrato e gera uma operação acompanhável; sua chamada não deve ser confundida com uma baixa financeira ou uma entrada de estoque. Se houver timeout, consulte o processamento existente antes de pedir outro evento. Não considere o manifesto encerrado apenas porque a requisição HTTP foi aceita.
A API desta entrega atende o modal rodoviário e oferece emissão, consulta, cancelamento e encerramento. Os outros eventos ou modalidades que constem nos manuais nacionais não se tornam parte do produto automaticamente. Consulte as capacidades do emitente e o contrato publicado; os requisitos de homologação e habilitação continuam aplicáveis.
Exemplo de requisição em homologação
POST https://erp.fideflow.com.br/api/flow-fiscal/v1/homologacao/emitentes/{emitente}/documentos/mdfe
Authorization: Bearer {credencial_de_homologacao}
Content-Type: application/json
Idempotency-Key: exemplo-mdfe-001
{
"referencia_externa": "exemplo-mdfe-001",
"dados": {
"cabecalho": {
"uf_inicio": "SP",
"uf_fim": "SP",
"veiculo_tracao_id": 1,
"cnpj_contratante": "11222333000181",
"condutor_nome": "Condutor",
"condutor_cpf": "52998224725",
"valor_carga": "10.00",
"quantidade_carga": "1.00",
"cep_carrega": "01001000",
"cep_descarrega": "01001000",
"produto_pred_nome": "Mercadoria",
"produto_pred_ncm": "19059090",
"tp_carga": "05",
"tp_emit": 1
},
"municipiosCarregamento": [
{
"cidade_id": 1
}
],
"infoDescarga": [
{
"cidade_id": 1,
"nfe": {
"chave": "35261011222333000181550010000000011000000012"
}
}
]
}
}Exemplo extraído do OpenAPI v1, com IDs e valores fictícios. Substitua os cadastros pelos do emitente e acompanhe o resultado após HTTP 202.
Contrato, credencial e processamento
Abra o painel API de emissão do Flow Fiscal para configurar os CNPJs, criar os vínculos e gerar uma credencial de homologação. O cadastro de uma empresa já existente exige autorização do titular; informar um CNPJ na chamada não concede acesso a ele. Software houses podem trabalhar com vários clientes sob uma contratação, mantendo credenciais, documentos e permissões separados.
A integração usa Bearer com validade, ambiente e escopos específicos. Cada comando com efeito leva uma Idempotency-Key e uma referencia_externa estável. HTTP 202 confirma que a operação foi aceita para processamento; o cliente acompanha o identificador retornado por consulta ou webhook. Em caso de falha de rede, consulte a referência existente antes de tentar transmitir novamente.
O guia de integração reúne o endereço base, OpenAPI, Postman, exemplos e a sequência de configuração. IDs de clientes, veículos, cidades e demais cadastros precisam existir no contexto autorizado; exemplos não copiam dados reais e não representam uma operação pronta para transmissão em produção.
XML, PDF e consumo compartilhado
Depois da autorização comprovada, o acervo privado reúne o XML fiscal e o documento auxiliar em PDF. Eventos preservam seus próprios protocolos e arquivos. O integrador consulta o resultado e baixa os artefatos com a credencial e os vínculos autorizados; os arquivos não são publicados como links abertos. Uma falha na geração do PDF não deve provocar uma nova emissão.
O opcional de emissão custa R$ 29,90 por mês além do plano Flow Fiscal. A franquia é de 300 documentos autorizados em produção por contratante no ciclo mensal, compartilhada entre os seus CNPJs. Cada autorização excedente custa R$ 0,50 e entra automaticamente na cobrança. Cancelar depois da autorização não devolve a unidade; rejeições, homologação, consultas, downloads, eventos e reentregas não consomem a franquia.
A emissão registra o documento fiscal sem movimentar contas a receber, contas a pagar ou estoque automaticamente. Uma integração adicional com essas áreas depende de uma ação explícita. O opcional anterior de API de documentos recebidos continua independente: baixar os arquivos da própria emissão não exige contratar a API de recebidos.
Perguntas frequentes sobre a API de MDF-e
O MDF-e substitui a NF-e ou o CT-e?
Não. O manifesto referencia os documentos transportados e reúne dados da viagem; NF-e e CT-e mantêm suas finalidades e contratos próprios.
Posso encerrar o MDF-e pela API?
Sim, com a permissão correspondente, dados válidos e observância das condições fiscais. Acompanhe a operação e o protocolo para confirmar o encerramento.
O encerramento gera uma cobrança de documento?
Não. O consumo é gerado pela autorização do MDF-e em produção pela API. Consultas, downloads, cancelamento e encerramento não acrescentam unidades.
Fontes oficiais
No teste grátis do Flow Fiscal, a API de emissão vem completa, sem contratar; depois do teste, requer plano Flow Fiscal ativo e o opcional de emissão contratado. Exige certificado A1 válido e vínculo autorizado de cada CNPJ. CT-e, CT-e OS e MDF-e atendem o modal rodoviário; NFS-e segue o padrão nacional e os requisitos do município. Consulte as capacidades do emitente antes de transmitir.