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. A mensagem do
400 nomeia o que foi recusado.
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
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, e o texto nomeia o que foi recusado.
Token ausente, expirado, com audiência diferente de dfetech.contentdeclaration.api, ou
chave de API no lugar de um JWT.
O token autentica, mas não autoriza: falta o escopo ou o papel da operação, ou a assinatura
da URL não é do token (nem acessível ao usuário). Leia o type para distinguir — o de
assinatura é …/subscription-scope-undetermined.