Consulta com OData (CT-e)

O endpoint OData permite consultas avançadas com filtros, ordenação e paginação.

Sumário

• Buscar Lista de CT-es
• Parâmetros OData Suportados
• Exemplos de Filtros
• Paginação com $skiptoken
• Buscar Eventos de CT-e
• Buscar Eventos de NF-e

Buscar Lista de CT-es

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

Parâmetros OData Suportados

Parâmetro	Descrição	Exemplo
$filter	Filtra registros	issuedOn ge 2024-01-01
$top	Máximo de registros por página (máx: 1000)	$top=100
$skip	Ignora N registros (offset)	$skip=200
$skiptoken	Token de paginação (mais eficiente que skip)	$skiptoken=abc123
$orderby	Ordenação	$orderby=issuedOn desc
$select	Seleciona campos específicos	$select=accessKey,issuedOn

Exemplos de Filtros

CT-es do mês de janeiro de 2024:

GET /v2/companies/{company_id}/inbound/odata/TransportationInvoices
  ?$filter=issuedOn ge 2024-01-01T00:00:00Z and issuedOn lt 2024-02-01T00:00:00Z
  &$top=100
  &$orderby=issuedOn desc

CT-es com NSU maior que 5000:

GET /v2/companies/{company_id}/inbound/odata/TransportationInvoices
  ?$filter=nsu gt 5000
  &$top=50

Paginação com $skiptoken

Para listas grandes, use $skiptoken em vez de $skip. O token é retornado na resposta quando há mais páginas:

{
  "@odata.context": "...",
  "@odata.nextLink": "https://api.nfe.io/v2/companies/comp_123/inbound/odata/TransportationInvoices?$skiptoken=abc123",
  "value": [
    { "accessKey": "...", "issuedOn": "..." },
    { "accessKey": "...", "issuedOn": "..." }
  ]
}

Na próxima requisição, use a URL de @odata.nextLink diretamente.

Buscar Eventos de CT-e

GET /v2/companies/{company_id}/inbound/odata/TransportationInvoiceEvents
  ?$filter=receiptOn ge 2024-01-01T00:00:00Z
  &$top=100

O campo de filtro para eventos é receiptOn (data de recebimento) em vez de issuedOn.

Buscar Eventos de NF-e

Os eventos de uma NF-e (ciência, confirmação, cancelamento, CC-e etc.) são listados por ProductInvoiceEvents, com filtro obrigatório pela chave de acesso da NF-e:

GET /v2/companies/{company_id}/inbound/odata/ProductInvoiceEvents
  ?$filter=accessKey eq '35240612345678000195550010000012341123456789'
  &$top=50

{
  "value": [
    {
      "id": "65fa2c11abc1234567890def",
      "createdOn": "2026-04-09T11:00:00Z",
      "company": { "id": "comp_123", "federalTaxNumber": "12345678000195" },
      "eventId": "210210352406123456780001955500100000123411234567891",
      "accessKey": "35240612345678000195550010000012341123456789",
      "parentAccessKey": "35240612345678000195550010000012341123456789",
      "type": "productInvoiceEvent",
      "nsu": 373290,
      "receiptOn": "2026-04-09T10:55:00Z",
      "description": "Ciência da Operação",
      "xmlUrl": "https://api.nfse.io/v2/companies/comp_123/inbound/35240612345678000195550010000012341123456789/events/210210352406123456780001955500100000123411234567891/xml"
    }
  ]
}

• accessKey e parentAccessKey trazem a chave da NF-e a que o evento pertence. Antes, parentAccessKey vinha nulo.
• eventId identifica o evento: tpEvento + chave da NF-e + sequência.
• xmlUrl aponta para o XML do evento (procEventoNFe): .../inbound/{accessKey}/events/{eventId}/xml. Antes, apontava para o XML do documento (.../inbound/{accessKey}/xml).

Veja também

• Endpoints de CT-e
• Endpoints de NF-e
• Exemplos de integração (Python OData)
• Tipos e enums