> ## Documentation Index > Fetch the complete documentation index at: https://developers.useqx.com/llms.txt > Use this file to discover all available pages before exploring further. # Listar as coletas > Lista as coletas da organização da chave, da coleta mais nova à mais antiga. A lista não traz a coleta arquivada. `GET /collections/{id}` mostra a coleta arquivada, com `discarded` igual a `true`. Cada filtro reduz a lista, e os filtros valem juntos. ## OpenAPI ````yaml /openapi.yaml get /collections openapi: 3.1.0 info: title: QX API version: 1.0.0 description: >- A API do QX cria e lê os contatos, as coletas e os documentos da organização e lista os pacotes. Cada chamada leva a chave de API da organização. servers: - url: https://app.useqx.com/api/v1 description: Produção security: - bearerAuth: [] tags: - name: Coletas description: >- As coletas da organização. A coleta pede ao contato os documentos de um pacote. - name: Contatos description: >- As pessoas e as empresas da organização. A pessoa tem um CPF, e a empresa tem um CNPJ. - name: Documentos description: >- Os documentos da organização. O documento enviado sem coleta entra na Triagem, e o documento enviado com coleta ocupa o slot do tipo. - name: Pacotes description: Os pacotes da organização e os requisitos de cada pacote. paths: /collections: get: tags: - Coletas summary: Listar as coletas description: >- Lista as coletas da organização da chave, da coleta mais nova à mais antiga. A lista não traz a coleta arquivada. `GET /collections/{id}` mostra a coleta arquivada, com `discarded` igual a `true`. Cada filtro reduz a lista, e os filtros valem juntos. operationId: listCollections parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - name: contact_id in: query description: >- O id do contato da coleta. O id da pessoa começa com `per_`, e o id da empresa começa com `com_`. schema: type: string example: com_12 - name: tax_id in: query description: O CPF ou o CNPJ do contato da coleta, com ou sem pontuação. schema: type: string example: 12.345.678/0001-95 - name: created_from in: query description: >- A primeira data de criação, no formato `AAAA-MM-DD`. A data usa o fuso horário da organização, e o dia inteiro entra na lista. schema: type: string format: date example: '2026-09-01' - name: created_to in: query description: >- A última data de criação, no formato `AAAA-MM-DD`. A data usa o fuso horário da organização, e o dia inteiro entra na lista. schema: type: string format: date example: '2026-09-30' - name: state in: query description: O estado da coleta. O campo `state` da coleta explica cada valor. schema: $ref: '#/components/schemas/CollectionState' example: assembling - name: pack_id in: query description: >- O id do pacote que a coleta pede. A coleta sem contato também entra na lista, antes de o destinatário se identificar. schema: type: string example: pck_12 - name: number in: query description: >- O protocolo da coleta, ou um número impresso num documento da coleta, como o número da fatura. A busca ignora a diferença entre maiúscula e minúscula. A busca não acha a coleta pelo número que um documento só cita. schema: type: string example: INV-81244/2026 responses: '200': description: Uma página de coletas. content: application/json: schema: $ref: '#/components/schemas/CollectionList' examples: page: summary: Uma página com uma coleta value: data: - id: col_40 protocol: DOC-2026-00123 state: assembling discarded: false contact: id: com_12 type: company name: Importadora Exemplo Ltda recipient: null packs: - id: pck_12 name: Importação marítima numbers: - INV-81244/2026 created_at: '2026-09-25T10:31:12.000-03:00' ready_at: null has_more: true next_cursor: WyIyMDI2LTA5LTI1VDEzOjMxOjEyLjAwMDAwMFoiLDQwXQ '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: Limit: name: limit in: query description: A quantidade de itens da página, de 1 a 100. O padrão é 25. schema: type: integer minimum: 1 maximum: 100 default: 25 example: 25 Cursor: name: cursor in: query description: >- O valor de `next_cursor` da página anterior. Sem este parâmetro, a lista começa no item mais novo. schema: type: string example: WyIyMDI2LTA5LTI1VDEzOjMxOjEyLjAwMDAwMFoiLDQwXQ schemas: CollectionState: type: string enum: - assembling - reviewing - ready_to_dispatch - awaiting_partner - cancelled description: >- O estado da coleta. `assembling`: a coleta está em montagem e espera os documentos. `reviewing`: o operador revisa os documentos. `ready_to_dispatch`: todo documento obrigatório chegou, e nenhuma validação bloqueia a coleta. `awaiting_partner`: o operador enviou a coleta ao parceiro. `cancelled`: o operador cancelou a coleta. CollectionList: type: object additionalProperties: false required: - data - has_more - next_cursor properties: data: type: array items: $ref: '#/components/schemas/CollectionSummary' has_more: type: boolean description: Com `true`, a lista tem mais itens depois desta página. next_cursor: type: - string - 'null' description: >- O valor do parâmetro `cursor` para a próxima página. Na última página, o valor é `null`. CollectionSummary: description: Uma coleta, sem a lista de documentos. allOf: - $ref: '#/components/schemas/CollectionFields' unevaluatedProperties: false Problem: type: object description: Um erro no formato da RFC 9457. required: - type - title - status - detail - code properties: type: type: string const: about:blank description: Sempre `about:blank`. title: type: string description: A frase do status HTTP, em inglês. examples: - Unauthorized status: type: integer description: O status HTTP. examples: - 401 detail: type: string description: A explicação do erro, em português. code: type: string description: O código do erro, em inglês. O código não muda entre versões da v1. CollectionFields: type: object description: Os campos de toda coleta. required: - id - protocol - state - discarded - contact - recipient - packs - numbers - created_at - ready_at properties: id: type: string pattern: ^col_[1-9][0-9]*$ description: O id da coleta. examples: - col_40 protocol: type: string description: O protocolo da coleta. examples: - DOC-2026-00123 state: $ref: '#/components/schemas/CollectionState' discarded: type: boolean description: Com `true`, a coleta está arquivada. contact: description: >- O contato da coleta. O valor é `null` na coleta sem contato, até o destinatário se identificar. anyOf: - $ref: '#/components/schemas/CollectionContact' - type: 'null' recipient: description: >- O destinatário da coleta criada sem contato. Na coleta criada com contato, o valor é `null`. anyOf: - $ref: '#/components/schemas/CollectionRecipient' - type: 'null' packs: type: array description: Os pacotes que a coleta pede. items: $ref: '#/components/schemas/PackReference' numbers: type: array description: >- Os números da operação, como a tela da coleta mostra. A lista traz os números impressos nos documentos dos requisitos identificadores do pacote. Sem esses números, a lista traz os números impressos nos outros documentos da coleta. Na coleta sem pacote de operação, a lista é vazia. items: type: string examples: - - INV-81244/2026 created_at: type: string format: date-time description: A data e a hora da criação, no fuso horário da organização. examples: - '2026-09-25T10:30:00.000-03:00' ready_at: type: - string - 'null' format: date-time description: >- A data e a hora em que a coleta ficou pronta pela última vez, no fuso horário da organização. O valor é `null` quando a coleta nunca ficou pronta. CollectionContact: type: object additionalProperties: false required: - id - type - name properties: id: type: string pattern: ^(per|com)_[1-9][0-9]*$ description: O id do contato. examples: - com_12 type: type: string enum: - person - company description: '`person` para a pessoa e `company` para a empresa.' name: type: - string - 'null' description: O nome do contato. examples: - Importadora Exemplo Ltda CollectionRecipient: type: object additionalProperties: false required: - name - email description: >- O destinatário da coleta sem contato. Ele recebe o convite e se identifica no portal com o CPF ou o CNPJ. Informe o destinatário só quando a chamada não traz `contact_id` nem `tax_id`. properties: name: type: string description: O nome do destinatário. examples: - Importadora Exemplo Ltda email: type: string format: email description: O e-mail do destinatário. examples: - fiscal@importadora.com.br PackReference: type: object additionalProperties: false required: - id - name properties: id: type: string pattern: ^pck_[1-9][0-9]*$ description: O id do pacote. examples: - pck_12 name: type: string description: O nome do pacote. examples: - Importação marítima responses: BadRequest: description: Um parâmetro falta ou tem um valor inválido. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - invalid_parameter examples: invalid_parameter: summary: O limit passa de 100 value: type: about:blank title: Bad Request status: 400 detail: O parâmetro limit tem um valor inválido. code: invalid_parameter Unauthorized: description: A chave falta, não existe ou está revogada. headers: WWW-Authenticate: $ref: '#/components/headers/WwwAuthenticate' content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - unauthorized examples: unauthorized: summary: A chave falta ou não vale value: type: about:blank title: Unauthorized status: 401 detail: >- A chamada não trouxe uma chave de API válida. Envie a chave no cabeçalho Authorization, no formato Bearer . code: unauthorized PaymentRequired: description: A assinatura da organização está bloqueada. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - subscription_blocked examples: subscription_blocked: summary: A assinatura está bloqueada value: type: about:blank title: Payment Required status: 402 detail: >- A assinatura da organização está bloqueada. Regularize o pagamento no QX para usar a API. code: subscription_blocked Forbidden: description: >- A organização está arquivada, ou o plano da organização não inclui a API. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - organization_archived - plan_required examples: plan_required: summary: O plano gratuito não inclui a API value: type: about:blank title: Forbidden status: 403 detail: >- O plano gratuito não inclui a API. Assine um plano pago no QX para usar a API. code: plan_required TooManyRequests: description: A chave ou o endereço IP passou de um limite. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - rate_limited - daily_limit_reached - too_many_invalid_keys examples: rate_limited: summary: A chave passou do limite por minuto value: type: about:blank title: Too Many Requests status: 429 detail: >- A chave passou de um limite por minuto. Espere os segundos do cabeçalho Retry-After e chame de novo. code: rate_limited headers: WwwAuthenticate: description: O esquema de autenticação que a API espera. required: true schema: type: string example: Bearer realm="QX API" RetryAfter: description: Os segundos de espera antes da próxima chamada. required: true schema: type: integer minimum: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: >- A chave de API da organização, no cabeçalho `Authorization: Bearer `. A chave começa com `qx_`. ````