Ativando o Serviço de Inbound

Antes de receber documentos, você precisa ativar o serviço de inbound para cada CNPJ que deseja monitorar.

Sumário

• Ativar Inbound de NF-e
• Ativar Inbound de CT-e
  • Filtrar por papel da sua empresa no CT-e
  • Alterar o filtro depois
• Verificar Configuração Atual
• Desativar Inbound

Ativar Inbound de NF-e

POST /v2/companies/{company_id}/inbound/productinvoices
Authorization: ApiKey {api_key}
Content-Type: application/json

{
  "StartFromNsu": 0,
  "StartFromDate": "2024-01-01T00:00:00Z",
  "EnvironmentSEFAZ": "Production",
  "AutomaticManifesting": {
    "MinutesToWaitAwarenessOperation": 60
  },
  "WebhookVersion": 2
}

Campos do corpo:

Campo	Tipo	Obrigatório	Descrição
StartFromNsu	long	Não	NSU inicial. 0 = busca desde o início. Use um NSU específico para sincronizar com histórico
StartFromDate	DateTime	Não	Data inicial para busca. Padrão: 90 dias atrás
EnvironmentSEFAZ	string	Sim	"Production" (produção SEFAZ) ou "Test" (homologação SEFAZ)
EventType	string	Não	Filtro de tipos de evento (códigos separados por vírgula). null = todos
Schema	int	Não	0=NF-e + Eventos, 1=Somente NF-e, 2=Somente Eventos
AutomaticManifesting.MinutesToWaitAwarenessOperation	int	Não	Minutos aguardados antes de auto-manifestar ciência. Mínimo: 5
WebhookVersion	int	Não	Versão do formato de webhook. Use 2 (mais recente)

Resposta de sucesso (200):

{
  "companyId": "comp_123",
  "environmentSEFAZ": "Production",
  "startFromNsu": 0,
  "startFromDate": "2024-01-01T00:00:00Z",
  "status": "Active",
  "createdOn": "2024-03-15T10:30:00Z"
}

Ativar Inbound de CT-e

POST /v2/companies/{company_id}/inbound/transportationinvoices
Authorization: ApiKey {api_key}
Content-Type: application/json

{
  "StartFromNsu": 0,
  "StartFromDate": "2024-01-01T00:00:00Z",
  "EnvironmentSEFAZ": "Production",
  "InterestedPartyRoles": ["Taker"]
}

Filtrar por papel da sua empresa no CT-e (InterestedPartyRoles)

A distribuição da SEFAZ devolve todo CT-e em que o seu CNPJ é mencionado — inclusive aqueles em que ele aparece apenas como destinatário ou recebedor de uma carga que não é sua responsabilidade contratual. Se você só quer os CT-e em que a sua empresa é a tomadora do serviço de transporte, informe o filtro:

Papel	Onde a SEFAZ registra	Significado
Taker	CTeMetadata.taker (via ide/toma3, ide/toma03 ou ide/toma4)	Tomador do serviço de transporte
Sender	infCte/rem	Remetente da carga
Dispatcher	infCte/exped	Expedidor
Receiver	infCte/receb	Recebedor
Recipient	infCte/dest	Destinatário

• Ausente ou array vazio = sem filtro — todos os documentos capturados são enviados (comportamento histórico). Não existe um valor "All".
• Um mesmo CNPJ pode ocupar mais de um papel no mesmo CT-e (é comum ser destinatário e tomador). Basta casar com um dos papéis do filtro.
• O emitente (a transportadora, infCte/emit) não é filtrável: esse ator não é capturado nos metadados.
• Documentos que o filtro suprime não são bilhetados como captura efetiva: o uso é registrado em ações próprias (ProcessDocFiltered, ProcessDocReprocessFiltered, ProcessEventFiltered). Confirme o efeito comercial no seu plano.

Taker com toma de 0 a 3 aponta para outro ator

Com toma=4 o tomador é declarado explicitamente. Com toma de 0 a 3, o XML apenas indica qual dos outros atores é o tomador (remetente, expedidor, recebedor ou destinatário) e o CNPJ daquele ator é copiado para o campo do tomador. Por isso Taker frequentemente coincide com um dos outros quatro papéis — o que é o comportamento correto, não duplicação.

Filtrar por Sender exige o tópico de webhook de saída

Um CT-e que passa um filtro ["Sender"] é, por definição, um documento emitido pela sua empresa — e vai para o tópico de webhook outbound_successfully, não para o de entrada. Se o seu endpoint não estiver registrado nesse tópico, o filtro não entrega nada. Veja Webhook events.

O filtro nunca é causa de perda por dado ausente (fail-open)

Entregar a mais é recuperável; suprimir em silêncio não. Então o documento é entregue quando: não há filtro configurado; ou o CT-e não trouxe nenhum dos cinco atores (os grupos são opcionais no schema e <CNPJ></CNPJ> vazio é válido — "nenhum ator capturado" é lacuna de dado, não prova de que a empresa está fora do filtro).

Quando algum ator veio, mas não o do papel filtrado, o documento é suprimido: não há como confirmar o papel, e presumir o contrário entregaria (e cobraria) exatamente o que você pediu para não receber.

Alterar o filtro depois

PUT /v2/companies/{company_id}/inbound/transportationinvoices/webhook/filter
Authorization: ApiKey {api_key}
Content-Type: application/json

{
  "InterestedPartyRoles": ["Taker", "Recipient"]
}

Envie array vazio ([]) para remover o filtro e voltar a receber todos os documentos. O campo é obrigatório: omiti-lo ou enviar null retorna 400, de propósito, para não confundir "limpar o filtro" com "não informado". A empresa precisa ter configuração de inbound ativa, senão a resposta também é 400.

A alteração do filtro não é bilhetada como captura.

Verificar Configuração Atual

GET /v2/companies/{company_id}/inbound/productinvoices
Authorization: ApiKey {api_key}

Desativar Inbound

DELETE /v2/companies/{company_id}/inbound/productinvoices
Authorization: ApiKey {api_key}

Referência completa da API

• 📖 API Reference — Consulta NF-e Distribuição
• 📖 API Reference — Consulta CT-e v2

Veja também

• Ativar via painel — alternativa sem código
• Configurar webhook
• Endpoints de NF-e
• Endpoints de CT-e
• Tipos e enums