Docs
Operações

Upload de documento

Sobe o PDF que será assinado e devolve um identificador pronto pra usar em files[].id na criação da operação.

Ponto de partida de toda integração. Você envia um PDF via multipart/form-data, o servidor valida e normaliza o arquivo (corrige versão, lê páginas, calcula dimensões), armazena e devolve um id pronto pra ser referenciado em files[].id ao criar a operação.

Aceita somente PDF qualquer outro formato retorna 400.
Múltiplos uploads você pode subir N arquivos antes de criar a operação.
Token de pré-visualização curta duração (2h) pra renderizar as páginas como imagens.
Documentos órfãos expiram se um upload não for referenciado, ele é descartado em lote.

O endpoint não converte formatos. Word, Excel, imagens — converta antes. PDFs protegidos por senha também são rejeitados.

Endpoint

POST
/api/v2/document/upload
X-Api-Key<token>

Token de integracao. Envie no header X-Api-Key.

In: header

Header Parameters

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

curl -X POST "https://example.com/api/v2/document/upload" \  -F file="string"
Empty

Exemplo de requisição

curl -X POST "https://api.forsign.digital/api/v2/document/upload" \
  -H "X-Api-Key: $FORSIGN_API_KEY" \
  -F "file=@./contrato.pdf;type=application/pdf"
import fs from 'node:fs';

const form = new FormData();
form.set(
  'file',
  new Blob([fs.readFileSync('contrato.pdf')], { type: 'application/pdf' }),
  'contrato.pdf',
);

const res = await fetch('https://api.forsign.digital/api/v2/document/upload', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.FORSIGN_API_KEY },
  body: form,
});
const { data } = await res.json();
console.log(data.id); // use em files[].id
import requests

with open("contrato.pdf", "rb") as f:
    r = requests.post(
        "https://api.forsign.digital/api/v2/document/upload",
        headers={"X-Api-Key": api_key},
        files={"file": ("contrato.pdf", f, "application/pdf")},
    )

document_id = r.json()["data"]["id"]
using var content = new MultipartFormDataContent();
using var stream = File.OpenRead("contrato.pdf");
var fileContent = new StreamContent(stream);
fileContent.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
content.Add(fileContent, "file", "contrato.pdf");

var resp = await http.PostAsync("/api/v2/document/upload", content);
var body = await resp.Content.ReadFromJsonAsync<JsonElement>();
var id = body.GetProperty("data").GetProperty("id").GetString();

Resposta de sucesso (200)

{
  "success": true,
  "statusCode": 200,
  "data": {
    "id": "114488ce-8fc6-42c2-9b13-d4233a3ce089",
    "fileName": "114488ce-8fc6-42c2-9b13-d4233a3ce089.pdf",
    "token": "9eI9Z9RSW0ZJnflCzIqjoRwNR3mzfB0slFiPxU9DqLAbd...",
    "imagesDetail": [
      { "page": 1, "originalSize": { "width": 826.39, "height": 1169.44 } },
      { "page": 2, "originalSize": { "width": 826.39, "height": 1169.44 } }
    ],
    "totalPages": 2
  },
  "messages": [{ "value": "Realizado upload com sucesso" }]
}
CampoDescrição
data.idIdentificador do documento temporário. Use esse valor em files[].id ao criar a operação. Trate como string opaca.
data.fileNameNome do arquivo atribuído pela ForSign. Você não precisa dele pra criar a operação.
data.tokenToken de curta duração (24h) pra acessar a renderização PNG das páginas via GET /api/v2/document/temporary/pages/{page}?token=.... Útil pra prévia em UI de posicionamento de campos.
data.imagesDetail[]Para cada página: número (page) e dimensões originais em pontos (width, height). Use pra converter coordenadas X/Y de pixels para % ao posicionar assinaturas.
data.totalPagesNúmero total de páginas do PDF (depois da normalização).

Comportamento e gotchas

  • O PDF é normalizado no upload — versões antigas de PDF são convertidas para uma versão estável. O conteúdo e as assinaturas existentes são preservados (os bytes do arquivo podem mudar).
  • Documentos não referenciados expiram. O upload fica disponível até ser usado em uma operação; uploads que nunca são referenciados são descartados automaticamente após um período.
  • Não defina o Content-Type manualmente — sua biblioteca HTTP gera o multipart/form-data com boundary automaticamente.

Erros comuns

StatusCausa
400Arquivo não é PDF, está corrompido ou protegido por senha.
400Campo file ausente.
401X-Api-Key ausente ou inválida.
403Sem permissão para criar documentos.

Próximo passo

On this page