openapi: 3.0.3
info:
  title: API CTe-OS da CTE Brasil
  version: 1.1.1
  x-ctebrasil-updated-at: '2026-09-02'
  x-ctebrasil-versioning:
    strategy: SemVer
    url-major-version: v1
    compatible-change: Incrementa a versão secundária; a URL permanece em `/api/v1`.
    correction: Incrementa a versão de correção; a URL permanece em `/api/v1`.
    breaking-change: Incrementa a versão principal e publica uma nova URL, como `/api/v2`.
  x-ctebrasil-changelog:
    - version: 1.1.1
      date: '2026-09-02'
      changes:
        - A validação de ICMS45 passa a identificar explicitamente o caminho ICMS.ICMS45.CST e os códigos 40, 41 e 51, diferenciando-o de IBSCBS.cClassTrib.
        - O CST do grupo ICMS45 passa a constar como obrigatório no contrato, e o exemplo de emissão isenta separa esse campo dos dados independentes de IBS/CBS.
        - As obrigatoriedades condicionais dos grupos ICMS00, ICMS20, ICMS90, ICMSOutraUF, ICMSUFFim e IBSCBS passam a ser descritas no contrato e validadas com mensagens de campo específicas.
        - O percentual de redução da base em ICMSOutraUF passa a ser opcional, conforme o esquema oficial do CT-eOS.
    - version: 1.1.0
      date: '2026-08-04'
      changes:
        - A referência de classificações IBS/CBS passa a informar a redução fixa da base e os indicadores de tributação regular e estorno de crédito.
        - Corrigidos os exemplos de IBS de 2026 para manter a parcela municipal zerada.
        - A consulta de classificações IBS/CBS passa a aceitar `asOf` e retorna as regras aplicáveis à data de referência.
        - O retorno informa grupos, reduções, alíquotas padrão e mudanças futuras oficiais em `upcomingChanges`.
        - A documentação identifica a proibição de `gDevTrib` no CT-eOS a partir de 31/08/2026 e orienta a consulta temporal das regras.
    - version: 1.0.0
      date: '2026-07-29'
      changes:
        - Publicação original.
  x-ctebrasil-documentation:
    playground: structured-json-inputs
    reference-groups: native-section-headings
    reference-rendering: server-rendered-groups-with-stable-layout
    conditional-groups: json-discriminator-and-empty-array-pruning
    payload-encoding: utf-8-base64-decoded-before-json-parse
    array-controls: generic-nested-add-and-item-remove-controls-derived-from-json-arrays
    examples: populated-synthetic-effective-request-body; playground-model-kept-separate
    endpoint-anchors: semantic-method-and-route-slugs
    source-of-truth: request-body examples and schemas
    synchronization: Atualizações da tela api-docs exigem atualização e validação deste contrato no mesmo lote.
  description: |
    Contrato da API CTe-OS da CTE Brasil. Cadastros e consultas usam a base
    `/api/v1`; somente emissão e eventos fiscais recebem o ambiente na URL.
    Cada Chave identifica a empresa emissora, suas permissões e seus limites.
    Os valores apresentados nos exemplos são fictícios; os códigos HTTP, os
    campos e a estrutura reproduzem o contrato efetivamente montado pela API.
servers:
  - url: https://www.ctebrasil.com.br/api/v1
    description: URL base da API em produção.
x-ctebrasil-rate-limits:
  scope: api-key
  description: |
    Os quatro limites são aplicados simultaneamente e de forma independente a
    cada Chave da API. Uma chamada aceita consome as janelas de 15 segundos,
    60 segundos e 1 hora e ocupa uma vaga de concorrência até a resposta ser
    concluída. Ao exceder qualquer limite, aguarde a janela correspondente e
    tente novamente; a API retorna HTTP 429 com
    `integration_rate_limit_exceeded` para uma janela de tempo ou
    `integration_concurrency_exceeded` para concorrência.
  max-concurrent: 2
  windows:
    - seconds: 15
      limit: 15
    - seconds: 60
      limit: 60
    - seconds: 3600
      limit: 1000
x-ctebrasil-uf-values: &ufValues [AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO]
x-ctebrasil-uf-labels: &ufLabels
  AC: Acre
  AL: Alagoas
  AP: Amapá
  AM: Amazonas
  BA: Bahia
  CE: Ceará
  DF: Distrito Federal
  ES: Espírito Santo
  GO: Goiás
  MA: Maranhão
  MT: Mato Grosso
  MS: Mato Grosso do Sul
  MG: Minas Gerais
  PA: Pará
  PB: Paraíba
  PR: Paraná
  PE: Pernambuco
  PI: Piauí
  RJ: Rio de Janeiro
  RN: Rio Grande do Norte
  RS: Rio Grande do Sul
  RO: Rondônia
  RR: Roraima
  SC: Santa Catarina
  SP: São Paulo
  SE: Sergipe
  TO: Tocantins
tags:
  - name: Referências
    description: Dados auxiliares usados para preencher cadastros e documentos sem adivinhação.
  - name: Minha empresa
    description: Consulta e manutenção da empresa emissora vinculada à Chave.
  - name: Tomadores
    description: Cadastro das pessoas ou empresas responsáveis pelo pagamento do transporte.
  - name: Veículos
    description: Cadastro da frota utilizada nas emissões.
  - name: CTe-OS
    description: Consultas, validação, emissão e eventos fiscais do CTe-OS.
  - name: CTe-OS - Complementares
    description: Catálogos e operações auxiliares específicas do CTe-OS.
paths:
  /municipios:
    get:
      tags: [Referências]
      summary: Lista municípios e códigos IBGE para preenchimento do CTe-OS
      operationId: listMunicipalities
      x-ctebrasil-response-example: { ok: true, status: 200, data: { items: [{ nome: Caxias do Sul, uf: RS, ibge: '4305108' }] } }
      description: Pesquise pelo nome e, se necessário, limite o resultado a uma UF. Use o código IBGE retornado em cMunIni, cMunFim e cod_municipio.
      security: [{ bearerAuth: [] }]
      parameters:
        - name: uf
          in: query
          description: Sigla da UF usada para filtrar os municípios. Deixe sem informar para pesquisar em todo o Brasil.
          example: RS
          schema:
            type: string
            enum: *ufValues
            x-ctebrasil-enum-labels: *ufLabels
        - name: busca
          in: query
          description: Parte do nome do município, sem necessidade de informar o nome completo.
          example: Caxias
          schema: { type: string, minLength: 1 }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /municipios/{codigo_ibge}:
    get:
      tags: [Referências]
      summary: Consulta um município pelo código IBGE usado no XML
      operationId: readMunicipality
      x-ctebrasil-response-example: { ok: true, status: 200, data: { codigo_ibge: '4305108', nome: Caxias do Sul, uf: RS } }
      description: Retorna nome e UF oficiais de um código IBGE de sete dígitos.
      security: [{ bearerAuth: [] }]
      parameters:
        - name: codigo_ibge
          in: path
          required: true
          description: Código IBGE de sete dígitos, sem pontuação.
          example: '4305108'
          schema: { type: string, pattern: '^\\d{7}$' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
  /referencias/ibscbs/csts:
    get:
      tags: [CTe-OS - Complementares]
      summary: Lista os CSTs do IBS/CBS disponíveis para emissão
      operationId: listIbsCbsCsts
      x-ctebrasil-response-example: { ok: true, status: 200, data: { items: [{ cst: '000', descricao: Tributação integral, ind_gibscbs: '1', ind_gibscbsmono: '0', ind_gred: '0', ind_gdif: '0', ind_gtransfcred: '0' }] } }
      description: Use esta consulta para preencher a lista de CSTs. São retornados somente CSTs ativos que possuem ao menos uma classificação tributária disponível.
      security: [{ bearerAuth: [] }]
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /referencias/ibscbs/csts/{cst}/classificacoes:
    get:
      tags: [CTe-OS - Complementares]
      summary: Lista as classificações tributárias vinculadas a um CST do IBS/CBS
      operationId: listIbsCbsClassificationsByCst
      x-ctebrasil-response-example:
        ok: true
        status: 200
        data:
          asOf: '2026-08-15'
          items:
            - cst: '222'
              cod_classif: '222001'
              descricao: Transporte internacional de passageiros, ida e volta, vendidos conjuntamente.
              description: Transporte internacional de passageiros, ida e volta, vendidos conjuntamente.
              pRedIBS: null
              pRedCBS: null
              pRedBC: '50.0000'
              ind_redutorbc: '1'
              ind_credpres: '0'
              ind_gtribregular: '0'
              ind_gestornocred: '0'
              vig_ini: '2025-05-05'
              vig_fim: ''
              effectiveFrom: '2025-05-05'
              effectiveUntil: null
              groups: { gIBSCBS: true, gRed: false, gDif: false, gDevTrib: true, gTribRegular: false, gEstornoCred: false, indDoacao: false, gALCZFMCBS: false, gTribCompraGov: false }
              percentages: { pRedBC: 50, pRedIBS: null, pRedCBS: null }
              defaultRates: { pIBSUF: 0.1, pIBSMun: 0, pCBS: 0.9 }
          upcomingChanges:
            - effectiveFrom: '2026-08-31'
              changeType: PROHIBITION
              field: gDevTrib
              status: PROHIBITED
              description: O grupo gDevTrib não poderá ser informado no CT-eOS.
              source: { document: NT CT-e 2026.002 RTC, version: '1.00' }
      description: Informe um CST obtido em `/referencias/ibscbs/csts`. O retorno contém as classificações tributárias vigentes na data `asOf`, ou na data atual quando o parâmetro for omitido. Os campos legados permanecem disponíveis; `groups`, `percentages` e `defaultRates` apresentam a regra resolvida, enquanto `upcomingChanges` lista alterações oficiais posteriores à data de referência.
      security: [{ bearerAuth: [] }]
      parameters:
        - name: cst
          in: path
          required: true
          description: CST do IBS/CBS com três dígitos.
          example: '000'
          schema: { type: string, pattern: '^\\d{3}$' }
        - name: asOf
          in: query
          required: false
          description: Data de referência fiscal no formato ISO `YYYY-MM-DD`. Quando omitida, utiliza a data atual. As classificações e alíquotas retornadas são as vigentes nessa data, e `upcomingChanges` contém somente alterações posteriores.
          example: '2026-08-15'
          schema: { type: string, format: date }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /empresa:
    get:
      tags: [Minha empresa]
      summary: Retorna dados públicos da empresa emissora da Chave
      operationId: readCompany
      x-ctebrasil-response-example: { ok: true, status: 200, data: { nome: Empresa Modelo Ltda., fantasia: Empresa Modelo, cnpj: '11222333000181', ie: '1234567890', cep: '95010000', endereco: Rua das Integrações, nro: '100', complemento: Sala 2, bairro: Centro, municipio: Caxias do Sul, uf: RS, cod_municipio: '4305108', fone: '54999999999', email: integracao@empresa.com.br, ambiente_operacional: homologacao, status: '1' } }
      description: Use esta consulta para confirmar qual empresa será usada pela Chave antes de emitir documentos ou alterar cadastros.
      security:
        - bearerAuth: []
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '503': { $ref: '#/components/responses/RateLimitUnavailable' }
    patch:
      tags: [Minha empresa]
      summary: Atualiza dados cadastrais permitidos da empresa emissora da Chave
      operationId: updateCompany
      x-ctebrasil-response-example: { ok: true, status: 200, data: { cnpj: '11222333000181' } }
      description: Identidade da empresa, cobrança, vínculos, ambiente persistido e parâmetros fiscais são imutáveis por este endpoint.
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              additionalProperties: false
              properties:
                nome: { type: string, description: Razão social exibida nos documentos e no painel. }
                fantasia: { type: string, description: Nome fantasia da empresa emissora. }
                ie: { type: string, description: Inscrição Estadual da empresa emissora. }
                cep: { type: string, pattern: '^\\d{8}$', description: CEP com oito dígitos e sem hífen. }
                endereco: { type: string, description: Logradouro da sede da empresa. }
                nro: { type: string, description: Número do endereço da sede. }
                complemento: { type: string, description: 'Complemento do endereço, como sala ou bloco.' }
                bairro: { type: string, description: Bairro da sede da empresa. }
                municipio: { type: string, description: Nome oficial do município correspondente a cod_municipio. }
                uf:
                  type: string
                  enum: *ufValues
                  x-ctebrasil-enum-labels: *ufLabels
                  description: UF da sede da empresa emissora.
                cod_municipio: { type: string, pattern: '^\\d{7}$', description: Código IBGE de sete dígitos do município da sede. Consulte GET /municipios. }
                fone: { type: string, description: 'Telefone principal da empresa, preferencialmente com DDD.' }
                email: { type: string, format: email, description: E-mail principal para contatos operacionais e fiscais. }
                security_email: { type: string, format: email, description: E-mail destinado a alertas de segurança e acesso. }
                security_fone: { type: string, description: 'Telefone destinado a alertas de segurança, preferencialmente com DDD.' }
                NroRegEstadual: { type: string, description: Número da licença estadual geral da empresa para transporte dentro do estado. }
                taf: { type: string, description: Número da autorização ANTT geral da empresa para trajetos interestaduais ou internacionais. }
                suframa_inscricao: { type: string, description: 'Inscrição SUFRAMA da empresa, quando aplicável.' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /cteos/numeracao-inicial:
    put:
      tags: [Minha empresa]
      summary: Define a numeração inicial antes da primeira emissão da empresa emissora
      operationId: setInitialCteosNumbering
      x-ctebrasil-response-example: { ok: true, status: 200, data: { numero: '1', serie: '1' } }
      description: Não altera uma empresa externa à Chave e recusa a operação após existir qualquer CTe-OS.
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [numero]
              additionalProperties: false
              properties:
                numero: { type: string, pattern: '^\\d{1,9}$', description: Primeiro número sequencial que será usado na emissão do CTe-OS. }
                serie: { type: string, pattern: '^\\d{0,3}$', default: '', description: Série fiscal com até três dígitos. Deixe vazia para usar a série padrão permitida pelo sistema. }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /empresa/certificado:
    put:
      tags: [Minha empresa]
      summary: Instala certificado A1 na empresa emissora da Chave
      operationId: updateCompanyCertificate
      x-ctebrasil-response-example: { ok: true, status: 200, data: { cnpj: '11222333000181' } }
      description: Envie um PFX ou P12 binário pelo campo file de multipart/form-data e a senha pelo campo cert_pass. O conteúdo e a senha não são retornados nem registrados na auditoria.
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, cert_pass]
              additionalProperties: false
              properties:
                file: { type: string, format: binary, x-ctebrasil-accept: '.pfx,.p12', x-ctebrasil-max-bytes: 10485760, description: 'Arquivo PKCS#12/A1 PFX ou P12, com no máximo 10 MiB.' }
                cert_pass: { type: string, format: password, writeOnly: true, description: Senha do arquivo A1. A senha é usada somente durante a instalação e não aparece na resposta. }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /empresa/logotipo:
    put:
      tags: [Minha empresa]
      summary: Substitui o logotipo da empresa emissora da chave da API
      operationId: updateCompanyLogo
      x-ctebrasil-response-example: { ok: true, status: 200, data: { cnpj: '11222333000181', mime_type: image/png, width: 1200, height: 600, max_width: 1920, max_height: 1080 } }
      description: >-
        Envie uma única imagem binária pelo campo file de multipart/form-data.
        São aceitos arquivos JPG, JPEG e PNG, com até 5 MB e até
        40 megapixels. A API valida o tipo real do arquivo; alterar somente a
        extensão não é suficiente. Imagens maiores que 1.920 × 1.080 pixels
        são redimensionadas proporcionalmente, sem deformação. O novo arquivo
        substitui o logotipo anterior da empresa vinculada à chave da API.
        A chave utilizada deve possuir o escopo empresa:logo.
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              additionalProperties: false
              properties:
                file:
                  type: string
                  format: binary
                  x-ctebrasil-accept: 'image/jpeg,image/png'
                  x-ctebrasil-max-bytes: 5242880
                  description: Arquivo de imagem JPG, JPEG ou PNG com no máximo 5 MB.
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /tomadores:
    get:
      tags: [Tomadores]
      summary: Lista tomadores da empresa emissora da Chave
      operationId: listClients
      x-ctebrasil-response-example: { ok: true, status: 200, data: { page: 1, per_page: 25, total: 1, items: [{ nome: Tomador Modelo Ltda., fantasia: Tomador Modelo, cpf: '', cnpj: '11222333000181', ie: '1234567890', indIEToma: '1', cep: '80010000', endereco: Avenida das Integrações, nro: '200', complemento: Conjunto 4, bairro: Centro, municipio: Curitiba, uf: PR, cod_municipio: '4106902', fone: '41999999999', email: fiscal@tomador.com.br, status: '1', tpCompraGov: '0', UFIni: '', xMunIni: '', cMunIni: '', UFFim: '', xMunFim: '', cMunFim: '', CFOP: '', infAdFisco: '', tpFretamento: '0', documento: '11222333000181' }] } }
      description: Retorna os tomadores com o CPF/CNPJ sem formatação usado em tomador_documento.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '503': { $ref: '#/components/responses/RateLimitUnavailable' }
    post:
      tags: [Tomadores]
      summary: Cria tomador para a empresa emissora da Chave
      operationId: createClient
      x-ctebrasil-response-example: { ok: true, status: 201, data: { status: ok, message: Tomador adicionado com sucesso, documento: '11222333000181' } }
      description: 'Cadastre CPF ou CNPJ, identificação, endereço e preferências fiscais. Os campos UFIni, xMunIni, cMunIni, UFFim, xMunFim, cMunFim, CFOP, infAdFisco e tpFretamento são opcionais e usados exclusivamente para automatizar o preenchimento da emissão realizada pelo site ou sistema da CTE Brasil. A API não usa esses valores ao receber nem ao validar uma emissão.'
      security:
        - bearerAuth: []
      requestBody: { $ref: '#/components/requestBodies/ClientPayload' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '202': { $ref: '#/components/responses/Accepted' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /tomadores/{documento}:
    patch:
      tags: [Tomadores]
      summary: Edita um tomador pertencente à empresa emissora
      operationId: updateClient
      x-ctebrasil-response-example: { ok: true, status: 200, data: { status: ok, message: Tomador editado com sucesso, documento: '11222333000181' } }
      description: Envie somente os campos que deseja alterar. O tomador precisa pertencer à empresa vinculada à chave da API. UFIni, xMunIni, cMunIni, UFFim, xMunFim, cMunFim, CFOP, infAdFisco e tpFretamento são opcionais e usados exclusivamente para automatizar o preenchimento da emissão realizada pelo site ou sistema da CTE Brasil; a API não usa esses valores ao receber nem ao validar uma emissão.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/ClientDocument' }]
      requestBody: { $ref: '#/components/requestBodies/ClientPayload' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
    delete:
      tags: [Tomadores]
      summary: Exclui um tomador pertencente à empresa emissora
      operationId: deleteClient
      x-ctebrasil-response-example: { ok: true, status: 200, data: { status: ok, documento: '11222333000181' } }
      description: Exclui o cadastro informado. Documentos já emitidos não são alterados.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/ClientDocument' }]
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
  /veiculos:
    get:
      tags: [Veículos]
      summary: Lista veículos da empresa emissora da Chave
      operationId: listVehicles
      x-ctebrasil-response-example: { ok: true, status: 200, data: { page: 1, per_page: 25, total: 1, items: [{ nome: Ônibus Rodoviário Modelo, placa: ABC1D23, marca: Mercedes-Benz, modelo: O 500, ano: '2025', ano_modelo: '2026', capacidade: '46', categoria: '1', renavam: '12345678901', uf: RS, status: '1', financiamento: '1', financ_termino: '31/12/2028', individual_license: '1', taf: '123456789012', registro: '1234567890123456789012345' }] } }
      description: Retorna os veículos com a placa sem formatação usada em veiculo_placa.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '503': { $ref: '#/components/responses/RateLimitUnavailable' }
    post:
      tags: [Veículos]
      summary: Cria veículo para a empresa emissora da Chave
      operationId: createVehicle
      x-ctebrasil-response-example: { ok: true, status: 201, data: { status: ok, message: Veículo adicionado com sucesso, placa: ABC1D23 } }
      description: Cadastre identificação, capacidade e licenças do veículo. A API usa os mesmos dados e regras do formulário do painel.
      security: [{ bearerAuth: [] }]
      requestBody: { $ref: '#/components/requestBodies/VehicleCreatePayload' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /veiculos/{placa}:
    patch:
      tags: [Veículos]
      summary: Edita um veículo pertencente à empresa emissora
      operationId: updateVehicle
      x-ctebrasil-response-example: { ok: true, status: 200, data: { status: ok, message: Veículo editado com sucesso, placa: ABC1D23 } }
      description: Envie somente os campos que deseja alterar. O veículo precisa pertencer à empresa identificada pela Chave.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/VehiclePlate' }]
      requestBody: { $ref: '#/components/requestBodies/VehicleUpdatePayload' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
    delete:
      tags: [Veículos]
      summary: Exclui um veículo pertencente à empresa emissora
      operationId: deleteVehicle
      x-ctebrasil-response-example: { ok: true, status: 200, data: { status: ok, placa: ABC1D23 } }
      description: Exclui o cadastro informado. Documentos já emitidos não são alterados.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/VehiclePlate' }]
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
  /cteos:
    get:
      tags: [CTe-OS]
      summary: Lista CTe-OS da empresa emissora em todos os ambientes
      operationId: listCteos
      x-ctebrasil-response-example: { ok: true, status: 200, data: { page: 1, per_page: 25, total: 1, items: [{ codigo: '12345678', chave: '43260711222333000181570010000001231000001234', recibo: '143260000000001', tomador: Tomador Modelo Ltda., emissao: '2026-07-20 09:30:00', gerada: '2026-07-20 09:30:05', sequencia: '1', serie: '1', cte_version: '4.00', transmissao_tentativas: '1', transmissao_ultima_tentativa: '2026-07-20 09:30:05', transmissao_ultimo_cstat: '100', transmissao_chave_retorno: '43260711222333000181570010000001231000001234', transmissao_cliente_ref: PEDIDO-123, ambiente_operacional: homologacao, transmission_state: autorizado }] } }
      description: Não inclui corpo fiscal, XML ou mensagens técnicas da transmissão; cada item informa ambiente_operacional e transmission_state.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/Page' }, { $ref: '#/components/parameters/PerPage' }]
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /{ambiente}/cteos/antecipacoes:
    get:
      tags: [CTe-OS - Complementares]
      summary: Lista pagamentos antecipados disponíveis para finalização
      operationId: listCteosAdvances
      description: Use esta consulta antes de emitir com cteos_emission_mode igual a finalizacao. A chave retornada é o valor aceito em cteos_antecipacao_chave; IDs internos não fazem parte do contrato público.
      x-ctebrasil-response-example: { ok: true, status: 200, data: { items: [{ chave: '43260711222333000181570010000001231000001234', sequencia: '1', serie: '1', tomador: Tomador Modelo Ltda., emissao: '20/07/2026 09:30', valor: '500.00' }] } }
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/Ambiente' }]
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /{ambiente}/cteos:
    post:
      tags: [CTe-OS]
      summary: Pré-visualiza ou emite um CTe-OS
      operationId: emitCteos
      x-ctebrasil-response-example: { ok: true, status: 201, data: { codigo: '12345678', chave: '43260711222333000181570010000001231000001234', recibo: '143260000000001', tomador: Tomador Modelo Ltda., emissao: '2026-07-20 09:30:00', gerada: '2026-07-20 09:30:05', sequencia: '1', serie: '1', cte_version: '4.00', transmissao_tentativas: '1', transmissao_ultima_tentativa: '2026-07-20 09:30:05', transmissao_ultimo_erro: '', transmissao_ultimo_cstat: '100', transmissao_chave_retorno: '43260711222333000181570010000001231000001234', transmissao_cliente_ref: PEDIDO-123, ambiente_operacional: homologacao, transmission_state: autorizado, downloads: { xml_url: 'https://www.ctebrasil.com.br/download/xml/43260711222333000181570010000001231000001234', dacte_url: 'https://www.ctebrasil.com.br/download/dacte/43260711222333000181570010000001231000001234' }, legacy_status: followlink, simulated: false } }
      description: Recebe os mesmos dados da tela de emissão. Use previsualizar=1 para validar e gerar somente a prévia; use 0 (ou omita) para transmitir à SEFAZ. Retorna 201 quando autorizado. No HTTP 202, guarde data.chave e data.transmission_state; não repita a emissão, pois a tentativa e o XML assinado já foram persistidos. Use POST /{ambiente}/cteos/{chave}/reenvios com essa chave. Retorna 409 quando outra pendência bloqueia e 422 para validação ou rejeição definitiva. O estado processando (0) não bloqueia emissões concorrentes. IDs internos de CTe-OS não são expostos.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/Ambiente' }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CteosPreflightRequest' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '202': { $ref: '#/components/responses/Accepted' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /{ambiente}/cteos/pendencias:
    get:
      tags: [CTe-OS]
      summary: Lista pendências de emissão do ambiente
      operationId: listPendingCteos
      description: Consulta opcional de reconciliação. Use para recuperar chaves quando a resposta original da emissão foi perdida, retomar o acompanhamento após reinício do cliente, auditar a fila de pendências ou localizar pendências esquecidas. Se a integração guardou data.chave do HTTP 202, pode chamar o reenvio diretamente sem consultar esta lista. Lista resultados fiscais incertos (estados 2, 3 e 4) e rejeições definitivas (estado 5); somente os estados 2, 3 e 4 aceitam reenvio. O estado processando (0) não aparece nesta fila e não bloqueia emissões concorrentes.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/Ambiente' }, { $ref: '#/components/parameters/Page' }, { $ref: '#/components/parameters/PerPage' }]
      x-ctebrasil-response-example: { ok: true, status: 200, data: { page: 1, per_page: 25, total: 1, items: [{ codigo: '12345678', chave: '43260711222333000181570010000001231000001234', recibo: '', tomador: Tomador Modelo Ltda., emissao: '2026-07-20 09:30:00', gerada: '2026-07-20 09:30:05', sequencia: '123', serie: '1', cte_version: '4.00', transmissao_tentativas: '1', transmissao_ultima_tentativa: '2026-07-20 09:30:05', transmissao_ultimo_erro: Não foi possível confirmar a emissão., transmissao_ultimo_cstat: '', transmissao_chave_retorno: '43260711222333000181570010000001231000001234', transmissao_cliente_ref: PEDIDO-123, ambiente_operacional: homologacao, transmission_state: pendente, blocks_new_emissions: true }] } }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /{ambiente}/cteos/{chave}/reenvios:
    post:
      tags: [CTe-OS]
      summary: Reenvia o XML assinado de uma pendência
      operationId: resendPendingCteos
      description: Use a chave retornada em data.chave pelo HTTP 202 da emissão ou recuperada pela lista de pendências. Reenvia somente pendências dos estados 2, 3 ou 4, preservando número, série, chave e o XML assinado já persistido. Envie Content-Type application/json e somente o objeto vazio {}; não reenvie tomador, veículo, valores, impostos nem o corpo original da emissão. Use o mesmo ambiente da emissão. Retorna 200 quando autorizado, 202 quando o resultado continua incerto e deve ser tentado novamente mais tarde, 404 quando a chave não identifica uma pendência reenviável no ambiente e 422 quando a SEFAZ rejeita definitivamente.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/Ambiente' }, { $ref: '#/components/parameters/CteosKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, maxProperties: 0, additionalProperties: false }
            example: {}
      x-ctebrasil-response-example: { ok: true, status: 200, data: { codigo: '12345678', chave: '43260711222333000181570010000001231000001234', recibo: '143260000000001', tomador: Tomador Modelo Ltda., emissao: '2026-07-20 09:30:00', gerada: '2026-07-20 09:30:05', sequencia: '123', serie: '1', cte_version: '4.00', transmissao_tentativas: '2', transmissao_ultima_tentativa: '2026-07-20 09:35:00', transmissao_ultimo_erro: '', transmissao_ultimo_cstat: '100', transmissao_chave_retorno: '43260711222333000181570010000001231000001234', transmissao_cliente_ref: PEDIDO-123, ambiente_operacional: homologacao, transmission_state: autorizado, downloads: { xml_url: 'https://www.ctebrasil.com.br/download/xml/43260711222333000181570010000001231000001234', dacte_url: 'https://www.ctebrasil.com.br/download/dacte/43260711222333000181570010000001231000001234' }, simulated: false } }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '202': { $ref: '#/components/responses/Accepted' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /cteos/{chave}:
    get:
      tags: [CTe-OS]
      summary: Consulta o estado seguro de um CTe-OS da empresa emissora
      operationId: readCteos
      x-ctebrasil-response-example: { ok: true, status: 200, data: { codigo: '12345678', chave: '43260711222333000181570010000001231000001234', recibo: '143260000000001', tomador: Tomador Modelo Ltda., emissao: '2026-07-20 09:30:00', gerada: '2026-07-20 09:30:05', sequencia: '1', serie: '1', cte_version: '4.00', transmissao_tentativas: '1', transmissao_ultima_tentativa: '2026-07-20 09:30:05', transmissao_ultimo_cstat: '100', transmissao_chave_retorno: '43260711222333000181570010000001231000001234', transmissao_cliente_ref: PEDIDO-123, ambiente_operacional: homologacao, transmission_state: autorizado, downloads: { xml_url: 'https://www.ctebrasil.com.br/download/xml/43260711222333000181570010000001231000001234', dacte_url: 'https://www.ctebrasil.com.br/download/dacte/43260711222333000181570010000001231000001234' } } }
      description: Consulte situação, protocolo e dados de acompanhamento usando a chave de acesso de 44 dígitos retornada na emissão ou na listagem.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/CteosKey' }]
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
  /{ambiente}/cteos/{chave}/cartas-correcao:
    post:
      tags: [CTe-OS]
      summary: Registra uma Carta de Correção do CTe-OS
      operationId: createCorrectionLetter
      x-ctebrasil-response-example: { ok: true, status: 200, data: { chave: '43260711222333000181570010000001231000001234', downloads: { xml_url: 'https://www.ctebrasil.com.br/download/cartaCorrecao/43260711222333000181570010000001231000001234/143260000000001', dacte_url: 'https://www.ctebrasil.com.br/download/dacte/43260711222333000181570010000001231000001234' }, simulated: false } }
      description: Selecione cada campo na lista versionada do contrato e informe o novo valor. O servidor localiza o documento pela chave de acesso e monta os grupos fiscais necessários. data.downloads.xml_url baixa o XML da CC-e e data.downloads.dacte_url baixa o DACTe-OS atualizado.
      x-ctebrasil-workflow:
        - title: Escolha o campo
          description: Use a lista fixa de `field` apresentada neste contrato. Ela é atualizada pela CTE Brasil quando uma Nota Técnica alterar os campos permitidos.
        - title: Informe o novo valor
          description: Adicione um item em `corrections` para cada campo corrigido. Não envie grupo, subgrupo ou nome de tag XML.
        - title: Inclua dependências
          description: Alguns campos exigem itens adicionais no mesmo array, conforme indicado no rótulo e na descrição das opções.
        - title: Envie o evento
          description: Use a chave de acesso de 44 dígitos no caminho e o objeto `fields` completo no corpo.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/Ambiente' }, { $ref: '#/components/parameters/CteosKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [corrections]
              additionalProperties: false
              properties:
                corrections:
                  type: array
                  minItems: 1
                  description: Lista dos campos corrigidos. Não repita o mesmo campo.
                  items:
                    $ref: '#/components/schemas/CorrectionLetterItem'
                  example:
                    - field: 3
                      value: 'Informação complementar corrigida: embarque no Terminal Rodoviário Central.'
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /{ambiente}/cteos/{chave}/cancelamentos:
    post:
      tags: [CTe-OS]
      summary: Cancela um CTe-OS autorizado
      operationId: cancelCteos
      x-ctebrasil-response-example: { ok: true, status: 200, data: { chave: '43260711222333000181570010000001231000001234', downloads: { xml_url: 'https://www.ctebrasil.com.br/download/cancelxml/43260711222333000181570010000001231000001234', dacte_url: 'https://www.ctebrasil.com.br/download/dacte/43260711222333000181570010000001231000001234' }, simulated: false } }
      description: Localiza o documento pela chave de acesso e registra o evento de cancelamento. A justificativa deve explicar claramente o motivo do cancelamento. data.downloads.xml_url baixa o XML do evento e data.downloads.dacte_url baixa o DACTe-OS atualizado.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/Ambiente' }, { $ref: '#/components/parameters/CteosKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              additionalProperties: false
              properties:
                reason:
                  type: string
                  minLength: 15
                  maxLength: 255
                  description: Justificativa do cancelamento enviada no evento fiscal. Informe um texto objetivo, sem usar apenas palavras genéricas como erro ou teste.
                  example: Serviço cancelado pelo tomador antes do início da viagem.
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /{ambiente}/cteos/substituicoes:
    post:
      tags: [CTe-OS]
      summary: Emite um CTe-OS de substituição
      operationId: substituteCteos
      x-ctebrasil-response-example: { ok: true, status: 201, data: { codigo: '12345679', chave: '43260711222333000181570010000001231000001235', recibo: '143260000000002', tomador: Tomador Modelo Ltda., emissao: '2026-07-20 10:00:00', gerada: '2026-07-20 10:00:05', sequencia: '2', serie: '1', cte_version: '4.00', transmissao_tentativas: '1', transmissao_ultima_tentativa: '2026-07-20 10:00:05', transmissao_ultimo_erro: '', transmissao_ultimo_cstat: '100', transmissao_chave_retorno: '43260711222333000181570010000001231000001235', transmissao_cliente_ref: SUBSTITUICAO-123, ambiente_operacional: homologacao, transmission_state: autorizado, downloads: { xml_url: 'https://www.ctebrasil.com.br/download/xml/43260711222333000181570010000001231000001235', dacte_url: 'https://www.ctebrasil.com.br/download/dacte/43260711222333000181570010000001231000001235' }, legacy_status: followlink, simulated: false } }
      description: O tomador é herdado do CTe-OS original e não deve ser informado. Envie os dados fiscais da nova emissão, veiculo_placa, chCte e xObs com justificativa entre 140 e 2.000 caracteres. O servidor define tpCTe=3.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/Ambiente' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CteosEmissionFields'
                - type: object
                  required: [veiculo_placa, chCte, xObs]
                  properties:
                    veiculo_placa: { type: string, pattern: '^[A-Z]{3}[0-9][A-Z0-9][0-9]{2}$', description: Placa sem formatação do veículo da empresa vinculada à Chave. }
                    chCte: { type: string, pattern: '^\d{44}$', description: Chave de acesso de 44 dígitos do CTe-OS original que será substituído. }
                    xObs: { type: string, minLength: 140, maxLength: 2000, description: Justificativa detalhada da substituição., example: 'Substituição emitida para corrigir os dados fiscais e operacionais do CTe-OS original, preservando o mesmo tomador e descrevendo de forma completa o motivo da alteração solicitada.' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /{ambiente}/cteos/complementares:
    post:
      tags: [CTe-OS]
      summary: Emite um CTe-OS complementar
      operationId: complementCteos
      x-ctebrasil-response-example: { ok: true, status: 201, data: { codigo: '12345680', chave: '43260711222333000181570010000001231000001236', recibo: '143260000000003', tomador: Tomador Modelo Ltda., emissao: '2026-07-20 10:30:00', gerada: '2026-07-20 10:30:05', sequencia: '3', serie: '1', cte_version: '4.00', transmissao_tentativas: '1', transmissao_ultima_tentativa: '2026-07-20 10:30:05', transmissao_ultimo_erro: '', transmissao_ultimo_cstat: '100', transmissao_chave_retorno: '43260711222333000181570010000001231000001236', transmissao_cliente_ref: COMPLEMENTAR-123, ambiente_operacional: homologacao, transmission_state: autorizado, downloads: { xml_url: 'https://www.ctebrasil.com.br/download/xml/43260711222333000181570010000001231000001236', dacte_url: 'https://www.ctebrasil.com.br/download/dacte/43260711222333000181570010000001231000001236' }, legacy_status: followlink, simulated: false } }
      description: Tomador e veículo são herdados do CTe-OS original e não devem ser informados. Envie os dados fiscais do complemento e chCte. O servidor define tpCTe=1.
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/Ambiente' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CteosEmissionFields'
                - type: object
                  required: [chCte]
                  properties:
                    chCte: { type: string, pattern: '^\d{44}$', description: Chave de acesso de 44 dígitos do CTe-OS original que receberá o complemento. }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /cteos/{chave}/cobrancas-vinculadas:
    get:
      tags: [CTe-OS - Complementares]
      summary: Lista cobranças vinculadas
      operationId: listBillingLinks
      description: Lista cobranças vinculadas, sua origem, situação e protocolos de evento do CTe-OS. Esta consulta não exige ambiente porque apenas lê registros já existentes.
      x-ctebrasil-response-example: { ok: true, status: 200, data: { chave: '43260711222333000181570010000001231000001234', items: [{ id: 12, nPag: 1, idTransacao: PIX-EXEMPLO-001, tpMeioPgto: '17', CNPJReceb: '11222333000181', CNPJBasePSP: '11222333', origem: evento, status: ativo, protocolo_vinc: '262607000000001', protocolo_cancel: '' }] } }
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/CteosKey' }]
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /{ambiente}/cteos/{chave}/cobrancas-vinculadas:
    post:
      tags: [CTe-OS - Complementares]
      summary: Vincula cobrança
      operationId: createBillingLink
      description: 'Registra na SEFAZ uma cobrança vinculada criada depois da emissão. O parâmetro path.ambiente identifica o ambiente fiscal do evento. CNPJReceb é opcional: quando omitido, a API usa o CNPJ da empresa emissora. downloads.xml_url baixa o XML do evento de vinculação recém-registrado, não o XML original do CTe-OS.'
      x-ctebrasil-response-example: { ok: true, status: 200, data: { chave: '43260711222333000181570010000001231000001234', protocolo: '262607000000001', downloads: { xml_url: 'https://www.ctebrasil.com.br/download/eventoCobranca/43260711222333000181570010000001231000001234/262607000000001', dacte_url: 'https://www.ctebrasil.com.br/download/dacte/43260711222333000181570010000001231000001234' } } }
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/Ambiente' }, { $ref: '#/components/parameters/CteosKey' }]
      requestBody: { $ref: '#/components/requestBodies/BillingLinkCreatePayload' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /{ambiente}/cteos/{chave}/cobrancas-vinculadas/cancelamentos:
    post:
      tags: [CTe-OS - Complementares]
      summary: Cancela vínculos de cobrança
      operationId: cancelBillingLinks
      description: 'Cancela na SEFAZ os vínculos de cobrança ativos criados por evento. O parâmetro path.ambiente identifica o ambiente fiscal do evento. A resposta contém um item para cada billing_link_id processado; cada items[].downloads.xml_url baixa o XML do respectivo evento de cancelamento, e não o XML original do CTe-OS.'
      x-ctebrasil-response-example: { ok: true, status: 200, data: { chave: '43260711222333000181570010000001231000001234', items: [{ billing_link_id: 12, protocolo: '262607000000002', downloads: { xml_url: 'https://www.ctebrasil.com.br/download/eventoCobranca/43260711222333000181570010000001231000001234/262607000000002', dacte_url: 'https://www.ctebrasil.com.br/download/dacte/43260711222333000181570010000001231000001234' } }] } }
      security: [{ bearerAuth: [] }]
      parameters: [{ $ref: '#/components/parameters/Ambiente' }, { $ref: '#/components/parameters/CteosKey' }]
      requestBody: { $ref: '#/components/requestBodies/BillingLinkCancelPayload' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/InvalidJson' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/RateLimited' }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Chave
      description: Chave iniciada por `ctebrasil_`, exibida somente na criação.
  parameters:
    Ambiente:
      name: ambiente
      in: path
      required: true
      description: Ambiente fiscal da operação. Homologação não possui validade fiscal; produção possui validade fiscal.
      example: homologacao
      schema:
        type: string
        enum: [homologacao, producao]
        x-ctebrasil-enum-labels:
          homologacao: Homologação — testes fiscais na SEFAZ
          producao: Produção — documentos com validade fiscal
    Page:
      name: page
      in: query
      description: Número da página, iniciando em 1.
      example: 1
      schema: { type: integer, minimum: 1, default: 1 }
    PerPage:
      name: per_page
      in: query
      description: Quantidade de registros por página. O padrão é 25; o servidor limita o resultado ao intervalo de 1 a 100 e reduz valores maiores para 100.
      example: 25
      schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
    ClientDocument:
      name: documento
      in: path
      required: true
      description: CPF ou CNPJ sem formatação, localizado somente dentro da empresa vinculada à Chave.
      example: '11222333000181'
      schema: { type: string, pattern: '^\d{11}(?:\d{3})?$' }
    VehiclePlate:
      name: placa
      in: path
      required: true
      description: Placa sem formatação, localizada somente dentro da empresa vinculada à Chave.
      example: ABC1D23
      schema: { type: string, pattern: '^[A-Z]{3}[0-9][A-Z0-9][0-9]{2}$' }
    CteosKey:
      name: chave
      in: path
      required: true
      description: Chave de acesso de 44 dígitos retornada pela emissão ou pela listagem de CTe-OS.
      example: '43260711222333000181570010000001231000001234'
      schema: { type: string, pattern: '^\\d{44}$' }
  requestBodies:
    ClientPayload:
      required: true
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ClientPayload' }
    VehicleCreatePayload:
      required: true
      content:
        application/json:
          schema: { $ref: '#/components/schemas/VehicleCreatePayload' }
    VehicleUpdatePayload:
      required: true
      content:
        application/json:
          schema: { $ref: '#/components/schemas/VehiclePayload' }
    BillingLinkCreatePayload:
      required: true
      content:
        application/json:
          schema: { $ref: '#/components/schemas/BillingLinkCreatePayload' }
    BillingLinkCancelPayload:
      required: true
      content:
        application/json:
          schema: { $ref: '#/components/schemas/BillingLinkCancelPayload' }
  schemas:
    CfopCteos:
      type: string
      enum: ['1206', '2206', '3206', '5206', '5351', '5352', '5353', '5354', '5355', '5356', '5357', '5359', '5360', '5601', '5602', '5603', '5605', '5606', '5932', '5949', '6206', '6351', '6352', '6353', '6354', '6355', '6356', '6357', '6359', '6360', '6603', '6932', '6949', '7206', '7358', '7949']
      description: Código Fiscal de Operações e Prestações aceito pelo formulário do CTe-OS. Em geral, série 5 é usada dentro da UF, série 6 entre UFs e série 7 no exterior; confirme a escolha fiscal com o contador.
      x-ctebrasil-enum-labels:
        '1206': Anulação de valor de prestação de transporte
        '2206': Anulação de valor de prestação de transporte
        '3206': Anulação de valor de prestação de transporte
        '5206': Anulação de valor de aquisição de transporte
        '5351': Transporte para execução de serviço da mesma natureza
        '5352': Transporte para estabelecimento industrial
        '5353': Transporte para estabelecimento comercial
        '5354': Transporte para prestador de comunicação
        '5355': Transporte para geradora ou distribuidora de energia
        '5356': Transporte para produtor rural
        '5357': Transporte para não contribuinte
        '5359': Transporte de mercadoria dispensada de nota fiscal
        '5360': Transporte para contribuinte substituto
        '5601': Transferência de crédito de ICMS acumulado
        '5602': Transferência de saldo credor de ICMS
        '5603': Ressarcimento de ICMS por substituição tributária
        '5605': Transferência de saldo devedor de ICMS
        '5606': Uso de saldo credor para compensar débitos
        '5932': Transporte iniciado em outra UF
        '5949': Outra prestação de serviço não especificada
        '6206': Anulação de valor de aquisição de transporte
        '6351': Transporte para execução de serviço da mesma natureza
        '6352': Transporte para estabelecimento industrial
        '6353': Transporte para estabelecimento comercial
        '6354': Transporte para prestador de comunicação
        '6355': Transporte para geradora ou distribuidora de energia
        '6356': Transporte para produtor rural
        '6357': Transporte para não contribuinte
        '6359': Transporte de mercadoria dispensada de nota fiscal
        '6360': Transporte para contribuinte substituto
        '6603': Ressarcimento de ICMS por substituição tributária
        '6932': Transporte iniciado em outra UF
        '6949': Outra prestação de serviço não especificada
        '7206': Anulação de valor de aquisição de transporte
        '7358': Prestação de transporte para o exterior
        '7949': Outra prestação de serviço não especificada
    ClientPayload:
      type: object
      description: >-
        Mesmo cadastro de tomador do painel. No POST, informe os dados exigidos
        para o perfil escolhido; no PATCH, envie somente os campos que deseja alterar. UFIni, xMunIni, cMunIni, UFFim, xMunFim, cMunFim, CFOP, infAdFisco e tpFretamento são opcionais e usados exclusivamente para automatizar o preenchimento da emissão realizada pelo site ou sistema da CTE Brasil; a API não usa esses valores ao receber nem ao validar uma emissão.
      minProperties: 1
      properties:
        cpf: { type: string, pattern: '^$|^\\d{11}$', description: 'CPF do tomador pessoa física, com 11 dígitos e sem pontuação. Não envie junto com cnpj.' }
        cnpj: { type: string, pattern: '^$|^\\d{14}$', description: 'CNPJ do tomador pessoa jurídica, com 14 dígitos e sem pontuação. Não envie junto com cpf.' }
        nome: { type: string, maxLength: 60, description: Nome completo ou razão social que será usada no CTe-OS. }
        fantasia: { type: string, maxLength: 60, description: 'Nome fantasia do tomador, quando existir.' }
        ie: { type: string, maxLength: 14, description: 'Inscrição Estadual. É exigida quando indIEToma for 1; para isento, use a regra do cadastro do painel.', x-ctebrasil-dependencies: 'Obrigatória quando indIEToma for 1.' }
        indIEToma:
          type: string
          enum: ['1', '2', '9']
          description: Situação do tomador perante o ICMS.
          x-ctebrasil-enum-labels:
            '1': Contribuinte do ICMS
            '2': Contribuinte isento de Inscrição Estadual
            '9': Não contribuinte do ICMS
        cep: { type: string, pattern: '^$|^\\d{8}$', description: 'CEP do endereço, com oito dígitos e sem hífen.' }
        endereco: { type: string, maxLength: 255, description: 'Logradouro do endereço, por exemplo Rua das Integrações.' }
        nro: { type: string, maxLength: 60, description: Número do endereço. Use S/N somente quando o endereço realmente não possuir número. }
        complemento: { type: string, maxLength: 60, description: 'Complemento do endereço, como sala, bloco ou conjunto.' }
        bairro: { type: string, maxLength: 60, description: Bairro do endereço do tomador. }
        municipio: { type: string, description: Nome do município correspondente a cod_municipio. Consulte GET /municipios para evitar divergências. }
        uf:
          type: string
          enum: *ufValues
          x-ctebrasil-enum-labels: *ufLabels
          description: UF do endereço do tomador.
        cod_municipio: { type: string, pattern: '^$|^\\d{7}$', description: Código IBGE do município do cadastro. }
        fone: { type: string, maxLength: 14, description: 'Telefone de contato do tomador, preferencialmente com DDD.' }
        email: { type: string, format: email, maxLength: 60, description: E-mail de contato do tomador. }
        status:
          type: string
          enum: ['0', '1']
          description: Define se o tomador aparece disponível para novas operações.
          x-ctebrasil-enum-labels: { '0': Inativo, '1': Ativo }
        tpCompraGov:
          type: string
          default: '0'
          enum: ['0', '1', '2', '3', '4', '5', '6']
          description: Identifica se o tomador é um ente governamental e qual esfera será usada nas regras fiscais.
          x-ctebrasil-enum-labels:
            '0': Não governamental
            '1': União ou órgão federal
            '2': Estado
            '3': Distrito Federal
            '4': Município
            '5': Consórcio público
            '6': Comitê Gestor do IBS
        UFIni:
          type: string
          pattern: '^$|^[A-Z]{2}$'
          enum: *ufValues
          x-ctebrasil-enum-labels: *ufLabels
          description: Campo opcional usado somente para automatizar o preenchimento de emissões feitas pelo site ou sistema da CTE Brasil. A API não usa este valor na emissão recebida.
        xMunIni: { type: string, description: Campo opcional usado somente para automatizar o preenchimento de emissões feitas pelo site ou sistema da CTE Brasil. Deve corresponder a cMunIni; a API não usa este valor na emissão recebida. }
        cMunIni: { type: string, pattern: '^$|^\\d{7}$', description: Campo opcional usado somente para automatizar o preenchimento de emissões feitas pelo site ou sistema da CTE Brasil. A API não usa este valor na emissão recebida. }
        UFFim:
          type: string
          pattern: '^$|^[A-Z]{2}$'
          enum: *ufValues
          x-ctebrasil-enum-labels: *ufLabels
          description: Campo opcional usado somente para automatizar o preenchimento de emissões feitas pelo site ou sistema da CTE Brasil. A API não usa este valor na emissão recebida.
        xMunFim: { type: string, description: Campo opcional usado somente para automatizar o preenchimento de emissões feitas pelo site ou sistema da CTE Brasil. A API não usa este valor na emissão recebida. }
        cMunFim: { type: string, pattern: '^$|^\\d{7}$', description: Campo opcional usado somente para automatizar o preenchimento de emissões feitas pelo site ou sistema da CTE Brasil. A API não usa este valor na emissão recebida. }
        CFOP: { $ref: '#/components/schemas/CfopCteos', description: Campo opcional usado somente para automatizar o preenchimento de emissões feitas pelo site ou sistema da CTE Brasil. A API não usa este valor na emissão recebida. }
        infAdFisco: { type: string, maxLength: 2000, description: Campo opcional usado somente para automatizar o preenchimento de emissões feitas pelo site ou sistema da CTE Brasil. A API não usa este valor na emissão recebida. }
        tpFretamento:
          type: string
          enum: ['0', '1', '2']
          description: Campo opcional usado somente para automatizar o preenchimento de emissões feitas pelo site ou sistema da CTE Brasil. A API não usa este valor na emissão recebida.
          x-ctebrasil-enum-labels: { '0': Não automatizar, '1': Eventual, '2': Contínuo }
      additionalProperties: false
    VehiclePayload:
      type: object
      description: Mesmo cadastro de veículo do painel. No PATCH, envie somente os campos a alterar.
      minProperties: 1
      properties:
        categoria:
          type: string
          enum: ['1', '2', '3', '4']
          description: Categoria visual e operacional do veículo no painel.
          x-ctebrasil-enum-labels: { '1': Ônibus, '2': Micro-ônibus, '3': Van, '4': Outros }
        placa: { type: string, pattern: '^$|^[A-Z0-9]{7}$', description: 'Placa brasileira com sete caracteres, sem hífen ou espaço.' }
        nome: { type: string, maxLength: 60, description: Apelido ou número interno usado para identificar o veículo. }
        financiamento:
          type: string
          enum: ['0', '1']
          description: Informa se o veículo possui financiamento ativo.
          x-ctebrasil-enum-labels: { '0': Não, '1': Sim }
        financ_termino: { type: string, pattern: '^$|^\\d{2}/\\d{2}/\\d{4}$', description: 'Data aproximada do fim do financiamento, em dd/mm/aaaa. Informe somente quando financiamento for 1.', x-ctebrasil-dependencies: 'Informe somente quando financiamento for 1.' }
        status:
          type: string
          enum: ['0', '1']
          description: Define se o veículo ainda está em uso e disponível nas emissões.
          x-ctebrasil-enum-labels: { '0': Não está em uso, '1': Em uso }
        capacidade: { type: string, pattern: '^\\d{1,3}$', description: Quantidade máxima de passageiros do veículo. }
        renavam: { type: string, pattern: '^\\d{9,11}$', description: 'RENAVAM com 9 a 11 dígitos, sem pontuação.' }
        uf:
          type: string
          enum: *ufValues
          x-ctebrasil-enum-labels: *ufLabels
          description: UF em que o veículo está emplacado.
        ano: { type: string, pattern: '^$|^\\d{4}$', description: Ano de fabricação com quatro dígitos. }
        ano_modelo: { type: string, pattern: '^$|^\\d{4}$', description: Ano do modelo com quatro dígitos. }
        marca: { type: string, maxLength: 45, description: Marca ou fabricante do veículo. }
        modelo: { type: string, maxLength: 45, description: Modelo comercial do veículo. }
        individual_license:
          type: string
          enum: ['0', '1']
          description: Indica se as licenças de transporte são específicas deste veículo, em vez das licenças gerais da empresa.
          x-ctebrasil-enum-labels: { '0': Não, '1': Sim }
        taf: { type: string, maxLength: 12, description: Número da autorização ANTT do veículo., x-ctebrasil-dependencies: 'Quando individual_license for 1, informe taf, registro ou ambos.' }
        registro: { type: string, maxLength: 25, description: Número da licença estadual do veículo., x-ctebrasil-dependencies: 'Quando individual_license for 1, informe taf, registro ou ambos.' }
      additionalProperties: false
    VehicleCreatePayload:
      allOf:
        - $ref: '#/components/schemas/VehiclePayload'
        - type: object
          description: Na criação, os campos marcados como obrigatórios correspondem aos exigidos no cadastro de veículos. status inicia como 1 quando não for informado.
          required: [categoria, placa, financiamento, capacidade, renavam, uf, ano, ano_modelo, marca, modelo, individual_license]
    BillingLinkCreatePayload:
      type: object
      description: Dados da cobrança criada após a emissão do CTe-OS. Cada chamada registra apenas uma cobrança vinculada.
      required: [tpMeioPgto, idTransacao, CNPJBasePSP]
      additionalProperties: false
      properties:
        nPag: { type: integer, minimum: 1, maximum: 990, description: 'Sequência da cobrança. Se omitida, a API atribui a próxima sequência disponível.' }
        tpMeioPgto:
          type: string
          enum: ['15', '17', '18', '20', '23', '24']
          description: Meio usado para realizar o pagamento vinculado.
          x-ctebrasil-enum-labels: { '15': Boleto bancário, '17': Pix com QR Code dinâmico, '18': TED, '20': Pix por chave ou QR Code estático, '23': Pix automático, '24': TEF ou transferência entre contas do mesmo banco }
        idTransacao: { type: string, minLength: 2, maxLength: 35, description: Identificador único da transação no provedor de pagamento. }
        CNPJReceb: { type: string, pattern: '^\\d{14}$', description: 'CNPJ de quem recebe o pagamento. Se omitido, a API usa o CNPJ da empresa emissora.' }
        CNPJBasePSP: { type: string, pattern: '^\\d{8}$', description: Oito primeiros dígitos do CNPJ do banco ou instituição de pagamento. }
    BillingLinkCancelPayload:
      type: object
      description: Lista dos identificadores de vínculos ativos, originados por evento, que serão cancelados.
      required: [billing_link_ids]
      additionalProperties: false
      properties:
        billing_link_ids:
          type: array
          minItems: 1
          description: IDs retornados por GET /cteos/{chave}/cobrancas-vinculadas. Cada ID deve ser de um vínculo ativo criado por evento.
          items: { type: integer, minimum: 1, description: Identificador do vínculo de cobrança. }
    CorrectionLetterItem:
      type: object
      required: [field, value]
      additionalProperties: false
      properties:
        field:
          type: integer
          enum: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37]
          description: Código estável do campo da CC-e. Escolha uma das opções; a CTE Brasil atualizará este contrato se uma Nota Técnica alterar a lista.
          x-ctebrasil-enum-labels:
            '1': Estado de destino (exige 2 e 35)
            '2': Município de destino (exige 35)
            '3': Observações gerais
            '4': Informação adicional 1
            '5': Informação adicional 2
            '6': Informação adicional 3
            '7': Razão social do emitente
            '8': Nome fantasia do emitente
            '9': Endereço do emitente (exige 10)
            '10': Número do endereço do emitente
            '11': Bairro do emitente
            '12': Telefone do emitente
            '13': Complemento do endereço do emitente
            '14': Nome ou razão social do tomador
            '15': Nome fantasia do tomador
            '16': Endereço do tomador (exige 17)
            '17': Número do endereço do tomador
            '18': Complemento do endereço do tomador
            '19': Bairro do tomador
            '20': CEP do tomador
            '21': Município do tomador (exige 36)
            '22': CEP do emitente
            '23': Informação adicional ao Fisco
            '24': Descrição do serviço
            '25': Quantidade de passageiros
            '26': Número da licença
            '27': Placa do veículo (exige 28 e 29)
            '28': RENAVAM do veículo
            '29': UF da placa do veículo
            '30': Tipo de fretamento (1 eventual ou 2 contínuo)
            '31': Data de partida (exige 32)
            '32': Hora de partida
            '33': Data de retorno (exige 34)
            '34': Hora de retorno
            '35': Código IBGE do município de destino
            '36': Código IBGE do município do tomador
            '37': Telefone do tomador
        value:
          type: string
          minLength: 1
          description: Novo conteúdo do campo. Datas usam dd/mm/aaaa, horas usam HH:MM, placas usam AAA0A00 e o tipo de fretamento usa 1 ou 2.
    CteosPreflightRequest:
      allOf:
        - $ref: '#/components/schemas/CteosEmissionFields'
        - type: object
          required: [tomador_documento, veiculo_placa]
          properties:
            tomador_documento:
              type: string
              pattern: '^\d{11}(?:\d{3})?$'
              description: CPF ou CNPJ sem formatação. A API localiza o tomador dentro da empresa vinculada à Chave.
              x-ctebrasil-options-endpoint: /tomadores
            veiculo_placa:
              type: string
              pattern: '^[A-Z]{3}[0-9][A-Z0-9][0-9]{2}$'
              description: Placa sem formatação. A API localiza o veículo dentro da empresa vinculada à Chave.
              x-ctebrasil-options-endpoint: /veiculos
    CteosEmissionFields:
      type: object
      description: >-
        Corpo bruto da mesma emissão CTe-OS do painel. A API recebe somente os
        dados que o formulário recebe; empresa emissora, tomador e veículo são
        resolvidos pelos respectivos cadastros. Valores monetários podem ser 0,00.
      required: [cCT, CFOP, cMunIni, cMunFim, aceite, xDescServ, tpFretamento, qCarga, vTPrest, vRec, ICMS, InfTribFed]
      properties:
        cMunIni:
          type: string
          pattern: '^\\d{7}$'
          description: Código IBGE de origem. A API preenche UFIni e xMunIni canônicos.
        cMunFim:
          type: string
          pattern: '^\\d{7}$'
          description: Código IBGE de destino. A API preenche UFFim e xMunFim canônicos.
        cCT:
          type: string
          pattern: '^\\d{8}$'
          description: Código de controle preservado como texto, inclusive zeros à esquerda.
        aceite:
          type: string
          enum: ['1']
          description: Confirma que os dados informados são verdadeiros e de responsabilidade do emissor, como na caixa de aceite da tela.
          x-ctebrasil-enum-labels: { '1': Confirmo os dados da emissão }
        previsualizar:
          type: integer
          enum: [0, 1]
          default: 0
          description: Use 1 para validar e gerar somente a prévia; use 0 para transmitir o CTe-OS à SEFAZ.
          x-ctebrasil-enum-labels: { '0': Transmitir à SEFAZ, '1': Gerar apenas prévia }
        dhEmiUser:
          type: string
          pattern: '^\\d{2}/\\d{2}/\\d{4}$'
          description: Data da emissão em dd/mm/aaaa. Se omitida, o servidor usa a data atual.
        CFOP:
          $ref: '#/components/schemas/CfopCteos'
        xDescServ:
          type: string
          maxLength: 30
          description: Descrição objetiva do serviço de transporte, com no máximo 30 caracteres.
        tpFretamento:
          type: string
          enum: ['1', '2']
          description: Eventual é uma viagem específica; contínuo é um serviço recorrente contratado.
          x-ctebrasil-enum-labels: { '1': Eventual, '2': Contínuo }
        dViagem:
          type: string
          pattern: '^$|^\\d{2}/\\d{2}/\\d{4}$'
          description: Data de partida da viagem, em dd/mm/aaaa. Obrigatória no fretamento eventual; no contínuo, não é obrigatória.
          x-ctebrasil-dependencies: 'Obrigatória quando tpFretamento for 1; exige hViagem quando informada.'
        hViagem:
          type: string
          pattern: '^$|^(?:[01][0-9]|2[0-3]):[0-5][0-9]$'
          description: Hora de partida correspondente a dViagem, em HH:MM. Obrigatória quando dViagem for informada.
          x-ctebrasil-dependencies: 'Obrigatória quando dViagem for informada.'
        dRetorno:
          type: string
          pattern: '^$|^\\d{2}/\\d{2}/\\d{4}$'
          description: Data de retorno da viagem, em dd/mm/aaaa. Opcional; se informada, exige hRetorno.
          x-ctebrasil-dependencies: 'Exige hRetorno quando informada.'
        hRetorno:
          type: string
          pattern: '^$|^(?:[01][0-9]|2[0-3]):[0-5][0-9]$'
          description: Hora de retorno correspondente a dRetorno, em HH:MM. Não informe sem dRetorno.
          x-ctebrasil-dependencies: 'Informe somente quando dRetorno for informada.'
        qCarga:
          type: string
          pattern: '^\\d+(?:\\.\\d{1,4})?$'
          description: Quantidade de passageiros, com até quatro casas decimais.
        vTPrest:
          type: string
          description: Valor total da prestação. Aceita 0,00 quando essa for a informação fiscal correta.
        vRec:
          type: string
          description: Valor a receber. Aceita 0,00 quando essa for a informação fiscal correta.
        vTotTrib: { type: string, description: Valor aproximado total de tributos. }
        infPercurso:
          type: array
          maxItems: 25
          items:
            type: string
            enum: *ufValues
            x-ctebrasil-enum-labels: *ufLabels
            description: UF intermediária atravessada entre a origem e o destino.
          description: UFs intermediárias na ordem do trajeto; cada índice do array define a sequência no XML.
        infAdFisco: { type: string, maxLength: 2000, description: Informação adicional destinada ao Fisco. }
        xObs: { type: string, maxLength: 2000, description: Observações gerais operacionais ou comerciais do CTe-OS. }
        obs3: { $ref: '#/components/schemas/AdditionalObservation' }
        obs4: { $ref: '#/components/schemas/AdditionalObservation' }
        obs5: { $ref: '#/components/schemas/AdditionalObservation' }
        ICMS: { $ref: '#/components/schemas/IcmsPayload' }
        ICMSUFFim: { $ref: '#/components/schemas/IcmsUfFimPayload' }
        InfTribFed:
          type: object
          description: Grupo dos tributos federais retidos ou calculados na prestação.
          required: [vINSS]
          properties:
            vINSS: { type: string, description: 'Informe 0,00 quando não houver retenção.' }
            vPIS: { type: string, description: Valor de PIS da prestação. }
            vCOFINS: { type: string, description: Valor de COFINS da prestação. }
            vIR: { type: string, description: Valor de IR retido. }
            vCSLL: { type: string, description: Valor de CSLL retido. }
        IBSCBS: { $ref: '#/components/schemas/IbsCbsPayload', description: Grupo da tributação IBS/CBS aplicável à prestação. }
        tpCompraGov:
          type: string
          default: '0'
          enum: ['0', '1', '2', '3', '4', '5', '6']
          description: Ente governamental do tomador. Use 0 quando a prestação não for uma compra governamental.
          x-ctebrasil-enum-labels:
            '0': Não governamental
            '1': União ou órgão federal
            '2': Estado
            '3': Distrito Federal
            '4': Município
            '5': Consórcio público
            '6': Comitê Gestor do IBS
        tpOperGov:
          type: string
          enum: ['1', '2', '3', '4']
          description: Momento do fornecimento em relação ao pagamento. É obrigatório quando tpCompraGov for diferente de 0 e define se refDFeAnt é proibido, único ou múltiplo.
          x-ctebrasil-dependencies: 'Obrigatório quando tpCompraGov for diferente de 0; define a regra de refDFeAnt.'
          x-ctebrasil-enum-labels:
            '1': Fornecimento com pagamento posterior
            '2': Recebimento do pagamento com fornecimento já realizado
            '3': Fornecimento com pagamento já realizado
            '4': Recebimento do pagamento com fornecimento posterior
        pRedutorCompraGov: { type: string, description: 'Percentual de redução aplicado à compra governamental, quando aplicável.', x-ctebrasil-dependencies: 'Informe somente quando a regra da compra governamental exigir redução.' }
        refDFeAnt: { type: array, items: { type: string, pattern: '^\\d{44}$' }, description: Chaves de DF-e anteriores. É vedado em tpOperGov 1 e 4; exige uma chave em tpOperGov 2 e ao menos uma em tpOperGov 3., x-ctebrasil-dependencies: 'tpOperGov: proibido em 1 e 4; uma chave em 2; ao menos uma em 3.' }
        origem_tpCompraGov:
          type: string
          enum: ['0', '1']
          description: Indica se tpCompraGov veio do cadastro do tomador ou foi informado nesta emissão. Quando for 1, o sistema também atualiza o cadastro do tomador após emitir.
          x-ctebrasil-enum-labels: { '0': Veio do cadastro do tomador, '1': Informado nesta emissão }
        gTribCompraGov:
          type: object
          description: Valores de IBS e CBS calculados especificamente para a compra governamental, quando este grupo for exigido.
          x-ctebrasil-dependencies: 'Informe somente quando a classificação fiscal da compra governamental exigir este grupo.'
          properties:
              pAliqIBSUF: { type: string, description: Alíquota de IBS da UF para compra governamental. }
              vTribIBSUF: { type: string, description: Valor de IBS da UF para compra governamental. }
              pAliqIBSMun: { type: string, description: Alíquota de IBS municipal para compra governamental. }
              vTribIBSMun: { type: string, description: Valor de IBS municipal para compra governamental. }
              pAliqCBS: { type: string, description: Alíquota de CBS para compra governamental. }
              vTribCBS: { type: string, description: Valor de CBS para compra governamental. }
          additionalProperties: false
        pgtoVinc:
          type: array
          maxItems: 99
          description: Cobranças vinculadas. Use apenas quando a emissão possuir pagamentos vinculados.
          x-ctebrasil-dependencies: 'Informe somente quando a emissão possuir pagamentos vinculados.'
          items:
            type: object
            required: [idTransacao, tpMeioPgto, CNPJReceb, CNPJBasePSP]
            properties:
              nPag: { type: integer, minimum: 1, maximum: 990, description: 'Sequência da cobrança; se omitida, o servidor atribui a sequência.' }
              idTransacao: { type: string, minLength: 2, maxLength: 35, description: Identificador da transação de pagamento no provedor. }
              tpMeioPgto:
                type: string
                enum: ['15', '17', '18', '20', '23', '24']
                description: Meio usado para realizar o pagamento vinculado.
                x-ctebrasil-enum-labels:
                  '15': Boleto bancário
                  '17': Pix com QR Code dinâmico
                  '18': TED
                  '20': Pix por chave ou QR Code estático
                  '23': Pix automático
                  '24': TEF ou transferência entre contas do mesmo banco
              CNPJReceb: { type: string, pattern: '^\\d{14}$', description: CNPJ completo do recebedor do pagamento. }
              CNPJBasePSP: { type: string, pattern: '^\\d{8}$', description: Oito primeiros dígitos do CNPJ do PSP. }
            additionalProperties: false
        cteos_emission_mode:
          type: string
          enum: [normal, antecipado, finalizacao]
          description: Define se a emissão é comum, registra pagamento antecipado ou finaliza um serviço que já possui entrada.
          x-ctebrasil-enum-labels: { normal: Emissão normal, antecipado: Pagamento antecipado, finalizacao: Finalizar serviço com entrada }
        cteos_antecipacao_chave:
          type: string
          pattern: '^$|^\d{44}$'
          description: Chave de 44 dígitos retornada pela listagem de pagamentos antecipados. Informe somente quando cteos_emission_mode for finalizacao.
          x-ctebrasil-dependencies: 'Informe somente quando cteos_emission_mode for finalizacao.'
          x-ctebrasil-options-endpoint: '/{ambiente}/cteos/antecipacoes'
        transmissao_cliente_ref: { type: string, maxLength: 100, description: Referência própria do integrador para conciliar a transmissão. }
      additionalProperties: false
    AdditionalObservation:
      type: object
      description: Grupo de informação adicional. Não envie um valor em obs3, obs4 ou obs5; preencha os dois subcampos xCampo e xTexto juntos.
      x-ctebrasil-dependencies: 'xCampo e xTexto devem ser informados juntos; não envie o grupo se ambos estiverem vazios.'
      properties:
        xCampo: { type: string, maxLength: 20, description: 'Rótulo que identifica a informação adicional, por exemplo ROTA, EMBARQUE ou REFERÊNCIA.' }
        xTexto: { type: string, maxLength: 160, description: Conteúdo correspondente ao rótulo informado em xCampo. }
      additionalProperties: false
    IcmsPayload:
      type: object
      description: Envie tipo e apenas o objeto de mesmo nome correspondente ao tipo selecionado.
      required: [tipo]
      oneOf:
        - title: ICMS00
          required: [ICMS00]
          properties: { tipo: { enum: [ICMS00] } }
        - title: ICMS20
          required: [ICMS20]
          properties: { tipo: { enum: [ICMS20] } }
        - title: ICMS45
          required: [ICMS45]
          properties: { tipo: { enum: [ICMS45] } }
        - title: ICMS90
          required: [ICMS90]
          properties: { tipo: { enum: [ICMS90] } }
        - title: ICMSOutraUF
          required: [ICMSOutraUF]
          properties: { tipo: { enum: [ICMSOutraUF] } }
        - title: ICMSSN
          properties: { tipo: { enum: [ICMSSN] } }
      properties:
        tipo:
          type: string
          enum: [ICMS00, ICMS20, ICMS45, ICMS90, ICMSOutraUF, ICMSSN]
          description: Regime de ICMS da prestação. Ao escolher um tipo, envie somente o grupo de mesmo nome.
          x-ctebrasil-enum-labels:
            ICMS00: Tributação normal
            ICMS20: Tributação com redução da base de cálculo
            ICMS45: Isento, não tributado ou diferido
            ICMS90: Outros tratamentos de ICMS
            ICMSOutraUF: ICMS devido a outra UF
            ICMSSN: Simples Nacional
        ICMS00:
          type: object
          description: Campos usados quando tipo for ICMS00.
          x-ctebrasil-dependencies: 'Informe somente quando ICMS.tipo for ICMS00.'
          required: [vBC, pICMS, vICMS]
          properties:
            vBC: { type: string, description: 'Valor da base de cálculo do ICMS, em reais.' }
            pICMS: { type: string, description: Alíquota do ICMS em percentual. }
            vICMS: { type: string, description: 'Valor calculado do ICMS, em reais.' }
        ICMS20:
          type: object
          description: Campos usados quando tipo for ICMS20.
          x-ctebrasil-dependencies: 'Informe somente quando ICMS.tipo for ICMS20.'
          required: [pRedBC, vBC, pICMS, vICMS]
          properties:
            pRedBC: { type: string, description: 'Percentual de redução da base de cálculo, maior que zero.' }
            vBC: { type: string, description: 'Base de cálculo já reduzida, em reais.' }
            pICMS: { type: string, description: Alíquota do ICMS em percentual. }
            vICMS: { type: string, description: 'Valor calculado do ICMS, em reais.' }
            vICMSDeson: { type: string, description: 'Valor do ICMS desonerado. Quando informado, cBenef também é obrigatório.', x-ctebrasil-dependencies: 'Exige cBenef quando informado.' }
            cBenef: { type: string, description: 'Código do benefício fiscal correspondente à desoneração. Quando informado, vICMSDeson também é obrigatório.', x-ctebrasil-dependencies: 'Exige vICMSDeson quando informado.' }
        ICMS45:
          type: object
          description: Campos usados quando tipo for ICMS45.
          x-ctebrasil-dependencies: 'Informe somente quando ICMS.tipo for ICMS45.'
          required: [CST]
          properties:
            CST:
              type: string
              enum: ['40', '41', '51']
              description: Campo ICMS.ICMS45.CST obrigatório. Use 40 para prestação isenta, 41 para não tributada ou 51 para diferida. Não confundir com IBSCBS.CST nem IBSCBS.cClassTrib.
              x-ctebrasil-enum-labels: { '40': Isenta, '41': Não tributada, '51': Diferida }
            vICMSDeson: { type: string, description: 'Valor do ICMS desonerado. Quando informado, cBenef também é obrigatório.', x-ctebrasil-dependencies: 'Exige cBenef quando informado.' }
            cBenef: { type: string, description: 'Código do benefício fiscal correspondente à desoneração. Quando informado, vICMSDeson também é obrigatório.', x-ctebrasil-dependencies: 'Exige vICMSDeson quando informado.' }
        ICMS90:
          type: object
          description: Campos usados quando tipo for ICMS90.
          x-ctebrasil-dependencies: 'Informe somente quando ICMS.tipo for ICMS90.'
          required: [vBC, pICMS, vICMS]
          properties:
            pRedBC: { type: string, description: 'Percentual de redução da base, quando houver.' }
            vBC: { type: string, description: 'Valor da base de cálculo do ICMS, em reais.' }
            pICMS: { type: string, description: Alíquota do ICMS em percentual. }
            vICMS: { type: string, description: 'Valor calculado do ICMS, em reais.' }
            vCred: { type: string, description: 'Valor do crédito presumido de ICMS, quando aplicável.' }
            vICMSDeson: { type: string, description: 'Valor do ICMS desonerado. Quando informado, cBenef também é obrigatório.', x-ctebrasil-dependencies: 'Exige cBenef quando informado.' }
            cBenef: { type: string, description: 'Código do benefício fiscal correspondente à desoneração. Quando informado, vICMSDeson também é obrigatório.', x-ctebrasil-dependencies: 'Exige vICMSDeson quando informado.' }
        ICMSOutraUF:
          type: object
          description: Campos usados quando tipo for ICMSOutraUF.
          x-ctebrasil-dependencies: 'Informe somente quando ICMS.tipo for ICMSOutraUF.'
          required: [vBCOutraUF, pICMSOutraUF, vICMSOutraUF]
          properties:
            pRedBCOutraUF: { type: string, description: Percentual de redução da base de cálculo na outra UF. }
            vBCOutraUF: { type: string, description: Base de cálculo do ICMS devido à outra UF. }
            pICMSOutraUF: { type: string, description: Alíquota de ICMS da outra UF. }
            vICMSOutraUF: { type: string, description: Valor do ICMS devido à outra UF. }
            vICMSDeson: { type: string, description: 'Valor do ICMS desonerado. Quando informado, cBenef também é obrigatório.', x-ctebrasil-dependencies: 'Exige cBenef quando informado.' }
            cBenef: { type: string, description: 'Código do benefício fiscal correspondente à desoneração. Quando informado, vICMSDeson também é obrigatório.', x-ctebrasil-dependencies: 'Exige vICMSDeson quando informado.' }
        ICMSSN: { type: object, maxProperties: 0, additionalProperties: false, description: Sem campos manuais para o regime Simples Nacional., x-ctebrasil-dependencies: 'Informe somente quando ICMS.tipo for ICMSSN.' }
      additionalProperties: false
    IcmsUfFimPayload:
      type: object
      description: Partilha do ICMS entre as UFs de início e término, quando exigida para a operação interestadual.
      x-ctebrasil-dependencies: 'Informe somente quando a regra fiscal da operação interestadual exigir partilha de ICMS.'
      required: [vBCUFFim, pFCPUFFim, pICMSUFFim, pICMSInter, vFCPUFFim, vICMSUFFim, vICMSUFIni]
      properties:
        vBCUFFim: { type: string, description: Base de cálculo do ICMS na UF de término. }
        pFCPUFFim: { type: string, description: Alíquota do FCP na UF de término. }
        pICMSUFFim: { type: string, description: Alíquota interna do ICMS na UF de término. }
        pICMSInter: { type: string, description: Alíquota interestadual. }
        vFCPUFFim: { type: string, description: Valor do FCP na UF de término. }
        vICMSUFFim: { type: string, description: ICMS de partilha na UF de término. }
        vICMSUFIni: { type: string, description: ICMS de partilha na UF de início. }
      additionalProperties: false
    IbsCbsPayload:
      type: object
      description: Tributação da Reforma Tributária. Consulte os CSTs e, em seguida, as classificações vinculadas ao CST escolhido.
      required: [CST, cClassTrib]
      properties:
        CST:
          type: string
          pattern: '^\\d{3}$'
          description: Código de Situação Tributária IBS/CBS com três dígitos. Consulte os CSTs vigentes em GET /referencias/ibscbs/csts.
          x-ctebrasil-options-endpoint: /referencias/ibscbs/csts
        cClassTrib:
          type: string
          pattern: '^\\d{6}$'
          description: Código de Classificação Tributária com seis dígitos, vinculado ao CST escolhido. Consulte GET /referencias/ibscbs/csts/{cst}/classificacoes.
          x-ctebrasil-dependencies: 'CST escolhido; consulte as classificações vigentes para esse CST.'
          x-ctebrasil-options-endpoint: /referencias/ibscbs/csts/{IBSCBS.CST}/classificacoes
        indDoacao:
          type: string
          enum: ['1']
          description: Indicador de doação. Só é usado quando a classificação tributária escolhida exigir este grupo.
          x-ctebrasil-dependencies: 'Informe somente quando a classificação tributária escolhida exigir doação.'
          x-ctebrasil-enum-labels: { '1': Operação de doação }
        gIBSCBS:
          type: object
          description: Valores consolidados de IBS e CBS da prestação.
          properties:
            vBC: { type: string, description: Base de cálculo. }
            vIBS: { type: string, description: Valor total do IBS. }
            gIBSUF: { $ref: '#/components/schemas/IbsUfPayload', description: Parcela estadual do IBS. }
            gIBSMun: { $ref: '#/components/schemas/IbsMunicipalPayload', description: Parcela municipal do IBS. }
            gCBS: { $ref: '#/components/schemas/CbsPayload', description: Valores da CBS federal. }
            gTribRegular:
              type: object
              description: Tributação regular usada quando a classificação principal exigir comparação com o regime normal.
              x-ctebrasil-dependencies: 'Informe somente quando a classificação tributária exigir comparação com o regime normal.'
              properties:
                CSTReg: { type: string, pattern: '^\\d{3}$', description: CST que seria aplicado na tributação regular. Deve formar um par ativo e vigente com cClassTribReg na data de emissão. }
                cClassTribReg: { type: string, pattern: '^\\d{6}$', description: Classificação tributária correspondente ao CST regular. Deve pertencer ao CSTReg e estar vigente na data de emissão. }
                pAliqEfetRegIBSUF: { type: string, description: 'Alíquota efetiva regular do IBS estadual, em percentual.' }
                vTribRegIBSUF: { type: string, description: Valor do IBS estadual calculado pela tributação regular. }
                pAliqEfetRegIBSMun: { type: string, description: 'Alíquota efetiva regular do IBS municipal, em percentual.' }
                vTribRegIBSMun: { type: string, description: Valor do IBS municipal calculado pela tributação regular. }
                pAliqEfetRegCBS: { type: string, description: 'Alíquota efetiva regular da CBS, em percentual.' }
                vTribRegCBS: { type: string, description: Valor da CBS calculado pela tributação regular. }
              additionalProperties: false
          additionalProperties: false
        gEstornoCred:
          type: object
          description: Estorno de créditos de IBS e CBS, somente quando previsto pela classificação tributária.
          x-ctebrasil-dependencies: 'Informe somente quando previsto pela classificação tributária escolhida.'
          properties:
            vIBSEstCred: { type: string, description: Valor do crédito de IBS estornado. }
            vCBSEstCred: { type: string, description: Valor do crédito de CBS estornado. }
          additionalProperties: false
      additionalProperties: false
    IbsUfPayload:
      type: object
      description: Parcela estadual do IBS.
      properties:
        pIBSUF: { type: string, description: 'Alíquota do IBS estadual, em percentual.' }
        vIBSUF: { type: string, description: 'Valor do IBS estadual, em reais.' }
        gRed: { type: object, description: 'Redução da alíquota estadual, quando prevista pela classificação.', x-ctebrasil-dependencies: 'Informe somente quando previsto pela classificação tributária escolhida.', properties: { pRedAliq: { type: string, description: Percentual de redução da alíquota. }, pAliqEfet: { type: string, description: Alíquota efetiva após a redução. } }, additionalProperties: false }
        gDif: { type: object, description: 'Diferimento do IBS estadual, quando previsto pela classificação.', x-ctebrasil-dependencies: 'Informe somente quando previsto pela classificação tributária escolhida.', properties: { pDif: { type: string, description: Percentual diferido. }, vDif: { type: string, description: Valor diferido. } }, additionalProperties: false }
        gDevTrib: { type: object, description: 'Devolução do IBS estadual, quando prevista pela classificação e somente para emissões até 30/08/2026.', x-ctebrasil-dependencies: 'Proibido no CT-eOS a partir de 31/08/2026. Consulte upcomingChanges usando a data de emissão em asOf.', properties: { vDevTrib: { type: string, description: Valor devolvido. } }, additionalProperties: false }
      additionalProperties: false
    IbsMunicipalPayload:
      type: object
      description: Parcela municipal do IBS.
      properties:
        pIBSMun: { type: string, description: 'Alíquota do IBS municipal, em percentual.' }
        vIBSMun: { type: string, description: 'Valor do IBS municipal, em reais.' }
        gRed: { type: object, description: 'Redução da alíquota municipal, quando prevista pela classificação.', x-ctebrasil-dependencies: 'Informe somente quando previsto pela classificação tributária escolhida.', properties: { pRedAliq: { type: string, description: Percentual de redução da alíquota. }, pAliqEfet: { type: string, description: Alíquota efetiva após a redução. } }, additionalProperties: false }
        gDif: { type: object, description: 'Diferimento do IBS municipal, quando previsto pela classificação.', x-ctebrasil-dependencies: 'Informe somente quando previsto pela classificação tributária escolhida.', properties: { pDif: { type: string, description: Percentual diferido. }, vDif: { type: string, description: Valor diferido. } }, additionalProperties: false }
        gDevTrib: { type: object, description: 'Devolução do IBS municipal, quando prevista pela classificação e somente para emissões até 30/08/2026.', x-ctebrasil-dependencies: 'Proibido no CT-eOS a partir de 31/08/2026. Consulte upcomingChanges usando a data de emissão em asOf.', properties: { vDevTrib: { type: string, description: Valor devolvido. } }, additionalProperties: false }
      additionalProperties: false
    CbsPayload:
      type: object
      description: Valores da Contribuição sobre Bens e Serviços.
      properties:
        pCBS: { type: string, description: 'Alíquota da CBS, em percentual.' }
        vCBS: { type: string, description: 'Valor da CBS, em reais.' }
        gRed: { type: object, description: 'Redução da alíquota de CBS, quando prevista pela classificação.', x-ctebrasil-dependencies: 'Informe somente quando previsto pela classificação tributária escolhida.', properties: { pRedAliq: { type: string, description: Percentual de redução da alíquota. }, pAliqEfet: { type: string, description: Alíquota efetiva após a redução. } }, additionalProperties: false }
        gDif: { type: object, description: 'Diferimento da CBS, quando previsto pela classificação.', x-ctebrasil-dependencies: 'Informe somente quando previsto pela classificação tributária escolhida.', properties: { pDif: { type: string, description: Percentual diferido. }, vDif: { type: string, description: Valor diferido. } }, additionalProperties: false }
        gDevTrib: { type: object, description: 'Devolução da CBS, quando prevista pela classificação e somente para emissões até 30/08/2026.', x-ctebrasil-dependencies: 'Proibido no CT-eOS a partir de 31/08/2026. Consulte upcomingChanges usando a data de emissão em asOf.', properties: { vDevTrib: { type: string, description: Valor devolvido. } }, additionalProperties: false }
        gALCZFMCBS:
          type: object
          description: Tributação regular da CBS usada em operações da Área de Livre Comércio ou Zona Franca de Manaus.
          x-ctebrasil-dependencies: 'Informe somente quando a classificação tributária prever operação em Área de Livre Comércio ou Zona Franca de Manaus.'
          properties:
            pAliqEfetRegCBS: { type: string, description: 'Alíquota efetiva regular da CBS, em percentual.' }
            vTribRegCBS: { type: string, description: Valor da CBS pela tributação regular. }
          additionalProperties: false
      additionalProperties: false
    SuccessEnvelope:
      type: object
      description: Estrutura usada quando a operação termina sem erro.
      required: [ok, status, data]
      properties:
        ok: { type: boolean, enum: [true], description: Sempre true nas respostas concluídas. }
        status: { type: integer, example: 200, description: Repete o código HTTP para facilitar o tratamento do JSON. }
        data: { type: object, additionalProperties: true, description: Resultado da operação. O formato exato aparece no exemplo de resposta de cada endpoint. }
    FiscalDownloads:
      type: object
      description: Links de download retornados pelas operações que criam um CTe-OS ou um evento fiscal. xml_url sempre representa o XML criado pela operação; dacte_url representa o DACTe-OS atualizado.
      required: [xml_url, dacte_url]
      properties:
        xml_url: { type: string, format: uri, description: URL completa para baixar o XML do CTe-OS ou do evento recém-criado. }
        dacte_url: { type: string, format: uri, description: URL completa para baixar o DACTe-OS atualizado do CTe-OS relacionado. }
    ErrorEnvelope:
      type: object
      description: Estrutura usada quando a API recusa ou não consegue concluir a operação.
      required: [ok, status, error]
      properties:
        ok: { type: boolean, enum: [false], description: Sempre false nas respostas de erro. }
        status: { type: integer, description: Repete o código HTTP retornado pela API. }
        error:
          type: object
          description: Dados que ajudam a integração a identificar e corrigir a falha.
          required: [code, message]
          properties:
            code: { type: string, description: Código estável para decisões no sistema cliente; não dependa do texto de message. }
            message: { type: string, description: Explicação em português destinada à pessoa que está corrigindo a requisição. }
            details: { type: object, additionalProperties: true, description: 'Recurso fiscal persistido associado ao erro, quando existir, identificado por chave e transmission_state.' }
  responses:
    Success:
      description: Leitura ou operação concluída.
      content: { application/json: { schema: { $ref: '#/components/schemas/SuccessEnvelope' } } }
    InvalidJson:
      description: Corpo ausente, lista JSON ou JSON inválido.
      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
    Unauthorized:
      description: Bearer ausente ou formato inválido.
      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
    NotFound:
      description: Recurso inexistente ou fora da empresa/ambiente da Chave.
      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
    Forbidden:
      description: Chave sem serviço ativo ou escopo exigido.
      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
    ValidationFailed:
      description: Validação fiscal/legada recusou a carga.
      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
    Accepted:
      description: Tentativa persistida, mas ainda processando ou sem confirmação fiscal conclusiva.
      content: { application/json: { schema: { $ref: '#/components/schemas/SuccessEnvelope' } } }
    Conflict:
      description: Uma pendência fiscal anterior impede temporariamente a nova emissão.
      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
    RateLimited:
      description: |
        Um dos limites cumulativos da Chave foi excedido: 2 chamadas
        simultâneas, 15 chamadas em 15 segundos, 60 chamadas em 60 segundos ou
        1.000 chamadas em 1 hora. Aguarde a conclusão das chamadas concorrentes
        ou a renovação da janela correspondente antes de tentar novamente.
        O código é `integration_concurrency_exceeded` para concorrência ou
        `integration_rate_limit_exceeded` para uma janela de tempo.
      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
    RateLimitUnavailable:
      description: |
        Serviço temporariamente indisponível. Aguarde e tente novamente.
      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
    ServiceUnavailable:
      description: Armazenamento local temporariamente indisponível.
      content: { application/json: { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } }
