Documentação da API Rubriq

API REST pra integrar o Rubriq em sistemas externos. Crie assinaturas, templates, contatos e webhooks. Toda a superfície da plataforma fica sob /v1/, autenticada por API key.

Visão geral em 3 minutos

1. Gere uma API key no painel da Rubriq (planos Pro e Business).
2. Crie templates de assinatura (posições de cada signatário no PDF) — opcional, mas acelera.
3. Faça POST /v1/assinaturas com o PDF em base64 + lista de signatários.
4. Configure um webhook pra receber assinatura.concluida quando todos assinarem.
5. Baixe o PDF final selado pelo GET /v1/assinaturas/:id/documento.

Autenticação

A API /v1/ exige uma API key (prefixo rbq_live_…). Gere/gerencie em Acesso API dentro do painel (disponível nos planos Pro e Business). Você pode mandar a key em qualquer um destes headers:

Authorization: Bearer rbq_live_xxxxxxxxxxxxxxxxxxxxxxxx
# ou
x-api-key: rbq_live_xxxxxxxxxxxxxxxxxxxxxxxx

A key é validada a cada requisição. Verificamos que a organização está ativa, que o plano tem a feature api_access, e atualizamos o contador de uso pra rate-limit.

Boas práticas

• Nunca exponha a key no front-end. Trate como senha.
• Use uma key por integração — facilita revogar uma sem derrubar as outras.
• Roteie chamadas pelo servidor (não direto do browser do usuário).

Formato de resposta

Toda resposta é JSON com a forma { "ok": boolean, ... }.

Sucesso

{
  "ok": true,
  "data": { ... }
}

Erro

{
  "ok": false,
  "error": "Mensagem amigável",
  "code": "quota_exceeded"
}

Códigos HTTP típicos

Rate limit & cotas

• Rate limit: 60 requisições/min por API key. Headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset em toda resposta (padrão IETF draft-7 — sem prefixo X-).
• Cota de assinaturas: definida pelo plano (Pro 20/50/100, Business ilimitado). Estouro: 429 quota_exceeded.
• Cota de IA: Free = 5 usos/mês; Pro/Business = ilimitado. Endpoints de IA retornam 402 ia_quota_exceeded.
• Tamanho do PDF: 20 MB.
• Batch: 100 itens por requisição.

Convenções

Datas

Todas as datas/horas seguem ISO 8601 com timezone: 2026-12-31T23:59:59Z ou 2026-12-31T20:59:59-03:00.

CPF / CNPJ / WhatsApp

Aceitamos com ou sem máscara. Internamente normalizamos pra só dígitos. WhatsApp em formato E.164 com + (+5511999990000).

Posicionamento de assinatura

Coordenadas x e y em % da página (0–100). A âncora é a base-centro: a base do rabisco encosta na linha y%.

IDs

IDs de assinatura, template, pasta, contato são strings opacas. Não tente parsear/inferir significado.

Cria uma assinatura. O PDF entra em base64 (até 20 MB). Os signatários recebem o convite por e-mail e/ou WhatsApp automaticamente.

Body

Schema do signatário

Schema de posição

Exemplo de requisição

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,JVBERi0xLjQK...",
    "signatarios": [
      {
        "nome": "Maria Souza",
        "cpf": "12345678909",
        "whatsapp": "+5511999990001",
        "email": "maria@x.com",
        "role": "CONTRATANTE"
      }
    ],
    "templateId": "contrato-cliente",
    "tags": ["vendas", "q1"]
  }'

Resposta de sucesso

{
  "ok": true,
  "data": {
    "id": "abc123",
    "orgId": "org-x",
    "templateId": "contrato-cliente",
    "totalPaginas": 3,
    "posicoesDetectadas": 2,
    "signatarios": [
      {
        "nome": "Maria Souza", "cpf": "12345678909",
        "whatsapp": "+5511999990001", "email": "maria@x.com",
        "role": "CONTRATANTE", "token": "…", "totalPosicoes": 1
      }
    ]
  }
}

signatarios[].token é a credencial do link de assinatura desta pessoa neste documento (o Rubriq já convida por e-mail/WhatsApp automaticamente — o token só importa se você quiser montar seu próprio link/notificação). Trate como uma senha: quem tem o token assina no lugar da pessoa. Fale com o suporte se precisar do formato exato do link.

Erros comuns

Query params

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

Retorna metadados completos da assinatura, incluindo lista de signatários (sem o token opaco do signer).

Query params

Resposta

{
  "ok": true,
  "data": {
    "id": "abc123",
    "documentoNome": "Contrato — Cliente X",
    "status": "ASSINADO",
    "metodoAutenticacao": "qualquer",
    "icpBrasilSelado": false,
    "totalSignatarios": 1,
    "assinados": 1,
    "criadoEm": "2026-05-23T18:00:00Z",
    "assinadoEm": "2026-05-23T19:42:11Z",
    "hashFinal": "ff29dfd84ca10b29c3d8c35ea94eb3ba…",
    "tags": ["vendas", "q1"],
    "pastaId": "pasta-a",
    "envelope": { "id": "6743a949-...", "nome": "Contratação Maria", "total": 2, "indice": 1 },
    "signatarios": [
      {
        "nome": "Maria Souza",
        "cpf": "12345678909",
        "role": "CONTRATANTE",
        "email": "maria@x.com",
        "assinadoEm": "2026-05-23T19:42:11Z",
        "ip": "200.x.x.x",
        "userAgent": "Mozilla/5.0…",
        "assinaturaTipo": "icp_brasil",
        "icpBrasil": {
          "cn": "MARIA SOUZA",
          "ac": "AC SOLUTI Multipla v5",
          "tipo": "PF",
          "numeroSerie": "0x9c6b…",
          "validadeFim": "2027-04-17T23:59:59Z"
        }
      }
    ]
  }
}

envelope só aparece quando o documento faz parte de um envio agrupado (ver Batch) — total é quantos documentos tem o envio, indice a posição deste (a partir de 1).

Endpoint dedicado pra trilha de auditoria completa — todos os eventos no ciclo de vida da assinatura, com IP, user agent e detalhes específicos por tipo. Ideal pra integradores que exibem a timeline forense pro cliente final.

Tipos de evento

Resposta

{
  "ok": true,
  "data": {
    "total": 6,
    "eventos": [
      { "tipo": "criada", "timestamp": "2026-05-23T18:00:00Z",
        "usuario": { "uid": "abc", "email": "voce@empresa.com" },
        "detalhes": { "totalSignatarios": 1, "templateId": "contrato" } },
      { "tipo": "aberto", "timestamp": "2026-05-23T19:30:11Z",
        "signatarioIdx": 0, "ip": "200.x.x.x", "userAgent": "Mozilla/5.0…" },
      { "tipo": "otp_email_solicitado", "timestamp": "2026-05-23T19:31:05Z",
        "signatarioIdx": 0, "ip": "200.x.x.x" },
      { "tipo": "assinado_icp", "timestamp": "2026-05-23T19:42:11Z",
        "signatarioIdx": 0, "ip": "200.x.x.x", "userAgent": "Mozilla/5.0…",
        "detalhes": { "ac": "AC SOLUTI…", "numeroSerie": "0x9c6b…",
                      "hashCertHex": "abc123…" } },
      { "tipo": "finalizado", "timestamp": "2026-05-23T19:42:13Z",
        "detalhes": { "hashFinal": "ff29dfd…", "icpBrasil": true } }
    ]
  }
}

Por padrão devolve o PDF como stream binário (Content-Type: application/pdf) — pode ser usado direto em <iframe src>, <a download> ou range requests.

Query params

Headers de resposta (binário)

HTTP/2 200
Content-Type: application/pdf
Content-Disposition: inline; filename="Contrato - ASSINADO.pdf"
Cache-Control: private, max-age=300
Content-Length: 158234

<binário do PDF>

Sem assinatura concluída → 409. Use ?original=1 pra baixar antes de assinar.

Devolve URL assinada temporária do PDF no Cloud Storage. O client pode usar pra download direto (sem proxy via Rubriq), range requests nativas e UX mais leve.

Query params

Resposta

{
  "ok": true,
  "data": {
    "pdfUrl": "https://storage.googleapis.com/rubriq-saas.firebasestorage.app/organizations/.../assinado.pdf?X-Goog-Algorithm=...&X-Goog-Signature=...",
    "expiresAt": "2026-05-23T18:45:00Z"
  }
}

Cria várias assinaturas de uma vez. Máximo 100 itens por requisição.

{
  "items": [
    {
      "documentoNome": "Contrato A",
      "documentoBase64": "data:application/pdf;base64,...",
      "templateId": "contrato",
      "signatarios": [ { "nome": "Maria", ... } ]
    }
  ],
  "signatariosPadrao": [ { "nome": "Maria", ... } ],
  "envelopeNome": "Contratação Maria",
  "anexos": [
    { "documentoNome": "Regulamento interno", "documentoBase64": "data:application/pdf;base64,..." }
  ]
}

signatariosPadrao é usado quando o item não traz signatarios.

Resposta

{
  "ok": true,
  "data": {
    "total": 50,
    "criados": 48,
    "resultados": [
      { "ok": true, "id": "...", "documentoNome": "..." },
      { "ok": false, "error": "...", "documentoNome": "..." }
    ],
    "envelopeId": "6743a949-...",
    "anexos": 1
  }
}

envelopeId sai null quando só 1 peça foi enviada (sem envelope). anexos (contagem) só aparece quando existe envelope. Com envelopeId, GET /v1/assinaturas/:id (ver acima) passa a trazer envelope: { id, nome, total, indice } em cada documento do envio.

Devolve o link de assinatura de cada pessoa do envelope. Útil se você quer entregar o link pelo seu próprio canal (WhatsApp/e-mail/sistema interno) em vez de depender do convite automático do Rubriq.

Resposta

{
  "ok": true,
  "data": {
    "envelopeId": "6743a949-...",
    "envelopeNome": "Contratação Maria",
    "total": 2,
    "links": [
      {
        "nome": "Maria Souza",
        "email": "maria@x.com", "cpf": null, "whatsapp": null,
        "url": "https://assinar.rubriq.com.br/envelope/<token>"
      }
    ]
  }
}

links tem um item por pessoa (não por documento) — a mesma pessoa assina os N documentos do envio por esse link único. nome é melhor esforço (cruzado pelo e-mail com os documentos do envio; pode vir null). Trate url com o mesmo cuidado de uma senha: quem abre o link assina no lugar da pessoa. envelopeId de outra conta (ou inexistente) devolve 404, nunca dados de outra pessoa.

Recebe 1 PDF com N páginas + lista de N signatários alinhada por ordem de página. Gera N assinaturas, uma com cada página.

{
  "documentoBase64": "data:application/pdf;base64,...",
  "nomePadrao": "Holerite Out/2026",
  "signatarios": [
    { "nome": "André", "cpf": "...", "whatsapp": "...", "email": "...", "role": "FUNCIONARIO" }
  ],
  "templateId": "holerite-padrao"
}

Ciclo de vida

Por signatário

Reenvia o e-mail de convite ao signatário pendente.

Assinatura server-side. Pra integrações que coletam o rabisco no próprio sistema externo.

Atenção: envie ip e userAgent do navegador do signatário no body — sem eles, o carimbo de auditoria registra só o IP do seu servidor (que chamou a API), não o IP probatório do cliente final.

{
  "rabiscoBase64": "data:image/png;base64,iVBORw0KGgo...",
  "rabiscoRubricaBase64": "data:image/png;base64,iVBORw0KGgo...",
  "ip": "200.207.10.42",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ..."
}

rabiscoRubricaBase64 é opcional — só quando o documento tem posições de rubrica além da assinatura completa.

Detecção de template em duas camadas:

1. Nome do arquivo — grátis, sem IA, sem custo de cota.
2. Conteúdo do PDF (só se o nome não decidiu e você passou storagePath) — a IA lê o documento e compara com o perfil semântico de cada template. Consome 1 uso de cota de IA; sem cota, sem IA configurada no Rubriq, ou com falha, cai de volta pro resultado da camada 1 sem erro — reconhecer template é conveniência, nunca bloqueia o envio.

{ "documentoNome": "Termo de Confidencialidade - Empresa XPTO.pdf" }

Resposta

{
  "ok": true,
  "data": {
    "templateId": "nda",
    "nomeTemplate": "NDA",
    "via": "conteudo",
    "aplicar": true,
    "confianca": "alta",
    "motivo": "é um acordo de confidencialidade"
  }
}

data: null quando nada casou. via é "nome" ou "conteudo"; confianca é "alta", "media" ou "baixa".

IA lê o PDF e devolve: nome sugerido, problemas de ortografia, qual template casa.

{ "documentoBase64": "data:application/pdf;base64,..." }

IA propõe nome a partir do conteúdo do PDF.

IA lê o CPF de cada página do PDF e devolve pareamento com contatos cadastrados. Atalho perfeito antes de chamar split-enviar.

Análise jurídica do documento: resumo, pontos-chave, datas, riscos.

Listar / detalhar

• GET /v1/templates — lista resumida.
• GET /v1/templates/uso — { usado, limite, plano }.
• GET /v1/templates/:id — detalhe com posições.

Criar / atualizar

• POST /v1/templates
• PUT /v1/templates/:id
• DELETE /v1/templates/:id

Body

{
  "templateId": "holerite",
  "nomeTemplate": "Holerite Mensal",
  "totalPaginas": 1,
  "palavrasChave": ["holerite", "salário"],
  "posicoes": [
    {
      "pagina": 1,
      "x": 50, "y": 90,
      "tipo": "assinatura",
      "signatarioRole": "FUNCIONARIO"
    }
  ],
  "resumoIA": "Recibo mensal de pagamento do funcionário, com descontos e valor líquido.",
  "tipoDocumento": "holerite_pagamento",
  "aliases": ["holerite", "recibo de pagamento", "contracheque"],
  "entidades": ["salário bruto", "descontos", "valor líquido"]
}

resumoIA/tipoDocumento/aliases/entidades são o perfil semântico (o que o documento é) — opcionais, usados pela detecção por conteúdo. Sem eles, o template só entra na camada 1 (nome do arquivo).

palavrasChave só serve pro caminho rápido (nome do arquivo) — prefira termos discriminantes (siglas, número de norma, nome próprio do documento) em vez de termos genéricos do seu ramo, que empatam entre templates parecidos em vez de decidir.

IA lê um PDF modelo e propõe { nome, identificador, palavrasChave[], papeis[], resumoIA, tipoDocumento, aliases[], entidades[] }. Os 4 últimos campos são o perfil semântico acima — mande-os direto no POST/PUT pra o template já nascer com o perfil.

Pastas

Contatos

Retorna o uso atual da sua organização: plano, cota de assinaturas, créditos, cota de IA.

{
  "ok": true,
  "data": {
    "plano": "business",
    "assinaturas": { "usado": 142, "limite": null },
    "creditos": 0,
    "ia": { "ilimitado": true, "limite": null, "usado": 87, "restante": null },
    "periodoStart": "2026-05-01T00:00:00Z",
    "periodoFimEstimado": "2026-06-01T00:00:00Z",
    "subscription": {
      "status": "active",
      "ciclo": "mensal",
      "currentPeriodEnd": "2026-06-01T00:00:00Z",
      "cancelAtPeriodEnd": false
    },
    "planoSource": "paid",
    "grantedBy": null
  }
}

subscription.status é o estado da assinatura Stripe (active|trialing|past_due|canceled); planoSource distingue plano pago (paid) de cortesia/gratuito; grantedBy marca origem de cortesia (ex.: parceria), quando houver.

Configuração

Webhooks notificam seu sistema quando algo acontece (assinatura criada, concluída, cancelada). É o caminho recomendado pra integração assíncrona — evita polling.

Eventos disponíveis

Payload

Rubriq faz POST application/json pro seu endpoint:

POST /seu-endpoint HTTP/1.1
Content-Type: application/json
X-Rubriq-Event: assinatura.concluida
X-Rubriq-Delivery: 8e6a2bb0-9e1b-4cf9-a4f7-23d0aabd55c1
X-Rubriq-Signature: sha256=ff29dfd84ca10b29c3d8c35ea94eb3ba…

{
  "evento": "assinatura.concluida",
  "em": "2026-05-23T19:42:11Z",
  "dados": {
    "id": "abc123",
    "documentoNome": "Contrato — Cliente X",
    "hashFinal": "ff29dfd84ca10b29c3d8c35ea94eb3ba…",
    "totalSignatarios": 1
  }
}

Validar a assinatura HMAC

X-Rubriq-Signature é HMAC-SHA256 do corpo bruto (antes de qualquer JSON.parse) usando o secret retornado quando você criou o webhook.

const crypto = require('crypto');

function validarWebhook(rawBody, headerSignature, secret) {
  const esperado = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  // crypto.timingSafeEqual previne timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(headerSignature),
    Buffer.from(esperado),
  );
}

// Express
app.post('/webhook-rubriq', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-rubriq-signature'];
  if (!validarWebhook(req.body, sig, process.env.RUBRIQ_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const evento = JSON.parse(req.body.toString());
  // ... processar evento
  res.status(200).end();
});

Retry & entregas

• 3 tentativas in-process com back-off 0s / 2s / 5s.
• Pare confirmando com HTTP 2xx.
• Em qualquer outro status (ou timeout 10s), tentamos de novo.
• Após 3 falhas, o evento vai pro log de entregas com status failed — consultável em /v1/webhooks/entregas.
• Idempotência: garanta no seu lado processar duas vezes o mesmo X-Rubriq-Delivery sem efeito colateral.

Qualquer um pode confirmar que um documento foi assinado no Rubriq batendo nessa URL com o ID — sem API key. Retorna metadados públicos + hash (não expõe dados pessoais completos).

Pra validação criptográfica oficial pela ITI (selo "Assinatura Eletrônica Qualificada"), envie o PDF assinado em validar.iti.gov.br.

Códigos de erro úteis

Exemplo end-to-end

Fluxo completo em Node.js: cria assinatura, recebe webhook, baixa PDF assinado.

// 1) CRIAR ASSINATURA
import fs from 'node:fs';

const pdf = fs.readFileSync('./contrato.pdf').toString('base64');

const criada = await fetch('https://api.rubriq.com.br/v1/assinaturas', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.RBQ_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    documentoNome: 'Contrato — Cliente X',
    documentoBase64: `data:application/pdf;base64,${pdf}`,
    templateId: 'contrato-cliente',
    signatarios: [
      {
        nome: 'Maria Souza',
        cpf: '12345678909',
        whatsapp: '+5511999990001',
        email: 'maria@x.com',
        role: 'CONTRATANTE',
      },
    ],
    tags: ['vendas'],
  }),
}).then((r) => r.json());

console.log('Criada:', criada.data.id);
const id = criada.data.id;


// 2) AGUARDAR WEBHOOK 'assinatura.concluida' (configurado previamente)
//    → seu endpoint recebe POST com { dados: { id, ... } }


// 3) BAIXAR PDF FINAL (no handler do webhook) — resposta é BINÁRIA por
//    padrão; ?formato=base64 mantém o formato { pdfBase64 } se preferir.
const res = await fetch(
  `https://api.rubriq.com.br/v1/assinaturas/${id}/documento`,
  { headers: { Authorization: `Bearer ${process.env.RBQ_KEY}` } },
);
const buffer = Buffer.from(await res.arrayBuffer());
fs.writeFileSync('./contrato-assinado.pdf', buffer);

Changelog