Quando usar o modelo 67
O CT-e OS documenta outros serviços de transporte previstos nas regras do modelo 67. O enquadramento da prestação, do tomador e da tributação deve ser validado com a contabilidade antes de transmitir. O modelo 67 não é uma alternativa genérica ao modelo 57 para qualquer frete: o CT-e de carga possui outra finalidade e outro contrato.
O conector desta API atende o modal rodoviário. Configure as inscrições, o regime tributário, a série, o veículo e o certificado A1 do estabelecimento autorizado. Confira os municípios de início e fim e a descrição do serviço, além dos dados do tomador. Campos e grupos obrigatórios variam conforme a prestação; o schema versionado define o que pode ser enviado.
- Habilitação do estabelecimento para emitir CT-e OS e certificado A1 compatível.
- Série e numeração próprias do emitente, sem reaproveitar número já autorizado.
- Tomador e veículo vinculados ao contexto autorizado; dados da viagem e tributação conferidos.
- Ambiente de homologação para validar a operação antes de usar a credencial de produção.
Consulta, cancelamento e correção
A API permite consultar o resultado, solicitar cancelamento e registrar carta de correção quando o documento e a regra fiscal permitem. Cada evento tem sua própria operação e protocolo. O aceite do pedido não prova que a SEFAZ aceitou o evento: acompanhe o processamento até o resultado final e preserve a referência.
A carta de correção não substitui um novo documento quando a alteração é vedada pelas regras fiscais. O cancelamento depende da situação e das condições legais aplicáveis, não apenas de um prazo contado pelo integrador. Esta API não oferece inutilização para CT-e OS nem habilita automaticamente contingência, modais adicionais ou todos os eventos descritos no manual nacional.
Exemplo de requisição em homologação
POST https://erp.fideflow.com.br/api/flow-fiscal/v1/homologacao/emitentes/{emitente}/documentos/cte-os
Authorization: Bearer {credencial_de_homologacao}
Content-Type: application/json
Idempotency-Key: exemplo-cte-os-001
{
"referencia_externa": "exemplo-cte-os-001",
"dados": {
"cabecalho": {
"natureza_id": 1,
"municipio_envio": 1,
"municipio_inicio": 1,
"municipio_fim": 1,
"valor_transporte": "10.00",
"valor_receber": "10.00",
"cst": "90",
"perc_icms": "0.00",
"cfop": "5352",
"veiculo_id": 1,
"tomador_id": 1,
"descricao_servico": "Transporte de pessoas",
"quantidade_carga": "1.00",
"data_viagem": "2026-10-21",
"horario_viagem": "12:00"
}
}
}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 CT-e OS
CT-e OS e CT-e usam o mesmo endpoint?
Não. Os contratos são separados: documentos/cte-os para o modelo 67 e documentos/cte para o modelo 57, sob o mesmo ambiente e emitente autorizado.
O que recebo após enviar um CT-e OS?
O aceite HTTP 202 e os identificadores para acompanhar o processamento. O XML e o DACTE OS ficam disponíveis após a autorização comprovada.
CT-e OS cancelado volta para a franquia?
Não. A autorização em produção consome uma unidade; cancelamento posterior não estorna o consumo.
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.