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
Authorization
ApiKey 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[].idimport 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" }]
}| Campo | Descrição |
|---|---|
data.id | Identificador do documento temporário. Use esse valor em files[].id ao criar a operação. Trate como string opaca. |
data.fileName | Nome do arquivo atribuído pela ForSign. Você não precisa dele pra criar a operação. |
data.token | Token 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.totalPages | Nú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-Typemanualmente — sua biblioteca HTTP gera omultipart/form-datacomboundaryautomaticamente.
Erros comuns
| Status | Causa |
|---|---|
400 | Arquivo não é PDF, está corrompido ou protegido por senha. |
400 | Campo file ausente. |
401 | X-Api-Key ausente ou inválida. |
403 | Sem permissão para criar documentos. |