curl --request POST \
  --url https://app.useqx.com/api/v1/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form contact_id=com_12 \
  --form document_type_id=dtp_31 \
  --form collection_id=col_40

{
  "id": "doc_318",
  "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,
  "number": null,
  "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": 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": null
    },
    {
      "key": "line_items",
      "label": "Itens da Fatura",
      "value": null
    }
  ]
}

Documentos

Enviar um documento

Envia o arquivo de um documento, com o contato e o tipo do documento. Uma chamada leva um arquivo, e o arquivo vira um documento. Sem collection_id, o documento entra na Triagem, como o documento que chega por e-mail. A leitura começa, e o encaixe procura uma coleta para o documento quando a leitura termina. O documento que o encaixe não põe numa coleta espera na Triagem. Com collection_id, o documento ocupa o slot vazio do tipo na coleta, e a leitura começa. Quando todo documento obrigatório da coleta chega, a coleta passa a reviewing, e o QX avisa os operadores. O envio conta no limite de escritas pagas da chave.

POST

documents

curl --request POST \
  --url https://app.useqx.com/api/v1/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form contact_id=com_12 \
  --form document_type_id=dtp_31 \
  --form collection_id=col_40

{
  "id": "doc_318",
  "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,
  "number": null,
  "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": 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": null
    },
    {
      "key": "line_items",
      "label": "Itens da Fatura",
      "value": null
    }
  ]
}

Authorizations

Authorization

string

header

required

A chave de API da organização, no cabeçalho Authorization: Bearer <chave>. A chave começa com qx_.

Headers

Idempotency-Key

string

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.

Required string length: 1 - 255

Body

multipart/form-data

file

required

O arquivo do documento, até 25 MB. O QX aceita PDF, JPEG, PNG, TIFF, TXT, XLS, XLSX e XML. O tipo sem campo de arquivo aceita só PDF, JPEG e PNG, até 10 MB.

document_type_id

string

required

O id do tipo de documento. GET /packs lista os tipos que cada pacote pede.

Example:

"dtp_31"

contact_id

string

O id do contato do documento. Informe o contact_id ou o tax_id, só um dos dois.

Example:

"com_12"

tax_id

string

O CPF ou o CNPJ do contato do documento, com ou sem pontuação. Informe o contact_id ou o tax_id, só um dos dois.

Example:

"12.345.678/0001-95"

collection_id

string

O id de uma coleta aberta do mesmo contato. Sem este campo, o documento entra na Triagem.

Example:

"col_40"

Response

O documento criado, com os campos.

Um documento, com os campos.

string

required

O id do documento.

Pattern: ^doc_[1-9][0-9]*$

Example:

"doc_310"

document_type

object

required

Show child attributes

status

enum<string>

required

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.

Available options:

pending,

uploaded,

approved,

rejected

reading_status

enum<string>

required

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.

Available options:

not_started,

extracting,

enriching,

validating,

complete,

failed,

no_reader

contact

object | null

required

O contato do documento. O valor é null quando o documento não tem contato.

Show child attributes

collection_id

string | null

required

O id da coleta do documento. O valor é null enquanto o documento está na Triagem.

Pattern: ^col_[1-9][0-9]*$

Example:

"col_40"

in_triage

boolean

required

Com true, o documento está na Triagem e ainda não tem coleta.

discarded

boolean

required

Com true, o documento está descartado.

discard_reason

enum<string> | null

required

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.

Available options:

outside_pack,

identical_copy,

superseded,

operator,

null

number

string | null

required

O número impresso que identifica o documento, como o número da fatura. O valor é null antes da leitura.

Example:

"INV-81244/2026"

arrival_channel

enum<string> | null

required

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.

Available options:

email,

portal_upload,

operator_upload,

spreadsheet,

vault,

api,

null

arrived_at

string<date-time> | null

required

A data e a hora da chegada do arquivo, no fuso horário da organização. O valor é null no slot vazio.

files

object[]

required

Os arquivos do documento. No slot vazio, a lista é vazia.

Show child attributes

created_at

string<date-time>

required

A data e a hora da criação, no fuso horário da organização.

Example:

"2026-09-25T10:30:00.000-03:00"

fields

object[]

required

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.

Show child attributes

Primeiros passos

Referência

Enviar um documento

Authorizations

Headers

Body

Response