Configuração

Opções de configuração disponíveis em todos os SDKs.

Parâmetros

Parâmetro	Padrão	Descrição
`clientId`	— (obrigatório)	ID do cliente OAuth2
`clientSecret`	—	Secret para autenticação client_credentials
`privateKey`	—	Chave privada EC P-256 (PEM) para JWT assertion
`kid`	—	Key ID (obrigatório com privateKey)
`baseUrl`	`https://api.signdocs.com.br`	URL base da API
`timeout`	30 segundos	Timeout por requisição HTTP
`maxRetries`	5	Número máximo de tentativas em erros transientes
`scopes`	Todos	Scopes OAuth2 solicitados

Autenticação: informe clientSecret ou privateKey + kid. Nunca ambos.

Ambientes

Ambiente	Base URL	Uso
Produção	`https://api.signdocs.com.br`	Ambiente real
Homologação	`https://api-hml.signdocs.com.br`	Testes e desenvolvimento

Em homologação:

O código OTP é retornado na resposta ao iniciar OTP_CHALLENGE
Verificações biométricas usam thresholds reduzidos
Webhooks podem ser testados sem servidor público

Configuração completa

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

const client = new SignDocsBrasilClient({
  clientId: 'seu_client_id',
  clientSecret: 'seu_client_secret',
  baseUrl: 'https://api-hml.signdocs.com.br',
  timeout: 15_000,     // 15 segundos
  maxRetries: 3,
  scopes: ['transactions:read', 'transactions:write', 'steps:write'],
});

from signdocs_brasil import SignDocsBrasilClient, ClientConfig

client = SignDocsBrasilClient(ClientConfig(
    client_id='seu_client_id',
    client_secret='seu_client_secret',
    base_url='https://api-hml.signdocs.com.br',
    timeout=15000,     # 15 segundos (ms)
    max_retries=3,
    scopes=['transactions:read', 'transactions:write', 'steps:write'],
))

import (
    "time"
    signdocs "github.com/signdocsbrasil/signdocsbrasil-go"
)

client, err := signdocs.NewClient("seu_client_id",
    signdocs.WithClientSecret("seu_client_secret"),
    signdocs.WithBaseURL("https://api-hml.signdocs.com.br"),
    signdocs.WithTimeout(15 * time.Second),
    signdocs.WithMaxRetries(3),
    signdocs.WithScopes("transactions:read", "transactions:write", "steps:write"),
)

import com.signdocsbrasil.api.SignDocsBrasilClient;
import java.time.Duration;
import java.util.List;

SignDocsBrasilClient client = SignDocsBrasilClient.builder()
    .clientId("seu_client_id")
    .clientSecret("seu_client_secret")
    .baseUrl("https://api-hml.signdocs.com.br")
    .timeout(Duration.ofSeconds(15))
    .maxRetries(3)
    .scopes(List.of("transactions:read", "transactions:write", "steps:write"))
    .build();

use SignDocsBrasil\Api\SignDocsBrasilClient;
use SignDocsBrasil\Api\Config;

$client = new SignDocsBrasilClient(new Config(
    clientId: 'seu_client_id',
    clientSecret: 'seu_client_secret',
    baseUrl: 'https://api-hml.signdocs.com.br',
    timeout: 15,       // 15 segundos
    maxRetries: 3,
    scopes: ['transactions:read', 'transactions:write', 'steps:write'],
));

Scopes disponíveis

Scope	Descrição
`transactions:read`	Leitura de transações (list, get)
`transactions:write`	Criação, cancelamento, finalização de transações
`steps:write`	Iniciar e completar etapas de verificação
`evidence:read`	Leitura de evidências
`webhooks:write`	Gerenciamento de webhooks (registrar, listar, deletar, testar)

Por padrão, todos os scopes são solicitados. Restrinja conforme o princípio de menor privilégio.

HTTP Client customizado

Todos os SDKs permitem injetar um HTTP client customizado para proxying, métricas, certificados mTLS ou testes.

const client = new SignDocsBrasilClient({
  clientId: 'seu_client_id',
  clientSecret: 'seu_client_secret',
  httpClient: customFetch,   // qualquer implementação compatível com fetch
});

import requests

session = requests.Session()
session.verify = '/path/to/ca-bundle.crt'

client = SignDocsBrasilClient(ClientConfig(
    client_id='seu_client_id',
    client_secret='seu_client_secret',
    session=session,
))

httpClient := &http.Client{
    Timeout: 20 * time.Second,
    Transport: &http.Transport{
        MaxIdleConns:    10,
        IdleConnTimeout: 30 * time.Second,
    },
}

client, _ := signdocs.NewClient("seu_client_id",
    signdocs.WithClientSecret("seu_client_secret"),
    signdocs.WithHTTPClient(httpClient),
)

java.net.http.HttpClient httpClient = java.net.http.HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(10))
    .build();

SignDocsBrasilClient client = SignDocsBrasilClient.builder()
    .clientId("seu_client_id")
    .clientSecret("seu_client_secret")
    .httpClient(httpClient)
    .build();

use GuzzleHttp\Client as GuzzleClient;

$guzzle = new GuzzleClient(['proxy' => 'http://proxy:8080']);

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

Logging

Todos os SDKs suportam logging opcional de requisições HTTP. São logados apenas: método HTTP, path, status code e duração.

Segurança: Headers de autorização, corpos de request/response, tokens e dados pessoais nunca são logados.

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

const logger: Logger = {
  debug: (msg, ...args) => console.debug(msg, ...args),
  info:  (msg, ...args) => console.info(msg, ...args),
  warn:  (msg, ...args) => console.warn(msg, ...args),
  error: (msg, ...args) => console.error(msg, ...args),
};

const client = new SignDocsBrasilClient({
  clientId: 'seu_client_id',
  clientSecret: 'seu_client_secret',
  logger,
});

import logging

logger = logging.getLogger('signdocs')
logger.setLevel(logging.DEBUG)
logger.addHandler(logging.StreamHandler())

client = SignDocsBrasilClient(ClientConfig(
    client_id='seu_client_id',
    client_secret='seu_client_secret',
    logger=logger,
))

import "log/slog"

client, _ := signdocs.NewClient("seu_client_id",
    signdocs.WithClientSecret("seu_client_secret"),
    signdocs.WithLogger(slog.Default()),
)

import java.util.logging.Logger;

SignDocsBrasilClient client = SignDocsBrasilClient.builder()
    .clientId("seu_client_id")
    .clientSecret("seu_client_secret")
    .logger(Logger.getLogger("signdocs"))
    .build();

Para SLF4J, configure a bridge jul-to-slf4j.

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('signdocs');
$logger->pushHandler(new StreamHandler('php://stdout'));

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

Timeout por requisição

Além do timeout global configurado no client, todas as operações aceitam um timeout individual que sobrescreve o padrão.

// timeout em milissegundos
const tx = await client.transactions.get('tx_123', { timeout: 5000 });

const health = await client.health.check({ timeout: 2000 });

# timeout em milissegundos
tx = client.transactions.get('tx_123', timeout=5000)

health = client.health.check(timeout=2000)

// Go usa context.WithTimeout nativo
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

tx, err := client.Transactions.Get(ctx, "tx_123")

// timeout como java.time.Duration
Transaction tx = client.transactions().get("tx_123", Duration.ofSeconds(5));

HealthCheckResponse health = client.health().check(Duration.ofSeconds(2));

// timeout em segundos
$tx = $client->transactions->get('tx_123', timeout: 5);

$health = $client->health->check(timeout: 2);

Sandbox vs Produção

Característica	Produção	Homologação (Sandbox)
Base URL	`api.signdocs.com.br`	`api-hml.signdocs.com.br`
OTP	Enviado por e-mail/SMS	Retornado na resposta
Biometria	Thresholds de produção	Thresholds reduzidos
Certificados	Validação ICP-Brasil completa	Validação simplificada
Cobrança	Sim	Não
Webhooks	Requer HTTPS público	Aceita HTTP / localhost tunnels