Consultar DC-e em lista
GET/v1/subscriptions/:subscriptionId/taxpayers/:taxpayerId/contentdeclarations
Lista as DC-e do contribuinte, com filtro, ordenação e paginação em OData.
A listagem devolve as colunas promovidas do documento — o suficiente para desenhar uma
grade e decidir o que abrir. O documento inteiro (itens, transporte, endereços, histórico)
vem de GET {id}.
O escopo não é negociável
A assinatura e o contribuinte do caminho são aplicados por cima do que você escrever em
$filter. accountId e companyId são campos legíveis e filtráveis, e ainda assim não
ampliam nada: filtrar por outra assinatura resulta em página vazia, nunca em documento de
terceiro.
O que o $filter aceita
| Categoria | Aceito |
|---|---|
| Lógica | and, or, not, parênteses |
| Comparação | eq, ne, lt, le, gt, ge entre um campo e um literal |
| Nulo | eq null, ne null |
| Texto | contains(), startswith(), endswith() sobre campo de texto |
⚠️ O que responde 400, e de propósito: $apply, $search, $compute, $expand,
expressões aritméticas, lambdas (any/all) e comparação entre dois campos. A última
não tem índice por trás e varreria a tabela sob um filtro que parece barato. O 400 vem com
type …/unsupported-query, e o detail nomeia o que foi recusado.
📌 O filtro por batchId casa um GUID escrito com ou sem hífens: batchId eq '7c9a2f104b3d4e918a5f1d2c3b4a5e6f' encontra o lote 7c9a2f10-4b3d-4e91-8a5f-1d2c3b4a5e6f.
Ordenação e paginação
| Ordem padrão | createdAt desc, com desempate por id — o desempate é acrescentado sempre, inclusive quando você ordena por outro campo |
$top | máximo 200, que também é o padrão quando você não manda. Acima disso, 400 |
$skip | negativo responde 400 |
🔑 O desempate por id é o que faz a paginação cobrir o conjunto exatamente uma vez.
Sem ordem estável, páginas repetem e pulam documentos sem que nada parea errado.
O total, quando você precisa dele
$count=true acrescenta @odata.count ao envelope com o total sob o mesmo filtro — não
o tamanho da página. É uma segunda consulta: peça quando for desenhar um paginador, não por
hábito.
Request
Responses
- 200
- 400
- 401
- 403
- 404
A página, no envelope OData. @odata.count só aparece quando você pediu $count=true.
A consulta pede algo que a listagem não resolve — campo fora do conjunto aceito, opção
não suportada, $top acima do teto, $skip negativo ou literal incompatível com o
campo. O corpo é Problem Details com type …/unsupported-query, e o detail
nomeia o que foi recusado.
Token ausente, expirado ou inválido. O token tem validade curta: ao receber 401, peça um
token novo e repita a chamada.
O token autentica, mas a assinatura da URL não é a do token (nem uma a que o usuário tem
acesso). O type é …/subscription-scope-undetermined.
O contribuinte do caminho ({taxpayerId}) não existe ou não pertence à assinatura da URL.
A resposta é a mesma nos dois casos, e vem antes de qualquer coisa do pedido ser lida.