Assinar documento

POST

signer

signature

envelope-sessions

:sessionToken

sign

Assinar documento

curl --request POST \
  --url https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fileUuid": "<string>",
  "liveness": {
    "sessionId": "<string>",
    "captureId": "<string>",
    "verified": true,
    "status": "<string>",
    "failureReason": "<string>",
    "imageBase64": "<string>",
    "payload": {}
  }
}
'

import requests

url = "https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign"

payload = {
    "fileUuid": "<string>",
    "liveness": {
        "sessionId": "<string>",
        "captureId": "<string>",
        "verified": True,
        "status": "<string>",
        "failureReason": "<string>",
        "imageBase64": "<string>",
        "payload": {}
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fileUuid: '<string>',
    liveness: {
      sessionId: '<string>',
      captureId: '<string>',
      verified: true,
      status: '<string>',
      failureReason: '<string>',
      imageBase64: '<string>',
      payload: {}
    }
  })
};

fetch('https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fileUuid' => '<string>',
    'liveness' => [
        'sessionId' => '<string>',
        'captureId' => '<string>',
        'verified' => true,
        'status' => '<string>',
        'failureReason' => '<string>',
        'imageBase64' => '<string>',
        'payload' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign"

	payload := strings.NewReader("{\n  \"fileUuid\": \"<string>\",\n  \"liveness\": {\n    \"sessionId\": \"<string>\",\n    \"captureId\": \"<string>\",\n    \"verified\": true,\n    \"status\": \"<string>\",\n    \"failureReason\": \"<string>\",\n    \"imageBase64\": \"<string>\",\n    \"payload\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fileUuid\": \"<string>\",\n  \"liveness\": {\n    \"sessionId\": \"<string>\",\n    \"captureId\": \"<string>\",\n    \"verified\": true,\n    \"status\": \"<string>\",\n    \"failureReason\": \"<string>\",\n    \"imageBase64\": \"<string>\",\n    \"payload\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fileUuid\": \"<string>\",\n  \"liveness\": {\n    \"sessionId\": \"<string>\",\n    \"captureId\": \"<string>\",\n    \"verified\": true,\n    \"status\": \"<string>\",\n    \"failureReason\": \"<string>\",\n    \"imageBase64\": \"<string>\",\n    \"payload\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

HTTP/1.1 201 Created
Content-Type: application/json

{
  "url": "https://storage.googleapis.com/bucket/signed-550e8400.pdf?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=...",
  "expiresAt": "2025-07-27T16:00:30.000Z"
}

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "statusCode": 409,
  "message": "Envelope already signed"
}

Assina o documento no envelope. O sistema escolhe automaticamente entre PAdES avançado (Lacuna RestPKI, com certificado digital), VIDaaS (certificado em nuvem, se autorizado) ou assinatura eletrônica simples, conforme o resultado das verificações de autenticação (liveness, MFA) e autorização VIDaaS. Autenticação: use apenas o sessionToken na URL. Se o signatário tem uma autorização VIDaaS válida (obtida previamente em /vidaas/authorization*), este endpoint a usa automaticamente — nenhuma chamada separada é necessária.

Parâmetros

string

required

Token da sessão do signatário.

string

required

UUID do arquivo a assinar (obtido em GET /signer/v1/sign/:sessionToken).

object

Dados de verificação de liveness (para PAdES avançado). Opcional, mas recomendado.

Show Propriedades de liveness

string

ID da sessão de liveness.

string

ID da captura (foto/vídeo).

boolean

Se liveness foi verificado com sucesso.

string

Status: APPROVED, REJECTED, etc.

string

Se rejeitado, o motivo.

string

Imagem de liveness em base64 (opcional).

object

Payload adicional da verificação (opcional).

Respostas

string

URL assinada para download do PDF final assinado. Válida por 15 minutos.

string

Timestamp de expiração da URL.

Erros

Veja Autenticação e erros.

400: fileUuid não corresponde ao envelope, arquivo não encontrado.
404: Session token inválido.
410: Session token expirado.
409: Envelope já foi assinado ou está em estado terminal.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "url": "https://storage.googleapis.com/bucket/signed-550e8400.pdf?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=...",
  "expiresAt": "2025-07-27T16:00:30.000Z"
}

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "statusCode": 409,
  "message": "Envelope already signed"
}

Exemplo

curl -X POST "https://api.valid.com/signer/signature/envelope-sessions/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.../sign" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
    "liveness": {
      "sessionId": "liveness-sess-001",
      "captureId": "capture-001",
      "verified": true,
      "status": "APPROVED"
    }
  }'

Fluxo de assinatura

Pré-assinatura: signatário preenche campos pendentes (se houver).
Verificação: sistema valida liveness e/ou MFA.
Escolha de estratégia: se verificação passou → PAdES (avançado); caso contrário → Eletrônica simples.
Congelamento (templates): para envelopes baseados em template, o PDF é renderizado com campos finais antes da assinatura (one-time freeze).
Assinatura: documento é assinado e armazenado.
Finalização: se este for o último signatário, webhook FINISHED é disparado.

Padrões de assinatura

Estratégia	Requisito	Certificado	Caso de uso
PAdES Avançado	Liveness aprovado	Sim (Lacuna RestPKI)	Conformidade regulatória, documentos legais
VIDaaS	Autorização VIDaaS válida	Sim (certificado em nuvem)	Assinatura qualificada, usuário sem smartcard
Eletrônica Simples	MFA aprovado (ou nenhuma verificação)	Não	Fluxos internos, documentos de baixo risco

Relacionado

GET /signer/v1/sign/:sessionToken — obter estado da sessão
POST /signer/v1/sign/:sessionToken/submit — fluxo alternativo para templates (preenche + assina em uma chamada)
GET /signer/v1/sign/:sessionToken/signed-document — obter documento assinado após a assinatura
GET /signer/v1/sign/:sessionToken/vidaas/availability — verificar se o signatário tem certificado VIDaaS disponível
POST /signer/v1/sign/:sessionToken/vidaas/authorization — autorizar signatário no VIDaaS via QR Code ou push

⌘I

Assinar documento

curl --request POST \
  --url https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fileUuid": "<string>",
  "liveness": {
    "sessionId": "<string>",
    "captureId": "<string>",
    "verified": true,
    "status": "<string>",
    "failureReason": "<string>",
    "imageBase64": "<string>",
    "payload": {}
  }
}
'

import requests

url = "https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign"

payload = {
    "fileUuid": "<string>",
    "liveness": {
        "sessionId": "<string>",
        "captureId": "<string>",
        "verified": True,
        "status": "<string>",
        "failureReason": "<string>",
        "imageBase64": "<string>",
        "payload": {}
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fileUuid: '<string>',
    liveness: {
      sessionId: '<string>',
      captureId: '<string>',
      verified: true,
      status: '<string>',
      failureReason: '<string>',
      imageBase64: '<string>',
      payload: {}
    }
  })
};

fetch('https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fileUuid' => '<string>',
    'liveness' => [
        'sessionId' => '<string>',
        'captureId' => '<string>',
        'verified' => true,
        'status' => '<string>',
        'failureReason' => '<string>',
        'imageBase64' => '<string>',
        'payload' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign"

	payload := strings.NewReader("{\n  \"fileUuid\": \"<string>\",\n  \"liveness\": {\n    \"sessionId\": \"<string>\",\n    \"captureId\": \"<string>\",\n    \"verified\": true,\n    \"status\": \"<string>\",\n    \"failureReason\": \"<string>\",\n    \"imageBase64\": \"<string>\",\n    \"payload\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fileUuid\": \"<string>\",\n  \"liveness\": {\n    \"sessionId\": \"<string>\",\n    \"captureId\": \"<string>\",\n    \"verified\": true,\n    \"status\": \"<string>\",\n    \"failureReason\": \"<string>\",\n    \"imageBase64\": \"<string>\",\n    \"payload\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.valid.com/signer/signature/envelope-sessions/:sessionToken/sign")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fileUuid\": \"<string>\",\n  \"liveness\": {\n    \"sessionId\": \"<string>\",\n    \"captureId\": \"<string>\",\n    \"verified\": true,\n    \"status\": \"<string>\",\n    \"failureReason\": \"<string>\",\n    \"imageBase64\": \"<string>\",\n    \"payload\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

HTTP/1.1 201 Created
Content-Type: application/json

{
  "url": "https://storage.googleapis.com/bucket/signed-550e8400.pdf?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=...",
  "expiresAt": "2025-07-27T16:00:30.000Z"
}

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "statusCode": 409,
  "message": "Envelope already signed"
}

Primeiros Passos

Onboarding

Bureau

Liveness

Assinatura Digital

ID Check

Card Check

TrustPass

BPO

Extração Dados

Mensageria

Documentoscopia

Storage

Coleção Postman

Parâmetros

Respostas

Erros

Exemplo

Fluxo de assinatura

Padrões de assinatura

Relacionado

​Parâmetros

​Respostas

​Erros

​Exemplo

​Fluxo de assinatura

​Padrões de assinatura

​Relacionado

Parâmetros

Respostas

Erros

Exemplo

Fluxo de assinatura

Padrões de assinatura

Relacionado