Preparar assinatura com certificado local

POST

signer

sign

:sessionToken

web-pki

start

Preparar assinatura com certificado local

curl --request POST \
  --url https://api.valid.com/signer/v1/sign/:sessionToken/web-pki/start \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "certificate": "<string>",
  "fileUuid": "<string>"
}
'

import requests

url = "https://api.valid.com/signer/v1/sign/:sessionToken/web-pki/start"

payload = {
    "certificate": "<string>",
    "fileUuid": "<string>"
}
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({certificate: '<string>', fileUuid: '<string>'})
};

fetch('https://api.valid.com/signer/v1/sign/:sessionToken/web-pki/start', 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/v1/sign/:sessionToken/web-pki/start",
  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([
    'certificate' => '<string>',
    'fileUuid' => '<string>'
  ]),
  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/v1/sign/:sessionToken/web-pki/start"

	payload := strings.NewReader("{\n  \"certificate\": \"<string>\",\n  \"fileUuid\": \"<string>\"\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/v1/sign/:sessionToken/web-pki/start")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"certificate\": \"<string>\",\n  \"fileUuid\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.valid.com/signer/v1/sign/:sessionToken/web-pki/start")

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  \"certificate\": \"<string>\",\n  \"fileUuid\": \"<string>\"\n}"

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "certificateHolder": "Maria da Silva Santos",
  "certificateIdentifier": "98765432109",
  "expiresAt": "2025-07-27T15:30:00Z"
}

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "statusCode": 403,
  "message": "Certificate does not belong to signer"
}

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

{
  "statusCode": 409,
  "message": "Not signer's turn or already signed"
}

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "statusCode": 410,
  "message": "Session expired"
}

Prepara a assinatura com um certificado local (A1 ou A3), obtendo um token que o plugin Web PKI do navegador usa para assinar diretamente. A chave privada nunca sai do computador do signatário. Autenticação: use apenas o sessionToken na URL — nenhum header de autenticação é necessário.

Parâmetros

string

required

Token único da sessão do signatário.

string

required

Certificado em formato Base64 (DER ou PEM), lido pelo plugin Web PKI no navegador do signatário.

string

UUID do arquivo a assinar (obtido em GET /signer/v1/sign/:sessionToken). Se omitido, usa o primeiro arquivo do envelope.

Respostas

string

Token opaco usado pelo plugin Web PKI para pki.signWithRestPki({ token, thumbprint }). O plugin envia este token ao RestPKI junto com a assinatura realizada localmente.

string

Nome do titular do certificado.

string

CPF ou CNPJ do titular, só dígitos.

string

Timestamp (ISO 8601) de quando o preparo expira. O signatário precisa assinar antes desse momento.

Erros

Veja Autenticação e erros.

400: Certificado ilegível ou em formato inválido.
403: Certificado não pertence ao signatário (quando o envelope restringe a assinatura).
409: Não é a vez do signatário, ou já assinou este arquivo. Ou preparo anterior ainda ativo.
410: Session token expirado.
502: RestPKI recusou o preparo da assinatura.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "certificateHolder": "Maria da Silva Santos",
  "certificateIdentifier": "98765432109",
  "expiresAt": "2025-07-27T15:30:00Z"
}

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "statusCode": 403,
  "message": "Certificate does not belong to signer"
}

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

{
  "statusCode": 409,
  "message": "Not signer's turn or already signed"
}

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "statusCode": 410,
  "message": "Session expired"
}

Exemplo

curl -X POST "https://api.valid.com/signer/v1/sign/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.../web-pki/start" \
  -H "Content-Type: application/json" \
  -d '{
    "certificate": "MIIDXTCCAkWgAwIBAgIIODUXcDrNpwkwDQYJ...",
    "fileUuid": "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
  }'

Fluxo completo

Obtenha as configurações: GET .../web-pki/settings
Inicialize o plugin no navegador: pki.init({ license })
Liste certificados do computador: pki.listCertificates()
Deixe o signatário escolher um certificado
Leia o certificado: pki.readCertificate(thumbprint) → recebe Base64
Prepare a assinatura (esta chamada): envia o certificado, recebe token
Assine no navegador: pki.signWithRestPki({ token, thumbprint }) → o plugin assina e envia ao RestPKI
Finalize no backend: POST /signer/v1/sign/:sessionToken/sign

Importante

Sem rota de “finish”: o fechamento da assinatura é o POST /signer/v1/sign comum — o sistema detecta automaticamente que há um preparo Web PKI aberto e usa o token do preparo.
Certificado local: a chave privada nunca sai do computador — o plugin assina localmente e só envia a assinatura resultado para o RestPKI.
A1 e A3: ambos são aceitos (A1 instalado no SO, A3 em token/smartcard). Ambos têm o mesmo valor jurídico como assinatura qualificada ICP-Brasil.
Titularidade: se o envelope restringe a assinatura (restrictSigner: true), o CPF/CNPJ do certificado deve ser o do signatário — validação ocorre nesta chamada.
Validade: o certificado é validado duas vezes — no preparo (agora) e no fechamento (porque meia-noite do último dia válido pode passar entre uma e outra).

Relacionado

GET .../web-pki/settings — obter licença e URL do RestPKI
GET /signer/v1/sign/:sessionToken — obter dados da sessão e arquivos
POST /signer/v1/sign/:sessionToken/sign — finalizar a assinatura
GET /signer/v1/sign/:sessionToken/integraicp/clearances — alternativa: certificado em nuvem

⌘I

Preparar assinatura com certificado local

curl --request POST \
  --url https://api.valid.com/signer/v1/sign/:sessionToken/web-pki/start \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "certificate": "<string>",
  "fileUuid": "<string>"
}
'

import requests

url = "https://api.valid.com/signer/v1/sign/:sessionToken/web-pki/start"

payload = {
    "certificate": "<string>",
    "fileUuid": "<string>"
}
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({certificate: '<string>', fileUuid: '<string>'})
};

fetch('https://api.valid.com/signer/v1/sign/:sessionToken/web-pki/start', 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/v1/sign/:sessionToken/web-pki/start",
  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([
    'certificate' => '<string>',
    'fileUuid' => '<string>'
  ]),
  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/v1/sign/:sessionToken/web-pki/start"

	payload := strings.NewReader("{\n  \"certificate\": \"<string>\",\n  \"fileUuid\": \"<string>\"\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/v1/sign/:sessionToken/web-pki/start")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"certificate\": \"<string>\",\n  \"fileUuid\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.valid.com/signer/v1/sign/:sessionToken/web-pki/start")

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  \"certificate\": \"<string>\",\n  \"fileUuid\": \"<string>\"\n}"

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "certificateHolder": "Maria da Silva Santos",
  "certificateIdentifier": "98765432109",
  "expiresAt": "2025-07-27T15:30:00Z"
}

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "statusCode": 403,
  "message": "Certificate does not belong to signer"
}

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

{
  "statusCode": 409,
  "message": "Not signer's turn or already signed"
}

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "statusCode": 410,
  "message": "Session expired"
}

Primeiros Passos

Onboarding

Bureau

Liveness

Assinatura Digital

ID Check

Card Check

TrustPass

BPO

Extração Dados

Mensageria

Documentoscopia

Storage

Coleção Postman

Preparar assinatura com certificado local

Parâmetros

Respostas

Erros

Exemplo

Fluxo completo

Importante

Relacionado

​Parâmetros

​Respostas

​Erros

​Exemplo

​Fluxo completo

​Importante

​Relacionado

Parâmetros

Respostas

Erros

Exemplo

Fluxo completo

Importante

Relacionado