Documentos Fiscais · CT-e OS

Emitir CT-e OS POST

Emite um CT-e OS (Outros Serviços de Transporte, modelo 67) -- documento fiscal separado do CT-e normal (modelo 57), usado quando não há uma NF-e/CT-e de carga por trás, e sim um serviço avulso: transporte de valores, de pessoas, ou excesso de bagagem.

⚠️

Só tipo_servico "7" (Transporte de Valores) é suportado hoje. "6" (Pessoas) e "8" (Excesso de Bagagem) são rejeitados explicitamente pelo motor (NotSupportedException, não descartado em silêncio) -- só modal rodoviário existe no MVP.

POST https://areacliente.centralfiscal.com.br/v1/cte-os/emissoes

Corpo da requisição

Campo	Obrigatório	Observação
`emitente_documento`	Sim	CNPJ do transportador, já cadastrado.
`ide.serie`, `ide.numero`, `ide.data_emissao`, `ide.cfop`, `ide.natureza_operacao`	Sim
`ide.tipo_servico`	Sim	Só `"7"` funciona hoje.
`ide.modal`	Não	Default `"01"` (rodoviário).
`tomador`	Não	Objeto `<PessoaFiscal>` (documento/razão social).
`valores.valor_prestacao`	Sim
`valores.componentes`	Não	Detalha a composição do valor (ex.: custódia, seguro).
`impostos.icms`	Sim	Grupo `<imp>`, sempre ICMS00 (CST fixo `"00"`).
`tributos_federais`	Não	PIS/COFINS/IR/INSS/CSLL do CT-e OS vivem aqui (grupo `infTribFed` real), não em `impostos.pis`/`impostos.cofins` -- enviar nesses campos é rejeitado com erro explícito (diferente do CT-e normal, onde PIS/COFINS simplesmente não existe no layout).
`servico.descricao`	Sim
`documentos_referenciados`	Não	Array de `{numero, data_emissao, serie, subserie, valor_documento}` -- outros documentos que originaram o serviço.
`seguros`	Não	Array de `{responsavel, seguradora, numero_apolice}`.

curl -X POST https://areacliente.centralfiscal.com.br/v1/cte-os/emissoes \
  -H "Authorization: Bearer cf_live_51JqK..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: malote-0001" \
  -d '{
    "emitente_documento": "12345678000190",
    "ide": {
      "serie": "1",
      "numero": "4001",
      "data_emissao": "2026-08-07T10:00:00-03:00",
      "cfop": "5352",
      "natureza_operacao": "Prestacao de servico de transporte de valores",
      "tipo_servico": "7"
    },
    "tomador": {"documento": "98765432000110", "razao_social": "Cliente Exemplo Ltda"},
    "valores": {"valor_prestacao": 850, "componentes": [{"nome": "CUSTODIA", "valor": 850}]},
    "impostos": {"icms": {"base_calculo": 850, "aliquota": 12, "valor": 102}},
    "servico": {"descricao": "Transporte de valores", "quantidade": 1},
    "seguros": [{"responsavel": "4", "seguradora": "Seguradora Exemplo S.A.", "numero_apolice": "APOLICE-4001"}]
  }'

Fluxo da operação

POST /v1/cte-os/emissoes

→

Motor monta, assina e transmite pra SEFAZ da UF

→

200 OK · resultado final (mesma chamada)

💡

Síncrono, mesmo padrão de NF-e/CT-e/MDF-e/NFS-e -- resposta já vem com status final (AUTHORIZED/REJECTED/ERROR/PROCESSING).

Resposta

{
  "ambiente": "HOMOLOGATION",
  "documento": "CTEOS",
  "transmissao_id": "c9a0b1d2-3e4f-4a5b-8c6d-7e8f9a0b1c2d",
  "idempotencia": "viagem-0001",
  "id_externo": null,
  "status": "AUTHORIZED",
  "operacao": "ISSUE",
  "chave": "43260812345678000190670010000040011000040015",
  "numero_documento": "4001",
  "serie": "1",
  "protocolo": "143260000123456",
  "mensagem": "Autorizado o uso do CT-e OS",
  "criada_em": "2026-08-07T10:30:01-03:00",
  "concluida_em": "2026-08-07T10:30:03-03:00",
  "xml": {
    "disponivel": true,
    "status": "CTEOS_AUTORIZADA",
    "gerado": true,
    "assinado": true,
    "assinado_em": "2026-08-07T10:30:02-03:00",
    "etapa": "SEFAZ_AUTORIZADA",
    "validacao": null
  },
  "retorno_amigavel": {"codigo": "CTEOS_AUTORIZADO", "mensagem": "Autorizado o uso do CT-e OS"},
  "detalhes": {
    "estado_motor": "AUTORIZADA",
    "cstat": "100",
    "xmotivo": "Autorizado o uso do CT-e OS"
  }
}

Cancelamento

⚠️

Não existe POST /v1/cte-os/cancelamentos hoje -- diferente de NF-e/CT-e/MDF-e/NFS-e, o CT-e OS ainda não tem endpoint de cancelamento na API pública. O campo chave_cte_cancelado no corpo de emissão serve pra outra coisa (referenciar um CT-e OS anterior sendo substituído por esta nova emissão), não é um cancelamento.