Fiscal v1 · homologação

Manual de integração fiscal

Este guia organiza a jornada de integração para NF-e importadas, CT-e, eventos, CIOT e MDF-e. A referência é a fonte completa de campos, schemas e respostas.

Base fiscalsomente homologação
https://api.fleetpay.site/v1/fiscal
Autorizaçãochave FleetPay + escopo fiscal
Authorization: Bearer SUA_CHAVE_DE_API_FLEETPAY

Este é o único endereço do trilho fiscal: as chamadas autenticam com a credencial gerada no painel de homologação (OAuth2 client_credentials ou chave fp_hml_...) e exigem o escopo fiscal habilitado.

Abrir referência interativaBaixar OpenAPI Fiscal v1
Fluxo recomendado

Da chave à consulta do documento

1. Valide a chave e o ambiente

Use a chave de API da transportadora com o escopo fiscal habilitado. Confirme a conexão em GET /fiscal/status antes de criar documentos.

2. Consulte ou importe as NF-e

Use as rotas de NF-e para localizar documentos importados, iniciar uma importação e consultar uma chave de acesso. A NF-e é a base para montar o CT-e.

3. Monte e emita o CT-e

Crie o rascunho, consulte a prévia, emita e acompanhe a autorização. Depois da emissão, use a consulta, o DACTE e os eventos quando aplicáveis.

4. Execute o ciclo do CIOT

Valide os dados, emita o CIOT vinculado ao CT-e e acompanhe o resultado. O mesmo conjunto cobre cancelamento, retificação e encerramento.

5. Emita e encerre o MDF-e

Crie o MDF-e, informe os condutores, emita, consulte e conclua o ciclo por encerramento ou cancelamento. O DAMDFE fica disponível na mesma jornada.

Primeira chamada

Confirme o status antes de iniciar

A rota de status verifica se a chave, o ambiente e a jornada fiscal estão disponíveis.

bash
curl --request GET https://api.fleetpay.site/v1/fiscal/status \
  --header "Authorization: Bearer SUA_CHAVE_DE_API_FLEETPAY"

Checklist de implementação

  • A chave é uma chave FleetPay válida da transportadora.
  • O escopo fiscal está habilitado para essa chave.
  • A chamada usa exclusivamente o host de homologação.
  • A aplicação armazena o request_id das respostas de erro.
  • Consultas assíncronas respeitam o intervalo indicado pela API.

Para detalhes de payload, códigos de retorno e exemplos de cada operação, use a referência interativa. O arquivo OpenAPI contém as 46 operações do Fiscal v1 para importar no seu cliente de API.

Contra-CT-e

Emissão Subcontratada (Contra-CT-e)

Quando a sua transportadora executa um trecho como subcontratada, ela emite o CT-e dela contra o CT-e da contratante: a contratante entra como tomador (toma4), o CT-e dela é referenciado no grupo infDocAnt — e o preço do frete é o seu, nunca o dela (o valor da contratante viaja só como referência).

core · Fiscal › CT-e › Emissão SubcontratadaEmissão SubcontratadaInformar CT-e da ContratanteCT-e da Contratante5124 0761 7442 8500 0154 5700 0000 0123 4510 0000 0017Tomador: Contratante (toma4)Referência: infDocAntPreço: o Seu1 · RascunhoTrecho e valores seus2 · PréviaValida sem enviar3 · EmissãoAssina o A1 (e-CNPJ) e enviaAutorizadoDACTE · eventos · CIOT (passo separado)R$ 2.500,00

Pelo painel (desktop) — onde o contra-CT-e é emitido

  1. Em Fiscal → CT-e, escolha Emissão Subcontratada e informe o CT-e da contratante: XML, chave de 44 dígitos ou código de barras. O tomador vira a contratante (toma4) e a chave entra no infDocAnt.
  2. Complete o rascunho: o trecho e o preço são seus. O rascunho pode nascer sem NF-e próprias — a carga é descrita pelo CT-e da contratante.
  3. A prévia valida as pendências sem enviar nada; a emissão assina com o certificado A1 (e-CNPJ) da transportadora e envia à Sefaz.
  4. Autorizado: DACTE, eventos e, quando aplicável, o CIOT como passo separado.
App do Motorista1 · Certificado A1certificado.pfxSenha ••••••Enviado — guardado cifrado2 · Escanear CT-e da Contratante5124 0761 7442 8500 0154 57…0017Leitura Registradasó a chave, nada é emitido3 · Parcelas do RepasseBipagemR$ 1.250,00LiberadaConclusão no AppR$ 750,00PendentePrestação de ContasR$ 500,00Pendente

Pelo app do motorista — evidência e parcelas

  1. O motorista envia o certificado A1 dele (arquivo + senha, sobre TLS; guardado cifrado). O A1 do motorista serve à assinatura local — quem assina o contra-CT-e é sempre o e-CNPJ da empresa.
  2. Escaneia o CT-e da contratante: o app envia somente a chave de 44 dígitos. A leitura registra a evidência operacional do trecho — não cria rascunho nem emite documento.
  3. Com o serviço em andamento, as parcelas do repasse liberam pelos eventos reais: a bipagem libera a 1ª, a conclusão no app a 2ª e a prestação de contas a 3ª.

Os dois caminhos se completam: o app registra a evidência e movimenta as parcelas do repasse; o painel importa o CT-e da contratante, monta o rascunho e emite. Não há emissão de documento fiscal pelo aplicativo.

Pré-requisitos por caminho

App do Motorista (Leitura)Painel (Emissão)
AmbienteSomente homologaçãoO ambiente da emissão é o do painel em uso
Trilho fiscalHabilitado para a transportadoraHabilitado para a transportadora
Certificado A1Não exigido para a leiturae-CNPJ da transportadora, vigente, com cadastro fiscal concluído
Quem ageMotorista ativo, com vínculo ativo na transportadoraOperador com permissão fiscal
CIOT—Passo separado, pós-autorização, conforme o perfil do transportador

Próximo passo: consultar os contratos

Use a referência para encontrar a operação desejada e testar o contrato no ambiente de homologação.

Referência da APIFalar com o suporte