> ## 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. # Gravar campos ou enviar o arquivo > Faz uma de duas mudanças num documento. Com `fields`, em JSON, a chamada grava as respostas dos campos, e o valor gravado vence o valor que a leitura extraiu. O documento da Triagem volta ao encaixe, e a coleta do documento roda as validações de novo. Com `file`, em `multipart/form-data`, a chamada envia o arquivo de um documento de uma coleta aberta, e a leitura começa. No documento sem arquivo, a chamada anexa o arquivo ao mesmo documento e responde `200`. No documento com arquivo, a chamada faz uma troca de arquivo e responde `201`. A troca cria um documento novo com o arquivo, e o cabeçalho `Location` traz o caminho do documento novo. O documento antigo fica como versão anterior, com o arquivo, o estado e a leitura dele. A troca vale também para o documento aprovado, enquanto a coleta recebe documentos. A chamada com `file` conta no limite de escritas pagas da chave e aceita o cabeçalho `Idempotency-Key`. ## OpenAPI ````yaml /openapi.yaml patch /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. Todo erro sai no formato da RFC 9457 (`application/problem+json`), com um `code` estável. Além dos erros de cada operação, qualquer caminho sob `/api/v1` pode responder estes erros: - `404` com `route_not_found`: a API não tem o caminho, ou o caminho não aceita o método HTTP. - `405` com `method_not_allowed`: a API não reconhece o método HTTP. - `406` com `not_acceptable`: a API não reconhece o `Content-Type` ou o `Accept` da chamada. - outro status `4xx` com `request_refused`: a API não conseguiu completar a chamada. - um status `5xx` com `internal_error`: o QX teve um erro interno. 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}: patch: tags: - Documentos summary: Gravar campos ou enviar o arquivo description: >- Faz uma de duas mudanças num documento. Com `fields`, em JSON, a chamada grava as respostas dos campos, e o valor gravado vence o valor que a leitura extraiu. O documento da Triagem volta ao encaixe, e a coleta do documento roda as validações de novo. Com `file`, em `multipart/form-data`, a chamada envia o arquivo de um documento de uma coleta aberta, e a leitura começa. No documento sem arquivo, a chamada anexa o arquivo ao mesmo documento e responde `200`. No documento com arquivo, a chamada faz uma troca de arquivo e responde `201`. A troca cria um documento novo com o arquivo, e o cabeçalho `Location` traz o caminho do documento novo. O documento antigo fica como versão anterior, com o arquivo, o estado e a leitura dele. A troca vale também para o documento aprovado, enquanto a coleta recebe documentos. A chamada com `file` conta no limite de escritas pagas da chave e aceita o cabeçalho `Idempotency-Key`. operationId: updateDocument parameters: - $ref: '#/components/parameters/DocumentId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DocumentFieldsInput' examples: fields: summary: Grava o Incoterm da fatura value: fields: incoterm: CFR multipart/form-data: schema: $ref: '#/components/schemas/DocumentFileInput' examples: file: summary: Anexa o romaneio ao slot vazio da coleta value: file: romaneio.pdf swap: summary: Troca o arquivo da fatura value: file: fatura-corrigida.pdf responses: '200': description: O documento, com os campos. content: application/json: schema: $ref: '#/components/schemas/Document' examples: fields: summary: A fatura com o Incoterm gravado 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 replaced_by: 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: CFR - 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 file: summary: O romaneio ocupa o slot, e a leitura começa value: id: doc_312 document_type: id: dtp_33 name: Romaneio de Carga (Packing List) status: uploaded reading_status: extracting contact: id: com_12 type: company name: Importadora Exemplo Ltda collection_id: col_40 in_triage: false discarded: false discard_reason: null replaced_by: null number: null arrival_channel: api arrived_at: '2026-09-25T11:05:47.000-03:00' files: - name: romaneio.pdf content_type: application/pdf size: 96512 created_at: '2026-09-25T10:31:12.000-03:00' fields: - key: packing_list_number label: Número do Romaneio value: null - key: packing_list_date label: Data do Romaneio value: null - key: invoice_numbers label: Faturas Referenciadas value: null '201': description: >- A troca de arquivo criou um documento novo. O corpo traz o documento novo, com os campos, e o cabeçalho `Location` traz o caminho dele. headers: Location: $ref: '#/components/headers/Location' content: application/json: schema: $ref: '#/components/schemas/Document' examples: swap: summary: >- A fatura nova chega com o arquivo corrigido, e a leitura começa value: id: doc_325 document_type: id: dtp_31 name: Fatura Comercial (Commercial Invoice) status: uploaded reading_status: extracting contact: id: com_12 type: company name: Importadora Exemplo Ltda collection_id: col_40 in_triage: false discarded: false discard_reason: null replaced_by: null number: null arrival_channel: api arrived_at: '2026-09-26T09:14:22.000-03:00' files: - name: fatura-corrigida.pdf content_type: application/pdf size: 184310 created_at: '2026-09-26T09:14:22.000-03:00' fields: - key: invoice_number label: Número da Fatura value: null - key: invoice_date label: Data da Fatura value: null - key: exporter_name label: Exportador (Vendedor) value: null - key: invoice_amount label: Valor da Fatura value: null - key: currency label: Moeda value: null - key: incoterm label: Incoterm value: CFR - key: line_items label: Itens da Fatura value: null '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: >- O documento não aceita a mudança. `document_has_content`: o documento está na Triagem e já tem arquivo ou resposta, e a chamada trouxe `file`. `document_locked`: o documento está descartado, ou a coleta dele não recebe documentos. A chamada com `fields` recebe `document_locked` também num documento aprovado. A chamada com `file` recebe `document_locked` também num documento aprovado sem arquivo e num documento da Triagem sem arquivo. `document_replaced`: o documento é uma versão anterior, e o campo `replaced_by` traz o id do documento atual. A resposta `409` também chega quando outra chamada com o mesmo `Idempotency-Key` ainda está em curso. content: application/problem+json: schema: anyOf: - allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - document_has_content - document_locked - $ref: '#/components/schemas/DocumentReplacedProblem' - $ref: '#/components/schemas/IdempotencyKeyInUseProblem' examples: document_has_content: summary: O documento da Triagem já tem arquivo value: type: about:blank title: Conflict status: 409 detail: >- O documento da Triagem já tem arquivo ou resposta. A API só troca o arquivo de um documento de coleta. code: document_has_content document_replaced: summary: O documento é uma versão anterior value: type: about:blank title: Conflict status: 409 detail: >- O documento é uma versão anterior. O campo replaced_by traz o id do documento atual. code: document_replaced replaced_by: doc_325 idempotency_key_in_use: $ref: '#/components/examples/IdempotencyKeyInUse' '413': $ref: '#/components/responses/FileTooLarge' '422': description: >- Um campo tem erro, e a lista `errors` diz o erro de cada campo. A resposta também chega em três casos: o tipo não tem um campo com a chave, o tipo é um formulário sem campo de arquivo, ou o formato do arquivo não serve para o tipo. Nenhuma mudança fica gravada. A resposta `422` também chega quando o `Idempotency-Key` já atendeu uma chamada com outro conteúdo. content: application/problem+json: schema: anyOf: - $ref: '#/components/schemas/ValidationProblem' - $ref: '#/components/schemas/DocumentUpdateRefusedProblem' - $ref: '#/components/schemas/IdempotencyKeyReusedProblem' examples: unknown_field: summary: O tipo não tem um campo com a chave value: type: about:blank title: Unprocessable Content status: 422 detail: >- O tipo de documento não tem um campo com esta chave. O GET do documento lista as chaves dos campos. code: unknown_field validation_failed: summary: O valor não tem a forma do campo value: type: about:blank title: Unprocessable Content status: 422 detail: >- Um ou mais campos têm erro. A lista errors diz o erro de cada campo. code: validation_failed errors: - field: fields.line_items code: invalid message: >- O valor não tem a forma do campo. O campo de lista e o campo de tabela recebem uma lista, e os outros campos recebem um texto. idempotency_key_reused: $ref: '#/components/examples/IdempotencyKeyReused' '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 IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Um valor único que o seu sistema cria para cada escrita, como um UUID. A chamada repetida com o mesmo valor e o mesmo conteúdo recebe a primeira resposta e não grava nada de novo. A API guarda a resposta por 24 horas. schema: type: string minLength: 1 maxLength: 255 example: 5f0c7e8a-3a1b-4d2e-9c61-2b7f4e0d9a13 schemas: DocumentFieldsInput: type: object additionalProperties: false required: - fields properties: fields: type: object minProperties: 1 description: >- As respostas dos campos, no formato `{ "chave": valor }`, com pelo menos uma chave. A chave é a `key` de um campo em `GET /documents/{id}`. O valor tem a forma do `value` desse campo, e `null` apaga a resposta. additionalProperties: $ref: '#/components/schemas/DocumentFieldValue' examples: - invoice_number: INV-81244/2026 DocumentFileInput: type: object additionalProperties: false required: - file properties: file: type: string format: binary description: >- O arquivo do slot vazio, até 25 MB. O campo de arquivo do tipo decide os formatos aceitos. 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 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, no idioma da organização. A resposta que sai antes de a chave identificar a organização fica 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. DocumentReplacedProblem: description: >- O documento é uma versão anterior. O campo `replaced_by` traz o id do documento atual. allOf: - $ref: '#/components/schemas/Problem' - type: object required: - replaced_by properties: code: enum: - document_replaced replaced_by: type: string pattern: ^doc_[1-9][0-9]*$ description: O id do documento atual. examples: - doc_325 IdempotencyKeyInUseProblem: description: Outra chamada com o mesmo `Idempotency-Key` ainda está em curso. allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - idempotency_key_in_use ValidationProblem: description: Um erro de validação. A lista `errors` diz o erro de cada campo. allOf: - $ref: '#/components/schemas/Problem' - type: object required: - errors properties: code: enum: - validation_failed errors: type: array items: $ref: '#/components/schemas/FieldError' DocumentUpdateRefusedProblem: description: >- O tipo não tem um campo com a chave, o tipo é um formulário sem campo de arquivo, ou o formato do arquivo não serve para o tipo. allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - unknown_field - document_type_without_file - unsupported_file description: >- `unknown_field`: o tipo de documento não tem um campo com a chave. `document_type_without_file`: o tipo de documento é um formulário sem campo de arquivo. `unsupported_file`: o formato do arquivo não serve para o tipo de documento. IdempotencyKeyReusedProblem: description: O `Idempotency-Key` já atendeu uma chamada com outro conteúdo. allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - idempotency_key_reused 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' DocumentFields: type: object description: Os campos de todo documento. required: - id - document_type - status - reading_status - contact - collection_id - in_triage - discarded - discard_reason - replaced_by - 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 - replaced - 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. `replaced`: uma troca de arquivo criou um documento novo, e este documento ficou como versão anterior. replaced_by: type: - string - 'null' pattern: ^doc_[1-9][0-9]*$ description: >- Na versão anterior de uma troca de arquivo, o id do documento atual. O documento atual é o último documento da cadeia de trocas. Nos outros documentos, o valor é `null`. examples: - doc_325 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. FieldError: type: object additionalProperties: false required: - field - code - message properties: field: type: string description: O nome do campo com o erro. code: type: string description: O código do erro do campo, em inglês. message: type: string description: A explicação do erro do campo, no idioma da organização. 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 headers: Location: description: O caminho do documento criado. required: true schema: type: string example: /api/v1/documents/doc_325 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 responses: BadRequest: description: >- A API recusou a chamada. O `code` diz o motivo: - `invalid_parameter`: um parâmetro falta ou tem um valor inválido. - `malformed_request`: a API não conseguiu ler a chamada. Exemplos de causa: - o caminho ou a query tem uma codificação inválida; - a query repete um parâmetro em formas diferentes, como `limit=1&limit[]=2`; - o corpo não é um JSON válido; - o endereço do cabeçalho `Client-IP` não está no `X-Forwarded-For`. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - invalid_parameter - malformed_request 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 malformed_request: $ref: '#/components/examples/MalformedRequest' 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' FileTooLarge: description: >- O arquivo passa de 25 MB, ou passa de 10 MB num tipo sem campo de arquivo. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - file_too_large examples: file_too_large: summary: O arquivo passa do tamanho máximo value: type: about:blank title: Content Too Large status: 413 detail: >- O arquivo passa do tamanho máximo. O limite é de 25 MB por arquivo, e de 10 MB para o tipo sem campo de arquivo. code: file_too_large 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 examples: IdempotencyKeyInUse: summary: Outra chamada com o mesmo Idempotency-Key está em curso value: type: about:blank title: Conflict status: 409 detail: >- Outra chamada com este Idempotency-Key ainda está em curso. Espere essa chamada terminar e chame de novo. code: idempotency_key_in_use IdempotencyKeyReused: summary: O Idempotency-Key já atendeu outra chamada value: type: about:blank title: Unprocessable Content status: 422 detail: >- Este Idempotency-Key já atendeu uma chamada com outro conteúdo. Use um valor novo para a chamada nova. code: idempotency_key_reused MalformedRequest: summary: A API não conseguiu ler a chamada value: type: about:blank title: Bad Request status: 400 detail: >- A API não conseguiu ler a chamada. Confira a forma e a codificação do caminho e da query, o JSON do corpo e os cabeçalhos. code: malformed_request 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_`. ````