Cancelamento e carta de correção do CT-e

Cancelar CT-e

POST https://apifiscal.weesy.com.br/v1/cte/{id}/cancelamento

Pede à SEFAZ o cancelamento de um CT-e autorizado, por exemplo quando o frete não aconteceu. Regras da SEFAZ:

só é aceito em até 7 dias (168 horas) depois da autorização;
CT-e que já tem carta de correção registrada não pode ser cancelado;
a justificativa precisa ter de 15 a 255 caracteres.

A resposta confirma que recebemos o pedido. Em geral a SEFAZ responde na hora e o CT-e já volta cancelado (ou cancelamento_rejeitado); se a SEFAZ demorar, ele volta cancelamento_solicitado e o resultado chega pelo webhook ou consultando o CT-e.

Parâmetros

Nome	Onde	Tipo	Descrição
id obrigatório	caminho	string	Id do CT-e, devolvido no campo `id` quando você emitiu.

Exemplo de chamada

cURLcurl --request POST \
  --url "https://apifiscal.weesy.com.br/v1/cte/6ade6278e8340a492a46b564/cancelamento" \
  --header "Authorization: Bearer $WEESY_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "justificativa": "Frete não realizado, carga devolvida ao remetente."
}'

Node.jsconst resposta = await fetch("https://apifiscal.weesy.com.br/v1/cte/6ade6278e8340a492a46b564/cancelamento", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WEESY_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "justificativa": "Frete não realizado, carga devolvida ao remetente."
  }),
});
console.log(resposta.status, await resposta.text());

Pythonimport os

import requests

resposta = requests.post(
    "https://apifiscal.weesy.com.br/v1/cte/6ade6278e8340a492a46b564/cancelamento",
    headers={"Authorization": f"Bearer {os.environ['WEESY_TOKEN']}"},
    json={
        "justificativa": "Frete não realizado, carga devolvida ao remetente.",
    },
    timeout=30,
)
print(resposta.status_code, resposta.text)

PHP<?php

$corpo = <<<'JSON'
{
  "justificativa": "Frete não realizado, carga devolvida ao remetente."
}
JSON;

$contexto = stream_context_create(["http" => [
    "method" => "POST",
    "header" => implode("\r\n", ["Authorization: Bearer " . getenv("WEESY_TOKEN"), "Content-Type: application/json"]),
    "content" => $corpo,
    "ignore_errors" => true, // lê o corpo também nas respostas de erro
]]);
$resposta = file_get_contents("https://apifiscal.weesy.com.br/v1/cte/6ade6278e8340a492a46b564/cancelamento", false, $contexto);
echo $http_response_header[0], PHP_EOL, $resposta, PHP_EOL;

C#using System.Net.Http.Headers;
using System.Text;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("WEESY_TOKEN"));

var corpo = """
    {
      "justificativa": "Frete não realizado, carga devolvida ao remetente."
    }
    """;

using var resposta = await http.PostAsync(
    "https://apifiscal.weesy.com.br/v1/cte/6ade6278e8340a492a46b564/cancelamento",
    new StringContent(corpo, Encoding.UTF8, "application/json"));
Console.WriteLine($"{(int)resposta.StatusCode} {await resposta.Content.ReadAsStringAsync()}");

Corpo da requisição

Campo	Tipo	Descrição
justificativa obrigatório	string	Por que o CT-e está sendo cancelado, em texto livre (vai para a SEFAZ).

Exemplo

JSON

{
  "justificativa": "Frete não realizado, carga devolvida ao remetente."
}

Respostas

202: Pedido recebido. Veja status e o evento em eventos[].
400: Algum dado está errado ou faltando. A lista erros diz qual campo e o que corrigir (code = validacao). (formato de erro)
401: Token ausente, errado ou revogado (credencialinvalida). Confira o cabeçalho Authorization. (formato de erro)
404: ctenaoencontrado — não existe, ou é de outra empresa. (formato de erro)
409: ctestatusinvalido (o CT-e não está autorizado, já foi cancelado ou tem carta de correção) ou cteprazocancelamentoexpirado (passou das 168 horas). (formato de erro)
503: A prefeitura, o sistema nacional ou a SEFAZ estão fora do ar (autorizadorindisponivel). Tente de novo em alguns minutos. (formato de erro)

Campos da resposta 202

Campo Tipo Descrição

id
obrigatório

string

O id que a Weesy dá ao documento. Guarde como texto e não tente interpretar.

idIntegracao
obrigatório

string

O código seu que veio na emissão.

status
obrigatório

string

Situação do CT-e. A lista pode crescer: trate valor desconhecido sem quebrar.

Valor	Significado
`recebido`	Recebemos o CT-e; ele ainda vai para a SEFAZ
`em_processamento`	Enviado à SEFAZ; aguardando a resposta
`autorizado`	A SEFAZ autorizou — o CT-e vale e já tem chave de acesso e protocolo
`rejeitado`	A SEFAZ recusou por algum dado — veja `sefaz.mensagem`, corrija e mande de novo com o mesmo `idIntegracao`
`erro`	Falha técnica (SEFAZ fora do ar, tempo esgotado) — reenvie em `POST /cte/{id}/reprocessamento`
`cancelamento_solicitado`	Pedido de cancelamento enviado; aguardando a SEFAZ
`cancelado`	A SEFAZ confirmou o cancelamento
`cancelamento_rejeitado`	A SEFAZ recusou o cancelamento — o CT-e continua autorizado

A carta de correção não muda o status: ela aparece em eventos[].

ambiente
obrigatório

string

Onde o documento é emitido.

Valor	Significado
`producao`	Documento de verdade, com valor fiscal
`homologacao`	Teste na SEFAZ, sem valor fiscal. Exige certificado; os nomes das partes saem como "CTE EMITIDO EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL"

O ambiente simulacao (sem certificado, sem sair da Weesy), que a NFS-e tem, ainda não existe para CT-e e MDF-e.

empresa
obrigatório object

empresa.cnpj
obrigatório

string

CNPJ sem pontos, barra ou traço (14 posições). Já aceita o CNPJ com letras, que começa a valer em 2026.

empresa.razaoSocial
obrigatório string

empresa.uf

string

Sigla do estado, em maiúsculas.

Valores: 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.

serie
obrigatório string

numero

string ou null

Número do CT-e. Vazio até a Weesy montar o XML.

chaveAcesso string ou null

protocolo

string ou null

Protocolo de autorização da SEFAZ.

autorizadoEm string (date-time) ou null

cfop string

tomador object

tomador.papel

integer

Quem paga o frete (o "tomador do serviço") — código oficial toma do CT-e.

Código	Quem paga
0	O remetente
1	O expedidor
2	O recebedor
3	O destinatário
4	Outra pessoa — informe os dados dela no próprio `tomador`

Valor	Significado
`0`	Remetente
`1`	Expedidor
`2`	Recebedor
`3`	Destinatário
`4`	Outra pessoa (dados no próprio tomador)

tomador.cpfCnpj

string