Guias de Desenvolvimento

Signing Sessions

Guias dos SDKs

Autenticação

A API SignDocsBrasil suporta dois métodos de autenticação OAuth2 com grant_type=client_credentials:

  1. Client Secret — mais simples, ideal para ambientes server-side
  2. Private Key JWT (ES256) — mais seguro, o secret nunca trafega pela rede

Ambos os métodos retornam um token de acesso que é cacheado automaticamente pelo SDK e renovado 30 segundos antes da expiração.


Passo 1: Instalar o SDK

npm install @signdocs-brasil/api
pip install signdocs-brasil
go get github.com/signdocsbrasil/signdocsbrasil-go
<dependency>
    <groupId>com.signdocsbrasil</groupId>
    <artifactId>signdocsbrasil-api</artifactId>
    <version>1.0.0</version>
</dependency>
composer require signdocs-brasil/signdocs-brasil-php

Passo 2: Autenticar com Client Secret

import { SignDocsBrasilClient } from '@signdocs-brasil/api';

const client = new SignDocsBrasilClient({
  clientId: 'seu_client_id',
  clientSecret: 'seu_client_secret',
});
from signdocs_brasil import SignDocsBrasilClient, ClientConfig

client = SignDocsBrasilClient(ClientConfig(
    client_id='seu_client_id',
    client_secret='seu_client_secret',
))
import signdocs "github.com/signdocsbrasil/signdocsbrasil-go"

client, err := signdocs.NewClient("seu_client_id",
    signdocs.WithClientSecret("seu_client_secret"),
)
if err != nil {
    log.Fatal(err)
}
import com.signdocsbrasil.api.SignDocsBrasilClient;

SignDocsBrasilClient client = SignDocsBrasilClient.builder()
    .clientId("seu_client_id")
    .clientSecret("seu_client_secret")
    .build();
use SignDocsBrasil\Api\SignDocsBrasilClient;
use SignDocsBrasil\Api\Config;

$client = new SignDocsBrasilClient(new Config(
    clientId: 'seu_client_id',
    clientSecret: 'seu_client_secret',
));

Passo 3: Autenticar com Private Key JWT (ES256)

Neste modo o SDK gera um JWT assinado com sua chave privada EC P-256 e o envia como client_assertion na requisição de token. A chave privada nunca sai do seu ambiente.

import { SignDocsBrasilClient } from '@signdocs-brasil/api';
import fs from 'fs';

const privateKey = fs.readFileSync('./private-key.pem', 'utf8');

const client = new SignDocsBrasilClient({
  clientId: 'seu_client_id',
  privateKey,
  kid: 'seu-key-id',
});
from signdocs_brasil import SignDocsBrasilClient, ClientConfig

with open('./private-key.pem') as f:
    key_pem = f.read()

client = SignDocsBrasilClient(ClientConfig(
    client_id='seu_client_id',
    private_key=key_pem,
    kid='seu-key-id',
))
import (
    "os"
    signdocs "github.com/signdocsbrasil/signdocsbrasil-go"
)

pemBytes, err := os.ReadFile("./private-key.pem")
if err != nil {
    log.Fatal(err)
}

key, err := signdocs.ParseES256PrivateKeyFromPEM(pemBytes)
if err != nil {
    log.Fatal(err)
}

client, err := signdocs.NewClient("seu_client_id",
    signdocs.WithPrivateKey(key, "seu-key-id"),
)
import com.signdocsbrasil.api.SignDocsBrasilClient;
import java.nio.file.Files;
import java.nio.file.Path;

String keyPem = Files.readString(Path.of("./private-key.pem"));

SignDocsBrasilClient client = SignDocsBrasilClient.builder()
    .clientId("seu_client_id")
    .privateKey(keyPem)
    .kid("seu-key-id")
    .build();
use SignDocsBrasil\Api\SignDocsBrasilClient;
use SignDocsBrasil\Api\Config;

$keyPem = file_get_contents('./private-key.pem');

$client = new SignDocsBrasilClient(new Config(
    clientId: 'seu_client_id',
    privateKey: $keyPem,
    kid: 'seu-key-id',
));

Scopes Disponíveis

Scope Descrição
transactions:read Leitura de transações
transactions:write Criação, cancelamento e finalização de transações
steps:write Iniciar e completar etapas
evidence:read Leitura de evidências
webhooks:write Gerenciamento de webhooks

Todos os scopes são solicitados por padrão. Para restringir, consulte Configuração.


Caching de Tokens

O SDK gerencia automaticamente o ciclo de vida dos tokens:

Não é necessário gerenciar tokens manualmente.