Docs/CT-e

CT-e — Conhecimento de Transporte Eletrônico

API-first para emissão, consulta e cancelamento de CT-e (modelo 57) e CT-e OS (modelo 67). Não passa por venda nem por invoice de produto/serviço. A emissão é sempre em produção (SEFAZ tpAmb=1).

Ver requisitos de autenticação

Pré-requisitos

  • Certificado digital A1 válido na empresa
  • CT-e ativo na empresa. Toda empresa nasce com o CT-e desativado. O CT-e e o CT-e OS não aparecem no painel: a ativação e a configuração são só pela API, em PATCH /v1/companies/{companyId}/cte/settings (veja abaixo). Desativado, a emissão responde 422 CTE_INACTIVE.
  • Série e próximo número do CT-e (modelo 57), padrão série 1 e número 1. O CT-e OS (modelo 67) tem numeração própria (osSeries / osNumber); sem ela, a primeira emissão parte do número atual do CT-e. O RNTRC é opcional: se não for salvo aqui, pode vir em cada CT-e.
  • Recurso features.cteEmission habilitado na conta
  • Assinatura com direito a emitir (mesmo limite mensal de notas)

Ativar e configurar pela API

Não há configuração de CT-e no painel. Use GET para ler e PATCH para ligar, desligar ou ajustar. Campos ausentes ficam como estão; campo desconhecido responde 422. Só o titular ou um administrador da empresa pode alterar (403 COMPANY_SETTINGS_FORBIDDEN).

Shell
# Ativar e configurar
curl -X PATCH "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/cte/settings" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Api-Secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"active": true, "series": 1, "number": 1}'

# Desativar
curl -X PATCH "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/cte/settings" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Api-Secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

O próximo número só sobe. Número menor que o atual na mesma série responde 409 CTE_NUMBER_REGRESSION (ou CTE_OS_NUMBER_REGRESSION); para voltar mesmo assim, repita com ?confirmNumber=1. Série nova grava o número informado. Para parar de emitir, envie {"active": false}.

Fluxo assíncrono

POST /v1/companies/{companyId}/cte cria o documento e enfileira a transmissão à SEFAZ. A resposta imediata traz status: processing (ou pending se o módulo estiver inativo). O desfecho chega por webhook (cte.authorized / cte.rejected) ou por GET /v1/companies/{companyId}/cte/{id}.

Idempotência

Informe Idempotency-Key (header) ou externalId no body. A chave é única por empresa na coleção ctes.

CT-e OS

Use POST /v1/companies/{companyId}/cte-os para o modelo 67 (pessoas, valores ou excesso de bagagem). Requer serviceDescription, tomador (takerParty, exceto bagagem) e taf ou stateAgencyRegistration. Consulta e cancelamento usam as mesmas rotas /v1/companies/{companyId}/cte.