Integrando a API de assinatura da Rubriq em 5 minutos

A API expõe toda a superfície do produto sob /v1/, autenticada por API key. Base de produção: https://api.rubriq.com.br. Este guia cobre o caminho feliz; a referência completa está em /docs.

1. Autenticação

Toda requisição leva a API key num header. Vale Authorization: Bearer ou x-api-key:

# exporte a chave uma vez no seu shell
export RBQ_KEY=rbq_live_xxxxxxxxxxxxxxxxxxxxxxxx

curl -H "Authorization: Bearer $RBQ_KEY" \
  https://api.rubriq.com.br/v1/assinaturas?limit=5

Respostas seguem sempre o mesmo formato: { "ok": true, "data": { … } } no sucesso e { "ok": false, "error": "…" } no erro. Fique de olho nos códigos: 401 key inválida, 402 plano não cobre a feature, 429 rate-limit (60 req/min) ou cota de assinaturas esgotada.

2. Criar uma assinatura

Envie o PDF em base64 e a lista de signatários pra POST /v1/assinaturas. As posições da assinatura vêm de um templateId (criado na UI ou via API) ou de posicoesOverride explícitas:

curl -X POST https://api.rubriq.com.br/v1/assinaturas \
  -H "Authorization: Bearer $RBQ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documentoNome": "Contrato — Cliente X",
    "documentoBase64": "data:application/pdf;base64,JVBERi0xLjQ...",
    "signatarios": [
      {
        "nome": "Maria Souza",
        "cpf": "12345678909",
        "email": "maria@exemplo.com",
        "whatsapp": "+5511999990001",
        "role": "CONTRATANTE"
      }
    ],
    "templateId": "contrato-cliente",
    "tags": ["vendas", "q3"]
  }'

A Rubriq cria o documento, dispara o convite pra cada signatário (e-mail/WhatsApp) e devolve o id da assinatura. O PDF pode ter até 20 MB. Precisa mandar muitos de uma vez? Use POST /v1/assinaturas/batch (até 100 itens por chamada).

Não fique consultando GET /v1/assinaturas/:id em loop pra saber se assinaram. Registre um webhook e deixe a Rubriq te avisar — é o próximo passo.

3. Registrar um webhook

Diga à Rubriq qual URL chamar e em quais eventos. Os disponíveis são assinatura.criada, assinatura.concluida e assinatura.cancelada:

curl -X POST https://api.rubriq.com.br/v1/webhooks \
  -H "Authorization: Bearer $RBQ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-sistema.com/webhooks/rubriq",
    "eventos": ["assinatura.concluida"]
  }'

A resposta traz um secret — retornado uma única vez. Guarde-o: é com ele que você valida que o webhook veio mesmo da Rubriq.

4. Receber e validar o evento

Quando a assinatura fecha, a Rubriq faz um POST no seu endpoint:

POST /webhooks/rubriq
X-Rubriq-Event: assinatura.concluida
X-Rubriq-Signature: sha256=<hex>

{
  "evento": "assinatura.concluida",
  "em": "2026-07-15T12:34:56Z",
  "dados": { "id": "abc123", "documentoNome": "...", "hashFinal": "..." }
}

Sempre valide a assinatura HMAC antes de confiar no payload — é um HMAC-SHA256 do corpo cru com o seu secret:

// Express — use o corpo BRUTO, antes do JSON.parse
const crypto = require('crypto');

app.post('/webhooks/rubriq',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const esperado = 'sha256=' + crypto
      .createHmac('sha256', process.env.RUBRIQ_WEBHOOK_SECRET)
      .update(req.body)              // Buffer cru
      .digest('hex');

    const recebido = req.headers['x-rubriq-signature'];
    if (!crypto.timingSafeEqual(Buffer.from(recebido), Buffer.from(esperado))) {
      return res.status(401).end();  // assinatura não confere
    }

    const evento = JSON.parse(req.body);
    // ... processe evento.dados ...
    res.status(200).end();           // 2xx = entregue, para o retry
  }
);

5. Baixar o PDF assinado

Com o id do evento, baixe o documento finalizado (com estampa e hash):

curl -H "Authorization: Bearer $RBQ_KEY" \
  https://api.rubriq.com.br/v1/assinaturas/abc123/documento
# => { "pdfBase64": "data:application/pdf;base64,..." }

Adicione ?original=1 se quiser o PDF antes da estampa. Pronto — do upload ao arquivo assinado, sem nenhuma tela intermediária.

Resumo do fluxo

1. Autentique com a API key rbq_live_… (header).
2. Crie a assinatura com POST /v1/assinaturas.
3. Registre um webhook e guarde o secret.
4. Valide o HMAC ao receber assinatura.concluida e responda 2xx.
5. Baixe o PDF assinado por /documento.

Isso cobre a integração básica. Filtros de listagem, templates, lote, códigos de erro e o catálogo de eventos estão todos na documentação da API.