> ## 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 preencher um slot > 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 anexa o arquivo ao slot vazio de uma coleta aberta, e a leitura começa. A troca do arquivo de um documento que já tem arquivo não existe na v1. A chamada com `file` conta no limite de escritas pagas da chave. ## 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. 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 preencher um slot 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 anexa o arquivo ao slot vazio de uma coleta aberta, e a leitura começa. A troca do arquivo de um documento que já tem arquivo não existe na v1. A chamada com `file` conta no limite de escritas pagas da chave. operationId: updateDocument parameters: - $ref: '#/components/parameters/DocumentId' 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 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 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 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 '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 já tem arquivo ou resposta, e a chamada trouxe `file`. `document_locked`: o documento está aprovado ou descartado, ou a coleta dele não recebe documentos. content: application/problem+json: schema: allOf: - $ref: '#/components/schemas/Problem' - type: object properties: code: enum: - document_has_content - document_locked examples: document_has_content: summary: O documento já tem arquivo value: type: about:blank title: Conflict status: 409 detail: >- O documento já tem arquivo ou resposta. A API só anexa o arquivo ao slot vazio de uma coleta aberta. code: document_has_content '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. content: application/problem+json: schema: anyOf: - $ref: '#/components/schemas/ValidationProblem' - $ref: '#/components/schemas/DocumentUpdateRefusedProblem' 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. '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: 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, 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. 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. 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 - 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. 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, em português. 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 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 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 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_`. ````