> ## 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.

# Ler uma coleta

> Lê uma coleta da organização da chave, com os documentos da coleta. A chamada acha também a coleta arquivada.



## OpenAPI

````yaml /openapi.yaml get /collections/{id}
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/{id}:
    get:
      tags:
        - Coletas
      summary: Ler uma coleta
      description: >-
        Lê uma coleta da organização da chave, com os documentos da coleta. A
        chamada acha também a coleta arquivada.
      operationId: getCollection
      parameters:
        - name: id
          in: path
          required: true
          description: O id da coleta. O id começa com `col_`.
          schema:
            type: string
          example: col_40
      responses:
        '200':
          description: A coleta, com os documentos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
              examples:
                invoice_arrived:
                  summary: A coleta depois da chegada e da leitura da fatura
                  value:
                    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
                    documents:
                      - id: doc_311
                        document_type:
                          id: dtp_32
                          name: Bill of Lading (B/L)
                        status: pending
                        has_content: false
                      - id: doc_312
                        document_type:
                          id: dtp_33
                          name: Romaneio de Carga (Packing List)
                        status: pending
                        has_content: false
                      - id: doc_318
                        document_type:
                          id: dtp_31
                          name: Fatura Comercial (Commercial Invoice)
                        status: uploaded
                        has_content: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    Collection:
      description: Uma coleta, com a lista de documentos.
      allOf:
        - $ref: '#/components/schemas/CollectionFields'
        - type: object
          required:
            - documents
          properties:
            documents:
              type: array
              description: >-
                Os documentos da coleta, do mais antigo ao mais novo. O
                documento descartado fica de fora.
              items:
                $ref: '#/components/schemas/CollectionDocument'
      unevaluatedProperties: false
    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.
    CollectionDocument:
      type: object
      additionalProperties: false
      required:
        - id
        - document_type
        - status
        - has_content
      properties:
        id:
          type: string
          pattern: ^doc_[1-9][0-9]*$
          description: O id do documento.
          examples:
            - doc_310
        document_type:
          $ref: '#/components/schemas/DocumentTypeReference'
        status:
          type: string
          enum:
            - pending
            - uploaded
            - approved
            - rejected
          description: >-
            O andamento do documento. `pending`: o documento espera o envio.
            `uploaded`: o documento chegou e espera a revisão. `approved`: o
            operador aprovou o documento. `rejected`: o operador recusou o
            documento.
        has_content:
          type: boolean
          description: >-
            Com `true`, o documento tem arquivo anexado ou um campo com
            resposta. Com `false`, o documento é um slot vazio.
    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.
    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.
    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
    DocumentTypeReference:
      type: object
      additionalProperties: false
      required:
        - id
        - name
      properties:
        id:
          type: string
          pattern: ^dtp_[1-9][0-9]*$
          description: O id do tipo de documento.
          examples:
            - dtp_31
        name:
          type: string
          description: O nome do tipo de documento.
          examples:
            - Fatura Comercial (Commercial Invoice)
  responses:
    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 <chave>.
                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
    NotFound:
      description: O recurso não existe na organização da chave.
      content:
        application/problem+json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Problem'
              - type: object
                properties:
                  code:
                    enum:
                      - not_found
          examples:
            not_found:
              $ref: '#/components/examples/NotFound'
    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
  examples:
    NotFound:
      summary: O id não existe na organização da chave
      value:
        type: about:blank
        title: Not Found
        status: 404
        detail: O recurso não existe na organização da chave.
        code: not_found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A chave de API da organização, no cabeçalho `Authorization: Bearer
        <chave>`. A chave começa com `qx_`.

````