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).
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 responde422 CTE_INACTIVE. - Série e próximo número do CT-e (modelo 57), padrão série
1e número1. 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.cteEmissionhabilitado 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).
# 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.