{"openapi":"3.1.0","info":{"title":"API FleetPay","version":"1.0.0","description":"API pública FleetPay para cadastros, consultas, parcelas de repasse e o trilho Fiscal v1.\n\n## Recursos\n\n| Área | Operações públicas |\n|---|---|\n| **Cadastros** | convite de transportadora, consulta de agregados e conferência de chave PIX |\n| **Parcelas** | consulta, liberação e ordem de pagamento das parcelas de repasse ao motorista |\n| **Consultas** | situação do RNTRC e da frota do transportador na ANTT |\n| **API Fiscal v1** | configuração, certificado digital, NF-e, CT-e, eventos, CIOT, veículos, motoristas e MDF-e |\n\n## Ambientes\n\nA API é servida em dois ambientes, com credencial própria em cada um:\n\n- **Homologação** — `https://api.fleetpay.site/v1`\n- **Produção** — `https://api.fleetpay.tech/v1`\n\n## Autenticação\n\nDuas formas, e as duas valem nos **dois ambientes**. Em ambas a credencial entra no\nheader `Authorization: Bearer`:\n\n1. **Chave de API estática.** `fp_hml_...` em homologação, `fp_prd_...` em produção, gerada\n   no painel em **Configurações → API de Integração**. É o caminho mais curto para integrar.\n2. **OAuth2 `client_credentials`.** `POST /oauth/token` no host do ambiente (fora do `/v1`)\n   com `grant_type=client_credentials`, `client_id` e `client_secret`; o secret é mostrado\n   uma única vez. O access token é um JWT que expira em 1 hora e não tem refresh — quando\n   expirar, emita outro.\n\nA API distingue as duas pela **forma** do token: um JWT tem três segmentos separados por\nponto, a chave estática não tem nenhum. Não existe header extra para escolher.\n\nA credencial é **por ambiente**: a de homologação não funciona em produção e vice-versa —\na recusa é um `401` dirigido, que indica o ambiente esperado.\n\n## Autorização — escopos do painel\n\nA credencial nasce **sem acesso**. O que ela pode chamar é decidido pelos escopos\nhabilitados no painel, e isso vale para as duas formas de autenticação:\n\n- **fiscal** — trilho fiscal (`/fiscal/*`); exclusivo de transportadora.\n- **operacao** — liberar e pagar parcelas de repasse — o ato que move dinheiro.\n- **cadastros** — convite de transportadora, consulta de agregados e conferência de chave PIX.\n- **consultas** — consulta de RNTRC.\n\nChamada fora do escopo habilitado responde `403` com\n`error.code: \"escopo_nao_habilitado\"`.\n\n## Operações simuladas em homologação\n\nNem toda operação tem provedor real por trás em homologação. As de baixo respondem em **modo\nsimulado**: a resposta é gerada pela FleetPay, é plausível, é determinística — o mesmo pedido\ndevolve sempre o mesmo resultado — e **não tem efeito regulatório**.\n\n| Área | Operações |\n|---|---|\n| **CIOT** | validação, emissão, consulta, cancelamento, retificação e encerramento em `/fiscal/cte/{cte_uuid}/ciot/*` |\n| **Consultas ANTT** | `GET /consultas/rntrc` e `GET /consultas/frota` |\n\nO que isso significa para quem integra:\n\n- **O contrato é o definitivo.** Request, response e códigos de erro destas operações são os\n  de produção. Integre agora; não há retrabalho previsto.\n- **O comportamento é simulado.** Nada é registrado na ANTT: nenhum CIOT tratado aqui tem\n  valor legal e nenhuma consulta reflete o cadastro real do transportador.\n- **A troca pelo provedor real não muda o contrato.** Quando ele entrar, o mesmo pedido passa\n  a devolver dado real, no mesmo formato.\n- **Há sentinelas para exercitar falha.** Cada operação de consulta documenta os valores que\n  forçam registro inativo, placa fora da frota ou situação inconclusiva — é como você testa o\n  caminho de erro sem depender do acaso.\n- **A resposta se identifica como simulada.** Em `GET /consultas/rntrc` a `razao_social` não\n  é a real — vem `TRANSPORTES SIMULADOS HML LTDA` para CNPJ e `TRANSPORTADOR AUTONOMO\n  SIMULADO` para CPF; em `GET /consultas/frota` cada placa vem com `verificacao: \"simulada\"`.\n- **Em produção elas não simulam — elas recusam.** Estas mesmas operações, chamadas em\n  `https://api.fleetpay.tech/v1`, respondem erro de provedor indisponível enquanto não\n  houver provedor contratado. É deliberado: dado inventado servido como real seria pior\n  que a recusa. Só o que está nesta tabela se comporta assim.\n\nO trilho fiscal é outra história: **CT-e e MDF-e passam por integração fiscal real** no\nambiente de homologação do provedor fiscal — emissão, consulta, XML, documento auxiliar,\ncancelamento, carta de correção, encerramento e inclusão de condutor.\n\n## API Fiscal v1\n\nO trilho em `/fiscal` responde nos **dois ambientes**, cada um na sua base:\n`https://api.fleetpay.site/v1` e `https://api.fleetpay.tech/v1`. A diferença não é de\ncontrato, é de consequência: **em produção o documento emitido é documento fiscal real,\ncom valor legal**; em homologação, não.\n\nToda resposta do trilho carrega o campo `environment` (`homologacao` ou `producao`). É o\nque confirma, na própria resposta, contra qual ambiente o documento saiu — confira-o antes\nde tratar uma emissão como definitiva.\n\nCT-e e MDF-e usam UUID público; NF-e usa chave de acesso de 44 dígitos; veículos e\nmotoristas usam ID inteiro; eventos de CT-e usam uma chave opaca.\n\nUse uma credencial de transportadora ativa com o escopo `fiscal` habilitado; não envie\nCNPJ ou credenciais adicionais. O contrato detalhado, exemplos e regras de polling\nestão em `FISCAL_API_V1.md`. Credencial ausente ou inválida responde `401`; escopo\ndesabilitado ou credencial que não representa transportadora responde `403`; o limite\npor transportadora responde `429` com `Retry-After`.\n","contact":{"name":"Suporte FleetPay","email":"suporte@fleetpay.tech","url":"https://fleetpay.tech"},"license":{"name":"Proprietary — FleetPay LLC","url":"https://fleetpay.tech"}},"servers":[{"url":"https://api.fleetpay.site/v1","description":"Homologação"},{"url":"https://api.fleetpay.tech/v1","description":"Produção"}],"security":[{"oauth2":[]},{"chaveApi":[]}],"tags":[{"name":"Convites","description":"Convite de transportadora para o fluxo de cadastro FleetPay."},{"name":"Agregados","description":"Consulta de agregados vinculados à empresa autenticada e conferência da chave PIX de cada um."},{"name":"Consultas","description":"Consulta da situação do RNTRC e da frota de um transportador na ANTT. Exige o escopo\n`consultas`.\n\nEm homologação estas consultas respondem em **modo simulado**, sem provedor contratado por\ntrás e sem efeito regulatório — o contrato, esse, já é o definitivo. Cada operação\ndocumenta os valores sentinela que forçam resposta de falha.\n"},{"name":"Serviço","description":"Diagnóstico, catálogos e painel da API Fiscal v1."},{"name":"Configuração","description":"Dados fiscais e certificado digital A1 da transportadora."},{"name":"NF-e","description":"Entrada e consulta de NF-e pela chave de acesso."},{"name":"CT-e emitidos","description":"Os CT-e que a SUA transportadora emitiu e traz para a FleetPay. É por aqui que o documento\nentra no fluxo operacional e financeiro — serviço, entrega e recebível.\n\nÉ a alternativa a depender de um parceiro de armazenamento de XML: quem entrega é o seu\nsistema, autenticado pela sua credencial.\n"},{"name":"CT-e de subcontratação","description":"A caixa de entrada dos CT-e de **outras empresas** — e a emissão do contra-CT-e a partir\ndeles, um a um (`POST /fiscal/cte/contra`) ou em lote (`POST /fiscal/cte-subcontratacao/lote`,\n1:1 ou em pernas). Quem emite o contra-CT-e é sempre a **subcontratada**: a contratante entra\ncomo tomadora (`toma4`) e o CT-e dela vai no `infDocAnt`.\n\nO repasse ao motorista dos contra-CT-e segue a regra de parcelas do lote (a mesma do CIOT) e\né consultado, liberado e pago pela aba **Parcelas** — pelo `counter_cte_id`, pela chave ou\npelo MDF-e.\n"},{"name":"CT-e","description":"Rascunho, prévia, emissão, consulta e documento auxiliar de CT-e."},{"name":"Eventos CT-e","description":"Cancelamento, carta de correção, comprovante de entrega e reconciliação."},{"name":"CIOT","description":"Ciclo de vida do CIOT vinculado ao UUID público do CT-e.\n\nEm homologação estas operações respondem em **modo simulado**, sem provedor contratado por\ntrás e sem efeito regulatório: nada é registrado na ANTT e nenhum CIOT tratado por aqui tem\nvalor legal. O contrato, esse, já é o definitivo.\n"},{"name":"Veículos","description":"Frota da transportadora e seus dados fiscais."},{"name":"Motoristas","description":"Motoristas da transportadora e seus perfis fiscais."},{"name":"MDF-e","description":"Rascunho, emissão, consulta, eventos e documento auxiliar de MDF-e."},{"name":"Regras de tributação","description":"Regras de ICMS (e IBS/CBS) por rota UF → UF e, opcionalmente, por tipo de serviço (`tp_serv`:\nsubcontratação, redespacho…) que alimentam a emissão do CT-e — inclusive o contra-CT-e, que\nexige regra aplicável à rota do trecho. Mesmo cadastro da tela do painel.\n"},{"name":"Parcelas","description":"Parcelas do **repasse ao motorista**: consulta, liberação e ordem de pagamento.\n\n## Credencial e escopo\n\nEstas operações usam a mesma credencial de integração dos demais grupos (OAuth2 ou\nchave de API) e exigem o escopo **`operacao`** habilitado no painel — é o escopo do\nato que move dinheiro. Sem credencial, `401`; com credencial mas sem o escopo, `403`.\n\n## Modo automático × modo manual\n\nA regra de repasse do motorista tem um **modo de liberação**, e ele decide quais destas\nchamadas você precisa:\n\n- **Automático** — bipagem e conclusão no app liberam as parcelas, e o pagamento segue\n  sozinho. `liberar` serve só como destravamento de parcela presa; `pagar` não se aplica.\n- **Manual** — nenhum evento interno libera. Você chama `liberar` quando o evento acontece\n  no *seu* sistema, e depois `pagar` quando decidir pagar. **São dois atos**: liberar deixa\n  a parcela apta; pagar é que a coloca na fila.\n\n## Em lote, pelo MDF-e\n\n`liberar-por-mdfe` e `pagar-por-mdfe` aplicam o mesmo ato a **todos os CT-e de um manifesto**\ne devolvem um resultado por CT-e — o atalho para lotes de contra-CT-e, em que cada documento\ntem uma parcela na posição do seu bucket. Só tocam parcelas que já existem e só as do condutor\ndo MDF-e.\n\n## Contra-CT-e\n\nPara contra-CT-e o `documento` pode ser o `counter_cte_id` devolvido pelo lote, o\n`documento_financeiro` da perna (`ROUTE:...`) ou a chave do contra-CT-e autorizado.\n"},{"name":"Vale-Pedágio (VPO)","description":"Roteirização de praças de pedágio, cálculo de tarifas, compra e emissão do Vale-Pedágio Obrigatório\n(ANTT) com débito em Conta Operacional Swap, obtenção de recibos e cancelamento regulamentar em até 3 horas.\n\n## Credencial e escopo\n\nEstas operações usam a mesma credencial de integração dos demais grupos (OAuth2 `client_credentials`\nou chave de API `Authorization: Bearer`) e exigem o escopo **`operacao`** habilitado no painel FleetPay.\nSem a credencial, a resposta é `401`; com a credencial mas sem o escopo, a resposta é `403`.\n\n## Débito e Conta Operacional\n\nA compra do Vale-Pedágio realiza o débito instantâneo do valor do pedágio e da taxa de emissão\ndiretamente no saldo da Conta Operacional Swap da empresa. Em caso de cancelamento aprovado, o estorno\nintegral do pedágio e da tarifa é creditado automaticamente na conta.\n\n## Regra estrita de cancelamento (3 horas)\n\nO cancelamento via API (`POST /vale-pedagio/{uuid}/cancelar`) é permitido **estritamente dentro da janela regulamentar de até 3 horas**\napós a emissão e antes da primeira passagem na praça de pedágio pela operadora (Sem Parar / parceiras).\nCancelamentos após este prazo ou após utilização são rejeitados com código `422` por impedimento regulamentar da ANTT.\n"}],"paths":{"/fiscal/status":{"get":{"tags":["Serviço"],"summary":"Verificar acesso e prontidão fiscal","operationId":"getFiscalStatus","responses":{"200":{"$ref":"#/components/responses/StatusOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/configuracao":{"get":{"tags":["Configuração"],"summary":"Consultar configuração fiscal da transportadora","operationId":"getFiscalConfiguration","responses":{"200":{"$ref":"#/components/responses/FiscalConfigurationOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"put":{"tags":["Configuração"],"summary":"Atualizar configuração fiscal da transportadora","description":"Atualiza somente os campos informados. Envie null para limpar um campo opcional.","operationId":"updateFiscalConfiguration","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiscalConfigurationUpdate"}}}},"responses":{"200":{"$ref":"#/components/responses/FiscalConfigurationOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/certificado":{"get":{"tags":["Configuração"],"summary":"Consultar metadados do certificado digital","description":"Nunca devolve o arquivo nem a senha do certificado.","operationId":"getFiscalCertificate","responses":{"200":{"$ref":"#/components/responses/CertificateOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["Configuração"],"summary":"Enviar certificado digital A1","description":"Envia ou substitui o certificado digital da transportadora.","operationId":"uploadFiscalCertificate","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","cert_pass"],"properties":{"file":{"type":"string","format":"binary","description":"Certificado A1 em .pfx ou .p12, com no máximo 10 MB."},"cert_pass":{"type":"string","format":"password","description":"Senha do certificado; nunca é devolvida pela API."}}},"encoding":{"file":{"contentType":"application/x-pkcs12, application/octet-stream"}}}}},"responses":{"201":{"$ref":"#/components/responses/CertificateCreated"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"tags":["Configuração"],"summary":"Remover certificado digital","description":"Operação idempotente; removed é false quando não havia certificado cadastrado.","operationId":"deleteFiscalCertificate","responses":{"200":{"$ref":"#/components/responses/CertificateDeleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/catalogos":{"get":{"tags":["Serviço"],"summary":"Obter domínios fiscais","operationId":"getFiscalCatalogues","responses":{"200":{"$ref":"#/components/responses/CataloguesOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/painel":{"get":{"tags":["Serviço"],"summary":"Obter indicadores do trilho fiscal","operationId":"getFiscalDashboard","responses":{"200":{"$ref":"#/components/responses/DashboardOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/nfe":{"get":{"tags":["NF-e"],"summary":"Listar NF-e importadas","operationId":"listNfe","parameters":[{"name":"search","in":"query","description":"Emitente, destinatário, número ou chave de acesso.","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/NfeStatus"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"$ref":"#/components/responses/NfeListOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/nfe/importacoes":{"post":{"tags":["NF-e"],"summary":"Importar arquivos de NF-e","description":"Aceita de 1 a 20 arquivos XML, PDF ou ZIP, com até 10 MB cada. No multipart/form-data, envie cada parte usando o nome `arquivos[]` para formar o array `arquivos` aceito pela API.","operationId":"importNfe","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["arquivos"],"properties":{"arquivos":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"binary"}}}},"encoding":{"arquivos":{"style":"form","explode":true}}}}},"responses":{"201":{"$ref":"#/components/responses/NfeImportCreated"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/nfe/{access_key}":{"parameters":[{"$ref":"#/components/parameters/NfeAccessKey"}],"get":{"tags":["NF-e"],"summary":"Consultar NF-e","operationId":"getNfe","responses":{"200":{"$ref":"#/components/responses/NfeOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"tags":["NF-e"],"summary":"Remover NF-e não vinculada","operationId":"deleteNfe","responses":{"204":{"description":"NF-e removida; sem corpo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/BusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte-emitidos":{"post":{"tags":["CT-e emitidos"],"summary":"Entregar um CT-e emitido pela sua transportadora","description":"Entrega à FleetPay o XML de um CT-e que a **sua própria transportadora emitiu**. É por\naqui que o documento entra no fluxo operacional e financeiro da plataforma: vira serviço,\nentrega e recebível.\n\n## Por que existe\n\nAté aqui esse caminho dependia de um parceiro externo de armazenamento de XML: um\nprocesso nosso ia buscar o documento lá e trazia para dentro. Aquele processo opera sobre\num único CNPJ, então atende uma empresa e mais nenhuma.\n\nAqui quem entrega é o **seu sistema**, autenticado pela sua credencial. O documento segue\nexatamente o mesmo processamento de sempre — o que muda é quem traz.\n\n## Como enviar\n\nTrês formas, escolha uma:\n\n- `application/json` com o campo `xml` — o XML cru **ou em base64**. A codificação é\n  detectada pelo conteúdo; não há flag a acertar.\n- `multipart/form-data` com o campo `arquivo`.\n\nAceita o `cteProc` (com protocolo) ou o `CTe` cru, até 2 MB.\n\n## O que a FleetPay lê do XML\n\nVocê não monta payload nenhum — o XML basta. São lidos: a chave de acesso, a data de\nemissão, o emitente (a sua transportadora), o **tomador do frete** (pelo código `toma`,\nseja ele remetente, expedidor, recebedor, destinatário ou o grupo `toma4`), a rota\n(origem e destino, inclusive nos casos de redespacho), o valor da prestação e a chave da\nNF-e transportada.\n\n## Reenviar é seguro\n\nA operação é **idempotente pela chave de acesso**. O primeiro envio responde `201`; os\nseguintes respondem `200` com `first_reception: false` e **não reprocessam** o documento.\nRetry de rede e reprocessamento noturno não criam serviço duplicado nem erro.\n\n## Só o CT-e em que você é a emitente\n\nO `cnpj_carrier` é lido do grupo `emit` do XML e precisa ser o da transportadora\nautenticada. Um CT-e de outra empresa é recusado — o CT-e da contratante, que dá origem\nao seu contra-CT-e, entra por `POST /fiscal/cte-subcontratacao`.\n","operationId":"receiveEmittedCte","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmittedCteInput"}},"multipart/form-data":{"schema":{"type":"object","required":["arquivo"],"properties":{"arquivo":{"type":"string","format":"binary","description":"XML do CT-e, até 2 MB."}}}}}},"responses":{"200":{"$ref":"#/components/responses/EmittedCteAlreadyKnown"},"201":{"$ref":"#/components/responses/EmittedCteAccepted"},"400":{"$ref":"#/components/responses/ValidationFailed"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte-subcontratacao":{"get":{"tags":["CT-e de subcontratação"],"summary":"Listar CT-e recebidos","description":"A caixa de entrada da transportadora: os CT-e que **outras empresas** emitiram e que\nchegaram até ela. Não confundir com `GET /fiscal/cte`, que lista o que a sua empresa\nemite.\n","operationId":"listInboundCte","parameters":[{"name":"search","in":"query","description":"Casa com a chave de acesso, o CNPJ do emitente ou a razão social dele.","schema":{"type":"string"}},{"name":"carrier_role","in":"query","description":"Filtra pelo papel da sua empresa no documento.","schema":{"$ref":"#/components/schemas/InboundCteCarrierRole"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/InboundCteStatus"}},{"name":"from","in":"query","description":"Data inicial do RECEBIMENTO (não da emissão).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"Data final do RECEBIMENTO (não da emissão).","schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"$ref":"#/components/responses/InboundCteListOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["CT-e de subcontratação"],"summary":"Receber um CT-e de terceiro","description":"Entrega à FleetPay o XML de um CT-e emitido por outra empresa — tipicamente o da\ntransportadora **contratante**, que dá origem ao seu contra-CT-e de subcontratação.\n\n## Por que existe\n\nAs demais formas de recepção dependem de um terceiro entre você e a plataforma. Aqui é o\nseu sistema que entrega o documento, e ele passa a existir na FleetPay sem intermediário\n— inclusive quando nenhuma recepção automática está contratada.\n\nÉ também o que destrava `POST /fiscal/cte/contra`: aquele endpoint precisa do XML do CT-e\noriginal para montar o contra-CT-e, e passa a encontrá-lo aqui.\n\n## Como enviar\n\nDuas formas, escolha uma:\n\n- `application/json` com o campo `xml` — o XML cru ou em **base64**. A codificação é\n  detectada pelo conteúdo; não há flag a acertar.\n- `multipart/form-data` com o campo `arquivo`.\n\nO documento pode ser o `cteProc` (com protocolo) ou o `CTe` cru. Limite de 2 MB.\n\n## Reenviar é seguro\n\nA operação é **idempotente pela chave de acesso**. O primeiro envio responde `201`; os\nseguintes respondem `200` com o mesmo recurso e `received_count` somado. Retry de rede,\nreprocessamento noturno e clique duplo não criam registro duplicado nem erro.\n\nSe o reenvio trouxer um XML diferente do arquivado — o caso comum é mandar o `CTe` e\ndepois o `cteProc` com o protocolo —, o conteúdo é substituído pelo mais recente e\n`content_updated` vem `true`.\n\n## Receber não é emitir\n\nRegistrar a chegada não gera documento fiscal nenhum. O contra-CT-e continua nascendo em\n`POST /fiscal/cte/contra`, com motorista, veículo e o preço do **seu** trecho — nenhum dos\ntrês está no XML da contratante.\n\nUm CT-e que não admite contra-CT-e (por exemplo, um que a sua própria empresa emitiu) é\nrecebido do mesmo jeito: o campo `carrier_role` nomeia o seu papel e `allows_counter_cte`\nresponde a pergunta prática, sem que você precise reimplementar a regra.\n","operationId":"receiveInboundCte","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundCteInput"}},"multipart/form-data":{"schema":{"type":"object","required":["arquivo"],"properties":{"arquivo":{"type":"string","format":"binary","description":"XML do CT-e, até 2 MB."}}}}}},"responses":{"200":{"$ref":"#/components/responses/InboundCteReceivedAgain"},"201":{"$ref":"#/components/responses/InboundCteReceived"},"400":{"$ref":"#/components/responses/ValidationFailed"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte-subcontratacao/{access_key}":{"get":{"tags":["CT-e de subcontratação"],"summary":"Consultar um CT-e recebido","description":"O documento recebido pela chave de acesso, com os endereços completos das partes — que a\nlistagem não traz para não engordar cada página.\n","operationId":"getInboundCte","parameters":[{"$ref":"#/components/parameters/InboundCteAccessKey"}],"responses":{"200":{"$ref":"#/components/responses/InboundCteOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte-subcontratacao/{access_key}/xml":{"get":{"tags":["CT-e de subcontratação"],"summary":"Baixar o XML arquivado","description":"O XML exatamente como chegou, byte a byte. Não é reserializado pela FleetPay: um\ndocumento reescrito por nós deixaria de bater com a assinatura de quem o emitiu.\n","operationId":"getInboundCteXml","parameters":[{"$ref":"#/components/parameters/InboundCteAccessKey"}],"responses":{"200":{"description":"XML do CT-e recebido.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte-subcontratacao/autorizacoes":{"get":{"tags":["CT-e de subcontratação"],"summary":"Listar autorizações de emissão (concedidas e recebidas)","operationId":"listEmissionGrants","description":"Os dois lados da autorização de emissão entre transportadoras: `concedidas` (esta empresa,\ncomo subcontratada, autorizou estas contratantes a disparar contra-CT-e em nome dela) e\n`recebidas` (estas subcontratadas autorizaram esta empresa). A contratante consulta aqui\npor quem pode emitir antes de mandar `subcontratada.cnpj` no lote.\n","responses":{"200":{"description":"As autorizações ativas, nos dois sentidos.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["CT-e de subcontratação"],"summary":"Autorizar uma contratante a emitir contra-CT-e em seu nome","operationId":"grantEmission","description":"Quem chama é a **subcontratada** (a dona do certificado): ela autoriza a contratante do corpo\na disparar `POST /fiscal/cte-subcontratacao/lote` com `subcontratada.cnpj` = o CNPJ dela. O\nlote nasce na conta da subcontratada — certificado, numeração, caixa fiscal, motorista e\nveículo dela — e a contratante fica registrada como quem pediu. A contratante precisa ser\ntransportadora cliente da FleetPay. Idempotente: já ativa → `200`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contratante"],"properties":{"contratante":{"type":"object","required":["cnpj"],"properties":{"cnpj":{"type":"string","description":"CNPJ da contratante (com ou sem pontuação)."}}}}}}}},"responses":{"200":{"description":"Já estava autorizada (mesmo corpo do `201`)."},"201":{"description":"Autorização concedida.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`contratante_nao_encontrada` — o CNPJ não é de uma transportadora cliente."},"422":{"description":"`contratante_invalida` — o próprio CNPJ; ou erro de validação do corpo."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte-subcontratacao/autorizacoes/{cnpj}":{"delete":{"tags":["CT-e de subcontratação"],"summary":"Revogar a autorização de uma contratante","operationId":"revokeEmissionGrant","description":"Fecha a porta na hora: o próximo lote da contratante com `subcontratada.cnpj` responde\n`403 emissao_nao_autorizada`. Lotes já criados não mudam. A linha revogada fica para auditoria.\n","parameters":[{"name":"cnpj","in":"path","required":true,"schema":{"type":"string"},"description":"CNPJ da contratante (com ou sem pontuação)."}],"responses":{"200":{"description":"Autorização revogada.","content":{"application/json":{}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`autorizacao_nao_encontrada` — não há autorização ativa para essa contratante."},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte-subcontratacao/lote":{"post":{"tags":["CT-e de subcontratação"],"summary":"Emitir contra-CT-e em lote (1:1 ou em pernas)","operationId":"createContraCteBatch","description":"Emite **vários contra-CT-e numa chamada** e devolve um `batch_id`; a emissão roda em\nsegundo plano e o resultado por chave sai em `GET /fiscal/cte-subcontratacao/lote/{batch_id}`.\nCada CT-e da contratante precisa ter chegado antes por `POST /fiscal/cte-subcontratacao`.\n\n## Dois desenhos, um endpoint\n\n- **1:1** — um contra-CT-e integral por CT-e da contratante. `ctes[]` traz as chaves; o\n  motorista (`motorista.cpf`) e o veículo (`placa`) são os mesmos para o lote inteiro.\n- **Pernas** — um CT-e da contratante subcontratado em **trechos**: `ctes[].pernas[]`\n  descreve cada trecho com origem/destino próprios, e cada perna pode ter motorista,\n  veículo e valor próprios (o `motorista`/`placa` do lote são o padrão das pernas que não\n  informam os seus). Não misture chaves com e sem `pernas` no mesmo lote.\n\n## Valor: por chave OU rateio — nunca os dois\n\n- `ctes[].valor` (ou `pernas[].valor`) congela o valor de **cada** contra-CT-e; o fiscal\n  (`vTPrest`/`vRec`) e o repasse ao motorista saem desse valor, sem arredondar.\n- `valores.frete_bruto` no lote rateia `total ÷ N` em centavos, com o resíduo nas\n  **últimas** chaves da sequência; a soma fecha exata.\n\nInformar os dois responde `422`.\n\n## Rota do trecho\n\nPor padrão o contra-CT-e herda origem → destino da contratante. `origem`/`destino` no lote\n(ou por chave/perna) declaram a rota REAL do trecho — e é dela que saem CFOP e ICMS:\norigem na UF do emitente → `5360` (mesma UF) / `6360` (outra UF); origem fora da UF do\nemitente → `5932` (início e fim na mesma UF) / `6932`. Com regra de tributação **do tipo\nde serviço** (`tp_serv` na regra), o CFOP da regra é mantido quando a prestação começa na\nUF do emitente; o `5932`/`6932` continua imposto quando começa em outra UF. Os pares\nmunicípio × UF são validados; precisa existir regra de tributação aplicável à rota e ao\ntipo (`GET /fiscal/regras-tributacao`).\n\n## Tipo de serviço\n\n`tipo_servico` é o `ide/tpServ` de cada contra-CT-e, com precedência **perna → chave →\nlote → `1`** (subcontratação). Só `1` subcontratação, `2` redespacho e `3` redespacho\nintermediário. No redespacho a rota é o **trecho** que a subcontratada executa, não a\nviagem da contratante: `2` e `3` exigem `origem` e `destino` (na chave, no lote ou na\nperna — `422` sem eles), e um \"trecho\" igual à viagem inteira do CT-e da contratante é\nrecusado na linha com `redespacho_exige_rota`. Um CT-e da contratante vinculado a\nmultimodal (`tpServ` 4) não admite contra-CT-e (`origem_incompativel_com_tipo`; na caixa,\n`allows_counter_cte: false`). A linha de resultado devolve o `tipo_servico` com que o\ndocumento saiu (na linha `duplicated`, o tipo **pedido** — o do contra-CT-e existente está\nem `GET /fiscal/cte/{counter_cte_id}`, campo `service_type`).\n\n## Repasse ao motorista (mesma regra do CIOT)\n\n`repasse.parcelas` é a regra de parcelas do lote (posições 1..3, percentuais somando 100,\n`dias` de 0 a 30) e **vence a regra cadastrada do motorista**. Os contra-CT-e de um mesmo\nmotorista no lote formam um grupo:\n\n- **N ≥ nº de parcelas** → cada documento inteiro cai numa parcela (60/20/20 em 15 docs =\n  9/3/3 documentos, sempre ≥ 1 por parcela) — a parcela 1 libera na bipagem, a 2 na\n  conclusão, a 3 na prestação de contas;\n- **N < nº de parcelas** → cada documento é fracionado nas parcelas (60/20/20 do valor\n  dele).\n\nO bucket é decidido pela **posição no lote**, não pelo valor: com valores diferentes, a\nordem das chaves define quanto entra em cada parcela. A parcela só existe depois da\n**bipagem** do documento — consulte-a em `GET /carriers/parcelas-repasse/{documento}`\n(aceita o `counter_cte_id`).\n\n## Um modo por origem, e o que bloqueia\n\nUma chave com contra-CT-e integral ativo não aceita pernas (`origem_ja_subcontratada_1a1`)\ne vice-versa (`origem_ja_subcontratada_em_pernas`); cancelar o contra-CT-e libera o outro\nmodo. Chave já subcontratada no mesmo modo responde `duplicated` com o `counter_cte_id`\nexistente — reenviar o lote é seguro. CT-e emitido pela sua própria empresa responde\n`cte_proprio`; rota sem regra, `sem_regra_tributacao`; redespacho com o trecho igual à\nviagem inteira, `redespacho_exige_rota`; origem vinculada a multimodal,\n`origem_incompativel_com_tipo`; origem cujo repasse já foi pago não pode virar pernas.\n\nCancelar um contra-CT-e (`POST /fiscal/cte/{cte_uuid}/eventos/cancelamento`) cancela as\nparcelas ainda não pagas e tira o documento do grupo; o CT-e da contratante continua válido.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContraCteLoteInput"}}}},"responses":{"202":{"description":"Lote aceito; a emissão roda em segundo plano.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContraCteLoteAcceptedEnvelope"}}}},"400":{"$ref":"#/components/responses/Erro400"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Validação do payload (`error.details.fields`) ou regra de negócio antes de criar o lote:\n`motorista_nao_encontrado`, `veiculo_nao_encontrado` — nas pernas, o `message` aponta a\nperna (`ctes.0.pernas.2`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte-subcontratacao/lote/{batch_id}":{"get":{"tags":["CT-e de subcontratação"],"summary":"Acompanhar um lote de contra-CT-e","operationId":"getContraCteBatch","description":"O estado do lote e **uma linha por chave** (ou por perna). O relatório é gravado a cada\nchave processada: no meio do lote você já vê o que foi emitido. `status` do lote é\n`processing`, `done` ou `failed`; o de cada linha é `pending`, `emitted`, `duplicated` ou\n`failed`.\n\nCada linha `emitted` traz o `counter_cte_id` — o UUID do contra-CT-e para\n`GET /fiscal/cte/{cte_uuid}`, polling e DACTE — e, nas pernas, o `documento_financeiro`\n(o documento da perna, aceito em `GET /carriers/parcelas-repasse/{documento}`). Uma falha\n**depois** de o provedor aceitar o documento vem como `emitted` com `financeiro: failed`,\nnunca como `failed` sem `counter_cte_id`.\n","parameters":[{"$ref":"#/components/parameters/ContraCteBatchId"}],"responses":{"200":{"description":"O lote e o resultado por chave.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContraCteLoteEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Lote inexistente ou de outra transportadora (`lote_nao_encontrado`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/ciot":{"post":{"tags":["CIOT"],"summary":"Declarar CIOT sem CT-e","operationId":"declararCiot","description":"Registra uma Operação de Transporte na ANTT a partir da **viagem**, sem depender de um\nCT-e emitido pela FleetPay.\n\nÉ o irmão de `POST /fiscal/cte/{cte_uuid}/ciot/emissao`, e existe porque quem contrata\nfrete e precisa declarar o CIOT nem sempre é quem emite o documento fiscal dele. Nesta\nrota a viagem inteira chega no corpo — contratado, rota, carga, veículo, motorista,\ndocumentos e valores — e o CIOT é a única coisa que se produz.\n\n**As duas rotas convivem.** Se você emite o CT-e pela FleetPay e quer o CIOT amarrado a\nele, continue na rota ancorada: nada mudou lá.\n\n## O código de resposta conta o desfecho\n\n| Código | Significa | Pode seguir viagem? |\n|---|---|---|\n| `201` | A ANTT devolveu o CIOT: número e código verificador na resposta. | **Sim** |\n| `202` | A declaração foi entregue e o veredito vem depois. | **Não** — consulte antes |\n| `422` | A declaração não saiu daqui, ou foi recusada. | Não |\n\nTratar um `202` como sucesso põe caminhão na estrada com um CIOT que talvez não exista.\nEm `202`, releia a operação pelo `id` até o status sair de `sent`.\n\n## A operação existe mesmo quando a declaração falha\n\nA linha é criada **antes** da chamada ao provedor. Um `422` devolve o `id` da operação\nem `error.details.ciot.id`, e ela continua legível por `GET /fiscal/ciot/{id}` com o\nmotivo gravado. Guarde esse id: é por ele que se investiga uma recusa.\n\n## Idempotência\n\n`referencia_externa` é opcional e **única por empresa**. Com ela, um retry de rede\nesbarra em `400 validacao` em vez de gerar um segundo CIOT para o mesmo frete — o que\nseria problema regulatório, não inconveniência. Sem ela, o risco é seu.\n\n## Escopo desta versão\n\nCarga **lotação ou fracionada**, declarada **em nome próprio** (o\n`contratado.documento` tem de ser o CNPJ da empresa autenticada), de um a dez veículos\ne de um a cem documentos fiscais com remetente e destinatário.\n\nNo fracionado, informe `carga.contratantes`. `rota.trechos` pode detalhar até cem\npares de coleta e entrega; `rota.origem` e `rota.destino` continuam representando os\nextremos da viagem. TAC agregado, parcelas do frete e Vale-Pedágio com praças ainda\nnão são aceitos por esta rota.\n\n## Modo simulado em homologação\n\nEsta operação **não tem provedor de CIOT contratado** por trás: em homologação a\nresposta é gerada pela FleetPay, é determinística e **não tem efeito regulatório** —\nnada é registrado na ANTT e nenhum CIOT tratado aqui tem valor legal.\n\n### Sentinelas de teste\n\nEm modo simulado, estes valores de `referencia_externa` forçam um desfecho — use-os\npara exercitar os caminhos que não são o feliz:\n\n| `referencia_externa` | Resposta |\n|---|---|\n| `CIOT-PENDENTE` | `202` — declaração entregue, sem veredito |\n| `CIOT-RECUSAR` | `422 declaracao_recusada` — o provedor recusou |\n| qualquer outro valor | `201` — CIOT registrado |\n\nA referência externa serve de sentinela porque é o único campo do corpo que é seu, é\nopcional e **não vai para a ANTT** — pedir um desfecho por ela não contamina nenhum\ndado da operação.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeclaracaoCiot"}}}},"responses":{"201":{"description":"CIOT registrado na ANTT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaCiot"}}}},"202":{"description":"Declaração entregue e ainda sem desfecho. **Não siga viagem**: releia a operação\npelo `id` até o status sair de `sent`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaCiot"}}}},"400":{"description":"`validacao` — falta campo obrigatório da viagem, ou a `referencia_externa` já foi\nusada por outra operação desta empresa.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"422":{"description":"`declaracao_bloqueada` — a declaração não chegou a ser transmitida (o contratado\nnão é a empresa autenticada, o perfil dele não é coberto, ou não há provedor).\n`declaracao_recusada` — o provedor respondeu recusando.\n\nNos dois casos `error.details.ciot.id` traz o endereço da operação, que permanece\nlegível por `GET /fiscal/ciot/{id}`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/fiscal/ciot/{ciot_uuid}":{"get":{"tags":["CIOT"],"summary":"Consultar uma operação de transporte","operationId":"consultarOperacaoCiot","description":"O estado da operação declarada, **sem** falar com o provedor.\n\nÉ leitura pura: é o que você chama depois de um `202`, ou para reler um desfecho que\nnão guardou. Funciona inclusive para operações recusadas — que é justamente o caso em\nque o número do CIOT nunca existiu.\n","parameters":[{"name":"ciot_uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"O `id` devolvido pela declaração."}],"responses":{"200":{"description":"A operação.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaCiot"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"404":{"description":"`ciot_nao_encontrado` — não existe operação com esse id **nesta empresa**. Operação\nde outro tenant responde igual, de propósito.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/fiscal/cte":{"get":{"tags":["CT-e"],"summary":"Listar CT-e","operationId":"listCte","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/CteSituation"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"$ref":"#/components/responses/CteListOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["CT-e"],"summary":"Criar rascunho de CT-e","operationId":"createCte","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteDraftInput"}}}},"responses":{"201":{"description":"Rascunho criado.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteEnvelope"}}},"links":{"ConsultarCte":{"operationId":"getCte","parameters":{"cte_uuid":"$response.body#/data/id"}},"GerarPreviaCte":{"operationId":"previewCte","parameters":{"cte_uuid":"$response.body#/data/id"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/contra":{"post":{"tags":["CT-e"],"summary":"Emitir contra-CT-e (subcontratação ou redespacho)","description":"Emite o CT-e da transportadora **subcontratada** contra o CT-e da contratante, referenciando\na chave dele em `infDocAnt` e com a contratante como tomador.\n\n`tipo_servico` diz o `ide/tpServ` do contra-CT-e: `1` subcontratação (padrão), `2`\nredespacho, `3` redespacho intermediário. No redespacho a rota é o **trecho** executado,\nnão a viagem da contratante: `2` e `3` exigem `origem` e `destino` (`400` `validacao`\nsem eles); um trecho igual à viagem inteira do CT-e original responde `422`\n`contra_cte_invalido` (`redespacho_exige_rota`), e um CT-e original vinculado a\nmultimodal, `422` `contra_cte_invalido` (`origem_incompativel_com_tipo`). A regra de\ntributação é resolvida pela rota do trecho e pelo tipo.\n\nO payload é enxuto: informe a **chave do CT-e original** (que já precisa ter chegado pela\ncaixa do Monitor DFe), o **motorista** (por CPF) e o **veículo** (por placa) que executam o\ntrecho, e o **valor do frete** — o repasse ao motorista. Remetente, destinatário, carga,\nrota e tributação são lidos do XML do CT-e original.\n\n`valor_frete` é opcional: sem ele, a regra de precificação da transportadora sugere o valor\ndo trecho. Uma resposta 202 exige polling em `/cte/{cte_uuid}/consulta`.\n","operationId":"issueContraCte","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chave_cte_original","motorista","placa"],"properties":{"chave_cte_original":{"type":"string","minLength":44,"maxLength":44,"description":"Chave de acesso (44 dígitos) do CT-e da contratante."},"motorista":{"type":"object","required":["cpf"],"properties":{"cpf":{"type":"string","pattern":"^[0-9]{11}$","description":"CPF do motorista que executa o trecho (somente dígitos)."}}},"placa":{"type":"string","description":"Placa do veículo (padrão brasileiro, ex. ABC1D23 ou ABC1234)."},"valor_frete":{"type":"number","format":"double","minimum":0.01,"description":"Valor do repasse ao motorista pelo trecho. Opcional."},"tipo_servico":{"type":["integer","null"],"enum":[1,2,3,null],"description":"`ide/tpServ` do contra-CT-e: `1` subcontratação (padrão), `2` redespacho, `3` redespacho intermediário."},"origem":{"$ref":"#/components/schemas/ContraCteLoteRota"},"destino":{"$ref":"#/components/schemas/ContraCteLoteRota"}}}}}},"responses":{"202":{"description":"Emissão aceita ou com resultado ainda não conclusivo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteIssueEnvelope"}}}},"400":{"$ref":"#/components/responses/Erro400"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"get":{"tags":["CT-e"],"summary":"Consultar CT-e","operationId":"getCte","responses":{"200":{"$ref":"#/components/responses/CteOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"put":{"tags":["CT-e"],"summary":"Atualizar rascunho de CT-e","description":"Substitui os dados editáveis do rascunho. Documentos já enviados são imutáveis.","operationId":"updateCte","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteDraftInput"}}}},"responses":{"200":{"$ref":"#/components/responses/CteOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/subcontratacao":{"post":{"tags":["CT-e de subcontratação"],"summary":"Repassar o CT-e à subcontratada (ponte da subcontratação)","operationId":"declareCteSubcontracting","description":"A **contratante** declara a quem subcontratou um CT-e que ela emitiu pela FleetPay — e o\nXML autorizado dele cai na caixa fiscal da **subcontratada**, exatamente como se ela o\ntivesse entregue em `POST /fiscal/cte-subcontratacao`.\n\nSem isto, com as duas empresas na FleetPay, o ERP da subcontratada precisava reenviar um\ndocumento que a plataforma já tinha; esquecer esse passo fazia o lote de contra-CT-e\nresponder \"CT-e original não recebido\".\n\n- Só CT-e **autorizado** (`cte_nao_autorizado` caso contrário); o XML repassado é o\n  arquivado na autorização, byte a byte.\n- A subcontratada precisa ser uma transportadora cliente FleetPay\n  (`subcontratada_nao_encontrada`, `subcontratada_nao_transportadora`) e não pode ser a\n  própria empresa (`subcontratada_igual_contratante`).\n- A caixa de destino é a do **ambiente do CT-e**; a recepção é idempotente pela chave:\n  `201` na primeira entrega, `200` nas seguintes.\n- Nada financeiro acontece aqui; a partir daí a subcontratada segue o fluxo normal\n  (`POST /fiscal/cte/contra` ou `POST /fiscal/cte-subcontratacao/lote`).\n\nDepende do release que leva o PR core#1459.\n","parameters":[{"$ref":"#/components/parameters/CteUuid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subcontratada"],"properties":{"subcontratada":{"type":"object","required":["cnpj"],"properties":{"cnpj":{"type":"string","description":"CNPJ da transportadora subcontratada (com ou sem máscara; aceita CNPJ alfanumérico)."}}},"observacao":{"type":["string","null"],"maxLength":255}}}}}},"responses":{"200":{"description":"Reenvio — a caixa da subcontratada já tinha o documento (`received_count` somado)."},"201":{"description":"Primeira entrega — o CT-e entrou na caixa da subcontratada.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"cte":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"access_key":{"type":"string"}}},"subcontratada":{"type":"object","properties":{"cnpj":{"type":"string"},"nome":{"type":["string","null"]}}},"recebimento":{"$ref":"#/components/schemas/InboundCteReceipt"}}},"environment":{"$ref":"#/components/schemas/Environment"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"XML arquivado indisponível agora (`xml_indisponivel`) — tente novamente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/fiscal/cte/{cte_uuid}/previa":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["CT-e"],"summary":"Gerar prévia do CT-e","description":"Monta o conteúdo e valida pendências sem efetivar a emissão.","operationId":"previewCte","responses":{"200":{"$ref":"#/components/responses/CtePreviewOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/BusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/emissao":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["CT-e"],"summary":"Emitir CT-e","description":"Inicia a emissão em homologação. Uma resposta 202 exige polling em\n`/cte/{cte_uuid}/consulta`; não repita esta emissão enquanto o resultado for desconhecido.\n","operationId":"issueCte","responses":{"202":{"description":"Emissão aceita ou com resultado ainda não conclusivo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteIssueEnvelope"}}},"links":{"ConsultarAutorizacaoCte":{"operationId":"queryCte","parameters":{"cte_uuid":"$request.path.cte_uuid"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/consulta":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["CT-e"],"summary":"Consultar autorização do CT-e","description":"Endpoint de polling para emissão com resposta 202, timeout ou resultado ambíguo.","operationId":"queryCte","responses":{"200":{"$ref":"#/components/responses/CteQueryOk"},"202":{"$ref":"#/components/responses/CteQueryPending"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/dacte":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"get":{"tags":["CT-e"],"summary":"Baixar DACTE","operationId":"downloadDacte","responses":{"200":{"description":"Arquivo PDF da DACTE.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Content-Disposition":{"schema":{"type":"string"}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/BusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/fiscal/cte/{cte_uuid}/eventos/cancelamento":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["Eventos CT-e"],"summary":"Cancelar CT-e","operationId":"cancelCte","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JustificationInput"}}}},"responses":{"200":{"$ref":"#/components/responses/CteEventOk"},"202":{"$ref":"#/components/responses/CteEventPending"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/eventos/carta-correcao":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["Eventos CT-e"],"summary":"Registrar carta de correção","operationId":"correctCte","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteCorrectionInput"}}}},"responses":{"200":{"$ref":"#/components/responses/CteEventOk"},"202":{"$ref":"#/components/responses/CteEventPending"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/eventos/entrega":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["Eventos CT-e"],"summary":"Confirmar entrega do CT-e","operationId":"confirmCteDelivery","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteDeliveryInput"}}}},"responses":{"200":{"$ref":"#/components/responses/CteEventOk"},"202":{"$ref":"#/components/responses/CteEventPending"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/eventos/entrega/cancelamento":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["Eventos CT-e"],"summary":"Cancelar confirmação de entrega","operationId":"cancelCteDelivery","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteDeliveryCancellationInput"}}}},"responses":{"200":{"$ref":"#/components/responses/CteEventOk"},"202":{"$ref":"#/components/responses/CteEventPending"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/eventos/{event_key}/reconciliacao":{"parameters":[{"$ref":"#/components/parameters/CteUuid"},{"$ref":"#/components/parameters/EventKey"}],"post":{"tags":["Eventos CT-e"],"summary":"Reconciliar evento pendente do CT-e","operationId":"reconcileCteEvent","responses":{"200":{"$ref":"#/components/responses/CteEventOk"},"202":{"$ref":"#/components/responses/CteEventPending"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/BusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/ciot/validacao":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["CIOT"],"summary":"Validar dados para emissão do CIOT","operationId":"validateCiot","description":"**Modo simulado em homologação.** Esta operação não tem provedor de CIOT contratado por\ntrás: em homologação a resposta é gerada pela FleetPay, é determinística e **não tem\nefeito regulatório** — nada é registrado na ANTT e nenhum CIOT tratado por aqui tem\nvalor legal.\n\nO contrato de request e response já é o definitivo: integre agora. Quando o provedor real\nentrar, o comportamento deixa de ser simulado **sem mudança de contrato**.\n","responses":{"200":{"$ref":"#/components/responses/CiotCheckOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/BusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/ciot/emissao":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["CIOT"],"summary":"Emitir CIOT","description":"Em 202, consulte o CIOT antes de repetir qualquer comando.\n\n**Modo simulado em homologação.** Esta operação não tem provedor de CIOT contratado por\ntrás: em homologação a resposta é gerada pela FleetPay, é determinística e **não tem\nefeito regulatório** — nada é registrado na ANTT e nenhum CIOT tratado por aqui tem\nvalor legal.\n\nO contrato de request e response já é o definitivo: integre agora. Quando o provedor real\nentrar, o comportamento deixa de ser simulado **sem mudança de contrato**.\n","operationId":"issueCiot","responses":{"201":{"$ref":"#/components/responses/CiotCreated"},"202":{"description":"Emissão enviada e ainda não concluída.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CiotOperationEnvelope"}}},"links":{"ConsultarCiot":{"operationId":"queryCiot","parameters":{"cte_uuid":"$request.path.cte_uuid"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/BusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/ciot/consulta":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["CIOT"],"summary":"Consultar CIOT","operationId":"queryCiot","description":"**Modo simulado em homologação.** Esta operação não tem provedor de CIOT contratado por\ntrás: em homologação a resposta é gerada pela FleetPay, é determinística e **não tem\nefeito regulatório** — nada é registrado na ANTT e nenhum CIOT tratado por aqui tem\nvalor legal.\n\nO contrato de request e response já é o definitivo: integre agora. Quando o provedor real\nentrar, o comportamento deixa de ser simulado **sem mudança de contrato**.\n","responses":{"200":{"$ref":"#/components/responses/CiotOk"},"202":{"$ref":"#/components/responses/CiotPending"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/BusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/ciot/cancelamento":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["CIOT"],"summary":"Cancelar CIOT","operationId":"cancelCiot","description":"**Modo simulado em homologação.** Esta operação não tem provedor de CIOT contratado por\ntrás: em homologação a resposta é gerada pela FleetPay, é determinística e **não tem\nefeito regulatório** — nada é registrado na ANTT e nenhum CIOT tratado por aqui tem\nvalor legal.\n\nO contrato de request e response já é o definitivo: integre agora. Quando o provedor real\nentrar, o comportamento deixa de ser simulado **sem mudança de contrato**.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["justification"],"properties":{"justification":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"$ref":"#/components/responses/CiotOk"},"202":{"$ref":"#/components/responses/CiotPending"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/ciot/retificacao":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["CIOT"],"summary":"Retificar CIOT","operationId":"rectifyCiot","description":"**Modo simulado em homologação.** Esta operação não tem provedor de CIOT contratado por\ntrás: em homologação a resposta é gerada pela FleetPay, é determinística e **não tem\nefeito regulatório** — nada é registrado na ANTT e nenhum CIOT tratado por aqui tem\nvalor legal.\n\nO contrato de request e response já é o definitivo: integre agora. Quando o provedor real\nentrar, o comportamento deixa de ser simulado **sem mudança de contrato**.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CiotRectificationInput"}}}},"responses":{"200":{"$ref":"#/components/responses/CiotOk"},"202":{"$ref":"#/components/responses/CiotPending"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/cte/{cte_uuid}/ciot/encerramento":{"parameters":[{"$ref":"#/components/parameters/CteUuid"}],"post":{"tags":["CIOT"],"summary":"Encerrar CIOT","operationId":"closeCiot","description":"**Modo simulado em homologação.** Esta operação não tem provedor de CIOT contratado por\ntrás: em homologação a resposta é gerada pela FleetPay, é determinística e **não tem\nefeito regulatório** — nada é registrado na ANTT e nenhum CIOT tratado por aqui tem\nvalor legal.\n\nO contrato de request e response já é o definitivo: integre agora. Quando o provedor real\nentrar, o comportamento deixa de ser simulado **sem mudança de contrato**.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CiotClosingInput"}}}},"responses":{"200":{"$ref":"#/components/responses/CiotOk"},"202":{"$ref":"#/components/responses/CiotPending"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/veiculos":{"get":{"tags":["Veículos"],"summary":"Listar veículos ativos","operationId":"listVehicles","responses":{"200":{"$ref":"#/components/responses/VehicleListOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["Veículos"],"summary":"Cadastrar veículo","operationId":"createVehicle","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleCreateInput"}}}},"responses":{"201":{"$ref":"#/components/responses/VehicleCreated"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/veiculos/{id}/dados-fiscais":{"parameters":[{"$ref":"#/components/parameters/VehicleId"}],"put":{"tags":["Veículos"],"summary":"Atualizar dados fiscais do veículo","operationId":"updateVehicleFiscalData","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleFiscalInput"}}}},"responses":{"200":{"$ref":"#/components/responses/VehicleOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/motoristas":{"get":{"tags":["Motoristas"],"summary":"Listar motoristas","operationId":"listDrivers","responses":{"200":{"$ref":"#/components/responses/DriverListOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/motoristas/{id}/dados-fiscais":{"parameters":[{"$ref":"#/components/parameters/DriverId"}],"put":{"tags":["Motoristas"],"summary":"Atualizar dados fiscais do motorista","operationId":"updateDriverFiscalData","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverFiscalInput"}}}},"responses":{"200":{"$ref":"#/components/responses/DriverOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/mdfe":{"get":{"tags":["MDF-e"],"summary":"Listar MDF-e","operationId":"listMdfe","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/MdfeStatus"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"$ref":"#/components/responses/MdfeListOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["MDF-e"],"summary":"Criar rascunho de MDF-e","operationId":"createMdfe","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MdfeDraftInput"}}}},"responses":{"201":{"description":"Rascunho criado.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MdfeEnvelope"}}},"links":{"ConsultarMdfe":{"operationId":"getMdfe","parameters":{"mdfe_uuid":"$response.body#/data/id"}},"EmitirMdfe":{"operationId":"issueMdfe","parameters":{"mdfe_uuid":"$response.body#/data/id"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/mdfe/{mdfe_uuid}":{"parameters":[{"$ref":"#/components/parameters/MdfeUuid"}],"get":{"tags":["MDF-e"],"summary":"Consultar MDF-e","operationId":"getMdfe","responses":{"200":{"$ref":"#/components/responses/MdfeOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"put":{"tags":["MDF-e"],"summary":"Atualizar rascunho de MDF-e","description":"Substitui os dados editáveis do rascunho. Documentos já enviados são imutáveis.","operationId":"updateMdfe","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MdfeDraftInput"}}}},"responses":{"200":{"$ref":"#/components/responses/MdfeOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/mdfe/{mdfe_uuid}/emissao":{"parameters":[{"$ref":"#/components/parameters/MdfeUuid"}],"post":{"tags":["MDF-e"],"summary":"Emitir MDF-e","description":"Em 202, consulte o MDF-e antes de repetir qualquer comando.","operationId":"issueMdfe","responses":{"200":{"$ref":"#/components/responses/MdfeOperationOk"},"202":{"description":"Emissão enviada e ainda não concluída.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MdfeOperationEnvelope"}}},"links":{"ConsultarAutorizacaoMdfe":{"operationId":"queryMdfe","parameters":{"mdfe_uuid":"$request.path.mdfe_uuid"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/BusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/fiscal/mdfe/{mdfe_uuid}/consulta":{"parameters":[{"$ref":"#/components/parameters/MdfeUuid"}],"post":{"tags":["MDF-e"],"summary":"Consultar autorização do MDF-e","operationId":"queryMdfe","responses":{"200":{"$ref":"#/components/responses/MdfeOperationOk"},"202":{"$ref":"#/components/responses/MdfeOperationPending"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/BusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/fiscal/mdfe/{mdfe_uuid}/encerramento":{"parameters":[{"$ref":"#/components/parameters/MdfeUuid"}],"post":{"tags":["MDF-e"],"summary":"Encerrar MDF-e","operationId":"closeMdfe","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MdfeClosingInput"}}}},"responses":{"200":{"$ref":"#/components/responses/MdfeOperationOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/fiscal/mdfe/{mdfe_uuid}/cancelamento":{"parameters":[{"$ref":"#/components/parameters/MdfeUuid"}],"post":{"tags":["MDF-e"],"summary":"Cancelar MDF-e","operationId":"cancelMdfe","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JustificationInput"}}}},"responses":{"200":{"$ref":"#/components/responses/MdfeOperationOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/fiscal/mdfe/{mdfe_uuid}/condutores":{"parameters":[{"$ref":"#/components/parameters/MdfeUuid"}],"post":{"tags":["MDF-e"],"summary":"Incluir condutor no MDF-e","operationId":"addMdfeDriver","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MdfeDriverInput"}}}},"responses":{"200":{"$ref":"#/components/responses/MdfeOperationOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationOrBusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/fiscal/mdfe/{mdfe_uuid}/damdfe":{"parameters":[{"$ref":"#/components/parameters/MdfeUuid"}],"get":{"tags":["MDF-e"],"summary":"Baixar DAMDFE","operationId":"downloadDamdfe","responses":{"200":{"description":"Arquivo PDF da DAMDFE.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Content-Disposition":{"schema":{"type":"string"}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/BusinessRuleFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/fiscal/regras-tributacao":{"get":{"tags":["Regras de tributação"],"summary":"Listar regras de tributação","operationId":"listFiscalTaxRules","description":"Devolve `data.regras`, a lista das regras da transportadora autenticada — toda regra é\nda transportadora; a FleetPay não mantém camada própria por trás do cadastro.\nPrecedência na emissão: regra com o tipo de serviço casado (`tp_serv`) vence qualquer\nregra só de rota; depois, rota exata vence curinga, e origem casada pesa mais que destino\ncasado; a vigência filtra, e no empate vence a `valid_from` mais recente. Regra sem\n`tp_serv` vale para qualquer tipo.\n","responses":{"200":{"$ref":"#/components/responses/FiscalTaxRulesOk"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["Regras de tributação"],"summary":"Criar regra de tributação","operationId":"createFiscalTaxRule","description":"Cria uma regra para a transportadora autenticada — não existe `company_id` no contrato;\no escopo é sempre o da credencial. A regra é a autoridade em todos os caminhos de\nemissão: o motor resolve a regra pela rota do rascunho, calcula o ICMS, decide o CFOP\ne reaplica tudo na emissão. Em `POST /cte` e `PUT /cte/{cte_uuid}` a rota sem regra\nresponde `422` `regra_tributaria_ausente`, e o bloco `icms` do payload é substituído\npela regra (só sobrevivem ST retido e crédito presumido); no CT-e automático a partir\nda NF-e e no contra-CT-e a rota sem regra fica pendente com `sem_regra_tributacao`.\n\nNão há verbo de update: para corrigir, crie a regra nova (com a vigência dela) e remova\na antiga.\n\n`tp_serv` (opcional) restringe a regra a um tipo de serviço (`ide/tpServ`: 0 normal,\n1 subcontratação, 2 redespacho, 3 redespacho intermediário). Regra com tipo casado vence\nqualquer regra só de rota, e é por ela que a transportadora declara o regime de cada tipo\n(ex.: `5360` + `ICMS45`/CST `51` para a subcontratação, `5351` + ICMS normal para o\nredespacho) sem mexer nas regras de rota. Sem regra do tipo, o contra-CT-e segue o\ncomportamento anterior (`5360`/`6360`, ou `5932`/`6932` quando a prestação começa em\noutra UF).\n\nOs seis campos de IBS/CBS (Reforma Tributária, LC 214/2025) são opcionais, mas formam um\nbloco: informar qualquer uma das três alíquotas faz a regra responder pelas três, e as\ndeixadas em branco valem zero. Em 2026, o ano-teste, a lei fixa os percentuais (IBS\n0,10% e CBS 0,90%) e o CT-e já os destaca sem cadastro; a partir de 2027 a rota sem\nregra de IBS/CBS tem a emissão do CT-e recusada antes do envio.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiscalTaxRuleCreate"}}}},"responses":{"201":{"$ref":"#/components/responses/FiscalTaxRuleCreated"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/fiscal/regras-tributacao/{ruleId}":{"delete":{"tags":["Regras de tributação"],"summary":"Remover regra de tributação","operationId":"deleteFiscalTaxRule","description":"Remove uma regra da transportadora autenticada. Regra inexistente ou regra de outra\ntransportadora respondem `404 regra_nao_encontrada` — o gateway nunca confirma por `403`\naquilo que não pertence à credencial.\n","parameters":[{"name":"ruleId","in":"path","required":true,"description":"ID inteiro da regra, devolvido na criação e na listagem.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"$ref":"#/components/responses/FiscalTaxRuleDeleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/FiscalTaxRuleNotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/consultas/rntrc":{"get":{"tags":["Consultas"],"summary":"Consultar a situação do RNTRC","operationId":"consultarRntrc","description":"Consulta a situação cadastral de um RNTRC na ANTT: se está ativo, a razão social, o\ntipo de transportador e se é equiparado a TAC.\n\n**Pré-requisito da empresa que consulta:** ter o cadastro fiscal concluído — com o\ncertificado digital A1 enviado em Configurações. Sem isso a resposta é `422` com\n`empresa_nao_habilitada`.\n\nExige o escopo `consultas` habilitado no painel.\n\n## Modo simulado em homologação\n\nEsta consulta **não tem provedor contratado** por trás: em homologação a resposta é\ngerada pela FleetPay, é determinística e **não tem efeito regulatório** — o dado não vem\nda ANTT e não reflete o cadastro real do transportador. Para deixar isso explícito na\nresposta, o campo `razao_social` **não traz o nome real**: em modo simulado ele é\nsubstituído por inteiro por `TRANSPORTES SIMULADOS HML LTDA` quando o `documento` é um\nCNPJ, ou por `TRANSPORTADOR AUTONOMO SIMULADO` quando é um CPF.\n\nO contrato de request e response já é o definitivo: integre agora. Quando o provedor real\nentrar, o comportamento deixa de ser simulado **sem mudança de contrato**.\n\n\n### O par `documento` + `rntrc` precisa conferir\n\nOs dois parâmetros são uma pergunta só: *\"a situação DESTE registro DESTE\ntransportador\"*. Um RNTRC que não seja o daquele CPF/CNPJ não descreve transportador\nnenhum, e a resposta é **`400` com `rntrc_nao_confere`** — nunca um `200` sobre o\ncadastro que por acaso foi encontrado.\n\nÉ `400` e não `503` porque a consulta rodou e concluiu: não houve indisponibilidade. E\nnão é `404` porque o que está errado é a **combinação** dos dois parâmetros, não um\nrecurso ausente no endereço.\n\nAs sentinelas abaixo são **isentas** dessa checagem — elas existem justamente para não\nserem o RNTRC de ninguém.\n\n### Sentinelas de teste\n\nEm modo simulado, estes valores de `rntrc` respondem sempre a mesma coisa — use-os para\nexercitar o caminho de erro da sua integração:\n\n| `rntrc` | Resposta |\n|---|---|\n| `000000000` | Registro inativo — `ativo: false`, e `data_validade` no passado |\n| `111111111` | Registro ativo e equiparado a TAC — `ativo: true` e `equiparado_tac: true` |\n| o RNTRC do transportador consultado | Resposta de sucesso |\n| qualquer outro valor válido | `400` `rntrc_nao_confere` |\n","parameters":[{"name":"documento","in":"query","required":true,"schema":{"type":"string","pattern":"^([0-9]{11}|[0-9]{14})$"},"description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do transportador consultado, somente dígitos."},{"name":"rntrc","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]{8,9}$"},"description":"RNTRC do transportador consultado, com 8 ou 9 dígitos.\n\nEm homologação, `000000000` devolve registro inativo e `111111111` devolve registro\nativo equiparado a TAC; qualquer outro valor válido devolve sucesso.\n"}],"responses":{"200":{"description":"Situação do RNTRC consultado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaConsultaRntrc"}}}},"400":{"description":"`rntrc_nao_confere` — o RNTRC informado não é o registro deste CPF/CNPJ.\n`validacao` — algum parâmetro está fora do formato exigido.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"422":{"description":"A empresa autenticada ainda não concluiu o cadastro fiscal (`empresa_nao_habilitada`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"503":{"description":"A consulta está temporariamente indisponível (`consulta_indisponivel`). Aguarde e tente de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/consultas/veiculo-pedagio":{"get":{"tags":["Consultas"],"summary":"Consultar o veículo no operador de pedágio","operationId":"consultarVeiculoPedagio","description":"O que a **operadora informada** sabe sobre uma placa: se o veículo **carrega tag** e\nse dá para **emitir Vale-Pedágio** para ele.\n\n## O contrato é multi-operadora\n\n`operadora` é obrigatória, e as quatro aceitas são as quatro emissoras de tag do\nmercado:\n\n| `operadora` | | Disponível hoje |\n|---|---|---|\n| `sem_parar` | Sem Parar | **Sim** |\n| `conectcar` | ConectCar | ainda não |\n| `veloe` | Veloe | ainda não |\n| `move_mais` | Move Mais | ainda não |\n\nOperadora real ainda não atendida responde `422` com `operadora_indisponivel` — código\n**diferente** do `400` de operadora inexistente, e a distinção importa: um pede\naguardar a operadora entrar, o outro pede corrigir a chamada. Quando uma nova operadora\nfor atendida, nada muda na sua integração: o campo e o código de erro já existem.\n\n**Pré-requisito da empresa que consulta:** ter o cadastro fiscal concluído — com o\ncertificado digital A1 enviado em Configurações. Sem isso a resposta é `422` com\n`empresa_nao_habilitada`.\n\nExige o escopo `consultas` habilitado no painel.\n\n## As duas perguntas são independentes\n\nEsta é a parte que uma integração costuma errar, e o contrato as mantém em campos\nseparados de propósito:\n\n| | `tem_tag` | `habilitado_vale_pedagio` |\n|---|---|---|\n| via automática | `true` | `true` |\n| **sem tag, mas pode rodar** | `false` | `true` |\n| **com tag, bloqueado pelo operador** | `true` | `false` |\n\nAs duas linhas do meio são o ponto. O **Vale-Pedágio tradicional não exige tag** — um\nveículo sem tag continua podendo receber vale. E um veículo com tag pode estar\nbloqueado pelo operador por outro motivo.\n\nSe você colapsar os dois campos num só, sua integração vai **recusar frete que podia\nrodar**.\n\n## `tem_tag` é resposta, não inferência\n\nNão deduza a ausência de tag de `identificador_tag` vir nulo. `tem_tag` é a resposta;\n`identificador_tag` é o código, e só acompanha quem tem tag.\n\n## `404` é diferente de \"sem tag\"\n\nPlaca que o operador não conhece responde `404 veiculo_nao_encontrado` — e isso pede\numa providência diferente de um veículo cadastrado sem tag:\n\n| Resposta | O que fazer |\n|---|---|\n| `404` | cadastrar o veículo no operador de pedágio |\n| `200` com `tem_tag: false` | emitir o Vale-Pedágio tradicional |\n\n## Modo simulado em homologação\n\nEsta consulta **não tem operadora contratada** por trás: em homologação a resposta é\ngerada pela FleetPay, é determinística e **não reflete o cadastro real de nenhum\nveículo**. Cada resposta carrega `verificacao: \"simulada\"` — o campo viaja dentro do\ndado, e não só no envelope, porque um `tem_tag` gravado na sua base precisa carregar\nconsigo que nenhuma consulta real aconteceu.\n\nO contrato de request e response já é o definitivo: integre agora.\n\n### Só os veículos da massa de teste respondem\n\nPlaca fora da massa responde `404` — **não existe resposta genérica**. Ela existiu por\num dia e saiu: qualquer placa digitada recebia uma tag fabricada com cara de real, e um\n`tem_tag: true` gravado na sua base não carrega aviso de que a placa nem existia.\n\n| Placa | Estado |\n|---|---|\n| `TJD2D33` | com tag, habilitado — a via automática |\n| `AKS1I02` | **sem tag**, e ainda assim habilitado — o vale tradicional não exige tag |\n| `FTO0C61` | com tag, **não habilitado** — tag não autoriza por si |\n| qualquer outra placa | `404 veiculo_nao_encontrado` |\n","parameters":[{"name":"placa","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z]{3}[0-9][A-Za-z0-9][0-9]{2}$"},"description":"Placa antiga (`ABC1234`) ou Mercosul (`ABC1D23`), sem separador.\n"},{"name":"operadora","in":"query","required":true,"schema":{"type":"string","enum":["sem_parar","conectcar","veloe","move_mais"]},"description":"A operadora de tag consultada. Hoje só `sem_parar` está disponível; as demais\nrespondem `422 operadora_indisponivel` até serem atendidas.\n"}],"responses":{"200":{"description":"O que o operador tem para a placa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaVeiculoPedagio"}}}},"400":{"description":"`validacao` — a placa está fora do formato aceito, ou não foi informada.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"404":{"description":"`veiculo_nao_encontrado` — a placa não está cadastrada nesta operadora. **Não** é\na mesma coisa que um veículo cadastrado sem tag: um pede cadastrar o veículo na\noperadora, o outro pede emitir o vale tradicional.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"`operadora_indisponivel` — a operadora existe, mas ainda não é atendida; a\nmensagem diz quais estão disponíveis. **Aguarde**, não corrija a chamada.\n`empresa_nao_habilitada` — a empresa autenticada ainda não concluiu o cadastro\nfiscal.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"503":{"description":"`consulta_indisponivel` — não foi possível consultar o operador.\n\n**Nunca trate isto como \"o veículo não tem tag\".** Guardar ausência de tag porque a\nconsulta falhou faria você parar de oferecer a via automática a um caminhão que a tem.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/consultas/frota":{"get":{"tags":["Consultas"],"summary":"Consultar a frota de um transportador (ANTT)","operationId":"consultarFrota","description":"Verifica, para uma lista de placas, se cada uma pertence à frota de um transportador no\nRNTRC (ANTT). A resposta traz, por placa, `pertence` (`true`/`false`, ou `null` quando a\nANTT não deu situação conclusiva).\n\n**Pré-requisito da empresa que consulta:** ter o cadastro fiscal concluído — com o\ncertificado digital A1 enviado em Configurações. Sem isso a resposta é `422` com\n`empresa_nao_habilitada`.\n\nExige o escopo `consultas` habilitado no painel.\n\n## Modo simulado em homologação\n\nEsta consulta **não tem provedor contratado** por trás: em homologação a resposta é\ngerada pela FleetPay, é determinística e **não tem efeito regulatório** — o dado não vem\nda ANTT e não reflete a frota real do transportador. Cada item de `frota` carrega\n`verificacao: \"simulada\"`, marcando a natureza da verificação por placa — e o campo é\nopcional por natureza: item **sem** `verificacao` é verificação real.\n\nO contrato de request e response já é o definitivo: integre agora. Quando o provedor real\nentrar, o comportamento deixa de ser simulado **sem mudança de contrato**.\n\n\n### O par `documento` + `rntrc` precisa conferir\n\nOs dois parâmetros são uma pergunta só: *\"a situação DESTE registro DESTE\ntransportador\"*. Um RNTRC que não seja o daquele CPF/CNPJ não descreve transportador\nnenhum, e a resposta é **`400` com `rntrc_nao_confere`** — nunca um `200` sobre o\ncadastro que por acaso foi encontrado.\n\nÉ `400` e não `503` porque a consulta rodou e concluiu: não houve indisponibilidade. E\nnão é `404` porque o que está errado é a **combinação** dos dois parâmetros, não um\nrecurso ausente no endereço.\n\nAs sentinelas abaixo são **isentas** dessa checagem — elas existem justamente para não\nserem o RNTRC de ninguém.\n\nRepare que a recusa do par é **diferente** de `pertence: null`. `null` é uma placa\ninconclusiva dentro de uma frota que existe; o `400` é a ausência de transportador\nsobre o qual responder — por isso ele não vem por placa, e sim no lugar da resposta\ninteira.\n\n### Sentinelas de teste\n\nEm modo simulado, estas placas respondem sempre a mesma coisa — use-as para exercitar o\ncaminho de erro da sua integração:\n\n| Placa | Resposta |\n|---|---|\n| `ZZZ0X00` | Placa fora da frota do transportador — `pertence: false` |\n| `ZZZ9X99` | Situação inconclusiva na ANTT — `pertence: null` |\n| qualquer outra placa válida | Resposta de sucesso |\n","parameters":[{"name":"documento","in":"query","required":true,"schema":{"type":"string","pattern":"^([0-9]{11}|[0-9]{14})$"},"description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do transportador consultado, somente dígitos."},{"name":"rntrc","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9]{8,9}$"},"description":"RNTRC do transportador consultado, com 8 ou 9 dígitos."},{"name":"placas","in":"query","required":true,"style":"form","explode":true,"schema":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","pattern":"^[A-Za-z]{3}[0-9][A-Za-z0-9][0-9]{2}$"}},"description":"Placas a verificar (1 a 20). Envie `placas[]=ABC1D23&placas[]=XYZ4E56`.\n\nEm homologação, `ZZZ0X00` devolve `pertence: false` e `ZZZ9X99` devolve\n`pertence: null`; qualquer outra placa válida devolve sucesso.\n"}],"responses":{"200":{"description":"Situação de cada placa na frota do transportador.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"documento":{"type":"string"},"rntrc":{"type":"string"},"frota":{"type":"array","items":{"type":"object","properties":{"placa":{"type":"string"},"pertence":{"type":"boolean","nullable":true},"verificacao":{"type":"string","description":"Natureza da verificação desta placa. Em homologação vem\n`simulada`: a situação não foi apurada na ANTT, foi gerada em\nmodo simulado e não tem efeito regulatório.\n\nO marcador viaja **dentro de cada item**, e não no envelope da\nresposta, para sobreviver a ingestões que guardam só a lista de\nplacas e descartam o envelope.\n\n**Trate o campo como opcional.** Ele só existe enquanto a\nverificação é simulada: item **sem** `verificacao` é verificação\nreal. Um parser que exija o campo quebra na virada para o\nprovedor real — leia por presença, não por obrigatoriedade.\n"}}}}}},"environment":{"$ref":"#/components/schemas/Environment"}}}}}},"400":{"description":"`rntrc_nao_confere` — o RNTRC informado não é o registro deste CPF/CNPJ, então não\nhá frota sobre a qual responder.\n`validacao` — alguma placa está fora do formato Mercosul, ou falta parâmetro.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"422":{"description":"A empresa autenticada ainda não concluiu o cadastro fiscal (`empresa_nao_habilitada`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"503":{"description":"A consulta está temporariamente indisponível (`consulta_indisponivel`). Aguarde e tente de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/convites/transportadoras":{"post":{"tags":["Convites"],"summary":"Convidar uma transportadora","operationId":"convidarTransportadora","description":"Convida uma transportadora para abrir conta na FleetPay.\n\n**Voce nao cadastra a transportadora — voce a apresenta.** O cadastro e conduzido pela\nFleetPay junto ao representante legal: e ele quem informa os dados que so ele tem, faz a\nbiometria e conclui a abertura da conta digital. Por isso o convite pede so dois campos.\n\nO convite chega por **WhatsApp** no numero informado. A partir dai o acompanhamento e da\nFleetPay.\n\n**O `telefone` e o celular do representante legal**, nao o telefone comercial da\ntransportadora — e com essa pessoa que a FleetPay vai conversar para abrir a conta. Um\nnumero errado significa um convite que nao chega a ninguem.\n\n**O documento pode ser CPF ou CNPJ.** Transportadora pessoa fisica (o transportador\nautonomo) e caso comum e e aceita aqui.\n\n**Chamar de novo e seguro.** Se a transportadora ja foi convidada — inclusive por outra\nempresa — a resposta e `200` com `status: ja_convidada`, e nenhum convite novo e enviado.\nSo o primeiro convite dispara mensagem.\n\n> Este endpoint **nao** abre conta e **nao** habilita ninguem a receber pagamento. Ele\n> inicia a conversa.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConviteTransportadoraRequest"}}}},"responses":{"200":{"description":"A transportadora ja havia sido convidada. Nenhum convite novo foi enviado. Nao e erro: e o resultado de chamar duas vezes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaConvite"}}}},"201":{"description":"Convite enviado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaConvite"}}}},"400":{"$ref":"#/components/responses/Erro400"},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/agregados":{"get":{"tags":["Agregados"],"summary":"Listar os seus agregados e a situação de cada um","operationId":"listarAgregados","description":"Lista quem trabalha para a sua empresa na FleetPay e responde a pergunta que importa:\n**este agregado já pode receber?**\n\nÉ o outro lado do convite. `POST /convites/transportadoras` inicia a conversa; este\nendpoint conta onde ela chegou, sem você precisar perguntar ao suporte.\n\n**Quem entra na lista** — o vínculo, não o cadastro que você fez:\n\n| `tipo` | Quem é |\n|---|---|\n| `motorista` | motorista agregado da sua empresa (ou de uma filial do seu grupo) |\n| `transportadora` | transportadora que você contrata, **ou** que você convidou |\n\nUma transportadora que você convidou aparece aqui **antes** de concluir o cadastro, com\n`cadastro: \"convidado\"` — é exatamente o intervalo em que você quer saber se ela andou.\nQuando ela conclui, a mesma linha passa a `cadastro: \"cadastrado\"` e a mostrar a conta.\n\n**O campo que decide é `conta.habilitado_a_receber`.** Ele já combina situação da conta,\nbiometria e bloqueio; `situacao`, `biometria` e `pendencia` existem para você explicar ao\nseu operador o que falta, não para você recalcular a regra.\n\n> Esta consulta **não** devolve número de conta nem chave PIX. Ela responde *se* o\n> agregado pode receber, não por onde — o pagamento continua sendo conduzido pela\n> FleetPay.\n","parameters":[{"name":"tipo","in":"query","required":false,"schema":{"type":"string","enum":["motorista","transportadora"]},"description":"Filtra por natureza do agregado. Ausente, traz os dois."},{"name":"pagina","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"por_pagina","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Máximo de 200 por página."}],"responses":{"200":{"description":"Lista dos agregados da sua empresa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaAgregados"}}}},"400":{"$ref":"#/components/responses/Erro400"},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/agregados/{documento}":{"get":{"tags":["Agregados"],"summary":"Consultar um agregado pelo CPF/CNPJ","operationId":"consultarAgregado","description":"O mesmo conteúdo da listagem, para um documento só — para quando você já sabe de quem\nestá falando e quer checar antes de disparar uma operação.\n\n**Documento que não é seu agregado responde `404`, não `403`.** É deliberado: um `403`\nconfirmaria que aquele CPF/CNPJ existe na FleetPay, e transformaria este endpoint num\nconsultor de base alheia. Um `404` aqui significa \"não é seu agregado\" — não significa,\nnecessariamente, que a pessoa não existe.\n","parameters":[{"name":"documento","in":"path","required":true,"schema":{"type":"string"},"description":"CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita com ou sem pontuação."}],"responses":{"200":{"description":"O agregado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaAgregado"}}}},"400":{"$ref":"#/components/responses/Erro400"},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"404":{"description":"Nenhum agregado com este documento está vinculado à sua empresa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/agregados/{documento}/chave-pix":{"get":{"tags":["Agregados"],"summary":"Conferir a chave PIX de um agregado","operationId":"conferirChavePixDoAgregado","description":"**A chave PIX que este agregado me passou é a mesma que consta com vocês?**\n\nVocê manda o par (documento, chave) e recebe sim/não. É a conferência que vale a pena\nfazer **antes** de o dinheiro sair — principalmente quando a chave chegou por e-mail,\nWhatsApp ou num cadastro que alguém digitou.\n\n**O caso que este endpoint existe para pegar é `situacao: \"chave_de_outro_titular\"`:** a\nchave é real, está na sua base, e está cadastrada para **outro** agregado seu. É a\nassinatura da troca de chave — o golpe em que o pagamento sai certinho para a conta\nerrada. Um `if (chave === chaveQueTenhoNoERP)` do seu lado não pega isso.\n\n| `situacao` | O que fazer |\n|---|---|\n| `vinculada` | Segue o pagamento. |\n| `chave_de_outro_titular` | **Pare.** Confirme com o favorecido por um canal que você já usava antes. |\n| `nao_cadastrada` | Olhe `documento_possui_chave` antes de decidir (abaixo). |\n\n> ### Isto NÃO é uma consulta ao DICT do Bacen\n>\n> A resposta é sobre **o que está cadastrado na FleetPay**, não sobre a titularidade da\n> chave no arranjo de pagamentos. `vinculada: false` quer dizer \"não é a chave que consta\n> aqui\" — **nunca** \"esta chave não é dessa pessoa\". Tratar o `false` como prova de fraude\n> barra pagamento legítimo de agregado que simplesmente nunca cadastrou chave externa com\n> a gente. É para isso que existe o `documento_possui_chave`: com `false`, a FleetPay não\n> tem chave nenhuma dessa pessoa e não há divergência a apontar; com `true`, a pessoa tem\n> chave cadastrada e ela é **outra**.\n\n**O que sai daqui:** sim/não sobre o par que você mesmo mandou. Nem a chave de terceiro,\nnem o dono dela — em `chave_de_outro_titular` o `titular` vai `null` de propósito, para a\nconferência não virar um diretório reverso chave → pessoa.\n\nA chave pode ser mandada como você a tem, com ou sem máscara: comparamos CPF, CNPJ e\ntelefone por dígitos (o `+55` é opcional) e e-mail/chave aleatória sem diferenciar caixa.\n\n**Documento que não é seu agregado responde `404`, não `403`** — mesma regra do\n`GET /agregados/{documento}`, para o endpoint não virar oráculo de enumeração de CPF/CNPJ.\n","parameters":[{"name":"documento","in":"path","required":true,"schema":{"type":"string"},"description":"CPF (11 dígitos) ou CNPJ (14 dígitos) do agregado. Aceita com ou sem pontuação."},{"name":"chave","in":"query","required":true,"schema":{"type":"string","maxLength":77},"description":"A chave PIX a conferir: CPF, CNPJ, e-mail, telefone (`+55DDDNÚMERO`) ou chave aleatória (UUID)."}],"responses":{"200":{"description":"O resultado da conferência","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaConferenciaChavePix"}}}},"400":{"$ref":"#/components/responses/Erro400"},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"404":{"description":"Nenhum agregado com este documento está vinculado à sua empresa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/carriers/parcelas-repasse/{documento}":{"get":{"tags":["Parcelas"],"summary":"Consultar as parcelas de repasse de um documento","operationId":"consultarParcelasRepasse","description":"O livro completo do repasse deste documento: quanto o motorista recebe, em quantas\nparcelas, em que estado cada uma está e qual já virou pagamento.\n\nÉ por aqui que você descobre **o que fazer em seguida** — o campo `status` diz se a parcela\nespera evento, espera a sua ordem de pagamento, ou já está a caminho.\n\nDocumento de outra transportadora responde `404`, não `403`: um `403` confirmaria que\naquele documento existe na FleetPay.\n","parameters":[{"name":"documento","in":"path","required":true,"schema":{"type":"string"},"description":"O ID interno FleetPay, o número do documento (`internal_id`) ou a chave do CT-e de 44\ndígitos. A chave aceita a máscara com pontos.\n\nPara **contra-CT-e** vale também o `counter_cte_id` (o UUID devolvido pelo lote de\nsubcontratação), o `documento_financeiro` da perna (`ROUTE:<lote>:<hex>`) e, depois\nde autorizado, a chave do próprio contra-CT-e. No 1:1 o documento é o CT-e da\ncontratante importado como seu — a chave dele resolve.\n"}],"responses":{"200":{"description":"As parcelas do documento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaParcelasRepasse"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"description":"Credencial sem o escopo `operacao` habilitado. O livro expõe quanto cada motorista recebe e quando — habilite o escopo no painel antes de consultar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Documento não encontrado, ou de outra transportadora.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"O documento existe e é seu, mas não está sob uma regra de repasse parcelada — não há\nlivro para mostrar (`regra_nao_parcelada`). Nos endpoints de liberação e ordem o mesmo\nestado responde `sem_regra_parcelada`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/carriers/parcelas-repasse/liberar":{"post":{"tags":["Parcelas"],"summary":"Liberar uma parcela","operationId":"liberarParcelaRepasse","description":"Declara que o evento âncora da parcela aconteceu no seu sistema.\n\n**Em regra MANUAL**, liberar deixa a parcela **apta** — e nada mais. Ela fica sem\nvencimento e sem pagamento, esperando a ordem de pagamento. Isso é deliberado: no modo\nmanual quem decide quando o dinheiro sai é você, e o vencimento é o momento dessa decisão,\nnão uma data derivada do evento.\n\n**Em regra AUTOMÁTICA**, os eventos internos já liberam sozinhos. Esta chamada serve como\ndestravamento de parcela presa, e aí ela grava o vencimento (evento + prazo da regra) e o\npagamento segue sem passo extra.\n\n`ocorrido_em` **pode ser retroativa** — o evento pode ter acontecido antes de alguém\nregistrar. Data futura é recusada: seria criar vencimento a partir de um evento que não\nocorreu.\n\nLiberar de novo é **no-op**, não erro: retry não vira parcela duplicada.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiberarParcelaRepasse"}}}},"responses":{"200":{"description":"Parcela liberada (ou já liberada — a chamada é idempotente)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaParcelaRepasse"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"description":"Credencial sem o escopo `operacao` habilitado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Documento não encontrado, ou de outra transportadora.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"A liberação foi recusada. O `code` é estável e é por ele que você deve ramificar:\n\n| `code` | O que fazer |\n|---|---|\n| `sem_regra_parcelada` | O documento não está sob regra parcelada — não há o que liberar. |\n| `parcela_inexistente` | A regra não tem parcela nessa posição. |\n| `evento_fora_de_ordem` | Libere a parcela anterior primeiro. |\n| `data_anterior_ao_evento_anterior` | A data informada é anterior ao evento da parcela anterior. |\n| `data_no_futuro` | Use uma data até hoje. |\n| `parcela_cancelada` | O CT-e foi cancelado na SEFAZ; esta parcela não vai pagar nada. |\n| `servico_ainda_nao_concluido` | A parcela de conclusão precisa vir antes da prestação de contas. |\n| `regra_sem_prestacao_de_contas` | Posição 3 numa regra que não tem a parcela de prestação de contas. |\n| `data_anterior_a_conclusao` | Posição 3 com data anterior à conclusão do serviço. |\n| `falha_ao_liberar` | Falha interna ao gravar a liberação; repita a chamada. |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/carriers/parcelas-repasse/pagar":{"post":{"tags":["Parcelas"],"summary":"Pagar uma parcela","operationId":"pagarParcelaRepasse","description":"A ordem de pagamento — o segundo ato do modo manual. Só se aplica a parcela que está\n**aguardando ordem de pagamento** (`status: 5`), o estado em que `liberar` a deixa.\n\n**Não move dinheiro na hora.** Esta chamada coloca a parcela na fila: o vencimento passa a\nser hoje, o pagamento é criado e o repasse é enviado ao banco no processamento seguinte —\nnormalmente em minutos. Se você espera ver o valor na conta do motorista no instante da\nresposta, vai concluir que falhou e chamar de novo.\n\n**Não aceita data**, e a ausência é a regra: no modo manual o vencimento é o instante desta\nchamada. Se você mandar `ocorrido_em` junto, o campo é **ignorado em silêncio** e o\nvencimento sai hoje do mesmo jeito — não é erro, é o campo do `liberar`, que aqui não\nexiste.\n\nRepetir a ordem é **no-op**: duplo clique e retry não viram segundo pagamento, e a data da\nprimeira ordem não é reescrita.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PagarParcelaRepasse"}}}},"responses":{"200":{"description":"Parcela na fila de pagamento (ou já estava — a chamada é idempotente)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaParcelaRepasse"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"description":"Credencial sem o escopo `operacao` habilitado. Esta porta manda pagar — o escopo existe para que só quem pode mover dinheiro a acione.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Documento não encontrado, ou de outra transportadora.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"A ordem foi recusada. O `code` é estável:\n\n| `code` | O que fazer |\n|---|---|\n| `parcela_nao_liberada` | Chame `liberar` antes — a parcela ainda espera o evento. |\n| `parcela_anterior_sem_ordem` | Mande pagar a parcela anterior primeiro. |\n| `servico_inexistente` | O serviço deste documento ainda não existe; a conclusão precisa vir antes. |\n| `parcela_inexistente` | A regra não tem parcela nessa posição. |\n| `parcela_cancelada` | O CT-e foi cancelado na SEFAZ. |\n| `sem_regra_parcelada` | O documento não está sob regra parcelada. |\n| `documento_cancelado` | O documento financeiro foi invalidado; não há repasse a pagar mesmo que a parcela tenha ficado aberta. |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/carriers/parcelas-repasse/liberar-por-mdfe":{"post":{"tags":["Parcelas"],"summary":"Liberar a parcela N de todos os CT-e de um MDF-e","operationId":"liberarParcelasPorMdfe","description":"A liberação em **lote pelo manifesto**: informe o MDF-e (uuid, chave de acesso ou número)\ne a posição, e a FleetPay aplica `liberar` a cada CT-e vinculado à viagem — inclusive os\ncontra-CT-e de um lote de subcontratação — devolvendo **um resultado por CT-e**. Uma recusa\nnuma linha não impede as outras.\n\nTrês regras que valem a pena saber antes de chamar:\n\n- **Só parcelas que já existem.** A parcela nasce na bipagem; o MDF-e não é tratado como\n  evento de coleta. CT-e do manifesto ainda sem parcela na posição responde\n  `recusada / parcela_inexistente` na linha dele.\n- **Só o condutor do MDF-e.** Parcela de outro motorista é `ignorado / motorista_divergente`.\n- **Mesmas regras da liberação unitária** (`evento_fora_de_ordem`, `parcela_cancelada`...),\n  e a mesma idempotência: parcela já liberada é `ja_liberada`, não erro.\n\nO MDF-e pode estar em rascunho — ele é só o seletor dos CT-e. Manifesto de outra\ntransportadora ou inexistente responde `404`; manifesto sem CT-e, `422`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiberarParcelasPorMdfe"}}}},"responses":{"200":{"description":"O MDF-e foi processado; leia `resumo` e `documentos[].resultado`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaParcelasPorMdfe"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"description":"Credencial sem o escopo `operacao` habilitado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"MDF-e não encontrado, ou de outra transportadora (`mdfe_nao_encontrado`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"MDF-e sem CT-e vinculado (`mdfe_sem_documentos`), ou payload inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/carriers/parcelas-repasse/pagar-por-mdfe":{"post":{"tags":["Parcelas"],"summary":"Ordenar o pagamento da parcela N de todos os CT-e de um MDF-e","operationId":"pagarParcelasPorMdfe","description":"Gêmea de `pagar`, em lote pelo manifesto: aplica a ordem de pagamento da posição a cada\nCT-e do MDF-e e devolve um resultado por CT-e (`ordenada`, `ja_ordenada`, `recusada`,\n`ignorado`). Valem as regras da ordem unitária — parcela precisa estar liberada\n(`parcela_nao_liberada`), a anterior precisa ter ordem (`parcela_anterior_sem_ordem`) e o\nserviço precisa existir (`servico_inexistente`). Parcela em modo automático já liberada\nresponde `ja_ordenada`: não há ordem manual a dar.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PagarParcelasPorMdfe"}}}},"responses":{"200":{"description":"O MDF-e foi processado; leia `resumo` e `documentos[].resultado`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaParcelasPorMdfe"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"description":"Credencial sem o escopo `operacao` habilitado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"MDF-e não encontrado, ou de outra transportadora (`mdfe_nao_encontrado`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"MDF-e sem CT-e vinculado (`mdfe_sem_documentos`), ou payload inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/vale-pedagio/roteirizar":{"post":{"tags":["Vale-Pedágio (VPO)"],"summary":"Roteirizar trajeto e calcular tarifas de pedágio","operationId":"roteirizarValePedagio","description":"Calcula o trajeto rodoviário entre origem e destino, identificando as praças de pedágio no percurso,\nvalores tarifários unitários para a quantidade de eixos informada e os custos consolidados por modalidade\nde rota (`planejada`, `estendida` e `customizada`).\n\nPara forçar o trajeto (rodovia específica, rota do seu roteirizador), informe `pontos_parada` — cidades\nou coordenadas intermediárias, na ordem da viagem. A operadora traça a rota por esses pontos e devolve as\npraças; a compra (`/vale-pedagio/comprar`) usa as praças da rota escolhida, não a geometria.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CotarVpoRequest"}}}},"responses":{"200":{"description":"Rotas e tarifas de pedágio calculadas com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CotarVpoResponse"}}}},"400":{"$ref":"#/components/responses/Erro400"},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/vale-pedagio/cotacao":{"post":{"tags":["Vale-Pedágio (VPO)"],"summary":"Cotação de rotas e tarifas de Vale-Pedágio","operationId":"cotarValePedagio","description":"Alias do endpoint de roteirização para simulação e cotação de custos do Vale-Pedágio.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CotarVpoRequest"}}}},"responses":{"200":{"description":"Cotação calculada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CotarVpoResponse"}}}},"400":{"$ref":"#/components/responses/Erro400"},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/vale-pedagio/comprar":{"post":{"tags":["Vale-Pedágio (VPO)"],"summary":"Comprar e emitir Vale-Pedágio Obrigatório (VPO)","operationId":"comprarValePedagio","description":"Efetiva a compra e emissão do Vale-Pedágio Obrigatório perante a ANTT e a operadora credenciada.\n\nO valor total (tarifas de pedágio + tarifa de serviço da modalidade) é **debitado instantaneamente\nda Conta Operacional Swap** da empresa contratante/embarcadora.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmitirVpoRequest"}}}},"responses":{"201":{"description":"Vale-Pedágio emitido e registrado com sucesso na ANTT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmitirVpoResponse"}}}},"400":{"$ref":"#/components/responses/Erro400"},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"422":{"description":"Saldo insuficiente na Conta Operacional ou erro de validação da operadora","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/vale-pedagio/{uuid}":{"get":{"tags":["Vale-Pedágio (VPO)"],"summary":"Consultar detalhes de um Vale-Pedágio","operationId":"consultarValePedagio","description":"Consulta o status, dados da emissão, número de registro ANTT, NSU e comprovante de um Vale-Pedágio.\n","parameters":[{"$ref":"#/components/parameters/VpoUuid"}],"responses":{"200":{"description":"Dados do Vale-Pedágio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetalhesVpoResponse"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"404":{"description":"Vale-Pedágio não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/vale-pedagio/{uuid}/cancelar":{"post":{"tags":["Vale-Pedágio (VPO)"],"summary":"Cancelar Vale-Pedágio Obrigatório","operationId":"cancelarValePedagio","description":"Cancela o Vale-Pedágio perante a ANTT e a operadora credenciada.\n\n**Regra estrita de 3 horas:** O cancelamento é aceito estritamente dentro da janela regulamentar de\naté 3 horas após a emissão e antes do uso em praça de pedágio. O saldo debitado é estornado integralmente\nna Conta Operacional Swap da empresa.\n","parameters":[{"$ref":"#/components/parameters/VpoUuid"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelarVpoRequest"}}}},"responses":{"200":{"description":"Vale-Pedágio cancelado com sucesso e saldo estornado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelarVpoResponse"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"404":{"description":"Vale-Pedágio não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"Cancelamento recusado (prazo de 3 horas expirado ou já utilizado)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/vale-pedagio/{uuid}/recibo":{"get":{"tags":["Vale-Pedágio (VPO)"],"summary":"Obter recibo/comprovante do Vale-Pedágio","operationId":"obterReciboValePedagio","description":"Obtém os dados do comprovante e cupom oficial emitido pela operadora para impressão ou guarda documental.\n","parameters":[{"$ref":"#/components/parameters/VpoUuid"}],"responses":{"200":{"description":"Recibo do Vale-Pedágio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReciboVpoResponse"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"404":{"description":"Vale-Pedágio não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}},"/vale-pedagio/{uuid}/complemento":{"post":{"tags":["Vale-Pedágio (VPO)"],"summary":"Emitir Vale-Pedágio complementar por desvio de rota","operationId":"emitirComplementoValePedagio","description":"Emite um Vale-Pedágio complementar vinculado a um VPO existente em decorrência de desvio\nautorizado de trajeto ou acréscimo de praças de pedágio.\n","parameters":[{"$ref":"#/components/parameters/VpoUuid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmitirVpoRequest"}}}},"responses":{"201":{"description":"Vale-Pedágio complementar emitido com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComplementoVpoResponse"}}}},"401":{"$ref":"#/components/responses/Erro401"},"403":{"$ref":"#/components/responses/Erro403"},"404":{"description":"Vale-Pedágio de origem não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"422":{"description":"Saldo insuficiente ou erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"$ref":"#/components/responses/Erro429"},"500":{"$ref":"#/components/responses/Erro500"}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth2 `client_credentials` — a forma recomendada. Gere `client_id` e\n`client_secret` no painel FleetPay em **Configurações → API de Integração**\n(o secret é mostrado uma única vez). O access token é um JWT com validade de\n1 hora, enviado como `Authorization: Bearer`; não há refresh token — quando\nexpirar, emita outro.\n\nA autorização não vem de escopos OAuth: vem dos escopos habilitados no painel\n(`fiscal`, `operacao`, `cadastros`, `consultas`), que valem para as duas formas\nde autenticação.\n","flows":{"clientCredentials":{"tokenUrl":"https://api.fleetpay.tech/oauth/token","scopes":{}}}},"chaveApi":{"type":"http","scheme":"bearer","bearerFormat":"fp_hml_...","description":"Chave de API estática no header `Authorization: Bearer`. Chaves novas nascem com\no prefixo do ambiente (`fp_hml_` homologação, `fp_prd_` produção); chaves antigas\nsem prefixo continuam valendo. A chave é por ambiente: a de homologação não\nfunciona em produção e vice-versa (a recusa é um `401` dirigido).\n"}},"responses":{"FiscalTaxRulesOk":{"description":"Regras de tributação da transportadora autenticada.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiscalTaxRuleListEnvelope"}}}},"FiscalTaxRuleCreated":{"description":"Regra criada para a transportadora autenticada, com o `cst` e o `icms_variante_rotulo`\njá derivados.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiscalTaxRuleEnvelope"}}}},"FiscalTaxRuleDeleted":{"description":"Regra removida.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiscalTaxRuleDeleteEnvelope"}}}},"FiscalTaxRuleNotFound":{"description":"`regra_nao_encontrada` — a regra não existe ou pertence a outra transportadora. Os dois\ncasos respondem igual, de propósito.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Erro400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"Erro401":{"description":"Não autenticado (`autenticacao`): credencial ausente, inválida ou expirada — inclusive chave de API usada no ambiente errado. A chave de homologação não vale em produção, nem a de produção em homologação; a mensagem do erro indica o ambiente esperado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"Erro403":{"description":"Escopo não habilitado para esta credencial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"Erro429":{"description":"Limite de requisições excedido (`limite_requisicoes`). Aguarde o intervalo indicado no header `Retry-After` antes de repetir. Pode vir do provedor, repassado, ou do teto anti-abuso da própria FleetPay — contado por empresa autenticada e por grupo de rotas, com uma janela curta que pega a rajada e uma longa que pega o robô lento. Os tetos são folgados de propósito: integração real, inclusive lote grande processado de uma vez, não chega perto deles. Se a sua chegar, fale com a FleetPay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"Erro500":{"description":"Erro interno (`erro_interno`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"StatusOk":{"description":"Acesso fiscal disponível para a transportadora.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusEnvelope"}}}},"FiscalConfigurationOk":{"description":"Configuração fiscal da transportadora autenticada.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiscalConfigurationEnvelope"}}}},"CertificateOk":{"description":"Metadados do certificado digital da transportadora.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateEnvelope"}}}},"CertificateCreated":{"description":"Certificado digital enviado e metadados atualizados.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateEnvelope"}}}},"CertificateDeleted":{"description":"Resultado da remoção do certificado digital.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateDeleteEnvelope"}}}},"CataloguesOk":{"description":"Domínios fiscais vigentes.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CataloguesEnvelope"}}}},"DashboardOk":{"description":"Indicadores fiscais da transportadora.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardEnvelope"}}}},"NfeListOk":{"description":"Página de NF-e.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfeListEnvelope"}}}},"NfeOk":{"description":"NF-e encontrada.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfeEnvelope"}}}},"NfeImportCreated":{"description":"Lote processado e relatório de importação criado.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfeImportEnvelope"}}}},"EmittedCteAccepted":{"description":"CT-e recebido pela primeira vez e encaminhado ao processamento.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmittedCteEnvelope"}}}},"EmittedCteAlreadyKnown":{"description":"Documento já entregue antes. A operação é idempotente: nada é reprocessado e\n`first_reception` vem `false`.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmittedCteEnvelope"}}}},"InboundCteListOk":{"description":"Página de CT-e recebidos.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundCteListEnvelope"}}}},"InboundCteOk":{"description":"CT-e recebido encontrado.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundCteEnvelope"}}}},"InboundCteReceived":{"description":"Primeira chegada deste documento; o recurso foi criado.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundCteReceiptEnvelope"}}}},"InboundCteReceivedAgain":{"description":"Documento já conhecido. A entrega é idempotente: o mesmo recurso volta, com\n`received_count` somado.\n","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundCteReceiptEnvelope"}}}},"CteListOk":{"description":"Página de CT-e.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteListEnvelope"}}}},"CteOk":{"description":"CT-e encontrado.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteEnvelope"}}}},"CtePreviewOk":{"description":"Prévia montada sem efetivar a emissão.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CtePreviewEnvelope"}}}},"CteQueryOk":{"description":"Consulta concluída; verifique `authorization.outcome`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteQueryEnvelope"}}}},"CteQueryPending":{"description":"Autorização pendente ou temporariamente indisponível; mantenha o polling.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"description":"Pode ser informado pelo gateway; se ausente, aplique backoff no cliente.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteQueryEnvelope"}}}},"CteEventOk":{"description":"Evento concluído.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteEventEnvelope"}}}},"CteEventPending":{"description":"Evento registrado localmente e pendente de reconciliação.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CteEventEnvelope"}}}},"CiotCheckOk":{"description":"Validação executada; o CIOT pode ser emitido.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CiotCheckEnvelope"}}}},"CiotCreated":{"description":"CIOT registrado.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CiotOperationEnvelope"}}}},"CiotOk":{"description":"Operação de CIOT concluída.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CiotOperationEnvelope"}}}},"CiotPending":{"description":"Operação de CIOT ainda pendente ou ambígua; consulte novamente.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CiotOperationEnvelope"}}}},"VehicleListOk":{"description":"Veículos ativos.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleListEnvelope"}}}},"VehicleCreated":{"description":"Veículo cadastrado.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleEnvelope"}}}},"VehicleOk":{"description":"Veículo atualizado.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleEnvelope"}}}},"DriverListOk":{"description":"Motoristas da transportadora.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverListEnvelope"}}}},"DriverOk":{"description":"Perfil fiscal atualizado.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverEnvelope"}}}},"MdfeListOk":{"description":"Página de MDF-e.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MdfeListEnvelope"}}}},"MdfeOk":{"description":"MDF-e encontrado.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MdfeEnvelope"}}}},"MdfeOperationOk":{"description":"Operação de MDF-e concluída.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MdfeOperationEnvelope"}}}},"MdfeOperationPending":{"description":"Operação de MDF-e ainda pendente; consulte novamente.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MdfeOperationEnvelope"}}}},"Unauthorized":{"description":"Chave de API FleetPay ausente ou inválida.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"Escopo fiscal desabilitado na chave, ou chave sem transportadora ativa.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Recurso não encontrado no tenant autenticado.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationFailed":{"description":"Payload inválido.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"BusinessRuleFailed":{"description":"Pendência ou regra de negócio impediu a operação.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ValidationOrBusinessRuleFailed":{"description":"Payload inválido, pendência ou regra de negócio.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalError":{"description":"Falha interna sem detalhes de integrações operacionais.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServiceUnavailable":{"description":"Não foi possível confirmar ou obter o resultado agora. Consulte antes de repetir comandos.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Limite por transportadora excedido.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"description":"Segundos até uma nova tentativa.","required":true,"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"schemas":{"FiscalTaxRuleIcmsVariant":{"type":"string","enum":["ICMS00","ICMS20","ICMS45","ICMS60","ICMS90","ICMSOutraUF","ICMSSN"],"description":"Variante de ICMS que a regra aplica ao CT-e."},"ContraCteLoteParcela":{"type":"object","required":["posicao","percentual","dias"],"properties":{"posicao":{"type":"integer","minimum":1,"maximum":3,"description":"1 = bipagem, 2 = conclusão no app, 3 = prestação de contas."},"percentual":{"type":"integer","minimum":1,"maximum":100},"dias":{"type":"integer","minimum":0,"maximum":30,"description":"Prazo em dias a partir do evento da parcela."}}},"ContraCteLoteRota":{"type":"object","properties":{"uf":{"type":"string","minLength":2,"maxLength":2},"municipio":{"type":"string","maxLength":120},"codigo_municipio":{"type":"string","pattern":"^\\d{7}$","description":"Código IBGE, 7 dígitos; precisa pertencer à `uf`."}}},"ContraCteLotePerna":{"type":"object","description":"Um trecho do CT-e da contratante. `motorista`/`placa` ausentes herdam os do lote; `valor`\né obrigatório quando o lote não usa `valores.frete_bruto`. Duas pernas com o mesmo trecho\nna mesma chave são recusadas.\n","properties":{"leg_ref":{"type":["string","null"],"maxLength":64,"description":"Rótulo seu para reconhecer a perna no relatório (`results[].ref` traz o caminho `ctes.i.pernas.j`)."},"motorista":{"type":"object","properties":{"cpf":{"type":"string","pattern":"^\\d{11}$"}}},"placa":{"type":"string","pattern":"^[A-Za-z]{3}[0-9][A-Za-z0-9][0-9]{2}$"},"valor":{"type":["number","null"],"minimum":0.01},"origem":{"$ref":"#/components/schemas/ContraCteLoteRota"},"destino":{"$ref":"#/components/schemas/ContraCteLoteRota"},"tipo_servico":{"type":["integer","null"],"enum":[1,2,3,null],"description":"Tipo de serviço da perna; ausente herda o da chave e depois o do lote (padrão `1`). Em `2`/`3` a perna precisa de `origem` e `destino`."}}},"ContraCteLoteItem":{"type":"object","required":["chave"],"properties":{"chave":{"type":"string","minLength":44,"maxLength":44,"description":"Chave de acesso do CT-e da contratante (44 dígitos, DV válido). Não repita a mesma chave no lote."},"valor":{"type":["number","null"],"minimum":0.01,"description":"Valor do contra-CT-e desta chave (modo por documento). Exclusivo com `valores.frete_bruto`."},"origem":{"$ref":"#/components/schemas/ContraCteLoteRota"},"destino":{"$ref":"#/components/schemas/ContraCteLoteRota"},"tipo_servico":{"type":["integer","null"],"enum":[1,2,3,null],"description":"Tipo de serviço desta chave (`1` subcontratação, `2` redespacho, `3` redespacho intermediário); ausente herda o do lote. Em `2`/`3` a chave (ou o lote) precisa de `origem` e `destino`."},"pernas":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ContraCteLotePerna"}}}},"ContraCteLoteInput":{"type":"object","required":["ctes","motorista","placa"],"properties":{"ctes":{"type":"array","minItems":1,"description":"Cada item é a chave (string) ou um objeto com `chave` e os campos opcionais.","items":{"oneOf":[{"type":"string","minLength":44,"maxLength":44},{"$ref":"#/components/schemas/ContraCteLoteItem"}]}},"motorista":{"type":"object","required":["cpf"],"properties":{"cpf":{"type":"string","description":"CPF do motorista (com ou sem pontuação). No lote de pernas é o padrão das pernas sem motorista próprio."}}},"placa":{"type":"string","pattern":"^[A-Za-z]{3}[0-9][A-Za-z0-9][0-9]{2}$"},"valores":{"type":"object","properties":{"frete_bruto":{"type":"number","minimum":0.01,"description":"Rateia `total ÷ N` entre as chaves/pernas (resíduo de centavos nas últimas). Exclusivo com `valor` por chave/perna."}}},"origem":{"$ref":"#/components/schemas/ContraCteLoteRota"},"destino":{"$ref":"#/components/schemas/ContraCteLoteRota"},"tipo_servico":{"type":["integer","null"],"enum":[1,2,3,null],"description":"`ide/tpServ` dos contra-CT-e do lote: `1` subcontratação (padrão), `2` redespacho,\n`3` redespacho intermediário. Sobrescrevível por chave (`ctes[].tipo_servico`) e por\nperna (`pernas[].tipo_servico`). Em `2`/`3` o trecho (`origem` e `destino`) é obrigatório.\n"},"repasse":{"type":"object","required":["parcelas"],"description":"**Opcional.** Sem este bloco o lote é **só fiscal**: emite os contra-CT-e e não cria grupo de\nrepasse, parcela, ROUTE de perna nem neutraliza o repasse da origem — as linhas emitidas voltam\ncom `financeiro: \"nenhum\"`. Com o bloco, o CT-e de origem — na conta da **contratante** — entra\nnum grupo de repasse dela com estas parcelas e o motorista do lote: quem paga o motorista é a\ncontratante, e a subcontratada nunca ganha documento financeiro. O payments manda o dinheiro\npara a conta de motorista (PF) ou para a Conta Operação da transportadora dele (PJ). Exige o\nopt-in da contratante; sem ele a linha volta `financeiro: \"nenhum\"` com\n`motivo: contratante_sem_opt_in`.\n","properties":{"parcelas":{"type":"array","minItems":1,"maxItems":3,"description":"Posições contíguas a partir de 1; percentuais somam 100.","items":{"$ref":"#/components/schemas/ContraCteLoteParcela"}}}},"referencia_externa":{"type":["string","null"],"maxLength":64,"description":"Identificador seu, devolvido em `external_reference`."},"subcontratada":{"type":"object","required":["cnpj"],"description":"**Em nome da subcontratada.** A chamada é da CONTRATANTE (chave de API dela) e o lote nasce\nna conta da subcontratada deste CNPJ — certificado, numeração, caixa fiscal, motorista e\nveículo dela. Exige a autorização concedida pela subcontratada em\n`POST /fiscal/cte-subcontratacao/autorizacoes`; sem ela, `403 emissao_nao_autorizada`;\nCNPJ que não é cliente, `404 subcontratada_nao_encontrada`. O próprio CNPJ é aceito e não\nmuda nada. Com `repasse`, o opt-in da contratante é implícito: ela mesma pediu a emissão.\n","properties":{"cnpj":{"type":"string","description":"CNPJ da subcontratada (com ou sem pontuação)."}}}}},"ContraCteLoteAccepted":{"type":"object","properties":{"batch_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["processing"]},"total":{"type":"integer"},"expected_document_count":{"type":"integer"}}},"ContraCteLoteAcceptedEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContraCteLoteAccepted"},"environment":{"$ref":"#/components/schemas/Environment"}}},"ContraCteLoteResult":{"type":"object","description":"Uma linha do relatório — uma chave (1:1) ou uma perna.","properties":{"chave":{"type":"string"},"ref":{"type":"string","description":"Só nas pernas — o caminho da perna no payload (`ctes.0.pernas.2`)."},"status":{"type":"string","enum":["pending","emitted","duplicated","failed"]},"counter_cte_id":{"type":"string","format":"uuid","description":"UUID do contra-CT-e (em `emitted`, `duplicated` e nas falhas em que o rascunho já existia)."},"outcome":{"type":"string","description":"Resultado da aceitação pelo provedor (ex.: `accepted`)."},"tipo_servico":{"type":"integer","enum":[1,2,3],"description":"O `ide/tpServ` com que a chave/perna saiu (perna → chave → lote → `1`). Na linha `duplicated` é o tipo pedido; o do contra-CT-e existente está em `GET /fiscal/cte/{counter_cte_id}` (`service_type`)."},"documento_financeiro":{"type":"string","description":"Só nas pernas — `internal_id` do documento da perna (`ROUTE:<lote>:<hex>`)."},"financeiro":{"type":"string","enum":["failed","nenhum","contratante","ja_configurado"],"description":"O passo financeiro da chave emitida: `nenhum` (lote sem `repasse`, ou com `repasse` mas sem\nvínculo — veja `motivo`), `contratante` (o CT-e de origem entrou no grupo de repasse da\ncontratante),\n`ja_configurado` (a origem já tinha repasse na contratante e não foi sobrescrita).\n`failed`: o provedor aceitou o documento mas a perna financeira falhou.\n"},"motivo":{"type":"string","enum":["contratante_nao_encontrada","contratante_sem_opt_in","origem_nao_encontrada_na_contratante","motorista_nao_vinculado_a_contratante","origem_ja_faturada_na_contratante"],"description":"Só com `repasse` e `financeiro: \"nenhum\"` — por que a contratante não recebeu o vínculo.\n"},"reason":{"type":"string","description":"Motivo da recusa/duplicidade. Códigos estáveis: `cte_proprio`, `sem_regra_tributacao`,\n`origem_ja_subcontratada_1a1`, `origem_ja_subcontratada_em_pernas`,\n`redespacho_exige_rota` (tipo 2/3 com o trecho igual à viagem inteira da contratante),\n`origem_incompativel_com_tipo` (origem vinculada a multimodal); os demais são\ntexto (ex.: \"contra-CT-e já existe\", \"CT-e original não recebido\").\n"},"message":{"type":"string"},"valor":{"type":"string","description":"Valor congelado da chave (modo por documento), enquanto `pending`."},"driver_user_id":{"type":"integer","description":"Só nas pernas, enquanto `pending`."}}},"ContraCteLote":{"type":"object","properties":{"batch_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["processing","done","failed"]},"external_reference":{"type":["string","null"]},"total":{"type":"integer"},"emitted":{"type":"integer"},"duplicated":{"type":"integer"},"failed":{"type":"integer"},"em_nome_de":{"type":["object","null"],"description":"Presente quando o lote foi disparado pela contratante em nome da subcontratada; traz o CNPJ da emissora.","properties":{"cnpj":{"type":"string"}}},"repasse_group_ref":{"type":"string","description":"Referência do grupo de repasse do lote (nas pernas, cada motorista tem `<batch_id>:m<driver_user_id>`)."},"results":{"type":"array","items":{"$ref":"#/components/schemas/ContraCteLoteResult"}},"error_message":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"ContraCteLoteEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ContraCteLote"},"environment":{"$ref":"#/components/schemas/Environment"}}},"LiberarParcelasPorMdfe":{"type":"object","required":["mdfe","posicao","ocorrido_em"],"properties":{"mdfe":{"type":"string","maxLength":64,"description":"UUID do MDF-e, chave de acesso (44) ou número."},"posicao":{"type":"integer","minimum":1,"maximum":3},"ocorrido_em":{"type":"string","format":"date","description":"Data do evento; hoje ou passado."}}},"PagarParcelasPorMdfe":{"type":"object","required":["mdfe","posicao"],"properties":{"mdfe":{"type":"string","maxLength":64},"posicao":{"type":"integer","minimum":1,"maximum":3}}},"ParcelaPorMdfeLinha":{"type":"object","properties":{"cte_uuid":{"type":"string","format":"uuid"},"chave_cte":{"type":["string","null"]},"documento_id":{"type":["integer","null"]},"documento_numero":{"type":["string","null"],"description":"O `internal_id` do documento financeiro (chave da origem no 1:1; `ROUTE:...` na perna)."},"resultado":{"type":"string","enum":["liberada","ja_liberada","ordenada","ja_ordenada","recusada","ignorado"]},"motivo":{"type":["string","null"],"description":"Em `recusada`, o mesmo código do endpoint unitário; em `ignorado`, `sem_documento_financeiro` ou `motorista_divergente`."},"mensagem":{"type":["string","null"]},"parcela":{"oneOf":[{"$ref":"#/components/schemas/ParcelaRepasse"},{"type":"null"}]}}},"RespostaParcelasPorMdfe":{"type":"object","properties":{"data":{"type":"object","properties":{"mdfe":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"numero":{"type":["integer","null"]},"serie":{"type":["string","null"]},"chave":{"type":["string","null"]},"status":{"type":"string"},"motorista_id":{"type":["integer","null"]}}},"posicao":{"type":"integer"},"resumo":{"type":"object","description":"Contagem por `resultado` (`documentos`, `liberada`, `ja_liberada`, `ordenada`, `ja_ordenada`, `recusada`, `ignorado`).","additionalProperties":{"type":"integer"}},"documentos":{"type":"array","items":{"$ref":"#/components/schemas/ParcelaPorMdfeLinha"}}}}}},"FiscalTaxRuleCreate":{"type":"object","required":["cfop","icms_variante"],"description":"`cfop` e `icms_variante` são sempre obrigatórios. `aliquota` é obrigatória em `ICMS00`,\n`ICMS20`, `ICMS90` e `ICMSOutraUF` e proibida nas demais; `p_red_bc` é obrigatória em\n`ICMS20`, `ICMS90` e `ICMSOutraUF` e proibida nas demais (enviar fora da variante\nresponde `422`). Os outros campos são opcionais e anuláveis. A vigência é filtro:\nregra fora da janela `valid_from`/`valid_until` não é considerada na emissão.\n\nOs campos de IBS/CBS formam um bloco: informar qualquer uma das três alíquotas\n(`ibs_uf_aliquota`, `ibs_mun_aliquota`, `cbs_aliquota`) faz a regra responder pelas\ntrês, e as deixadas em branco valem zero — zero também é decisão tributária. As\nalíquotas aceitam 4 casas decimais porque as reduções da LC 214/2025 produzem\npercentuais como `0.8825`.\n","properties":{"origin_state":{"type":["string","null"],"minLength":2,"maxLength":2,"description":"UF de origem; `null` (ou omitido) = qualquer origem."},"destination_state":{"type":["string","null"],"minLength":2,"maxLength":2,"description":"UF de destino; `null` (ou omitido) = qualquer destino."},"tp_serv":{"type":["integer","null"],"enum":[0,1,2,3,null],"description":"Tipo de serviço (`ide/tpServ`) a que a regra se aplica; `null` (ou omitido) =\nqualquer tipo. `0` normal, `1` subcontratação, `2` redespacho, `3` redespacho\nintermediário; o `4` (multimodal) não é aceito. Regra com tipo casado vence\nqualquer regra só de rota.\n"},"cfop":{"type":["string","null"],"pattern":"^\\d{4}$","description":"Obrigatório. CFOP que o motor grava na prestação. Nos contra-CT-e com regra sem\n`tp_serv` só empresta o dígito de operação (5xxx/6xxx) e o código final vem da rota\n(`5360`/`6360` ou `5932`/`6932`); com regra do tipo, o CFOP dela é mantido quando a\nprestação começa na UF do emitente (o `5932`/`6932` de prestação iniciada em outra UF\ncontinua imposto).\n"},"icms_variante":{"$ref":"#/components/schemas/FiscalTaxRuleIcmsVariant"},"cst":{"type":["string","null"],"enum":["40","41","51",null],"description":"Só para `ICMS45`, e nela é obrigatório (`40`, `41` ou `51`). Nas demais variantes o\ncampo é ignorado — o CST é derivado da variante no servidor (`ICMS00`→`00`,\n`ICMS20`→`20`, `ICMS60`→`60`, `ICMS90`/`ICMSOutraUF`/`ICMSSN`→`90`).\n"},"aliquota":{"type":["number","null"],"format":"double","minimum":0,"maximum":100,"description":"Percentual do ICMS. Obrigatório em `ICMS00`, `ICMS20`, `ICMS90` e `ICMSOutraUF`;\nproibido em `ICMS45`, `ICMS60` e `ICMSSN`.\n"},"p_red_bc":{"type":["number","null"],"format":"double","minimum":0,"maximum":100,"description":"Redução da base de cálculo do ICMS, em percentual. Obrigatória em `ICMS20`,\n`ICMS90` e `ICMSOutraUF`; proibida nas demais variantes.\n"},"ibs_cbs_cst":{"type":["string","null"],"pattern":"^\\d{3}$","description":"CST de IBS/CBS, com 3 dígitos — ex.: `000`, tributação integral. Não confundir com o\n`cst` do ICMS, de 2 dígitos: são vocabulários diferentes.\n"},"ibs_cbs_class_trib":{"type":["string","null"],"pattern":"^\\d{6}$","description":"Classificação tributária de IBS/CBS, com 6 dígitos — ex.: `000001`.\n"},"ibs_uf_aliquota":{"type":["number","null"],"format":"double","minimum":0,"maximum":100,"description":"Alíquota do IBS estadual, em percentual, com até 4 casas decimais."},"ibs_mun_aliquota":{"type":["number","null"],"format":"double","minimum":0,"maximum":100,"description":"Alíquota do IBS municipal, em percentual, com até 4 casas decimais."},"cbs_aliquota":{"type":["number","null"],"format":"double","minimum":0,"maximum":100,"description":"Alíquota da CBS, em percentual, com até 4 casas decimais."},"ibs_cbs_p_red_bc":{"type":["number","null"],"format":"double","minimum":0,"maximum":100,"description":"Redução da base de cálculo de IBS/CBS, em percentual, com até 4 casas decimais.\nAplicada antes das alíquotas.\n"},"valid_from":{"type":["string","null"],"format":"date"},"valid_until":{"type":["string","null"],"format":"date","description":"Não pode ser anterior a `valid_from`."},"notes":{"type":["string","null"],"maxLength":255}}},"FiscalTaxRule":{"type":"object","required":["id","origin_state","destination_state","tp_serv","tp_serv_rotulo","cfop","icms_variante","icms_variante_rotulo","cst","aliquota","p_red_bc","ibs_cbs_cst","ibs_cbs_class_trib","ibs_uf_aliquota","ibs_mun_aliquota","cbs_aliquota","ibs_cbs_p_red_bc","valid_from","valid_until","notes"],"properties":{"id":{"type":"integer","minimum":1,"description":"ID inteiro da regra; é ele que o `DELETE` recebe."},"origin_state":{"type":["string","null"],"minLength":2,"maxLength":2,"description":"UF de origem; `null` = qualquer origem (curinga)."},"destination_state":{"type":["string","null"],"minLength":2,"maxLength":2,"description":"UF de destino; `null` = qualquer destino (curinga)."},"tp_serv":{"type":["integer","null"],"enum":[0,1,2,3,null],"description":"Tipo de serviço (`ide/tpServ`) a que a regra se aplica; `null` = qualquer tipo."},"tp_serv_rotulo":{"type":["string","null"],"description":"Rótulo legível do tipo de serviço — ex.: `Subcontratação`; `null` quando a regra vale\npara qualquer tipo. Somente leitura: aparece no `GET` e no `201` do `POST`, e não é\naceito no envio.\n"},"cfop":{"type":["string","null"],"pattern":"^\\d{4}$","description":"CFOP sugerido no preenchimento do rascunho."},"icms_variante":{"$ref":"#/components/schemas/FiscalTaxRuleIcmsVariant"},"icms_variante_rotulo":{"type":"string","description":"Rótulo legível da variante de ICMS — ex.: `Tributação normal do ICMS (CST 00)`.\nSomente leitura: aparece no `GET` e no `201` do `POST`, e não é aceito no envio.\n"},"cst":{"type":"string","minLength":2,"maxLength":2,"description":"CST efetivo da regra, derivado da variante — informado pelo cliente somente em `ICMS45`."},"aliquota":{"type":["number","null"],"format":"double","minimum":0,"maximum":100,"description":"Percentual do ICMS."},"p_red_bc":{"type":["number","null"],"format":"double","minimum":0,"maximum":100,"description":"Redução da base de cálculo do ICMS, em percentual."},"ibs_cbs_cst":{"type":["string","null"],"pattern":"^\\d{3}$","description":"CST de IBS/CBS, com 3 dígitos — ex.: `000`, tributação integral. Vocabulário próprio\nda Reforma Tributária: não é o `cst` do ICMS, que tem 2 dígitos, e um não deriva do\noutro.\n"},"ibs_cbs_class_trib":{"type":["string","null"],"pattern":"^\\d{6}$","description":"Classificação tributária de IBS/CBS, com 6 dígitos — ex.: `000001`.\n"},"ibs_uf_aliquota":{"type":["number","null"],"format":"double","minimum":0,"maximum":100,"description":"Alíquota do IBS estadual, em percentual, com até 4 casas decimais."},"ibs_mun_aliquota":{"type":["number","null"],"format":"double","minimum":0,"maximum":100,"description":"Alíquota do IBS municipal, em percentual, com até 4 casas decimais."},"cbs_aliquota":{"type":["number","null"],"format":"double","minimum":0,"maximum":100,"description":"Alíquota da CBS, em percentual, com até 4 casas decimais."},"ibs_cbs_p_red_bc":{"type":["number","null"],"format":"double","minimum":0,"maximum":100,"description":"Redução da base de cálculo de IBS/CBS, em percentual, com até 4 casas decimais.\nAplicada antes das alíquotas.\n"},"valid_from":{"type":["string","null"],"format":"date"},"valid_until":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":255}}},"FiscalTaxRuleEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/FiscalTaxRule"},"environment":{"$ref":"#/components/schemas/Environment"}}},"FiscalTaxRuleListEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"type":"object","required":["regras"],"properties":{"regras":{"type":"array","description":"Regras da transportadora autenticada; são todas as que valem para ela.","items":{"$ref":"#/components/schemas/FiscalTaxRule"}}}},"environment":{"$ref":"#/components/schemas/Environment"}}},"FiscalTaxRuleDeleteData":{"type":"object","required":["id","removida"],"properties":{"id":{"type":"integer","minimum":1},"removida":{"type":"boolean","description":"Sempre `true` no `200` — regra inexistente responde `404`."}}},"FiscalTaxRuleDeleteEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/FiscalTaxRuleDeleteData"},"environment":{"$ref":"#/components/schemas/Environment"}}},"ParcelaRepasse":{"type":"object","description":"Uma parcela do repasse ao motorista. Os campos `*_label` são texto para exibição e podem\nmudar; ramifique por `status` e `evento`, que são estáveis.\n","properties":{"posicao":{"type":"integer","description":"Posição da parcela na regra, de 1 a 3."},"evento":{"type":"integer","enum":[1,2,3],"description":"O evento que libera esta parcela — sempre igual à posição:\n\n- `1` — bipagem\n- `2` — conclusão no app\n- `3` — prestação de contas\n"},"evento_label":{"type":"string"},"percentual":{"type":"integer","description":"Percentual do repasse total desta parcela, congelado na materialização."},"prazo_dias":{"type":"integer","description":"D+N da regra, contado a partir do evento. **Vale só no modo automático**: no manual o\nvencimento é a data da ordem de pagamento, e este número é informativo.\n"},"valor":{"type":"number","format":"float"},"status":{"type":"integer","enum":[1,2,3,4,5],"description":"| valor | significado | tem vencimento | tem pagamento |\n|---|---|---|---|\n| `1` | aguardando evento | não | não |\n| `5` | aguardando ordem de pagamento *(só modo manual)* | não | não |\n| `2` | liberada — tem vencimento e vai pagar | sim | ainda não |\n| `3` | pagamento gerado | sim | sim |\n| `4` | cancelada (CT-e cancelado na SEFAZ) | — | — |\n\nNo modo manual, `5` é onde a parcela para. `pagar` a leva para `2`.\n"},"status_label":{"type":"string"},"ocorrido_em":{"type":["string","null"],"format":"date-time","description":"Quando o evento âncora aconteceu, como você declarou."},"vencimento":{"type":["string","null"],"format":"date","description":"Só existe a partir da liberação (automático) ou da ordem de pagamento (manual). `null`\nenquanto a parcela não tem data — o que é estado normal, não erro.\n"},"liberado_em":{"type":["string","null"],"format":"date-time"},"origem_liberacao":{"type":["string","null"],"description":"Quem liberou: `api` (esta API), `panel` (alguém no painel) ou o evento interno —\n`scan` (bipagem), `completion` (conclusão no app) ou `import_delivered` (importação\njá entregue). Só `api` e `panel` contam como atestação do pagador para a antecipação.\n"},"antecipavel":{"type":"boolean","description":"Se a parcela entra na elegibilidade de antecipação. Depende só do prazo: `true` quando\n`prazo_dias` é 1 ou mais, `false` quando a parcela é D+0 — não muda com o `status`.\nUma parcela D+0 não tem janela entre liberação e pagamento, logo não há o que antecipar.\n"},"pagamento_id":{"type":["integer","null"],"description":"O pagamento gerado por esta parcela, quando já existe."}}},"RespostaParcelaRepasse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ParcelaRepasse"}}},"RespostaParcelasRepasse":{"type":"object","properties":{"data":{"type":"object","properties":{"documento":{"type":"object","properties":{"id":{"type":"integer"},"chave_cte":{"type":["string","null"]},"numero":{"type":["string","null"]},"servico_id":{"type":["integer","null"],"description":"`null` significa que o documento ainda não foi concluído. Sem serviço não há o\nque pagar — `pagar` responde `422 servico_inexistente`.\n"}}},"repasse_total":{"type":"number","format":"float","description":"O valor cheio do repasse. A soma das parcelas fecha com ele."},"parcelas":{"type":"array","items":{"$ref":"#/components/schemas/ParcelaRepasse"}}}}}},"LiberarParcelaRepasse":{"type":"object","required":["documento","posicao","ocorrido_em"],"properties":{"documento":{"type":"string","maxLength":64,"description":"Os mesmos identificadores do `GET`: ID interno FleetPay, número do documento\n(`internal_id`) ou chave do CT-e de 44 dígitos; para contra-CT-e, também o\n`counter_cte_id`, o `documento_financeiro` da perna (`ROUTE:...`) ou a chave do\ncontra-CT-e autorizado.\n"},"posicao":{"type":"integer","minimum":1,"maximum":3,"description":"1 bipagem · 2 conclusão no app · 3 prestação de contas."},"ocorrido_em":{"type":"string","format":"date","description":"Quando o evento aconteceu. Pode ser retroativa; futura é recusada com\n`data_no_futuro`.\n"}}},"PagarParcelaRepasse":{"type":"object","required":["documento","posicao"],"description":"**Sem campo de data**, de propósito: no modo manual o vencimento é o instante da chamada.\nCampo extra enviado aqui é ignorado sem erro.\n","properties":{"documento":{"type":"string","maxLength":64},"posicao":{"type":"integer","minimum":1,"maximum":3}}},"Erro":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Código estável, para máquina — é por ele que você ramifica. Cada operação documenta os códigos que devolve; trate a lista como aberta."},"message":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","request_id"]}}},"Ambiente":{"type":"string","enum":["hml","prd"],"description":"Ambiente em que a operação foi DE FATO executada: `hml` = homologação, `prd` = produção. Hoje a API pública responde em homologação."},"ConviteTransportadoraRequest":{"type":"object","required":["documento","telefone"],"description":"So dois campos, de proposito: o resto e coletado pela FleetPay com o representante legal.","properties":{"documento":{"type":"string","description":"CPF ou CNPJ da transportadora, somente digitos. CPF e aceito — transportador autonomo e pessoa fisica."},"telefone":{"type":"string","description":"Celular do REPRESENTANTE LEGAL, com DDD (10 ou 11 digitos). E por aqui que o convite chega, por WhatsApp. Aceita com ou sem o codigo do pais."}}},"Convite":{"type":"object","required":["documento","status","proximo_passo"],"properties":{"documento":{"type":"string","description":"O documento convidado, somente digitos."},"telefone":{"type":"string","description":"O celular normalizado. Ausente quando a transportadora ja havia sido convidada."},"status":{"type":"string","enum":["convite_enviado","ja_convidada","registrado_envio_pendente"],"description":"`convite_enviado` — a mensagem saiu. `ja_convidada` — ja existia convite e nada novo foi enviado. `registrado_envio_pendente` — o convite ficou registrado mas o envio da mensagem falhou; a FleetPay reenvia, nao repita a chamada."},"convidada_em":{"type":"string","description":"Quando o convite foi registrado."},"proximo_passo":{"type":"string","description":"Em texto, o que acontece a seguir."}}},"RespostaConvite":{"type":"object","required":["data","ambiente"],"properties":{"data":{"$ref":"#/components/schemas/Convite"},"ambiente":{"$ref":"#/components/schemas/Ambiente"}}},"ContaDoAgregado":{"type":"object","required":["situacao","biometria","habilitado_a_receber"],"description":"A conta digital FleetPay do agregado. Se você só for ler um campo, leia `habilitado_a_receber` — os outros existem para explicar o \"por quê\".","properties":{"situacao":{"type":"string","enum":["sem_conta","criada","em_analise","aprovada","reprovada","encerrada"],"description":"Em que ponto está a conta. `sem_conta` — o cadastro existe mas a abertura da conta não começou. `criada` / `em_analise` — a FleetPay está conduzindo. `aprovada` — a conta existe e funciona. `reprovada` / `encerrada` — desfechos finais. Trate como lista aberta: um valor novo não deve quebrar o seu cliente."},"biometria":{"type":"string","enum":["nao_iniciada","em_analise","aprovada","reprovada"],"description":"A verificação de identidade do titular. É o passo que mais segura conta parada, e é conduzido pela FleetPay com a pessoa — você não consegue destravá-lo pela API."},"habilitado_a_receber":{"type":"boolean","description":"**O campo que decide.** `true` só quando a conta está aprovada E não está bloqueada. Uma conta aprovada porém bloqueada continua existindo e continua não recebendo — por isso não basta olhar `situacao`."},"pendencia":{"type":["string","null"],"description":"O que falta, em uma frase que você pode mostrar ao seu operador. `null` quando não há nada pendente. É texto para leitura humana: não faça `if` em cima dele — use `situacao` e `biometria`."}}},"CertificadoDoAgregado":{"type":"object","required":["enviado"],"description":"Certificado digital A1 (e-CNPJ ou e-CPF) do agregado, como está na FleetPay. Sem ele a emissão de documento fiscal em nome desse agregado não acontece.","properties":{"enviado":{"type":"boolean","description":"Se o certificado já foi enviado à FleetPay. `true` continua verdadeiro para um certificado vencido — o que mudou nesse caso é `situacao`, não o envio."},"situacao":{"type":["string","null"],"enum":["valido","expirado",null],"description":"`null` quando nada foi enviado."},"valido_ate":{"type":["string","null"],"format":"date","description":"Último dia de validade. `null` quando nada foi enviado."}}},"Agregado":{"type":"object","required":["tipo","documento","cadastro","conta","certificado_digital"],"properties":{"tipo":{"type":"string","enum":["motorista","transportadora"],"description":"A natureza do agregado — motorista da sua empresa ou transportadora que você contrata/convidou."},"documento":{"type":"string","description":"CPF ou CNPJ, somente dígitos."},"nome":{"type":["string","null"],"description":"Como está cadastrado na FleetPay. `null` para quem foi convidado e ainda não concluiu o cadastro — nesse momento a FleetPay ainda não sabe o nome, e preferimos dizer isso a devolver um rótulo genérico."},"cadastro":{"type":"string","enum":["convidado","cadastrado"],"description":"`convidado` — o convite existe e o cadastro não; não há conta a mostrar ainda. `cadastrado` — existe cadastro na FleetPay, e `conta` reflete o estado real dele."},"conta":{"$ref":"#/components/schemas/ContaDoAgregado"},"certificado_digital":{"$ref":"#/components/schemas/CertificadoDoAgregado"}}},"PaginacaoAgregados":{"type":"object","required":["pagina","por_pagina","total","total_paginas"],"properties":{"pagina":{"type":"integer"},"por_pagina":{"type":"integer"},"total":{"type":"integer","description":"Total de agregados, não o tamanho desta página."},"total_paginas":{"type":"integer"}}},"RespostaAgregados":{"type":"object","required":["data","meta","ambiente"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agregado"}},"meta":{"$ref":"#/components/schemas/PaginacaoAgregados"},"ambiente":{"$ref":"#/components/schemas/Ambiente"}}},"RespostaAgregado":{"type":"object","required":["data","ambiente"],"properties":{"data":{"$ref":"#/components/schemas/Agregado"},"ambiente":{"$ref":"#/components/schemas/Ambiente"}}},"ChavePixInformada":{"type":"object","required":["tipo","valor"],"description":"Como interpretamos a chave que você mandou — confira aqui se ela chegou como você esperava.","properties":{"tipo":{"type":"string","enum":["cpf","cnpj","telefone","email","aleatoria"]},"valor":{"type":"string","description":"A chave em forma canônica: CPF/CNPJ só com dígitos, telefone como `+55DDDNÚMERO`, e-mail e chave aleatória em caixa baixa."}}},"ConferenciaChavePix":{"type":"object","required":["documento","chave_pix","vinculada","situacao","titular","documento_possui_chave","mensagem"],"properties":{"documento":{"type":"string","description":"CPF ou CNPJ consultado, somente dígitos."},"chave_pix":{"$ref":"#/components/schemas/ChavePixInformada"},"vinculada":{"type":"boolean","description":"Atalho para `situacao == \"vinculada\"`."},"situacao":{"type":"string","enum":["vinculada","chave_de_outro_titular","nao_cadastrada"],"description":"`vinculada` — a chave é a que consta no cadastro deste documento. `chave_de_outro_titular` — a chave existe na sua base, cadastrada para OUTRO agregado seu. **É o caso que pede ação:** é o padrão da troca de chave. `nao_cadastrada` — não há chave PIX externa com este valor para este documento."},"titular":{"type":["object","null"],"description":"Só vem preenchido quando `situacao` é `vinculada`. Em `chave_de_outro_titular` vai `null` de propósito, para a conferência não virar um diretório reverso chave → pessoa.","properties":{"tipo":{"type":"string","enum":["motorista"]},"nome":{"type":["string","null"]},"documento":{"type":"string"}}},"documento_possui_chave":{"type":"boolean","description":"Este documento tem ALGUMA chave PIX externa cadastrada com você. É o que separa \"não temos chave desta pessoa\" (`false`) de \"temos, e é outra\" (`true`) — as duas respondem `vinculada: false` e pedem ações opostas."},"mensagem":{"type":"string","description":"Frase pronta, redigida pela FleetPay, para você mostrar ao seu operador."}}},"RespostaConferenciaChavePix":{"type":"object","required":["data","ambiente"],"properties":{"data":{"$ref":"#/components/schemas/ConferenciaChavePix"},"ambiente":{"$ref":"#/components/schemas/Ambiente"}}},"EnderecoCiot":{"type":"object","required":["logradouro","numero","bairro","codigo_municipio","uf","cep"],"properties":{"logradouro":{"type":"string","maxLength":120},"numero":{"type":"string","maxLength":10},"bairro":{"type":"string","maxLength":60},"codigo_municipio":{"type":"string","pattern":"^[0-9]{7}$","description":"Código IBGE do município, 7 dígitos."},"uf":{"type":"string","minLength":2,"maxLength":2},"cep":{"type":"string","pattern":"^[0-9]{8}$"}}},"ParteDocumentoCiot":{"type":"object","required":["papel","documento","nome","endereco"],"description":"Quem está de cada lado da carga. **Remetente e destinatário são obrigatórios** porque a\nANTT identifica a operação por eles, não pelo número da nota: é o par que diz de onde a\ncarga saiu e para quem vai.\n","properties":{"papel":{"type":"string","enum":["remetente","destinatario","consignatario"]},"documento":{"type":"string","pattern":"^([0-9]{11}|[0-9]{14})$","description":"CPF ou CNPJ, somente dígitos."},"nome":{"type":"string","maxLength":120},"endereco":{"$ref":"#/components/schemas/EnderecoCiot"}}},"DocumentoCargaCiot":{"type":"object","required":["tipo","numero","peso_carga","valor_mercadoria","partes"],"properties":{"tipo":{"type":"string","enum":["nfe","nf","romaneio","outros"]},"numero":{"type":"string","maxLength":20},"serie":{"type":["string","null"],"maxLength":5},"chave_acesso":{"type":["string","null"],"pattern":"^[0-9]{44}$","description":"Opcional. A operação não exige que a NF-e exista na FleetPay — este endpoint declara\na viagem, não importa documento fiscal.\n"},"peso_carga":{"type":"number","format":"double","minimum":0.01},"valor_mercadoria":{"type":"number","format":"double","minimum":0.01},"partes":{"type":"array","minItems":2,"items":{"$ref":"#/components/schemas/ParteDocumentoCiot"}}}},"DeclaracaoCiot":{"type":"object","required":["tipo_operacao","contratado","viagem","rota","carga","veiculos","motorista","documentos","valores"],"allOf":[{"if":{"properties":{"tipo_operacao":{"const":"fracionado"}},"required":["tipo_operacao"]},"then":{"properties":{"carga":{"required":["contratantes"]}}}}],"properties":{"referencia_externa":{"type":["string","null"],"maxLength":64,"description":"O identificador **do seu sistema** para esta viagem. Opcional, e **único por\nempresa**: é a chave de idempotência que impede um retry de rede virar um segundo\nCIOT para o mesmo frete.\n\nNão vai para a ANTT.\n"},"tipo_operacao":{"type":"string","enum":["lotacao","fracionado"],"description":"`lotacao` para uma carga que ocupa a operação inteira; `fracionado` para cargas de\nvários contratantes na mesma viagem. TAC agregado continua fora desta versão.\n"},"contratado":{"type":"object","required":["documento","nome","rntrc"],"description":"Quem transporta. **Tem de ser a empresa autenticada**: esta rota declara em nome\npróprio. Um contratado diferente responde `422 declaracao_bloqueada`.\n","properties":{"documento":{"type":"string","pattern":"^([0-9]{11}|[0-9]{14})$"},"nome":{"type":"string","maxLength":120},"rntrc":{"type":"string","pattern":"^[0-9]{8,9}$"}}},"viagem":{"type":"object","required":["data_inicio","data_fim","distancia_percorrida"],"properties":{"data_inicio":{"type":"string","format":"date"},"data_fim":{"type":"string","format":"date","description":"Não pode ser anterior a `data_inicio`."},"distancia_percorrida":{"type":"integer","minimum":1,"description":"Em quilômetros."},"alto_desempenho":{"type":"boolean","default":false},"retorno_vazio":{"type":"boolean","default":false},"composicao_veicular":{"type":"boolean","default":false}}},"rota":{"type":"object","required":["origem","destino"],"properties":{"origem":{"type":"object","required":["codigo_municipio","cep","uf"],"properties":{"codigo_municipio":{"type":"string","pattern":"^[0-9]{7}$"},"cep":{"type":"string","pattern":"^[0-9]{8}$"},"uf":{"type":"string","minLength":2,"maxLength":2}}},"destino":{"type":"object","required":["codigo_municipio","cep","uf"],"properties":{"codigo_municipio":{"type":"string","pattern":"^[0-9]{7}$"},"cep":{"type":"string","pattern":"^[0-9]{8}$"},"uf":{"type":"string","minLength":2,"maxLength":2}}},"trechos":{"type":"array","maxItems":100,"description":"Coletas e entregas intermediárias. Opcional; os extremos gerais continuam em\n`origem` e `destino`.\n","items":{"type":"object","required":["origem_codigo_municipio","destino_codigo_municipio","distancia_percorrida"],"properties":{"origem_codigo_municipio":{"type":"string","pattern":"^[0-9]{7}$"},"destino_codigo_municipio":{"type":"string","pattern":"^[0-9]{7}$"},"distancia_percorrida":{"type":"integer","minimum":1,"maximum":99999}}}}}},"carga":{"type":"object","required":["codigo_tipo_carga","codigo_natureza_carga","peso_carga","valor_mercadoria"],"properties":{"codigo_tipo_carga":{"type":"integer","minimum":1},"codigo_natureza_carga":{"type":"string","maxLength":10},"peso_carga":{"type":"number","format":"double","minimum":0.01},"valor_mercadoria":{"type":"number","format":"double","minimum":0.01},"contratantes":{"type":"array","minItems":1,"maxItems":100,"description":"Obrigatório quando `tipo_operacao` for `fracionado`.","items":{"type":"object","required":["documento"],"properties":{"documento":{"type":"string","pattern":"^([0-9]{11}|[0-9]{14})$"}}}}}},"veiculos":{"type":"array","minItems":1,"maxItems":10,"description":"De um a dez veículos por operação.","items":{"type":"object","required":["placa","eixos"],"properties":{"placa":{"type":"string","pattern":"^[A-Za-z]{3}[0-9][A-Za-z0-9][0-9]{2}$"},"rntrc":{"type":["string","null"],"pattern":"^[0-9]{8,9}$","description":"Omitido, assume-se o RNTRC do contratado."},"eixos":{"type":"integer","minimum":2,"maximum":9}}}},"motorista":{"type":"object","required":["cpf","nome","data_nascimento","telefone"],"properties":{"cpf":{"type":"string","pattern":"^[0-9]{11}$"},"nome":{"type":"string","maxLength":120},"data_nascimento":{"type":"string","format":"date"},"telefone":{"type":"string","pattern":"^[0-9]{10,11}$","description":"DDD + número, somente dígitos."}}},"documentos":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/DocumentoCargaCiot"}},"valores":{"type":"object","required":["frete_bruto"],"properties":{"frete_bruto":{"type":"number","format":"double","minimum":0.01,"description":"O valor do frete da viagem, em reais."},"pedagio":{"type":["number","null"],"format":"double","minimum":0,"description":"Valor total de pedágio, quando houver. O Vale-Pedágio com detalhe de praças\nainda não é aceito por esta rota.\n"}}}}},"OperacaoCiot":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","format":"uuid","description":"O endereço público da operação. Nasce **antes** da chamada ao provedor, e por isso\nexiste mesmo quando a declaração é recusada — é o caso em que o número do CIOT\nnunca chegou a existir.\n"},"referencia_externa":{"type":["string","null"]},"status":{"type":"string","enum":["pending","sent","registered","error","cancelled","closed"],"description":"`registered` é o único que autoriza seguir viagem. `sent` é declaração entregue sem\nveredito — consulte antes de qualquer nova tentativa. `pending` é declaração que\nnem foi transmitida.\n"},"numero":{"type":["string","null"],"description":"O CIOT. `null` até a ANTT devolver — e para sempre, se ela recusar."},"codigo_verificador":{"type":["string","null"]},"protocolo":{"type":["string","null"]},"mensagem":{"type":["string","null"],"description":"O que o provedor respondeu, ou o motivo da recusa."},"tipo_operacao":{"type":"string","enum":["lotacao","fracionado"]},"declarado_em":{"type":["string","null"],"format":"date-time"},"registrado_em":{"type":["string","null"],"format":"date-time","description":"Quando o CIOT passou a existir na ANTT. `null` enquanto não existir."},"cte":{"type":["object","null"],"description":"O CT-e ao qual a operação está amarrada, quando houver. **`null` é o caso normal\ndesta rota** — o campo viaja sempre, mesmo nulo, para que a pergunta \"isto está\namarrado a um CT-e?\" tenha resposta explícita.\n","properties":{"id":{"type":"string","format":"uuid"}}}}},"RespostaCiot":{"type":"object","required":["data","environment"],"properties":{"data":{"type":"object","required":["ciot"],"properties":{"ciot":{"$ref":"#/components/schemas/OperacaoCiot"}}},"environment":{"$ref":"#/components/schemas/Environment"}}},"VeiculoPedagio":{"type":"object","required":["operadora","placa","tem_tag","habilitado_vale_pedagio"],"properties":{"operadora":{"type":"string","enum":["sem_parar","conectcar","veloe","move_mais"],"description":"A operadora que respondeu. Ecoada de propósito: o dado gravado na sua base carrega\na origem.\n"},"placa":{"type":"string","description":"A placa consultada, normalizada em maiúsculas e sem separador."},"tem_tag":{"type":"boolean","description":"Se o veículo carrega tag de pedágio — ou seja, se passa pela via automática.\n\nÉ **resposta**, não inferência: não deduza a ausência de tag de `identificador_tag`\nvir nulo.\n"},"identificador_tag":{"type":["string","null"],"description":"O código da tag. Só acompanha quem tem tag — vem `null` sempre que `tem_tag` é\n`false`.\n"},"proprietario":{"type":["string","null"],"description":"Quem o operador tem no cadastro do veículo."},"descricao":{"type":["string","null"],"description":"Marca, modelo e categoria, como o operador os devolve."},"eixos":{"type":["integer","null"],"minimum":2,"maximum":10},"habilitado_vale_pedagio":{"type":"boolean","description":"Se dá para emitir Vale-Pedágio para este veículo.\n\n**Pergunta independente de `tem_tag`.** O vale tradicional não exige tag, e um\nveículo com tag pode estar bloqueado pelo operador.\n"},"verificacao":{"type":"string","description":"`simulada` quando a resposta foi gerada pela FleetPay, sem operador contratado.\nAusente significa verificação real.\n"}}},"RespostaVeiculoPedagio":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/VeiculoPedagio"},"environment":{"$ref":"#/components/schemas/Environment"}}},"ConsultaRntrc":{"type":"object","required":["documento","rntrc","ativo","tipo"],"properties":{"documento":{"type":"string","description":"CPF ou CNPJ do transportador consultado, somente dígitos."},"rntrc":{"type":"string","description":"O RNTRC consultado."},"razao_social":{"type":["string","null"],"description":"Razão social (ou nome) do transportador no registro da ANTT.\n\nEm homologação, onde a consulta responde em modo simulado, o nome real **não é\ndevolvido**: o campo inteiro é substituído por um de dois valores fixos, conforme o\ndocumento consultado —\n\n| `documento` | `razao_social` |\n|---|---|\n| CNPJ (14 dígitos) | `TRANSPORTES SIMULADOS HML LTDA` |\n| CPF (11 dígitos, transportador autônomo) | `TRANSPORTADOR AUTONOMO SIMULADO` |\n\nÉ o marcador de que o dado não foi apurado na ANTT.\n"},"data_validade":{"type":["string","null"],"format":"date","description":"Até quando o registro no RNTRC é válido, em `AAAA-MM-DD`.\n\n`null` quando o provedor não informa a validade — o que **não** é o mesmo que\nvencido. Trate ausência e vencimento como casos distintos.\n\nEm homologação, onde a consulta responde em modo simulado, a data é derivada do\n**dia da consulta**: registro ativo devolve hoje + 1 ano; a sentinela de registro\ninativo (`rntrc=000000000`) devolve hoje − 1 ano, porque um RNTRC vencido é a\ncausa mais comum de inatividade e devolver validade futura junto de\n`ativo: false` seria uma resposta que se contradiz.\n\nÉ o único campo desta consulta que **não** é fixo entre dias: os demais são\ndeterminísticos, e este acompanha a data para não envelhecer.\n"},"ativo":{"type":"boolean","description":"Se o RNTRC está ativo na ANTT."},"tipo":{"type":"string","enum":["ETC","TAC","CTC"],"description":"Tipo do transportador: `ETC` (empresa), `TAC` (autônomo) ou `CTC` (cooperativa)."},"equiparado_tac":{"type":"boolean","description":"Se o transportador é equiparado a TAC."}}},"RespostaConsultaRntrc":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/ConsultaRntrc"},"environment":{"type":"string","enum":["homologacao","producao"],"description":"Ambiente em que a consulta rodou, decidido pelo endereço chamado."}}},"Environment":{"type":"string","enum":["homologacao","producao"],"description":"Ambiente em que a operação rodou, decidido pelo endereço chamado. `producao` significa\ndocumento fiscal com valor legal.\n"},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}}},"ErrorBody":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","description":"Código estável e próprio do contrato FleetPay."},"message":{"type":"string"},"details":{"type":["object","null"],"additionalProperties":true,"properties":{"pending_items":{"type":"array","items":{"type":"string"}}}},"request_id":{"type":"string","format":"uuid"}}},"Pagination":{"type":"object","required":["page","per_page","total","last_page"],"properties":{"page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer","minimum":0},"last_page":{"type":"integer","minimum":1}}},"CompanySummary":{"type":"object","required":["document","name"],"properties":{"document":{"type":"string","pattern":"^\\d{14}$"},"name":{"type":["string","null"]}}},"StatusData":{"type":"object","required":["company","environment","certificate","documents"],"properties":{"company":{"$ref":"#/components/schemas/CompanySummary"},"environment":{"$ref":"#/components/schemas/Environment"},"certificate":{"type":"object","required":["configured","valid_until"],"properties":{"configured":{"type":"boolean"},"valid_until":{"type":["string","null"],"format":"date"}}},"documents":{"type":"object","required":["nfe","cte","ciot","mdfe"],"properties":{"nfe":{"type":"boolean"},"cte":{"type":"boolean"},"ciot":{"type":"boolean"},"mdfe":{"type":"boolean"}}}}},"StatusEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/StatusData"},"environment":{"$ref":"#/components/schemas/Environment"}}},"FiscalConfigurationUpdate":{"type":"object","description":"Campos fiscais da transportadora. Todos são opcionais; envie null para limpar um valor.\nA série do CT-e não é configurável: série e número são atribuídos pelo provedor fiscal,\ne `cte_serie` no corpo responde `422`.\n","properties":{"state_registration":{"type":["string","null"],"maxLength":20,"description":"Inscrição estadual, normalizada em maiúsculas."},"rntrc":{"type":["string","null"],"pattern":"^\\d{8}$","description":"Registro Nacional de Transportadores Rodoviários de Cargas com 8 dígitos."},"rntrc_valid_until":{"type":["string","null"],"format":"date","description":"Data de validade do RNTRC no formato YYYY-MM-DD."},"city_code":{"type":["string","null"],"pattern":"^\\d{7}$","description":"Código IBGE do município com 7 dígitos."},"endereco":{"type":"object","description":"Endereço fiscal da empresa — o emitente do CT-e/MDF-e. Sem ele a prévia do CT-e\nrecusa com \"Endereço da empresa não cadastrado\".\n","required":["logradouro","numero","bairro","municipio","uf","cep"],"properties":{"logradouro":{"type":"string","maxLength":255},"numero":{"type":"string","maxLength":20},"complemento":{"type":["string","null"],"maxLength":100},"bairro":{"type":"string","maxLength":100},"municipio":{"type":"string","maxLength":60},"uf":{"type":"string","pattern":"^[A-Z]{2}$"},"cep":{"type":"string","pattern":"^\\d{8}$"},"codigo_municipio":{"type":["string","null"],"pattern":"^\\d{7}$"}}}}},"FiscalConfigurationData":{"type":"object","required":["state_registration","rntrc","rntrc_valid_until","cte_numbering","city_code","endereco"],"properties":{"state_registration":{"type":["string","null"]},"rntrc":{"type":["string","null"],"pattern":"^\\d{8}$"},"rntrc_valid_until":{"type":["string","null"],"format":"date"},"cte_numbering":{"type":"object","description":"Série e número do CT-e são do provedor fiscal; não há série local.","required":["authority","series_configurable"],"properties":{"authority":{"type":"string","enum":["provider"]},"series_configurable":{"type":"boolean","enum":[false]}}},"city_code":{"type":["string","null"],"pattern":"^\\d{7}$"},"endereco":{"type":["object","null"],"description":"Endereço fiscal padrão da empresa, o mesmo que a emissão usa; `null` quando não cadastrado.","properties":{"logradouro":{"type":["string","null"]},"numero":{"type":["string","null"]},"complemento":{"type":["string","null"]},"bairro":{"type":["string","null"]},"municipio":{"type":["string","null"]},"uf":{"type":["string","null"]},"cep":{"type":["string","null"]},"codigo_municipio":{"type":["string","null"]}}}}},"FiscalConfigurationEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/FiscalConfigurationData"},"environment":{"$ref":"#/components/schemas/Environment"}}},"CertificateMetadata":{"type":"object","required":["configured","holder_name","document","valid_from","valid_until","status"],"properties":{"configured":{"type":"boolean","description":"Indica se há certificado cadastrado para a transportadora."},"holder_name":{"type":["string","null"],"description":"Razão social extraída do certificado, quando disponível."},"document":{"type":["string","null"],"description":"Documento extraído do certificado, somente dígitos quando disponível."},"valid_from":{"type":["string","null"],"format":"date"},"valid_until":{"type":["string","null"],"format":"date"},"status":{"type":["string","null"],"enum":["valido","expirado",null],"description":"Situação calculada pela data de validade; null quando não há certificado."}}},"CertificateEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/CertificateMetadata"},"environment":{"$ref":"#/components/schemas/Environment"}}},"CertificateDeleteData":{"type":"object","required":["removed"],"properties":{"removed":{"type":"boolean","description":"True quando havia certificado e ele foi removido; false quando não havia certificado."}}},"CertificateDeleteEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/CertificateDeleteData"},"environment":{"$ref":"#/components/schemas/Environment"}}},"IntegerOption":{"type":"object","required":["value","label"],"properties":{"value":{"type":"integer"},"label":{"type":"string"}}},"StringOption":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string"},"label":{"type":"string"}}},"CataloguesData":{"type":"object","required":["fiscal","cte_statuses","mdfe_statuses"],"properties":{"fiscal":{"type":"object","required":["tiposCarga","tiposRodado","tiposCarroceria"],"properties":{"tiposCarga":{"type":"array","items":{"$ref":"#/components/schemas/IntegerOption"}},"tiposRodado":{"type":"array","items":{"$ref":"#/components/schemas/StringOption"}},"tiposCarroceria":{"type":"array","items":{"$ref":"#/components/schemas/StringOption"}}}},"cte_statuses":{"type":"array","items":{"$ref":"#/components/schemas/StringOption"}},"mdfe_statuses":{"type":"array","items":{"$ref":"#/components/schemas/StringOption"}}}},"CataloguesEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/CataloguesData"},"environment":{"$ref":"#/components/schemas/Environment"}}},"DashboardData":{"type":"object","required":["reference_month","nfe","cte","mdfe"],"properties":{"reference_month":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"nfe":{"type":"object","required":["available_for_cte"],"properties":{"available_for_cte":{"type":"integer","minimum":0}}},"cte":{"type":"object","required":["draft","waiting","authorized","rejected","awaiting_mdfe"],"properties":{"draft":{"type":"integer","minimum":0},"waiting":{"type":"integer","minimum":0},"authorized":{"type":"integer","minimum":0},"rejected":{"type":"integer","minimum":0},"awaiting_mdfe":{"type":"integer","minimum":0}}},"mdfe":{"type":"object","required":["authorized","closed","open"],"properties":{"authorized":{"type":"integer","minimum":0},"closed":{"type":"integer","minimum":0},"open":{"type":"integer","minimum":0}}}}},"DashboardEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/DashboardData"},"environment":{"$ref":"#/components/schemas/Environment"}}},"NfeStatus":{"type":"string","enum":["imported","linked","cancelled"]},"FiscalParty":{"type":"object","required":["document","name","city","state"],"properties":{"document":{"type":["string","null"]},"name":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]}}},"NfeCargo":{"type":"object","required":["total_value","gross_weight","net_weight","volume_quantity","predominant_product"],"properties":{"total_value":{"type":["number","null"],"format":"double"},"gross_weight":{"type":["number","null"],"format":"double"},"net_weight":{"type":["number","null"],"format":"double"},"volume_quantity":{"type":["integer","null"]},"predominant_product":{"type":["string","null"]}}},"Nfe":{"type":"object","required":["id","access_key","number","series","issued_at","issuer","recipient","cargo","status","linked_cte_count","created_at"],"properties":{"id":{"type":"string","pattern":"^\\d{44}$","description":"Chave de acesso da NF-e; é o identificador público do recurso."},"access_key":{"type":"string","pattern":"^\\d{44}$"},"number":{"type":"integer"},"series":{"type":"string"},"issued_at":{"type":["string","null"],"format":"date-time"},"issuer":{"$ref":"#/components/schemas/FiscalParty"},"recipient":{"$ref":"#/components/schemas/FiscalParty"},"cargo":{"$ref":"#/components/schemas/NfeCargo"},"status":{"$ref":"#/components/schemas/NfeStatus"},"linked_cte_count":{"type":"integer","minimum":0},"created_at":{"type":["string","null"],"format":"date-time"}}},"NfeEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/Nfe"},"environment":{"$ref":"#/components/schemas/Environment"}}},"NfeListEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Nfe"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"environment":{"$ref":"#/components/schemas/Environment"}}},"NfeImportResult":{"type":"object","required":["file_name","status","access_key","reason"],"properties":{"file_name":{"type":"string"},"status":{"type":"string","description":"Resultado individual, como `imported`, `duplicated` ou `failed`."},"access_key":{"type":["string","null"],"pattern":"^\\d{44}$"},"reason":{"type":["string","null"]}}},"NfeImportBatch":{"type":"object","required":["id","file_name","status","total","imported","duplicated","failed","results","created_at"],"properties":{"id":{"type":"integer"},"file_name":{"type":"string"},"status":{"type":"string"},"total":{"type":"integer","minimum":0},"imported":{"type":"integer","minimum":0},"duplicated":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"results":{"type":"array","items":{"$ref":"#/components/schemas/NfeImportResult"}},"created_at":{"type":["string","null"],"format":"date-time"}}},"NfeImportEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/NfeImportBatch"},"environment":{"$ref":"#/components/schemas/Environment"}}},"CteSituation":{"type":"string","enum":["rascunho","aguardando","autorizado","rejeitado","cancelado"]},"CteLifecycleStatus":{"type":"string","enum":["draft","ready","sent","waiting","authorized","rejected","cancelled"]},"CiotStatus":{"type":"string","enum":["pending","sent","registered","error","cancelled","closed"]},"FiscalRoute":{"type":"object","required":["origin_city_code","origin_city","origin_state","destination_city_code","destination_city","destination_state"],"properties":{"origin_city_code":{"type":["string","null"]},"origin_city":{"type":["string","null"]},"origin_state":{"type":["string","null"]},"destination_city_code":{"type":["string","null"]},"destination_city":{"type":["string","null"]},"destination_state":{"type":["string","null"]}}},"CteCiotSummary":{"type":"object","required":["status","number","verification_code","message","requested_at"],"properties":{"status":{"anyOf":[{"type":"string","allOf":[{"$ref":"#/components/schemas/CiotStatus"}]},{"type":"null"}]},"number":{"type":["string","null"]},"verification_code":{"type":["string","null"]},"message":{"type":["string","null"]},"requested_at":{"type":["string","null"],"format":"date-time"}}},"CteEvent":{"type":"object","required":["id","type","status","sequence","reference","protocol","reason","registered_at","created_at"],"properties":{"id":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Identificador público opaco usado para reconciliar o evento."},"type":{"type":"string","enum":["cancellation","correction","delivery_confirmation","delivery_cancellation"]},"status":{"type":"string","enum":["pending","registered","rejected"]},"sequence":{"type":"integer","minimum":1},"reference":{"type":["string","null"]},"protocol":{"type":["string","null"]},"reason":{"type":["string","null"]},"registered_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":["string","null"],"format":"date-time"}}},"Cte":{"type":"object","required":["id","status","lifecycle_status","freight","route","access_key","number","series","protocol","sefaz_protocol","cstat","reason","authorized_at","service_type","service_type_label","ciot","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"UUID público usado em todos os caminhos do CT-e."},"status":{"$ref":"#/components/schemas/CteSituation"},"lifecycle_status":{"$ref":"#/components/schemas/CteLifecycleStatus"},"freight":{"type":"object","required":["total_value","cargo_value"],"properties":{"total_value":{"type":["number","null"],"format":"double"},"cargo_value":{"type":["number","null"],"format":"double"}}},"route":{"$ref":"#/components/schemas/FiscalRoute"},"access_key":{"type":["string","null"],"pattern":"^\\d{44}$"},"number":{"type":["integer","null"]},"series":{"type":["string","null"]},"protocol":{"type":["string","null"]},"sefaz_protocol":{"type":["string","null"]},"cstat":{"type":["string","null"]},"reason":{"type":["string","null"]},"authorized_at":{"type":["string","null"],"format":"date-time"},"service_type":{"type":"integer","minimum":0,"maximum":4,"description":"`ide/tpServ` do documento: `0` normal, `1` subcontratação, `2` redespacho, `3`\nredespacho intermediário (`4` só em rascunhos antigos, que não emitem). Um contra-CT-e\ngravado antes do campo é `1`.\n"},"service_type_label":{"type":"string","description":"Rótulo legível do `service_type` — ex.: `Redespacho`.\n"},"ciot":{"$ref":"#/components/schemas/CteCiotSummary"},"nfe_count":{"type":"integer","minimum":0,"description":"Presente nas listagens."},"has_mdfe":{"type":"boolean","description":"Presente nas listagens."},"payload":{"type":"object","additionalProperties":true,"description":"Presente no detalhe; contém o payload público validado do rascunho."},"nfe":{"type":"array","description":"Presente no detalhe.","items":{"$ref":"#/components/schemas/Nfe"}},"events":{"type":"array","description":"Presente no detalhe.","items":{"$ref":"#/components/schemas/CteEvent"}},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"financial_document":{"type":["object","null"],"description":"Só para **perna de contra-CT-e**: o documento financeiro da perna (o que carrega o\nrepasse ao motorista). `internal_id` tem a forma `ROUTE:<lote>:<hex>` e é aceito em\n`GET /carriers/parcelas-repasse/{documento}`; `access_key` é a chave do contra-CT-e,\ncarimbada quando a SEFAZ autoriza. `null` nos demais CT-e.\n","properties":{"id":{"type":"integer"},"internal_id":{"type":"string"},"access_key":{"type":["string","null"]}}}}},"EmittedCteInput":{"type":"object","required":["xml"],"properties":{"xml":{"type":"string","maxLength":2097152,"description":"O XML do CT-e, cru ou em base64. Aceita `cteProc` (com protocolo) ou `CTe`.\n"}}},"EmittedCte":{"type":"object","required":["id","access_key","first_reception"],"properties":{"id":{"type":"string","pattern":"^\\d{44}$","description":"Chave de acesso do CT-e; é o identificador público do recurso."},"access_key":{"type":"string","pattern":"^\\d{44}$"},"document_id":{"type":["integer","null"],"description":"Identificador interno do documento criado na FleetPay."},"service_date":{"type":["string","null"],"format":"date","description":"Data de emissão do CT-e, lida de `ide/dhEmi`."},"service_cost":{"type":["number","null"],"description":"Valor total da prestação, lido de `vPrest/vTPrest`."},"shipper":{"type":"object","description":"O TOMADOR do frete, resolvido pelo código `toma` do XML.","properties":{"document":{"type":["string","null"]},"name":{"type":["string","null"]}}},"carrier":{"type":"object","description":"A sua transportadora — o `emit` do XML.","properties":{"document":{"type":["string","null"]}}},"nfe_access_key":{"type":["string","null"],"description":"Chave da NF-e transportada, quando o CT-e referencia uma."},"first_reception":{"type":"boolean","description":"`true` quando esta foi a primeira entrega deste documento (resposta `201`). Nos\nreenvios é `false` e nada é reprocessado.\n"}}},"EmittedCteEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/EmittedCte"},"environment":{"$ref":"#/components/schemas/Environment"}}},"InboundCteCarrierRole":{"type":"string","description":"O papel da SUA empresa dentro do CT-e recebido, lido do XML. É ele que decide se aquele\ndocumento admite um contra-CT-e seu.\n\n- `subcontracted` — você não é o emitente nem parte da carga: é o caso da subcontratação,\n  o único que admite contra-CT-e;\n- `issuer` — o CT-e foi emitido pela sua própria empresa;\n- `sender` — você é o remetente da carga;\n- `recipient` — você é o destinatário da carga.\n","enum":["subcontracted","issuer","sender","recipient"]},"InboundCteStatus":{"type":"string","description":"O ciclo do documento DENTRO da FleetPay — não é o status dele na SEFAZ, que é assunto de\nquem o emitiu.\n\n- `received` — chegou e ainda não originou nada;\n- `drafted` — já originou um contra-CT-e (veja `counter_cte_id`).\n","enum":["received","drafted"]},"InboundCteParty":{"type":"object","required":["document","name","city","state"],"properties":{"document":{"type":["string","null"],"description":"CNPJ ou CPF, somente dígitos."},"name":{"type":["string","null"]},"state_registration":{"type":["string","null"]},"city":{"type":["string","null"]},"city_code":{"type":["string","null"],"description":"Código IBGE do município."},"state":{"type":["string","null"]}}},"InboundCteAddress":{"type":"object","properties":{"street":{"type":["string","null"]},"number":{"type":["string","null"]},"complement":{"type":["string","null"]},"district":{"type":["string","null"]},"city":{"type":["string","null"]},"city_code":{"type":["string","null"]},"state":{"type":["string","null"]},"zip_code":{"type":["string","null"]}}},"InboundCteCargo":{"type":"object","properties":{"value":{"type":["number","null"],"description":"Valor da carga declarado no CT-e de origem."},"gross_weight":{"type":["number","null"]},"predominant_product":{"type":["string","null"]}}},"InboundCte":{"type":"object","required":["id","access_key","model","issuer","carrier_role","allows_counter_cte","status","origin","received_count"],"properties":{"id":{"type":"string","pattern":"^\\d{44}$","description":"Chave de acesso do CT-e; é o identificador público do recurso."},"access_key":{"type":"string","pattern":"^\\d{44}$"},"number":{"type":["integer","null"]},"series":{"type":["string","null"]},"model":{"type":"string","description":"Modelo do documento; sempre `57` para CT-e."},"service_type":{"type":["integer","null"],"description":"`tpServ` do CT-e de origem: 0 normal, 1 subcontratação, 2 redespacho, 3 redespacho\nintermediário, 4 serviço vinculado a multimodal (este não admite contra-CT-e).\n"},"service_type_label":{"type":["string","null"],"description":"Rótulo legível do `service_type` — ex.: `Normal`, `Subcontratação`; `null` quando o XML\nnão traz `tpServ`.\n"},"issuer":{"$ref":"#/components/schemas/InboundCteParty"},"sender":{"$ref":"#/components/schemas/InboundCteParty"},"recipient":{"$ref":"#/components/schemas/InboundCteParty"},"cargo":{"$ref":"#/components/schemas/InboundCteCargo"},"source_service_value":{"type":["number","null"],"description":"O `vTPrest` de quem emitiu — **referência, nunca o seu preço**. O valor do trecho\nsubcontratado é negociação que este XML não presenciou.\n"},"nfe_access_keys":{"type":"array","description":"Chaves das NF-e que o CT-e de origem transporta.","items":{"type":"string","pattern":"^\\d{44}$"}},"carrier_role":{"$ref":"#/components/schemas/InboundCteCarrierRole"},"carrier_role_label":{"type":"string"},"allows_counter_cte":{"type":"boolean","description":"Se este documento admite um contra-CT-e seu. `true` apenas quando `carrier_role` é\n`subcontracted`, o documento ainda não originou contra-CT-e e o tipo de serviço da\norigem o admite (um CT-e vinculado a multimodal, `service_type` 4, não admite).\n"},"status":{"$ref":"#/components/schemas/InboundCteStatus"},"status_label":{"type":"string"},"counter_cte_id":{"type":["string","null"],"format":"uuid","description":"UUID do contra-CT-e que este documento originou, quando já houver um."},"origin":{"type":"string","description":"Por qual porta o documento entrou. `api` é a entrega pelo seu sistema."},"received_count":{"type":"integer","minimum":1,"description":"Quantas vezes este mesmo documento foi entregue."},"first_received_at":{"type":["string","null"],"format":"date-time"},"last_received_at":{"type":["string","null"],"format":"date-time"},"addresses":{"type":"object","description":"Endereços completos das partes. Só na consulta por chave.","properties":{"issuer":{"$ref":"#/components/schemas/InboundCteAddress"},"sender":{"$ref":"#/components/schemas/InboundCteAddress"},"recipient":{"$ref":"#/components/schemas/InboundCteAddress"}}}}},"InboundCteReceipt":{"allOf":[{"$ref":"#/components/schemas/InboundCte"},{"type":"object","required":["first_reception","content_updated"],"properties":{"first_reception":{"type":"boolean","description":"`true` quando esta foi a primeira chegada deste documento (a resposta veio com\n`201`). Nos reenvios é `false`.\n"},"content_updated":{"type":"boolean","description":"`true` quando o reenvio trouxe um XML diferente do arquivado e o conteúdo foi\nsubstituído pelo mais recente.\n"}}}]},"InboundCteInput":{"type":"object","required":["xml"],"properties":{"xml":{"type":"string","maxLength":2097152,"description":"O XML do CT-e, cru ou em base64. Aceita `cteProc` (com protocolo) ou `CTe`.\n"}}},"InboundCteEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/InboundCte"},"environment":{"$ref":"#/components/schemas/Environment"}}},"InboundCteReceiptEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/InboundCteReceipt"},"environment":{"$ref":"#/components/schemas/Environment"}}},"InboundCteListEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/InboundCte"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"environment":{"$ref":"#/components/schemas/Environment"}}},"CteEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/Cte"},"environment":{"$ref":"#/components/schemas/Environment"}}},"CteListEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Cte"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"environment":{"$ref":"#/components/schemas/Environment"}}},"CtePreview":{"type":"object","required":["access_key","number","series","content","document"],"properties":{"access_key":{"type":"string","pattern":"^\\d{44}$"},"number":{"type":"integer"},"series":{"type":"string"},"content":{"description":"Conteúdo fiscal montado para inspeção.","oneOf":[{"type":"object","additionalProperties":true},{"type":"string"}]},"document":{"$ref":"#/components/schemas/Cte"}}},"CtePreviewEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/CtePreview"},"environment":{"$ref":"#/components/schemas/Environment"}}},"CteIssueResult":{"type":"object","required":["document","outcome","message"],"properties":{"document":{"anyOf":[{"type":"object","allOf":[{"$ref":"#/components/schemas/Cte"}]},{"type":"null"}]},"outcome":{"type":"string","enum":["accepted","refused","unknown"]},"message":{"type":["string","null"]}}},"CteIssueEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/CteIssueResult"},"environment":{"$ref":"#/components/schemas/Environment"}}},"CteAuthorization":{"type":"object","required":["outcome","cstat","access_key","message"],"properties":{"outcome":{"type":"string","enum":["authorized","cancelled","rejected","pending","unavailable","not_sent","no_credentials"]},"cstat":{"type":["string","null"]},"access_key":{"type":["string","null"],"pattern":"^\\d{44}$"},"message":{"type":["string","null"]}}},"CteQueryResult":{"type":"object","required":["document","authorization","financial"],"properties":{"document":{"anyOf":[{"type":"object","allOf":[{"$ref":"#/components/schemas/Cte"}]},{"type":"null"}]},"authorization":{"$ref":"#/components/schemas/CteAuthorization"},"financial":{"type":["object","null"],"additionalProperties":true}}},"CteQueryEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/CteQueryResult"},"environment":{"$ref":"#/components/schemas/Environment"}}},"CteEventEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/CteEvent"},"environment":{"$ref":"#/components/schemas/Environment"}}},"CteServiceInput":{"type":"object","required":["ind_ie_toma","retira"],"properties":{"cfop":{"type":["string","null"],"minLength":4,"maxLength":4},"nat_op":{"type":["string","null"],"maxLength":60},"tp_serv":{"type":["integer","null"],"minimum":0,"maximum":3,"description":"Tipo de serviço (`ide/tpServ`): `0` normal, `1` subcontratação, `2` redespacho, `3`\nredespacho intermediário. O `4` (vinculado a multimodal) não é emitido pela plataforma\ne responde `422`. Nos tipos 1, 2 e 3 a emissão exige `cte_anterior.chave` e tomador\n`4` (Outros); nos tipos 2 e 3 a rota do rascunho precisa ser o trecho executado, não a\nviagem inteira do CT-e anterior — recusas antes do envio, para todo provedor.\n"},"ind_ie_toma":{"type":"integer","enum":[1,2,9]},"retira":{"type":"string","enum":["0","1"]},"x_det_retira":{"type":["string","null"],"maxLength":160}}},"CteRouteInput":{"type":"object","required":["origem_uf","destino_uf"],"properties":{"origem_codigo_municipio":{"type":["string","null"],"pattern":"^\\d{7}$"},"origem_municipio":{"type":["string","null"],"maxLength":80},"origem_uf":{"type":"string","minLength":2,"maxLength":2},"destino_codigo_municipio":{"type":["string","null"],"pattern":"^\\d{7}$"},"destino_municipio":{"type":["string","null"],"maxLength":80},"destino_uf":{"type":"string","minLength":2,"maxLength":2}}},"CtePayerInput":{"type":"object","required":["tipo"],"properties":{"tipo":{"type":"integer","enum":[0,3,4],"description":"0 remetente, 3 destinatário, 4 outros."},"documento":{"type":["string","null"],"maxLength":14,"description":"Obrigatório quando `tipo` for 4."},"ie":{"type":["string","null"],"maxLength":20},"nome":{"type":["string","null"],"maxLength":120},"logradouro":{"type":["string","null"],"maxLength":120},"numero":{"type":["string","null"],"maxLength":20},"complemento":{"type":["string","null"],"maxLength":60},"bairro":{"type":["string","null"],"maxLength":80},"codigo_municipio":{"type":["string","null"],"pattern":"^\\d{7}$"},"municipio":{"type":["string","null"],"maxLength":80},"uf":{"type":["string","null"],"minLength":2,"maxLength":2},"cep":{"type":["string","null"],"pattern":"^\\d{8}$"},"email":{"type":["string","null"],"format":"email","maxLength":120}}},"CteValuesInput":{"type":"object","required":["total"],"properties":{"total":{"type":"number","format":"double","minimum":0.01},"receber":{"type":["number","null"],"format":"double","minimum":0},"componentes":{"type":["array","null"],"maxItems":20,"items":{"type":"object","properties":{"nome":{"type":["string","null"],"maxLength":60},"valor":{"type":["number","null"],"format":"double","minimum":0}}}}}},"CteIcmsInput":{"type":"object","description":"Aceito por compatibilidade: variante, CST, base, alíquota e redução são substituídos pela\nregra de tributação da rota. Só os valores transacionais são lidos daqui — o grupo de ST\nretido (`v_bc_st_ret`, `v_icms_st_ret`, `p_icms_st_ret`, obrigatório quando a regra é\n`ICMS60`) e o crédito presumido (`v_cred`, opcional em `ICMS90`).\n","properties":{"variante":{"type":"string","enum":["ICMS00","ICMS20","ICMS45","ICMS60","ICMS90","ICMSOutraUF","ICMSSN"]},"cst":{"type":"string","minLength":2,"maxLength":2},"v_bc":{"type":["number","null"],"format":"double","minimum":0},"p_icms":{"type":["number","null"],"format":"double","minimum":0,"maximum":100},"v_icms":{"type":["number","null"],"format":"double","minimum":0},"p_red_bc":{"type":["number","null"],"format":"double","minimum":0,"maximum":100},"v_bc_st_ret":{"type":["number","null"],"format":"double","minimum":0},"v_icms_st_ret":{"type":["number","null"],"format":"double","minimum":0},"p_icms_st_ret":{"type":["number","null"],"format":"double","minimum":0,"maximum":100},"v_cred":{"type":["number","null"],"format":"double","minimum":0}}},"CteCargoInput":{"type":["object","null"],"properties":{"valor":{"type":["number","null"],"format":"double","minimum":0},"produto_predominante":{"type":["string","null"],"maxLength":60},"peso_bruto":{"type":["number","null"],"format":"double","minimum":0},"peso_liquido":{"type":["number","null"],"format":"double","minimum":0},"volumes":{"type":["integer","null"],"minimum":0}}},"CteTripInput":{"type":["object","null"],"properties":{"trip_starts_at":{"type":["string","null"],"format":"date"},"trip_ends_at":{"type":["string","null"],"format":"date"},"trip_distance_km":{"type":["integer","null"],"minimum":0,"maximum":99999},"cargo_sh_code":{"type":["string","null"],"pattern":"^\\d{4}$"},"cargo_type_code":{"type":["integer","null"],"minimum":1,"maximum":12},"toll_value":{"type":["number","null"],"format":"double","minimum":0},"fuel_value":{"type":["number","null"],"format":"double","minimum":0},"driver_freight_value":{"description":"O que o **motorista** recebe por esta viagem, em reais. É o valor que o CIOT\ndeclara à ANTT (`vlrFrete`) e o repasse que o financeiro registra — nunca o preço\ncobrado do tomador, que é o `valores.total` do CT-e.\n\n**Opcional na maioria dos casos.** Omitido, o repasse é calculado pela regra do\nmotorista (percentual sobre o frete, diária ou valor por entrega, conforme a faixa\nque cobre o CEP de destino da NF-e), e é esse número que o CIOT declara.\n\nPassa a ser **obrigatório** quando não há de onde calcular, e o CIOT fica pendente\naté ser informado: a regra do motorista é \"Valor Informado pela Empresa\", o\nmotorista não tem regra de repasse vinculada, ou nenhuma faixa da regra cobre o CEP\nde destino.\n","type":["number","null"],"format":"double","exclusiveMinimum":0}}},"CteCiotInput":{"type":["object","null"],"properties":{"tipo_operacao":{"type":["integer","null"],"enum":[1,2,3]},"alto_desempenho":{"type":["boolean","null"]},"retorno_vazio":{"type":["boolean","null"]},"composicao_veicular":{"type":["boolean","null"]}}},"CtePreviousPartyInput":{"type":["object","null"],"properties":{"documento":{"type":["string","null"],"maxLength":14},"ie":{"type":["string","null"],"maxLength":20},"nome":{"type":["string","null"],"maxLength":120},"fantasia":{"type":["string","null"],"maxLength":120},"endereco":{"type":["object","null"],"properties":{"logradouro":{"type":["string","null"],"maxLength":120},"numero":{"type":["string","null"],"maxLength":20},"complemento":{"type":["string","null"],"maxLength":60},"bairro":{"type":["string","null"],"maxLength":80},"codigo_municipio":{"type":["string","null"],"pattern":"^\\d{7}$"},"municipio":{"type":["string","null"],"maxLength":80},"uf":{"type":["string","null"],"minLength":2,"maxLength":2},"cep":{"type":["string","null"],"pattern":"^\\d{8}$"},"telefone":{"type":["string","null"],"maxLength":20}}}}},"CtePreviousInput":{"type":["object","null"],"required":["chave"],"properties":{"chave":{"type":"string","pattern":"^\\d{44}$"},"tp_serv_origem":{"type":["integer","null"],"minimum":0,"maximum":4},"nfe_chaves":{"type":["array","null"],"maxItems":100,"items":{"type":"string","pattern":"^\\d{44}$"}},"carga":{"type":["object","null"],"properties":{"valor":{"type":["number","null"],"minimum":0},"produto_predominante":{"type":["string","null"],"maxLength":60},"peso_bruto":{"type":["number","null"],"minimum":0},"volumes":{"type":["integer","null"],"minimum":0}}},"v_prest_origem":{"type":["number","null"],"minimum":0},"emit":{"$ref":"#/components/schemas/CtePreviousPartyInput"},"rem":{"$ref":"#/components/schemas/CtePreviousPartyInput"},"dest":{"$ref":"#/components/schemas/CtePreviousPartyInput"}}},"CteDraftInput":{"type":"object","required":["prestacao","rota","tomador","valores","icms"],"description":"Informe `nfe_access_keys` com ao menos uma NF-e, ou `cte_anterior.chave` para\nsubcontratação. As referências de NF-e, veículo e motorista pertencem à transportadora autenticada.\n","properties":{"nfe_access_keys":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","pattern":"^\\d{44}$"}},"cte_anterior":{"$ref":"#/components/schemas/CtePreviousInput"},"prestacao":{"$ref":"#/components/schemas/CteServiceInput"},"rota":{"$ref":"#/components/schemas/CteRouteInput"},"tomador":{"$ref":"#/components/schemas/CtePayerInput"},"valores":{"$ref":"#/components/schemas/CteValuesInput"},"icms":{"$ref":"#/components/schemas/CteIcmsInput"},"carga":{"$ref":"#/components/schemas/CteCargoInput"},"veiculo":{"type":["object","null"],"properties":{"vehicle_id":{"type":["integer","null"],"minimum":1},"trailer_vehicle_id":{"type":["integer","null"],"minimum":1}}},"motorista":{"type":["object","null"],"properties":{"driver_user_id":{"type":["integer","null"],"minimum":1}}},"viagem":{"$ref":"#/components/schemas/CteTripInput"},"ciot":{"$ref":"#/components/schemas/CteCiotInput"},"observacoes":{"type":["string","null"],"maxLength":2000}}},"JustificationInput":{"type":"object","required":["justification"],"properties":{"justification":{"type":"string","minLength":15,"maxLength":255}}},"CteCorrectionInput":{"type":"object","required":["alterations"],"properties":{"alterations":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["group","field","value"],"properties":{"group":{"type":"string","maxLength":20},"field":{"type":"string","maxLength":20,"description":"Campos fiscais vedados não podem ser corrigidos por este evento."},"value":{"type":"string","maxLength":500},"item":{"type":["integer","null"],"minimum":1,"maximum":99}}}}}},"CteDeliveryInput":{"type":"object","required":["proof"],"properties":{"proof":{"type":"string","maxLength":14000000,"pattern":"^data:image/(png|jpe?g);base64,","description":"Imagem PNG ou JPEG em data URL base64."},"receiver_name":{"type":["string","null"],"minLength":2,"maxLength":60},"receiver_document":{"type":["string","null"],"minLength":2,"maxLength":60},"invoice_keys":{"type":["array","null"],"maxItems":2000,"uniqueItems":true,"items":{"type":"string","pattern":"^\\d{44}$"}},"delivered_at":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$"},"information":{"type":["string","null"],"maxLength":2000},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90}}},"CteDeliveryCancellationInput":{"type":"object","description":"Informe exatamente um entre `sequence` e `protocol`.","properties":{"sequence":{"type":["integer","null"],"minimum":1,"maximum":999},"protocol":{"type":["string","null"],"maxLength":80}},"oneOf":[{"required":["sequence"]},{"required":["protocol"]}]},"CiotCheckResult":{"type":"object","required":["can_issue","warnings","blocking_reason","fleet","checked_at"],"properties":{"can_issue":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}},"blocking_reason":{"type":["string","null"]},"fleet":{"type":["object","null"],"additionalProperties":true},"checked_at":{"type":"string","format":"date-time"}}},"CiotCheckEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/CiotCheckResult"},"environment":{"$ref":"#/components/schemas/Environment"}}},"CiotOperationData":{"type":"object","required":["document","ciot"],"properties":{"document":{"anyOf":[{"type":"object","allOf":[{"$ref":"#/components/schemas/Cte"}]},{"type":"null"}]},"ciot":{"type":"object","required":["status","number","verification_code","protocol","message"],"properties":{"status":{"$ref":"#/components/schemas/CiotStatus"},"number":{"type":["string","null"]},"verification_code":{"type":["string","null"]},"protocol":{"type":["string","null"]},"message":{"type":["string","null"]}}}}},"CiotOperationEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/CiotOperationData"},"environment":{"$ref":"#/components/schemas/Environment"}}},"CiotRouteLeg":{"type":"object","required":["origem","destino"],"properties":{"origem":{"type":"object","required":["codigo_municipio_origem"],"properties":{"codigo_municipio_origem":{"type":"string","pattern":"^\\d{7}$"}}},"destino":{"type":"object","required":["codigo_municipio_destino"],"properties":{"codigo_municipio_destino":{"type":"string","pattern":"^\\d{7}$"}}},"distancia_percorrida":{"type":["integer","null"],"minimum":1},"qtd_viagens":{"type":["integer","null"],"minimum":1,"maximum":999}}},"CiotCargoChange":{"type":["object","null"],"properties":{"codigo_natureza_carga":{"type":["string","null"],"pattern":"^\\d{4}$"},"peso_carga":{"type":["number","null"],"format":"double","exclusiveMinimum":0},"codigo_tipo_carga":{"type":["integer","null"],"minimum":4,"maximum":12}}},"CiotRectificationInput":{"type":"object","minProperties":1,"description":"Informe ao menos um grupo de alteração.","properties":{"valor_frete":{"type":["number","null"],"format":"double","exclusiveMinimum":0},"data_fim_viagem":{"type":["string","null"],"format":"date"},"origem_destino":{"type":["array","null"],"minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/CiotRouteLeg"}},"dados_carga":{"$ref":"#/components/schemas/CiotCargoChange"}}},"CiotClosingInput":{"type":"object","required":["peso_carga"],"properties":{"peso_carga":{"type":"number","format":"double","exclusiveMinimum":0},"origem_destino":{"type":["array","null"],"minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/CiotRouteLeg"}}}},"VehicleFiscalData":{"type":"object","required":["brand","model","vehicle_kind","axles","tare_kg","wheel_type","body_type","km_per_liter_model","km_per_liter_vehicle","owner_ie","owner_state"],"properties":{"brand":{"type":["string","null"]},"model":{"type":["string","null"]},"vehicle_kind":{"type":["integer","null"],"enum":[1,2]},"axles":{"type":["integer","null"]},"tare_kg":{"type":["integer","null"]},"wheel_type":{"type":["integer","null"]},"body_type":{"type":["integer","null"]},"km_per_liter_model":{"type":["number","null"],"format":"double"},"km_per_liter_vehicle":{"type":["number","null"],"format":"double"},"owner_ie":{"type":["string","null"]},"owner_state":{"type":["string","null"]}}},"Vehicle":{"type":"object","required":["id","plate","plate_state","renavam","owner_type","owner_document","owner_name","owner_rntrc","fiscal"],"properties":{"id":{"type":"integer","minimum":1},"plate":{"type":"string"},"plate_state":{"type":["string","null"]},"renavam":{"type":["string","null"]},"owner_type":{"type":"string","enum":["own","third"]},"owner_document":{"type":["string","null"]},"owner_name":{"type":["string","null"]},"owner_rntrc":{"type":["string","null"]},"fiscal":{"$ref":"#/components/schemas/VehicleFiscalData"}}},"VehicleCreateInput":{"type":"object","required":["plate"],"properties":{"plate":{"type":"string","pattern":"^[A-Z]{3}[0-9][A-Z0-9][0-9]{2}$"},"plate_state":{"type":["string","null"],"minLength":2,"maxLength":2},"renavam":{"type":["string","null"],"pattern":"^\\d{11}$"},"tare_kg":{"type":["number","null"],"minimum":0},"capacity_kg":{"type":["number","null"],"minimum":0},"capacity_m3":{"type":["number","null"],"minimum":0},"axles":{"type":["number","null"],"minimum":0,"maximum":255},"body_type":{"type":["number","null"],"minimum":0,"maximum":255},"wheel_type":{"type":["number","null"],"minimum":0,"maximum":255},"owner_type":{"type":["string","null"],"enum":["own","third"],"default":"own"},"owner_document":{"type":["string","null"],"maxLength":14},"owner_name":{"type":["string","null"],"maxLength":120},"owner_rntrc":{"type":["string","null"],"maxLength":8},"default_driver_user_id":{"type":["integer","null"],"minimum":1}}},"VehicleFiscalInput":{"type":"object","minProperties":1,"description":"Atualização parcial; envie ao menos uma propriedade.","properties":{"brand":{"type":["string","null"],"maxLength":40},"model":{"type":["string","null"],"maxLength":60},"vehicle_kind":{"type":["integer","null"],"enum":[1,2]},"axles":{"type":["integer","null"],"minimum":1,"maximum":255},"km_per_liter_model":{"type":["number","null"],"minimum":0,"maximum":999.99},"km_per_liter_vehicle":{"type":["number","null"],"minimum":0,"maximum":999.99},"tare_kg":{"type":["integer","null"],"minimum":1,"maximum":999999},"wheel_type":{"type":["string","null"],"enum":["01","02","03","04","05","06"]},"body_type":{"type":["string","null"],"enum":["00","01","02","03","04","05"]},"owner_ie":{"type":["string","null"],"maxLength":20},"owner_state":{"type":["string","null"],"minLength":2,"maxLength":2}}},"VehicleEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/Vehicle"},"environment":{"$ref":"#/components/schemas/Environment"}}},"VehicleListEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Vehicle"}},"environment":{"$ref":"#/components/schemas/Environment"}}},"DriverFiscalProfile":{"type":"object","required":["cnh_number","cnh_category","cnh_state","cnh_issued_at","cnh_valid_until","rg_number","rg_issuer","rg_state","father_name","mother_name"],"properties":{"cnh_number":{"type":["string","null"]},"cnh_category":{"type":["string","null"]},"cnh_state":{"type":["string","null"]},"cnh_issued_at":{"type":["string","null"],"format":"date"},"cnh_valid_until":{"type":["string","null"],"format":"date"},"rg_number":{"type":["string","null"]},"rg_issuer":{"type":["string","null"]},"rg_state":{"type":["string","null"]},"father_name":{"type":["string","null"]},"mother_name":{"type":["string","null"]}}},"Driver":{"type":"object","required":["id","name","document","fiscal_profile"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"},"document":{"type":["string","null"]},"fiscal_profile":{"anyOf":[{"type":"object","allOf":[{"$ref":"#/components/schemas/DriverFiscalProfile"}]},{"type":"null"}]}}},"DriverFiscalInput":{"type":"object","minProperties":1,"description":"Atualização parcial; envie ao menos uma propriedade.","properties":{"cnh_number":{"type":["string","null"],"pattern":"^\\d{11}$"},"cnh_category":{"type":["string","null"],"enum":["A","B","C","D","E","AB","AC","AD","AE"]},"cnh_state":{"type":["string","null"],"minLength":2,"maxLength":2},"cnh_issued_at":{"type":["string","null"],"format":"date"},"cnh_valid_until":{"type":["string","null"],"format":"date"},"rg_number":{"type":["string","null"],"maxLength":20},"rg_issuer":{"type":["string","null"],"maxLength":20},"rg_state":{"type":["string","null"],"minLength":2,"maxLength":2},"father_name":{"type":["string","null"],"maxLength":120},"mother_name":{"type":["string","null"],"maxLength":120}}},"DriverEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/Driver"},"environment":{"$ref":"#/components/schemas/Environment"}}},"DriverListEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Driver"}},"environment":{"$ref":"#/components/schemas/Environment"}}},"MdfeStatus":{"type":"string","enum":["draft","sent","waiting","authorized","rejected","closed","cancelled"]},"Mdfe":{"type":"object","required":["id","status","vehicle","driver_id","trailers","route","cte_ids","number","series","access_key","protocol","sefaz_protocol","cstat","reason","authorized_at","closed_at","closing_protocol","payload","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"UUID público usado em todos os caminhos do MDF-e."},"status":{"$ref":"#/components/schemas/MdfeStatus"},"vehicle":{"$ref":"#/components/schemas/Vehicle"},"driver_id":{"type":["integer","null"]},"trailers":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Vehicle"},{"type":"object","required":["position"],"properties":{"position":{"type":"integer","minimum":1,"maximum":3}}}]}},"route":{"allOf":[{"$ref":"#/components/schemas/FiscalRoute"},{"type":"object","required":["starts_at","ends_at"],"properties":{"starts_at":{"type":["string","null"],"format":"date"},"ends_at":{"type":["string","null"],"format":"date"}}}]},"cte_ids":{"type":"array","description":"UUIDs públicos dos CT-e autorizados cobertos pelo MDF-e.","items":{"type":"string","format":"uuid"}},"number":{"type":["integer","null"]},"series":{"type":["string","null"]},"access_key":{"type":["string","null"],"pattern":"^\\d{44}$"},"protocol":{"type":["string","null"]},"sefaz_protocol":{"type":["string","null"]},"cstat":{"type":["string","null"]},"reason":{"type":["string","null"]},"authorized_at":{"type":["string","null"],"format":"date-time"},"closed_at":{"type":["string","null"],"format":"date"},"closing_protocol":{"type":["string","null"]},"payload":{"type":"object","additionalProperties":true},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"MdfeInsuranceInput":{"type":["object","null"],"properties":{"responsavel":{"type":["string","null"],"enum":["1","2"]},"documento":{"type":["string","null"],"maxLength":14},"seguradora":{"type":["string","null"],"maxLength":30},"cnpj_seguradora":{"type":["string","null"],"pattern":"^\\d{14}$"},"apolice":{"type":["string","null"],"maxLength":20},"averbacoes":{"type":["array","null"],"maxItems":20,"items":{"type":["string","null"],"maxLength":40}}}},"MdfeTechnicalContactInput":{"type":["object","null"],"properties":{"cnpj":{"type":["string","null"],"pattern":"^\\d{14}$"},"contato":{"type":["string","null"],"maxLength":60},"email":{"type":["string","null"],"format":"email","maxLength":60},"telefone":{"type":["string","null"],"maxLength":20}}},"MdfeDraftInput":{"type":"object","required":["cte_uuids","vehicle_id","origin_state","destination_state"],"properties":{"cte_uuids":{"type":"array","minItems":1,"uniqueItems":true,"description":"UUIDs públicos de CT-e autorizados e disponíveis.","items":{"type":"string","format":"uuid"}},"vehicle_id":{"type":"integer","minimum":1},"trailers":{"type":["array","null"],"maxItems":3,"uniqueItems":true,"items":{"type":"integer","minimum":1}},"driver_user_id":{"type":["integer","null"],"minimum":1},"starts_at":{"type":["string","null"],"format":"date"},"ends_at":{"type":["string","null"],"format":"date"},"origin_city_code":{"type":["string","null"],"pattern":"^\\d{7}$"},"origin_city":{"type":["string","null"],"maxLength":80},"origin_state":{"type":"string","minLength":2,"maxLength":2},"destination_city_code":{"type":["string","null"],"pattern":"^\\d{7}$"},"destination_city":{"type":["string","null"],"maxLength":80},"destination_state":{"type":"string","minLength":2,"maxLength":2},"seguro":{"$ref":"#/components/schemas/MdfeInsuranceInput"},"salvar_seguro_padrao":{"type":["boolean","null"]},"info_fisco":{"type":["string","null"],"maxLength":2000},"observacoes":{"type":["string","null"],"maxLength":5000},"resp_tec":{"$ref":"#/components/schemas/MdfeTechnicalContactInput"},"serie":{"type":["string","null"],"maxLength":3}}},"MdfeEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/Mdfe"},"environment":{"$ref":"#/components/schemas/Environment"}}},"MdfeListEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Mdfe"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"environment":{"$ref":"#/components/schemas/Environment"}}},"MdfeOperationData":{"type":"object","required":["document","message"],"properties":{"document":{"anyOf":[{"type":"object","allOf":[{"$ref":"#/components/schemas/Mdfe"}]},{"type":"null"}]},"message":{"type":["string","null"]}}},"MdfeOperationEnvelope":{"type":"object","required":["data","environment"],"properties":{"data":{"$ref":"#/components/schemas/MdfeOperationData"},"environment":{"$ref":"#/components/schemas/Environment"}}},"MdfeClosingInput":{"type":"object","required":["closing_city_code","closed_on"],"properties":{"closing_city_code":{"type":"string","pattern":"^\\d{7}$"},"closing_city":{"type":["string","null"],"minLength":2,"maxLength":60},"closing_state":{"type":["string","null"],"minLength":2,"maxLength":2},"closed_on":{"type":"string","format":"date","description":"Data civil igual ou anterior à data atual."}}},"MdfeDriverInput":{"type":"object","required":["cpf","name"],"properties":{"cpf":{"type":"string","pattern":"^\\d{11}$"},"name":{"type":"string","minLength":2,"maxLength":60}}},"CotarVpoRequest":{"type":"object","required":["origem","destino","eixos"],"properties":{"origem":{"type":"string","minLength":3,"maxLength":150,"description":"CEP (com ou sem hífen) ou nome da cidade/endereço de partida."},"destino":{"type":"string","minLength":3,"maxLength":150,"description":"CEP (com ou sem hífen) ou nome da cidade/endereço de chegada."},"eixos":{"type":"integer","minimum":2,"maximum":10,"description":"Quantidade total de eixos do veículo comercial ou conjunto."},"placa":{"type":"string","maxLength":10,"nullable":true,"description":"Placa do veículo comercial (padrão Mercosul ou antigo)."},"modalidade":{"type":"string","enum":["planejada","estendida","customizada"],"nullable":true,"description":"Modalidade de rota pretendida (`planejada`: rota direta otimizada; `estendida`: rota com tolerância para desvios; `customizada`: praças específicas)."},"pontos_parada":{"type":"array","nullable":true,"maxItems":20,"description":"Pontos intermediários da viagem, **na ordem em que o veículo passa**, entre `origem` e `destino`.\nA operadora não aceita polyline: a rota é traçada por pontos de parada, e cada ponto pode ser uma\ncidade (`cidade`, no formato \"Cidade, UF\") **ou** um par `latitude`/`longitude` em graus decimais\n(vértices relevantes de um traçado próprio, por exemplo). Se um ponto trouxer cidade e coordenadas,\nvale a cidade. Use-o para forçar o trajeto por uma rodovia específica ou reproduzir a rota do seu\nroteirizador. Sem este campo a operadora escolhe o trajeto entre origem e destino.\n","items":{"$ref":"#/components/schemas/VpoPontoParada"}},"tipo_rota":{"type":"string","enum":["mais_rapida","mais_curta"],"nullable":true,"default":"mais_rapida","description":"Critério da operadora para traçar a rota principal entre os pontos."}}},"VpoPontoParada":{"type":"object","description":"Um ponto de parada — informe `cidade` ou o par `latitude`/`longitude`.","properties":{"cidade":{"type":"string","minLength":3,"maxLength":150,"nullable":true,"description":"Cidade e UF do ponto (\"Cidade, UF\")."},"latitude":{"type":"number","format":"double","minimum":-90,"maximum":90,"nullable":true,"description":"Latitude em graus decimais (obrigatória junto com `longitude` quando não há `cidade`)."},"longitude":{"type":"number","format":"double","minimum":-180,"maximum":180,"nullable":true,"description":"Longitude em graus decimais."},"descricao":{"type":"string","maxLength":60,"nullable":true,"description":"Rótulo livre do ponto, devolvido pela operadora em mensagens de erro."}}},"PracaPedagio":{"type":"object","description":"Praça de pedágio da rota.","properties":{"id":{"type":"string","description":"Identificador da praça na operadora — é o que vai em `pracas` na compra."},"nome":{"type":"string","description":"Nome da praça."},"concessionaria":{"type":"string","description":"Concessionária."},"rodovia":{"type":"string","description":"Rodovia."},"km":{"type":"string","description":"Quilômetro."},"eixos":{"type":"integer","description":"Eixos considerados."},"valor":{"type":"number","description":"Valor da praça quando a operadora o informa na cotação (a Sem Parar precifica a rota inteira — o detalhe por praça vem no recibo)."},"free_flow":{"type":"boolean","description":"Pórtico free flow (sem cabine)."},"sentido":{"type":"string","description":"Sentido da praça, quando informado.","nullable":true}}},"CustoModalidade":{"type":"object","description":"Valores de uma modalidade para a rota.","properties":{"valor_pedagio":{"type":"number","description":"Soma do pedágio das praças da rota (em reais)."},"valor_total":{"type":"number","description":"Valor total do Vale-Pedágio (pedágio + tarifa da modalidade), debitado da Conta Operacional."},"valor_pedagio_formatado":{"type":"string","description":"Pedágio formatado."},"valor_total_formatado":{"type":"string","description":"Valor total formatado."}}},"RotaPedagio":{"type":"object","properties":{"id":{"type":"string","description":"Identificador da rota (ids das praças)."},"nome":{"type":"string","description":"Nome da rota."},"distancia_km":{"type":"number","description":"Distância, quando informada pela operadora."},"tempo_estimado":{"type":"string","description":"Tempo estimado, quando informado."},"valor_total":{"type":"number","description":"Pedágio da rota (em reais) — use em `valor_pedagio` na compra."},"recomendada":{"type":"boolean","description":"Rota recomendada pela operadora."},"precificada":{"type":"boolean","description":"`true` quando o valor veio da operadora para esta placa/eixos."},"operadora_rota_id":{"type":"string","description":"Id da rota na operadora (informativo).","nullable":true},"pracas":{"type":"array","description":"Praças da rota — envie em `pracas` na compra.","items":{"$ref":"#/components/schemas/PracaPedagio"}},"custos":{"type":"object","description":"Valores por modalidade.","properties":{"planejada":{"$ref":"#/components/schemas/CustoModalidade"},"estendida":{"$ref":"#/components/schemas/CustoModalidade"},"customizada":{"$ref":"#/components/schemas/CustoModalidade"}}}}},"CotarVpoResponse":{"type":"object","properties":{"success":{"type":"boolean"},"rotas":{"type":"array","items":{"$ref":"#/components/schemas/RotaPedagio"}}}},"EmitirVpoRequest":{"type":"object","required":["transportador_documento","transportador_rntrc","placa","eixos","modalidade","valor_pedagio","vigencia_inicio","vigencia_fim","pracas"],"properties":{"transportador_documento":{"type":"string","description":"CPF ou CNPJ do transportador contratado (apenas números).","maxLength":20},"transportador_rntrc":{"type":"string","description":"RNTRC do transportador (a FleetPay confere na ANTT; vale o RNTRC da ANTT).","maxLength":20},"transportador_nome":{"type":"string","description":"Nome do transportador (opcional; sem ele vale o nome da ANTT).","nullable":true,"maxLength":150},"placa":{"type":"string","description":"Placa do veículo (com tag na operadora e na frota do RNTRC).","maxLength":10},"eixos":{"type":"integer","description":"Quantidade de eixos.","minimum":2,"maximum":10},"operadora":{"type":"string","description":"Operadora de pedágio.","enum":["sem_parar","conectcar","veloe","move_mais"],"nullable":true},"modalidade":{"type":"string","description":"Modalidade da rota.","enum":["planejada","estendida","customizada"]},"valor_pedagio":{"type":"number","description":"Pedágio da rota cotada (`rotas[n].valor_total`).","minimum":0.01},"vigencia_inicio":{"type":"string","description":"Início da vigência (AAAA-MM-DD).","format":"date"},"vigencia_fim":{"type":"string","description":"Fim da vigência (AAAA-MM-DD).","format":"date"},"pracas":{"type":"array","minItems":1,"description":"**Obrigatório para `sem_parar`.** As praças da rota escolhida na cotação (`rotas[n].pracas`), com o `id` de cada uma. Pode reenviar os objetos da cotação como vieram.","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Id da praça."},"nome":{"type":"string","description":"Nome da praça."}}}},"numero_ciot":{"type":"string","description":"Número do CIOT da operação de transporte.","nullable":true,"maxLength":50},"referencia_externa":{"type":"string","description":"Sua referência (pedido, viagem).","nullable":true,"maxLength":100},"origem_cidade":{"type":"string","description":"Cidade de origem.","nullable":true},"origem_uf":{"type":"string","description":"UF de origem.","nullable":true,"maxLength":2},"destino_cidade":{"type":"string","description":"Cidade de destino.","nullable":true},"destino_uf":{"type":"string","description":"UF de destino.","nullable":true,"maxLength":2},"desvio_autorizado_por":{"type":"string","description":"No complemento: quem autorizou o desvio.","enum":["embarcador","motorista"],"nullable":true},"emulado":{"type":"boolean","description":"**Somente homologação.** Com `true`, a emissão acontece de verdade na operadora (viagem, nº ANTT, recibo, cancelamento) mas **nenhum valor é debitado ou estornado** da Conta Operacional. Em produção o pedido é recusado (422).","nullable":true,"default":false}}},"ReciboValePedagio":{"type":"object","description":"Recibo do Vale-Pedágio, como a operadora o emite.","properties":{"numero_viagem":{"type":"string"},"tipo":{"type":"string"},"categoria_veiculo":{"type":"string"},"emissor":{"type":"object","description":"Embarcador que emitiu.","properties":{"cnpj":{"type":"string"},"nome":{"type":"string"}}},"transportador":{"type":"object","description":"Titular da tag na operadora.","properties":{"cnpj":{"type":"string"},"nome":{"type":"string"}}},"rota":{"type":"string"},"data_compra":{"type":"string","format":"date-time"},"data_viagem":{"type":"string","format":"date"},"data_expiracao":{"type":"string","format":"date"},"total":{"type":"number","description":"Pedágio total da viagem (em reais)."},"observacao":{"type":"string"},"pracas":{"type":"array","items":{"type":"object","properties":{"nome":{"type":"string"},"rodovia":{"type":"string"},"concessionaria":{"type":"string"},"tarifa":{"type":"number"}}}}}},"ValePedagioEmitido":{"type":"object","properties":{"uuid":{"type":"string","description":"Identificador do Vale-Pedágio na FleetPay — use nas demais chamadas.","format":"uuid"},"status":{"type":"string","description":"`pending_debit`, `debit_confirmed`, `confirmed`, `failed` ou `canceled`."},"status_descricao":{"type":"string","description":"Status por extenso."},"id_vpo_antt":{"type":"string","description":"Número do Vale-Pedágio registrado na ANTT.","nullable":true},"operadora":{"type":"string","description":"Operadora."},"numero_viagem":{"type":"string","description":"Número da viagem na operadora.","nullable":true},"nsu":{"type":"string","description":"NSU da compra na operadora.","nullable":true},"placa":{"type":"string","description":"Placa."},"valor_pedagio":{"type":"number","description":"Pedágio (em reais)."},"valor_total":{"type":"number","description":"Valor total debitado (em reais)."},"vigencia_inicio":{"type":"string","description":"Início da vigência.","format":"date-time"},"vigencia_fim":{"type":"string","description":"Fim da vigência.","format":"date-time"},"recibo":{"$ref":"#/components/schemas/ReciboValePedagio"},"emulado":{"type":"boolean","description":"`true` quando emitido em modo emulado (homologação)."}}},"EmitirVpoResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ValePedagioEmitido"}}},"ValePedagioDetalhe":{"type":"object","properties":{"uuid":{"type":"string","description":"Identificador do Vale-Pedágio na FleetPay — use nas demais chamadas.","format":"uuid"},"status":{"type":"string","description":"`pending_debit`, `debit_confirmed`, `confirmed`, `failed` ou `canceled`."},"status_descricao":{"type":"string","description":"Status por extenso."},"id_vpo_antt":{"type":"string","description":"Número do Vale-Pedágio registrado na ANTT.","nullable":true},"operadora":{"type":"string","description":"Operadora."},"numero_viagem":{"type":"string","description":"Número da viagem na operadora.","nullable":true},"nsu":{"type":"string","description":"NSU da compra na operadora.","nullable":true},"placa":{"type":"string","description":"Placa."},"valor_pedagio":{"type":"number","description":"Pedágio (em reais)."},"valor_total":{"type":"number","description":"Valor total debitado (em reais)."},"vigencia_inicio":{"type":"string","description":"Início da vigência.","format":"date-time"},"vigencia_fim":{"type":"string","description":"Fim da vigência.","format":"date-time"},"eixos":{"type":"integer","description":"Eixos."},"transportador_documento":{"type":"string","description":"CPF/CNPJ do transportador."},"transportador_rntrc":{"type":"string","description":"RNTRC (da ANTT)."},"modalidade":{"type":"string","description":"Modalidade."},"pracas":{"type":"array","items":{"$ref":"#/components/schemas/PracaPedagio"}},"desvio":{"type":"boolean","description":"`true` para Vale-Pedágio complementar."},"recibo":{"$ref":"#/components/schemas/ReciboValePedagio"},"emulado":{"type":"boolean","description":"`true` quando emitido em modo emulado (homologação)."}}},"DetalhesVpoResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ValePedagioDetalhe"}}},"CancelarVpoRequest":{"type":"object","properties":{"motivo":{"type":"string","description":"Motivo do cancelamento (opcional).","nullable":true}}},"CancelarVpoResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"ReciboVpoResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"id_vpo_antt":{"type":"string","nullable":true},"status":{"type":"string"},"recibo":{"$ref":"#/components/schemas/ReciboValePedagio"},"origem_recibo":{"type":"string","enum":["operadora","emissao"],"description":"`operadora` = recibo atual da operadora; `emissao` = o guardado na emissão (quando a operadora não o entrega mais, ex.: viagem cancelada)."}}}}},"ComplementoVpoResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Vale-Pedágio complementar."},"vpo_pai_uuid":{"type":"string","format":"uuid","description":"Vale-Pedágio original."},"id_vpo_antt":{"type":"string","nullable":true},"status":{"type":"string"},"valor_total":{"type":"number"},"emulado":{"type":"boolean"}}}}}},"parameters":{"ContraCteBatchId":{"name":"batch_id","in":"path","required":true,"description":"UUID do lote devolvido pelo `POST /fiscal/cte-subcontratacao/lote`.","schema":{"type":"string","format":"uuid"}},"InboundCteAccessKey":{"name":"access_key","in":"path","required":true,"description":"Chave de acesso do CT-e recebido, 44 dígitos.","schema":{"type":"string","pattern":"^\\d{44}$"}},"Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"PerPage":{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"NfeAccessKey":{"name":"access_key","in":"path","required":true,"description":"Chave de acesso da NF-e, com 44 dígitos.","schema":{"type":"string","pattern":"^\\d{44}$"}},"CteUuid":{"name":"cte_uuid","in":"path","required":true,"description":"UUID público do CT-e.","schema":{"type":"string","format":"uuid"}},"MdfeUuid":{"name":"mdfe_uuid","in":"path","required":true,"description":"UUID público do MDF-e.","schema":{"type":"string","format":"uuid"}},"EventKey":{"name":"event_key","in":"path","required":true,"description":"Identificador público opaco do evento, devolvido em `data.id`.","schema":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"VehicleId":{"name":"id","in":"path","required":true,"description":"ID inteiro do veículo.","schema":{"type":"integer","minimum":1}},"DriverId":{"name":"id","in":"path","required":true,"description":"ID inteiro do motorista.","schema":{"type":"integer","minimum":1}},"VpoUuid":{"name":"uuid","in":"path","required":true,"description":"UUID do Vale-Pedágio Obrigatório devolvido na emissão (`/vale-pedagio/comprar`).","schema":{"type":"string","format":"uuid"}}},"headers":{"RequestId":{"description":"Identificador de correlação da chamada.","schema":{"type":"string","format":"uuid"}}}}}