---
title: "Upload de documento (base64)"
method: POST
path: "/v1/transactions/{transactionId}/document"
tags: ["Documents"]
---

# Upload de documento (base64)

`POST /v1/transactions/{transactionId}/document`

## Request

- Base URL: `https://api.signdocs.com.br`
- URL: `https://api.signdocs.com.br/v1/transactions/{transactionId}/document`
- Auth: HTTP bearer

Envia o documento codificado em base64 diretamente no corpo da requisição. Suporta PDF, DOCX, XLSX, PPTX, ODT, imagens e outros formatos.
Para documentos maiores, utilize o fluxo de upload pré-assinado
(`presign` → upload direto ao S3 → `confirm`).

### Validação de qualidade do PDF

O documento é validado quanto à qualidade e integridade. Caso o PDF seja inválido,
corrompido, protegido por senha ou não atenda aos critérios mínimos de qualidade,
a API retorna `422 Unprocessable Entity` com detalhes do problema.

Requer scope `transactions:write`.

## Path parameters

- `transactionId` string, required

## Request body

- DocumentUploadRequest: Requisição de upload de documento inline (base64). Suporta PDF e outros formatos (DOCX, XLSX, imagens, XML, etc.). Para arquivos não-PDF, o campo `filename` é obrigatório.
  - `content` string, byte, required: Conteúdo do documento codificado em base64.
  - `filename` string: Nome do arquivo com extensão. Obrigatório para documentos não-PDF. Extensões permitidas: .docx, .doc, .xlsx, .xls, .pptx, .ppt, .odt, .ods, .odp, .rtf, .txt, .csv, .jpg, .jpeg, .png, .tiff, .tif, .bmp, .svg, .xml, .json, .html, .pdf

## Response `200`

Documento enviado com sucesso.

- DocumentUploadResponse: Resposta de upload de documento.
  - `transactionId` string, required
  - `documentHash` string, required: Hash SHA-256 do documento.
  - `documentFormat` 'pdf' | 'generic', required: Formato detectado do documento.
  - `status` 'DOCUMENT_UPLOADED', required
  - `uploadedAt` string, date-time, required

## Other responses

- `400`: Requisição inválida — parâmetros ausentes ou malformados.
- `401`: Autenticação ausente ou inválida.
- `403`: Permissões insuficientes para a operação solicitada. Inclui `purpose: "ACTION_AUTHENTICATION"` sem `featureFlags.trustSessionsEnabled`. A verificação é pelo `purpose`, não pela rota: vale em `/v1/transactions`, `/v1/signing-sessions` e `/v1/envelopes/{envelopeId}/sessions`, além de `/v1/trust-sessions`. O remédio é habilitar a flag para o tenant e provisionar a cota `monthlyTrustSessions`.
- `404`: Recurso não encontrado.
- `409`: Conflito de estado — a operação não pode ser realizada no estado atual do recurso.
- `422`: Entidade não processável — a requisição é sintaticamente válida mas semanticamente incorreta. Inclui o perfil de política não autorizado para o tenant. As rotas de criação (`/v1/transactions`, `/v1/signing-sessions` e `/v1/envelopes/{envelopeId}/sessions`) verificam a mesma regra, antes de cota, convite e gravação — a recusa não consome documento. As flags envolvidas são `featureFlags.customPolicyEnabled` (perfil `CUSTOM`), `serpro.enabled` (perfis SERPRO), `featureFlags.documentExtractionEnabled` (fallback por documento; `BIOMETRIC_SERPRO_AUTO_FALLBACK` exige as duas últimas) e `featureFlags.biometricRequired`. O remédio é habilitar a flag para o tenant. `signer.cpf` e `signer.birthDate`, exigidos pelos perfis SERPRO, são validados como **400** e não aqui: requisição malformada, corrigível na mesma chamada.
- `500`: Erro interno do servidor.

---

[API](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api.md) · [All operations](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signdocs/apis/signdocs-brasil-external-api/revisions/2d3805aed161?raw)