> ## 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 um documento > Lê um documento da organização da chave, com os campos que a leitura extraiu. A chamada acha também o documento descartado. ## OpenAPI ````yaml /openapi.yaml get /documents/{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: /documents/{id}: get: tags: - Documentos summary: Ler um documento description: >- Lê um documento da organização da chave, com os campos que a leitura extraiu. A chamada acha também o documento descartado. operationId: getDocument parameters: - $ref: '#/components/parameters/DocumentId' responses: '200': description: O documento, com os campos. content: application/json: schema: $ref: '#/components/schemas/Document' examples: read: summary: A fatura depois da leitura, com os campos preenchidos value: id: doc_318 document_type: id: dtp_31 name: Fatura Comercial (Commercial Invoice) status: uploaded reading_status: complete contact: id: com_12 type: company name: Importadora Exemplo Ltda collection_id: col_40 in_triage: false discarded: false discard_reason: null number: INV-81244/2026 arrival_channel: api arrived_at: '2026-09-25T10:32:05.000-03:00' files: - name: fatura.pdf content_type: application/pdf size: 182044 created_at: '2026-09-25T10:32:05.000-03:00' fields: - key: invoice_number label: Número da Fatura value: INV-81244/2026 - key: invoice_date label: Data da Fatura value: '2026-09-18' - key: exporter_name label: Exportador (Vendedor) value: Shanghai Example Trading Co., Ltd. - key: invoice_amount label: Valor da Fatura value: 48,250.00 - key: currency label: Moeda value: USD - key: incoterm label: Incoterm value: FOB - key: line_items label: Itens da Fatura value: - part_number: A-100 description: STAINLESS STEEL VALVE 1/2 IN quantity: '1000' quantity_unit: PCS unit_price: '25.00' total_price: 25,000.00 - part_number: B-220 description: BRASS FITTING 3/4 IN quantity: '500' quantity_unit: PCS unit_price: '46.50' total_price: 23,250.00 '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: parameters: DocumentId: name: id in: path required: true description: O id do documento. O id começa com `doc_`. schema: type: string example: doc_310 schemas: Document: description: Um documento, com os campos. allOf: - $ref: '#/components/schemas/DocumentFields' - type: object required: - fields properties: fields: type: array description: >- Os campos do tipo de documento, na ordem do catálogo, sem os campos de arquivo. O campo sem resposta vem com `value` igual a `null`. items: $ref: '#/components/schemas/DocumentField' unevaluatedProperties: false DocumentFields: type: object description: Os campos de todo documento. required: - id - document_type - status - reading_status - contact - collection_id - in_triage - discarded - discard_reason - number - arrival_channel - arrived_at - files - created_at 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: $ref: '#/components/schemas/DocumentStatus' reading_status: type: string enum: - not_started - extracting - enriching - validating - complete - failed - no_reader description: >- O andamento da leitura do documento. `not_started`: a leitura não começou. `extracting`, `enriching` e `validating`: a leitura está em curso. `complete`: a leitura terminou. `failed`: a leitura falhou. `no_reader`: o tipo de documento não tem leitura. contact: description: >- O contato do documento. O valor é `null` quando o documento não tem contato. anyOf: - $ref: '#/components/schemas/CollectionContact' - type: 'null' collection_id: type: - string - 'null' pattern: ^col_[1-9][0-9]*$ description: >- O id da coleta do documento. O valor é `null` enquanto o documento está na Triagem. examples: - col_40 in_triage: type: boolean description: Com `true`, o documento está na Triagem e ainda não tem coleta. discarded: type: boolean description: Com `true`, o documento está descartado. discard_reason: type: - string - 'null' enum: - outside_pack - identical_copy - superseded - operator - null description: >- O motivo do descarte. O valor é `null` no documento que não está descartado. `outside_pack`: nenhum pacote de operação ativo pede o tipo do documento. `identical_copy`: o documento repete o arquivo de outro documento. `superseded`: um documento mais novo substituiu este. `operator`: o operador descartou o documento. number: type: - string - 'null' description: >- O número impresso que identifica o documento, como o número da fatura. O valor é `null` antes da leitura. examples: - INV-81244/2026 arrival_channel: type: - string - 'null' enum: - email - portal_upload - operator_upload - spreadsheet - vault - api - null description: >- O canal de chegada do arquivo. O valor é `null` no slot vazio. `email`: o arquivo chegou por e-mail. `portal_upload`: o cliente enviou o arquivo no portal. `operator_upload`: o operador enviou o arquivo na tela. `spreadsheet`: o arquivo saiu de uma planilha. `vault`: o cliente reaproveitou no portal um arquivo do Cofre. `api`: o arquivo chegou pela API. arrived_at: type: - string - 'null' format: date-time description: >- A data e a hora da chegada do arquivo, no fuso horário da organização. O valor é `null` no slot vazio. files: type: array description: Os arquivos do documento. No slot vazio, a lista é vazia. items: $ref: '#/components/schemas/DocumentFile' 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' DocumentField: type: object additionalProperties: false required: - key - label - value properties: key: type: string description: A chave do campo. O `PATCH` usa esta chave em `fields`. examples: - invoice_number label: type: string description: O rótulo do campo, como a tela mostra. examples: - Número da Fatura value: $ref: '#/components/schemas/DocumentFieldValue' description: >- A resposta do campo. O valor é `null` quando o campo não tem resposta. 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. 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) DocumentStatus: 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. 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 DocumentFile: type: object additionalProperties: false required: - name - content_type - size properties: name: type: string description: O nome do arquivo. examples: - fatura.pdf content_type: type: - string - 'null' description: O tipo MIME do arquivo. examples: - application/pdf size: type: integer description: O tamanho do arquivo, em bytes. examples: - 182044 DocumentFieldValue: description: >- A resposta de um campo. O campo de texto, de número, de data e de opção guarda um texto. O campo de lista guarda uma lista de textos. O campo de tabela guarda uma lista de linhas, e cada linha liga a chave da coluna ao texto da célula. anyOf: - type: string - type: number - type: boolean - type: array items: anyOf: - type: string - type: object additionalProperties: type: string - type: 'null' 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 . 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 `. A chave começa com `qx_`. ````