StitsOS API Integration Suite • RESTful Architecture

Documentação Oficial da API StitsSign

Conecte seus sistemas ERP, CRMs ou e-commerces nativamente. Crie contratos automatizados, envie convites via WhatsApp/E-mail e receba confirmações de assinatura em tempo real.

Baixar Coleção Postman (.json)

⚡ Guia Quickstart (Integração em 5 Minutos)

Siga este fluxo simples de 4 passos para realizar a sua primeira assinatura automatizada via API:

PASSO 01
Gerar API Key
Acesse o Painel e crie sua chave secreta stits_live_key ou stits_test_key.
PASSO 02
Cadastrar Cliente
Envie um POST para /api/clients com os dados cadastrais do signatário.
PASSO 03
Disparar Contrato
Envie POST para /api/contracts usando Smart Templates dinâmicos.
PASSO 04
Receber Webhook
Receba a notificação contract.signed assim que o cliente assinar.

1. Visão Geral & Coleção Postman

A API do StitsSign é baseada no padrão REST. Ela utiliza verbos HTTP tradicionais (`GET`, `POST`, `PUT`, `DELETE`), retorna respostas codificadas em formato JSON e utiliza códigos de resposta HTTP padrão.

URL Base (Produção)
https://stitssign.fidycard.com.br/api
Formato dos Dados
Content-Type: application/json (UTF-8)
Coleção Oficial Postman
Download Postman .json

2. Ambientes: Sandbox vs Produção

O StitsSign disponibiliza dois ambientes distintos para garantir a segurança dos testes de integração:

🧪 Ambiente Sandbox (Testes)

Utilize chaves com prefixo stits_test_.... No modo Sandbox:

  • Disparos de E-mail/WhatsApp são simulados em log de teste.
  • Sem cobrança de saldo de assinaturas reais.
  • Ideal para homologação em staging/local.
🚀 Ambiente de Produção (Live)

Utilize chaves com prefixo stits_live_.... No modo Produção:

  • Disparos reais de e-mail e WhatsApp via StitsOS Hub.
  • Registro oficial de validade jurídica e selo de tempo.

3. Autenticação & Chaves de API

Todas as requisições para a API do StitsSign devem conter a sua chave de API secreta informada no cabeçalho `Authorization` HTTP no formato Bearer.

Cabeçalho de Autenticação HTTP:
Authorization: Bearer stits_live_sua_chave_secreta_aqui
Aviso de Segurança Importante: Nunca exponha suas chaves de API secretas no código front-end público (ex: formulários web no navegador). Execute sempre chamadas da API a partir do seu servidor backend seguro.

4. Gestão de Clientes / Signatários

Antes de gerar contratos, você pode cadastrar a entidade do Cliente/Contratante para reutilizar seus dados cadastrais e preenchimento dinâmico de variáveis em modelos.

POST/api/clients• Cadastrar novo cliente

Cria o cadastro do contratante com dados necessários para os termos de assinatura eletrônica.

Cadastrar Cliente
curl -X POST https://stitssign.fidycard.com.br/api/clients \
  -H "Authorization: Bearer stits_live_key_9f8a3b2c1d" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mariana Souza Santos",
    "email": "mariana.souza@email.com",
    "phone": "5511999998888",
    "document": "123.456.789-00",
    "rg": "12.345.678-9",
    "profession": "Engenheira de Software",
    "civilStatus": "Solteira",
    "address": "Av. Paulista, 1000, Apto 42 - São Paulo / SP"
  }'

5. Criação, Gestão & Download de PDF

O endpoint principal de criação de contratos aciona o Motor de Smart Templates do StitsSign (substituindo variáveis dinâmicas), calcula o Hash SHA-256 e dispara notificações via E-mail e WhatsApp.

POST/api/contracts• Criar e disparar contrato
Variáveis Dinâmicas Aceitas no Conteúdo:
{{NOME_CLIENTE}}{{DOCUMENTO_CLIENTE}}{{EMAIL_CLIENTE}}{{RG_CLIENTE}}{{ENDERECO_CLIENTE}}{{DATA_ATUAL}}
Exemplo de Requisição REST - Criar Contrato
curl -X POST https://stitssign.fidycard.com.br/api/contracts \
  -H "Authorization: Bearer stits_live_key_9f8a3b2c1d" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contrato de Prestação de Serviços de TI",
    "clientId": "cl_9812739812",
    "content": "CONTRATO CELEBRADO ENTRE A EMPRESA X E {{NOME_CLIENTE}}, CPF/CNPJ {{DOCUMENTO_CLIENTE}}...",
    "additionalSigners": [
      {
        "name": "Carlos Eduardo",
        "email": "carlos@empresa.com",
        "phone": "5511988887777",
        "role": "Testemunha"
      }
    ]
  }'
GET/api/contracts/:id/pdf• Obter dados e URL de download do PDF Assinado

Retorna os dados completos do documento assinado, Hash SHA-256 e o relatório detalhado da trilha de auditoria para arquivamento no ERP.

Obter Dados de Download do PDF
curl -X GET https://stitssign.fidycard.com.br/api/contracts/cm081239812000001/pdf \
  -H "Authorization: Bearer stits_live_key_9f8a3b2c1d"

6. Assinaturas & Trilha de Auditoria

Quando um usuário assina a página pública (/sign/:token), o StitsSign registra automaticamente os metadados jurídicos exigidos por lei.

Dados Capturados na Trilha de Auditoria:

  • Endereço IP do Signatário
  • Carimbo de Tempo (UTC / Selo de Tempo)
  • Geolocalização (Latitude/Longitude)
  • User-Agent do Navegador & Dispositivo
  • SVG / PNG da Assinatura Manual
  • Criptografia de Hash SHA-256 no PDF

7. Webhooks & Validação de Segurança HMAC

Evite polling na API! Configure seu webhook para receber requisições HTTP POST instantâneas quando um contrato for assinado.

Exemplo de Payload Webhook (contract.signed)
{
  "event": "contract.signed",
  "timestamp": "2026-07-27T04:00:00Z",
  "data": {
    "contractId": "cm081239812000001",
    "title": "Contrato de Prestação de Serviços",
    "hashSHA256": "8f3b2a1e09c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2",
    "status": "COMPLETED",
    "signedAt": "2026-07-27T03:59:45Z",
    "signer": {
      "name": "Mariana Souza Santos",
      "email": "mariana.souza@email.com",
      "ipAddress": "177.135.24.12",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X)",
      "geoCoordinates": "-23.550520, -46.633308"
    },
    "downloadUrl": "https://stitssign.fidycard.com.br/api/contracts/cm081239812000001/pdf"
  }
}

Validação do Cabeçalho X-Stits-Signature (HMAC-SHA256)

Para evitar ataques de falsificação de webhooks, valide a assinatura enviada no cabeçalho X-Stits-Signature comparando-a com o segredo do webhook cadastrado.

Código de Validação de Segurança HMAC-SHA256
import crypto from 'crypto';

// Exemplo em um handler Express.js / Next.js
export function verifyWebhookSignature(reqBodyString, signatureHeader, webhookSecret) {
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(reqBodyString, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expectedSignature)
  );
}

8. SDK Wrappers Leves (Node.js & Python)

Copie estas classes auxiliares leves para integrar o StitsSign na sua aplicação com poucas linhas de código:

SDK Wrapper Class Exemplo
// StitsSign SDK Wrapper Leve
class StitsSign {
  constructor(apiKey, baseUrl = 'https://stitssign.fidycard.com.br/api') {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async request(endpoint, method = 'GET', data = null) {
    const options = {
      method,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      }
    };
    if (data) options.body = JSON.stringify(data);
    const res = await fetch(`${this.baseUrl}${endpoint}`, options);
    return res.json();
  }

  createClient(clientData) { return this.request('/clients', 'POST', clientData); }
  createContract(contractData) { return this.request('/contracts', 'POST', contractData); }
  getContractPdf(contractId) { return this.request(`/contracts/${contractId}/pdf`, 'GET'); }
}

// Uso rápido:
const stits = new StitsSign('stits_live_key_9f8a3b2c1d');
const contract = await stits.createContract({ title: 'Contrato Comercial', clientId: 'cl_123' });

9. Códigos de Status & Rate Limits

Código HTTPStatusDescrição
200 / 201OK / CreatedA requisição foi processada e executada com sucesso.
400Bad RequestParâmetros obrigatórios ausentes ou JSON mal formatado.
401UnauthorizedAPI Key inválida, revogada ou ausente no cabeçalho.
404Not FoundO recurso solicitado (Contrato ou Cliente) não existe.
429Too Many RequestsLimite de taxa excedido (Limite padrão: 100 req/min por API Key).

10. Perguntas Frequentes de Integração (FAQ Técnico)

Qual é a validade jurídica dos documentos assinados via API do StitsSign?

Total validade jurídica em conformidade com a MP 2.200-2/2001 e a Lei 14.063/2020 (Assinatura Eletrônica Avançada). Cada assinatura gera um termo de auditoria contendo o Hash SHA-256, endereço IP, geolocalização, carimbo de tempo UTC e evidências biométricas/desenho.

Qual é a validade padrão (TTL) do link de assinatura enviado aos signatários?

Existe limite de signatários em um único contrato?

O que acontece se a chamada de Webhook falhar no meu servidor?

Como utilizar o ambiente Sandbox de Testes?