CTE Brasil API CTe-OS · V1 · Contrato 1.0.0

Integre o CTe-OS com segurança.

Consulte os dados aceitos, entenda cada regra e teste a mesma operação que seu sistema enviará à API.

Ver endpointsBaixar OpenAPIBaixar coleção Postman
Início rápido

Uma chave da API, uma empresa emissora.

Crie uma chave em Serviços → Chaves da API. A chave define a empresa e os escopos; o segredo só aparece no momento da criação.

Autenticação

Envie a chave em cada chamada. Não a grave no frontend, repositórios ou capturas de tela.

Authorization: Bearer ctebrasil_seu_segredo

Ambientes

Cadastros e consultas usam /api/v1. Operações fiscais pedem {ambiente} na URL.

homologacaoTestes fiscais enviados à SEFAZ em homologação.
producaoEmissões com validade fiscal na SEFAZ.

Paginação

As listagens aceitam page, com valor mínimo 1, e per_page, com padrão 25. Cada página pode retornar de 1 a 100 registros; valores de per_page acima de 100 são limitados pelo servidor a 100.

GET /tomadores?page=1&per_page=25

Limites de uso

Os quatro limites são cumulativos e aplicados separadamente a cada Chave da API. Uma chamada aceita consome as três janelas de tempo e ocupa uma vaga de concorrência até sua conclusão.

2 chamadas simultâneas15 chamadas em 15 segundos60 chamadas em 60 segundos1000 chamadas em 1 hora

Ao exceder qualquer limite, aguarde a conclusão das chamadas concorrentes ou a renovação da janela indicada e tente novamente. A API retorna 429 integration_rate_limit_exceeded para uma janela de tempo ou 429 integration_concurrency_exceeded para concorrência.

Respostas e erros

As respostas usam JSON. O código HTTP indica se você deve corrigir a requisição ou tentar novamente.

200/201 concluída202 persistida, resultado ainda incerto401 Chave da API inválida403 escopo não permitido422 dados inválidos ou rejeição429 limite atingido503 serviço temporariamente indisponível
{"ok":false,"status":422,"error":{"code":"integration_validation_failed","message":"Informe os dados obrigatórios."}}

Versionamento e atualizações

Contrato 1.0.0Publicado em 29/07/2026

Publicação original.

Downloads após registro fiscal

As operações que criam CTe-OS ou eventos na SEFAZ retornam data.downloads. Use sempre downloads.xml_url para baixar o XML criado naquela operação e downloads.dacte_url para o DACTe-OS atualizado. Em cancelamento e Carta de Correção, o XML aponta para o respectivo evento; o DACTe-OS aponta para a versão atualizada do CTe-OS.

{"downloads":{"xml_url":"https://www.ctebrasil.com.br/download/xml/CHAVE","dacte_url":"https://www.ctebrasil.com.br/download/dacte/CHAVE"}}
Referência completa

30 operações implementadas

Referências

GET/municipios?uf={uf}&busca={busca}

Listar municípios

Pesquise municípios e obtenha o código IBGE usado nos cadastros e no XML.

GET/municipios/{codigo_ibge}

Consultar município

Confirme nome e UF a partir de um código IBGE de sete dígitos.

Minha empresa

GET/empresa

Consultar empresa

Consulta os dados da empresa emissora vinculada à chave da API.

PATCH/empresa

Atualizar cadastro

Atualiza somente os campos cadastrais permitidos.

Corpo de exemplo
{
    "nome": "Transportes Modelo Ltda.",
    "fantasia": "Transportes Modelo",
    "ie": "1234567890",
    "cep": "95010010",
    "endereco": "Avenida Exemplo",
    "nro": "100",
    "complemento": "Sala 12",
    "bairro": "Centro",
    "municipio": "Caxias do Sul",
    "uf": "RS",
    "cod_municipio": "4305108",
    "fone": "5433334444",
    "email": "[email protected]",
    "security_email": "[email protected]",
    "security_fone": "54999990000",
    "NroRegEstadual": "REG-EST-001",
    "taf": "TAF-EXEMPLO-001",
    "suframa_inscricao": "SUFRAMA-EXEMPLO-001"
}
PUT/empresa/certificado

Enviar certificado A1

Envie o PFX ou P12 no campo file e a senha em cert_pass, usando multipart/form-data. O certificado e a senha não são retornados na resposta.

Corpo de exemplo
{
    "file": "@certificado.pfx",
    "cert_pass": "senha-do-certificado"
}
PUT/cteos/numeracao-inicial

Definir numeração inicial

Disponível somente antes da primeira emissão.

Corpo de exemplo
{
    "numero": "1",
    "serie": "1"
}
PUT/empresa/logotipo

Enviar logotipo

Envie a imagem no campo file, usando multipart/form-data. Aceita JPG, JPEG ou PNG, limitada a 5 MB e 40 megapixels. Imagens maiores que 1.920 × 1.080 pixels são redimensionadas proporcionalmente. Exige o escopo empresa:logo.

Corpo de exemplo
{
    "file": "@logotipo.png"
}

Tomadores

GET/tomadores?page={page}&per_page={per_page}

Listar tomadores

Lista os cadastros e retorna o CPF ou CNPJ usado para identificar o tomador na emissão.

POST/tomadores

Criar tomador

Cria um tomador vinculado à empresa da chave da API e identificado pelo CPF ou CNPJ.

Corpo de exemplo
{
    "cpf": "",
    "cnpj": "11222333000181",
    "nome": "Tomador Modelo Ltda.",
    "fantasia": "Tomador Modelo",
    "ie": "1234567890",
    "indIEToma": "1",
    "cep": "80010000",
    "endereco": "Rua das Integrações",
    "nro": "250",
    "complemento": "Conjunto 5",
    "bairro": "Centro",
    "municipio": "Curitiba",
    "uf": "PR",
    "cod_municipio": "4106902",
    "fone": "4133334444",
    "email": "[email protected]",
    "status": "1",
    "tpCompraGov": "4",
    "UFIni": "RS",
    "xMunIni": "Porto Alegre",
    "cMunIni": "4314902",
    "UFFim": "PR",
    "xMunFim": "Curitiba",
    "cMunFim": "4106902",
    "CFOP": "6353",
    "infAdFisco": "Operação interestadual de exemplo.",
    "tpFretamento": "1"
}
PATCH/tomadores/{documento}

Editar tomador

Localiza o tomador pelo CPF ou CNPJ sem formatação, sempre dentro da empresa vinculada à chave da API.

Corpo de exemplo
{
    "cpf": "",
    "cnpj": "11222333000181",
    "nome": "Tomador Modelo Ltda.",
    "fantasia": "Tomador Modelo",
    "ie": "1234567890",
    "indIEToma": "1",
    "cep": "80010000",
    "endereco": "Rua das Integrações",
    "nro": "250",
    "complemento": "Conjunto 5",
    "bairro": "Centro",
    "municipio": "Curitiba",
    "uf": "PR",
    "cod_municipio": "4106902",
    "fone": "4133334444",
    "email": "[email protected]",
    "status": "1",
    "tpCompraGov": "4",
    "UFIni": "RS",
    "xMunIni": "Porto Alegre",
    "cMunIni": "4314902",
    "UFFim": "PR",
    "xMunFim": "Curitiba",
    "cMunFim": "4106902",
    "CFOP": "6353",
    "infAdFisco": "Operação interestadual de exemplo.",
    "tpFretamento": "1"
}
DELETE/tomadores/{documento}

Excluir tomador

Exclui o cadastro pelo CPF ou CNPJ dentro da empresa vinculada à chave da API, sem alterar documentos já emitidos.

Veículos

GET/veiculos?page={page}&per_page={per_page}

Listar veículos

Lista os veículos e retorna a placa usada para identificá-los na emissão.

POST/veiculos

Criar veículo

Inclui um veículo identificado pela placa sem formatação.

Corpo de exemplo
{
    "categoria": "1",
    "placa": "ABC1D23",
    "nome": "Ônibus Rodoviário Modelo",
    "financiamento": "1",
    "financ_termino": "31/12/2028",
    "status": "1",
    "capacidade": "46",
    "renavam": "12345678901",
    "uf": "RS",
    "ano": "2024",
    "ano_modelo": "2025",
    "marca": "Marca Modelo",
    "modelo": "Rodoviário Executivo",
    "individual_license": "1",
    "taf": "TAF-EXEMPLO-001",
    "registro": "REG-ANTT-EXEMPLO-001"
}
PATCH/veiculos/{placa}

Editar veículo

Localiza o veículo pela placa no formato AAA0A00, sempre dentro da empresa vinculada à chave da API.

Corpo de exemplo
{
    "categoria": "1",
    "placa": "ABC1D23",
    "nome": "Ônibus Rodoviário Modelo",
    "financiamento": "1",
    "financ_termino": "31/12/2028",
    "status": "1",
    "capacidade": "46",
    "renavam": "12345678901",
    "uf": "RS",
    "ano": "2024",
    "ano_modelo": "2025",
    "marca": "Marca Modelo",
    "modelo": "Rodoviário Executivo",
    "individual_license": "1",
    "taf": "TAF-EXEMPLO-001",
    "registro": "REG-ANTT-EXEMPLO-001"
}
DELETE/veiculos/{placa}

Excluir veículo

Exclui o cadastro pela placa dentro da empresa vinculada à chave da API, sem alterar documentos já emitidos.

CTe-OS

GET/cteos?page={page}&per_page={per_page}

Listar CTe-OS

Lista documentos e retorna a chave de acesso usada nas consultas e eventos.

GET/cteos/{chave}

Consultar CTe-OS

Consulta situação e protocolo pela chave de acesso de 44 dígitos.

Corpo de exemplo
{
    "tomador_documento": "11222333000181",
    "veiculo_placa": "ABC1D23",
    "cCT": "12345678",
    "dhEmiUser": "30/07/2026",
    "CFOP": "6353",
    "cMunIni": "4314902",
    "cMunFim": "4106902",
    "aceite": "1",
    "cteos_emission_mode": "normal",
    "cteos_antecipacao_chave": "",
    "vTPrest": "1500.00",
    "vRec": "1485.00",
    "vTotTrib": "312.40",
    "xDescServ": "Transporte de passageiros",
    "qCarga": "42",
    "tpFretamento": "1",
    "dViagem": "21/07/2026",
    "hViagem": "08:30",
    "dRetorno": "21/07/2026",
    "hRetorno": "18:15",
    "infPercurso": [
        "SC"
    ],
    "infAdFisco": "Documento emitido em ambiente de exemplo.",
    "xObs": "Transporte interestadual de passageiros com retorno no mesmo dia.",
    "obs3": {
        "xCampo": "ROTA",
        "xTexto": "Porto Alegre/RS - Curitiba/PR"
    },
    "obs4": {
        "xCampo": "EMBARQUE",
        "xTexto": "Terminal rodoviário central"
    },
    "obs5": {
        "xCampo": "REFERÊNCIA",
        "xTexto": "Reserva EXEMPLO-2026-001"
    },
    "ICMS": {
        "tipo": "ICMS00",
        "ICMS00": {
            "vBC": "1500.00",
            "pICMS": "12.00",
            "vICMS": "180.00"
        }
    },
    "ICMSUFFim": {
        "vBCUFFim": "1500.00",
        "pFCPUFFim": "2.00",
        "pICMSUFFim": "19.50",
        "pICMSInter": "12.00",
        "vFCPUFFim": "30.00",
        "vICMSUFFim": "112.50",
        "vICMSUFIni": "67.50"
    },
    "InfTribFed": {
        "vPIS": "24.75",
        "vCOFINS": "114.00",
        "vIR": "15.00",
        "vINSS": "15.00",
        "vCSLL": "15.00"
    },
    "IBSCBS": {
        "CST": "000",
        "cClassTrib": "000001",
        "indDoacao": "",
        "gIBSCBS": {
            "vBC": "1500.00",
            "vIBS": "3.00",
            "gIBSUF": {
                "pIBSUF": "0.1000",
                "vIBSUF": "1.50",
                "gRed": {
                    "pRedAliq": "0.0000",
                    "pAliqEfet": "0.1000"
                }
            },
            "gIBSMun": {
                "pIBSMun": "0.1000",
                "vIBSMun": "1.50",
                "gRed": {
                    "pRedAliq": "0.0000",
                    "pAliqEfet": "0.1000"
                }
            },
            "gCBS": {
                "pCBS": "0.9000",
                "vCBS": "13.50",
                "gRed": {
                    "pRedAliq": "0.0000",
                    "pAliqEfet": "0.9000"
                }
            }
        }
    },
    "tpCompraGov": "4",
    "tpOperGov": "3",
    "pRedutorCompraGov": "0.0000",
    "refDFeAnt": [
        "43260711222333000181570010000001231000001234"
    ],
    "origem_tpCompraGov": "1",
    "gTribCompraGov": {
        "pAliqIBSUF": "0.1000",
        "pAliqIBSMun": "0.1000",
        "pAliqCBS": "0.9000",
        "vTribIBSUF": "1.50",
        "vTribIBSMun": "1.50",
        "vTribCBS": "13.50"
    },
    "pgtoVinc": [
        {
            "nPag": 1,
            "idTransacao": "PIX-EXEMPLO-20260720",
            "tpMeioPgto": "17",
            "CNPJReceb": "11222333000181",
            "CNPJBasePSP": "11222333"
        }
    ]
}
POST/{ambiente}/cteos

Emitir CTe-OS

Recebe os mesmos dados da tela de emissão e envia ao ambiente fiscal indicado na URL.

Entender os downloads retornados
Corpo de exemplo
{
    "tomador_documento": "11222333000181",
    "veiculo_placa": "ABC1D23",
    "cCT": "12345678",
    "dhEmiUser": "30/07/2026",
    "CFOP": "6353",
    "cMunIni": "4314902",
    "cMunFim": "4106902",
    "aceite": "1",
    "cteos_emission_mode": "normal",
    "cteos_antecipacao_chave": "",
    "vTPrest": "1500.00",
    "vRec": "1485.00",
    "vTotTrib": "312.40",
    "xDescServ": "Transporte de passageiros",
    "qCarga": "42",
    "tpFretamento": "1",
    "dViagem": "21/07/2026",
    "hViagem": "08:30",
    "dRetorno": "21/07/2026",
    "hRetorno": "18:15",
    "infPercurso": [
        "SC"
    ],
    "infAdFisco": "Documento emitido em ambiente de exemplo.",
    "xObs": "Transporte interestadual de passageiros com retorno no mesmo dia.",
    "obs3": {
        "xCampo": "ROTA",
        "xTexto": "Porto Alegre/RS - Curitiba/PR"
    },
    "obs4": {
        "xCampo": "EMBARQUE",
        "xTexto": "Terminal rodoviário central"
    },
    "obs5": {
        "xCampo": "REFERÊNCIA",
        "xTexto": "Reserva EXEMPLO-2026-001"
    },
    "ICMS": {
        "tipo": "ICMS00",
        "ICMS00": {
            "vBC": "1500.00",
            "pICMS": "12.00",
            "vICMS": "180.00"
        }
    },
    "ICMSUFFim": {
        "vBCUFFim": "1500.00",
        "pFCPUFFim": "2.00",
        "pICMSUFFim": "19.50",
        "pICMSInter": "12.00",
        "vFCPUFFim": "30.00",
        "vICMSUFFim": "112.50",
        "vICMSUFIni": "67.50"
    },
    "InfTribFed": {
        "vPIS": "24.75",
        "vCOFINS": "114.00",
        "vIR": "15.00",
        "vINSS": "15.00",
        "vCSLL": "15.00"
    },
    "IBSCBS": {
        "CST": "000",
        "cClassTrib": "000001",
        "indDoacao": "",
        "gIBSCBS": {
            "vBC": "1500.00",
            "vIBS": "3.00",
            "gIBSUF": {
                "pIBSUF": "0.1000",
                "vIBSUF": "1.50",
                "gRed": {
                    "pRedAliq": "0.0000",
                    "pAliqEfet": "0.1000"
                }
            },
            "gIBSMun": {
                "pIBSMun": "0.1000",
                "vIBSMun": "1.50",
                "gRed": {
                    "pRedAliq": "0.0000",
                    "pAliqEfet": "0.1000"
                }
            },
            "gCBS": {
                "pCBS": "0.9000",
                "vCBS": "13.50",
                "gRed": {
                    "pRedAliq": "0.0000",
                    "pAliqEfet": "0.9000"
                }
            }
        }
    },
    "tpCompraGov": "4",
    "tpOperGov": "3",
    "pRedutorCompraGov": "0.0000",
    "refDFeAnt": [
        "43260711222333000181570010000001231000001234"
    ],
    "origem_tpCompraGov": "1",
    "gTribCompraGov": {
        "pAliqIBSUF": "0.1000",
        "pAliqIBSMun": "0.1000",
        "pAliqCBS": "0.9000",
        "vTribIBSUF": "1.50",
        "vTribIBSMun": "1.50",
        "vTribCBS": "13.50"
    },
    "pgtoVinc": [
        {
            "nPag": 1,
            "idTransacao": "PIX-EXEMPLO-20260720",
            "tpMeioPgto": "17",
            "CNPJReceb": "11222333000181",
            "CNPJBasePSP": "11222333"
        }
    ]
}
POST/{ambiente}/cteos/substituicoes

Emitir substituição

O tomador é herdado do CTe-OS original e não deve ser informado. Envie a placa, a chave original e xObs com justificativa de 140 a 2.000 caracteres; o servidor define tpCTe 3.

Entender os downloads retornados
Corpo de exemplo
{
    "veiculo_placa": "ABC1D23",
    "cCT": "12345678",
    "dhEmiUser": "30/07/2026",
    "CFOP": "6353",
    "cMunIni": "4314902",
    "cMunFim": "4106902",
    "aceite": "1",
    "cteos_emission_mode": "normal",
    "cteos_antecipacao_chave": "",
    "vTPrest": "1500.00",
    "vRec": "1485.00",
    "vTotTrib": "312.40",
    "xDescServ": "Transporte de passageiros",
    "qCarga": "42",
    "tpFretamento": "1",
    "dViagem": "21/07/2026",
    "hViagem": "08:30",
    "dRetorno": "21/07/2026",
    "hRetorno": "18:15",
    "infPercurso": [
        "SC"
    ],
    "infAdFisco": "Documento emitido em ambiente de exemplo.",
    "xObs": "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.",
    "obs3": {
        "xCampo": "ROTA",
        "xTexto": "Porto Alegre/RS - Curitiba/PR"
    },
    "obs4": {
        "xCampo": "EMBARQUE",
        "xTexto": "Terminal rodoviário central"
    },
    "obs5": {
        "xCampo": "REFERÊNCIA",
        "xTexto": "Reserva EXEMPLO-2026-001"
    },
    "ICMS": {
        "tipo": "ICMS00",
        "ICMS00": {
            "vBC": "1500.00",
            "pICMS": "12.00",
            "vICMS": "180.00"
        }
    },
    "ICMSUFFim": {
        "vBCUFFim": "1500.00",
        "pFCPUFFim": "2.00",
        "pICMSUFFim": "19.50",
        "pICMSInter": "12.00",
        "vFCPUFFim": "30.00",
        "vICMSUFFim": "112.50",
        "vICMSUFIni": "67.50"
    },
    "InfTribFed": {
        "vPIS": "24.75",
        "vCOFINS": "114.00",
        "vIR": "15.00",
        "vINSS": "15.00",
        "vCSLL": "15.00"
    },
    "IBSCBS": {
        "CST": "000",
        "cClassTrib": "000001",
        "indDoacao": "",
        "gIBSCBS": {
            "vBC": "1500.00",
            "vIBS": "3.00",
            "gIBSUF": {
                "pIBSUF": "0.1000",
                "vIBSUF": "1.50",
                "gRed": {
                    "pRedAliq": "0.0000",
                    "pAliqEfet": "0.1000"
                }
            },
            "gIBSMun": {
                "pIBSMun": "0.1000",
                "vIBSMun": "1.50",
                "gRed": {
                    "pRedAliq": "0.0000",
                    "pAliqEfet": "0.1000"
                }
            },
            "gCBS": {
                "pCBS": "0.9000",
                "vCBS": "13.50",
                "gRed": {
                    "pRedAliq": "0.0000",
                    "pAliqEfet": "0.9000"
                }
            }
        }
    },
    "tpCompraGov": "4",
    "tpOperGov": "3",
    "pRedutorCompraGov": "0.0000",
    "refDFeAnt": [
        "43260711222333000181570010000001231000001234"
    ],
    "origem_tpCompraGov": "1",
    "gTribCompraGov": {
        "pAliqIBSUF": "0.1000",
        "pAliqIBSMun": "0.1000",
        "pAliqCBS": "0.9000",
        "vTribIBSUF": "1.50",
        "vTribIBSMun": "1.50",
        "vTribCBS": "13.50"
    },
    "pgtoVinc": [
        {
            "nPag": 1,
            "idTransacao": "PIX-EXEMPLO-20260720",
            "tpMeioPgto": "17",
            "CNPJReceb": "11222333000181",
            "CNPJBasePSP": "11222333"
        }
    ],
    "chCte": "43100123456789012345678901234567890123456789"
}
POST/{ambiente}/cteos/complementares

Emitir complementar

Tomador e veículo são herdados do CTe-OS original e não devem ser informados. Envie os dados fiscais do complemento e a chave original; o servidor define tpCTe 1.

Entender os downloads retornados
Corpo de exemplo
{
    "cCT": "12345678",
    "dhEmiUser": "30/07/2026",
    "CFOP": "6353",
    "cMunIni": "4314902",
    "cMunFim": "4106902",
    "aceite": "1",
    "cteos_emission_mode": "normal",
    "cteos_antecipacao_chave": "",
    "vTPrest": "1500.00",
    "vRec": "1485.00",
    "vTotTrib": "312.40",
    "xDescServ": "Transporte de passageiros",
    "qCarga": "42",
    "tpFretamento": "1",
    "dViagem": "21/07/2026",
    "hViagem": "08:30",
    "dRetorno": "21/07/2026",
    "hRetorno": "18:15",
    "infPercurso": [
        "SC"
    ],
    "infAdFisco": "Documento emitido em ambiente de exemplo.",
    "xObs": "Complemento dos valores da prestação informada no CTe-OS original.",
    "obs3": {
        "xCampo": "ROTA",
        "xTexto": "Porto Alegre/RS - Curitiba/PR"
    },
    "obs4": {
        "xCampo": "EMBARQUE",
        "xTexto": "Terminal rodoviário central"
    },
    "obs5": {
        "xCampo": "REFERÊNCIA",
        "xTexto": "Reserva EXEMPLO-2026-001"
    },
    "ICMS": {
        "tipo": "ICMS00",
        "ICMS00": {
            "vBC": "1500.00",
            "pICMS": "12.00",
            "vICMS": "180.00"
        }
    },
    "ICMSUFFim": {
        "vBCUFFim": "1500.00",
        "pFCPUFFim": "2.00",
        "pICMSUFFim": "19.50",
        "pICMSInter": "12.00",
        "vFCPUFFim": "30.00",
        "vICMSUFFim": "112.50",
        "vICMSUFIni": "67.50"
    },
    "InfTribFed": {
        "vPIS": "24.75",
        "vCOFINS": "114.00",
        "vIR": "15.00",
        "vINSS": "15.00",
        "vCSLL": "15.00"
    },
    "IBSCBS": {
        "CST": "000",
        "cClassTrib": "000001",
        "indDoacao": "",
        "gIBSCBS": {
            "vBC": "1500.00",
            "vIBS": "3.00",
            "gIBSUF": {
                "pIBSUF": "0.1000",
                "vIBSUF": "1.50",
                "gRed": {
                    "pRedAliq": "0.0000",
                    "pAliqEfet": "0.1000"
                }
            },
            "gIBSMun": {
                "pIBSMun": "0.1000",
                "vIBSMun": "1.50",
                "gRed": {
                    "pRedAliq": "0.0000",
                    "pAliqEfet": "0.1000"
                }
            },
            "gCBS": {
                "pCBS": "0.9000",
                "vCBS": "13.50",
                "gRed": {
                    "pRedAliq": "0.0000",
                    "pAliqEfet": "0.9000"
                }
            }
        }
    },
    "tpCompraGov": "4",
    "tpOperGov": "3",
    "pRedutorCompraGov": "0.0000",
    "refDFeAnt": [
        "43260711222333000181570010000001231000001234"
    ],
    "origem_tpCompraGov": "1",
    "gTribCompraGov": {
        "pAliqIBSUF": "0.1000",
        "pAliqIBSMun": "0.1000",
        "pAliqCBS": "0.9000",
        "vTribIBSUF": "1.50",
        "vTribIBSMun": "1.50",
        "vTribCBS": "13.50"
    },
    "pgtoVinc": [
        {
            "nPag": 1,
            "idTransacao": "PIX-EXEMPLO-20260720",
            "tpMeioPgto": "17",
            "CNPJReceb": "11222333000181",
            "CNPJBasePSP": "11222333"
        }
    ],
    "chCte": "43100123456789012345678901234567890123456789"
}
POST/{ambiente}/cteos/{chave}/cancelamentos

Cancelar CTe-OS

Localiza o documento pela chave de acesso e exige uma justificativa de 15 a 255 caracteres.

Entender os downloads retornados
Corpo de exemplo
{
    "reason": "Serviço cancelado pelo tomador antes do início da viagem."
}
POST/{ambiente}/cteos/{chave}/cartas-correcao

Registrar CC-e

Registra a Carta de Correção no ambiente fiscal indicado. O exemplo seleciona Observações gerais, código 3, que não exige campos dependentes.

Entender os downloads retornados
Corpo de exemplo
{
    "corrections": [
        {
            "field": 3,
            "value": "Informação complementar corrigida: embarque no Terminal Rodoviário Central."
        }
    ]
}
GET/{ambiente}/cteos/pendencias?page={page}&per_page={per_page}

Listar pendências

Consulta opcional de reconciliação: localiza pendências esquecidas, recupera chaves quando a resposta original foi perdida e permite monitorar a fila de pendências do ambiente. Não é necessário chamar esta lista quando a integração já guardou a chave recebida no HTTP 202.

Quando consultar a lista

Esta consulta não é uma etapa obrigatória antes do reenvio. Se sua integração guardou data.chave do retorno 202, pode reenviar diretamente. Use a lista para reconciliação periódica, recuperação após perda da resposta ou reinício do seu sistema, auditoria da fila de pendências e localização de pendências que não estejam mais registradas localmente. Ela também mostra rejeições definitivas para acompanhamento, mas somente os estados internos 2, 3 e 4 aceitam reenvio.

POST/{ambiente}/cteos/{chave}/reenvios

Reenviar pendência

Use a chave recebida na emissão ou recuperada pela lista. Envie apenas {}: a API reutiliza o XML assinado e preserva número, série e chave; não reenvie o corpo da emissão nem crie uma nova emissão.

Quando uma emissão ficar pendente

O HTTP 202 informa data.chave e data.transmission_state. Guarde a chave — ela é o identificador público do CTe-OS — e não crie outra emissão com o mesmo conteúdo. Depois de um intervalo adequado, chame este endpoint no mesmo ambiente e com a mesma chave da API.

  1. Envie Content-Type: application/json e somente {}.
  2. Não reenvie tomador, veículo, valores ou impostos; a API reutiliza o XML assinado persistido.
  3. Trate 200 como autorizado, 202 como ainda incerto, 422 como rejeição definitiva e 404 como pendência reenviável não encontrada.
POST /api/v1/homologacao/cteos/CHAVE_DE_44_DIGITOS/reenvios
Authorization: Bearer ctebrasil_seu_segredo
Content-Type: application/json

{}
Corpo de exemplo
[]

CTe-OS - Complementares

GET/referencias/ibscbs/csts

Listar CSTs do IBS/CBS

Retorna os CSTs ativos que possuem classificações tributárias disponíveis para emissão.

GET/referencias/ibscbs/csts/{cst}/classificacoes

Listar classificações de um CST do IBS/CBS

Informe o CST retornado pela consulta anterior para obter somente as classificações tributárias vinculadas a ele.

GET/{ambiente}/cteos/antecipacoes

Listar pagamentos antecipados

Retorna as entradas e respectivas chaves que podem ser escolhidas em cteos_antecipacao_chave ao finalizar um serviço.

GET/cteos/{chave}/cobrancas-vinculadas

Listar cobranças vinculadas

Lista as cobranças vinculadas e seus protocolos de evento.

POST/{ambiente}/cteos/{chave}/cobrancas-vinculadas

Vincular cobrança

Registra na SEFAZ uma cobrança criada após a emissão.

Corpo de exemplo
{
    "tpMeioPgto": "17",
    "idTransacao": "PIX-EXEMPLO-001",
    "CNPJReceb": "11222333000181",
    "CNPJBasePSP": "11222333"
}
POST/{ambiente}/cteos/{chave}/cobrancas-vinculadas/cancelamentos

Cancelar vínculos

Cancela na SEFAZ os vínculos de cobrança informados.

Corpo de exemplo
{
    "billing_link_ids": [
        12
    ]
}
Playground da operação

POST Preparar requisição

Preencha os mesmos campos do contrato. A chave fica somente neste navegador durante o teste.

Corpo JSON
Resposta 
Selecione uma operação para preparar a chamada.
Exemplo de integração

cURL

Fale com a gente nos enviando a sua dúvida ou sugestão