Introdução

Bem-vindo à documentação da API Rubrix.

Nossa plataforma permite a orquestração completa de assinaturas digitais e eletrônicas, oferecendo suporte a algoritmos clássicos (RSA) e pós-quânticos (PQC — ML-DSA). A API está dividida nos seguintes módulos:

  1. Fluxos (Flow) — Orquestração de múltiplos signatários com ordens de prioridade, quórum e notificações automáticas por e-mail.

  2. Assinatura Direta (Sign) — Assinatura de documentos sob demanda utilizando sessões temporárias, sem necessidade de fluxo persistente.

  3. Verificação (Verify) — Validação de integridade e conformidade de assinaturas em documentos PDF e XML.

Conceitos Principais

Tenants e Usuários

O Rubrix opera em um modelo multi-tenant. Cada organização possui um tenant que isola seus dados, fluxos e configurações.

  • Para criar um novo tenant, entre em contato com a equipe Rubrix. Ao registrar o tenant, você receberá acesso como Owner.

  • O gerenciamento de usuários (convites, atribuição de papéis e remoção) é feito pela interface web do Rubrix. Papéis disponíveis: OWNER, ADMIN, USER.

  • Um usuário pode pertencer a mais de um tenant e alternar entre eles via POST /auth/switch-tenant.

Autenticação

A API oferece dois mecanismos de autenticação:

  • Bearer Token (JWT) — Obtido via POST /auth/login. O token deve ser enviado no header Authorization: Bearer {token}. Possui tempo de expiração configurável (campo expires_in na resposta).

  • API Key — Criada via POST /api-keys. Deve ser enviada no header X-Api-Key: {apiKey}. Ideal para integrações de aplicação e automações. Não expira (a menos que uma data de expiração seja definida na criação).

Ambos os métodos são intercambiáveis — qualquer endpoint autenticado aceita tanto o JWT quanto a API Key.

Para testar se a autenticação está funcionando, utilize o endpoint GET /auth/me:

# Via API Key
curl --location 'https://rubrix.lat/core/api/auth/me' \
  --header 'X-Api-Key: <SUA_API_KEY>'

# Via Bearer Token (JWT)
curl --location 'https://rubrix.lat/core/api/auth/me' \
  --header 'Authorization: Bearer <SEU_TOKEN>'

Important

Todos os endpoints dos módulos de Flow e API Keys exigem autenticação (JWT ou API Key). Os endpoints do módulo de Assinatura Direta (/provider/init, /sign/ready, /sign) não exigem autenticação no momento.

Tipos de Assinatura

O Rubrix suporta os seguintes tipos de assinatura digital:

Tipo

Descrição

QUALIFIED

Assinatura qualificada (certificado ICP-Brasil A1/A3). Maior valor jurídico.

ADVANCED

Assinatura avançada (certificado em nuvem com identificação forte do signatário).

SIMPLE

Assinatura simples/eletrônica.

Perfis de Política de Assinatura

Ao assinar, é possível especificar o perfil de política (campo policyProfile):

Perfil

Descrição

B-B

Assinatura básica. Contém apenas o hash e a assinatura.

B-T

Inclui carimbo de tempo (timestamp) confiável.

B-LT

Inclui dados para validação de longo prazo (certificados e CRLs).

B-LTA

Inclui carimbo de tempo de arquivamento para validade estendida.

Provedores

A plataforma integra com diversos provedores de identidade digital:

  • INTEGRAICP — Certificados ICP-Brasil (A1/A3).

  • PIXSIGN — Certificado efêmero emitido via pagamento Pix.

  • GOLDID — Provedor de identidade digital.

  • SAFEWEB — Provedor de certificados.

  • SERPRO — Provedor governamental.

Fluxo de Assinatura via Flow

  1. O cliente inicia o fluxo via POST /flow/init, enviando o documento em Base64 e a lista de pools de signatários.

  2. A API retorna um flowId, o status WAITING e os links de assinatura para os signatários da prioridade atual.

  3. O sistema notifica os signatários por e-mail automaticamente.

  4. Qualquer pessoa com o link de assinatura pode acessar o fluxo e assinar.

  5. À medida que cada signatário assina (via POST /flow/sign), o status é atualizado e o próximo pool é ativado.

  6. Após a conclusão de todas as assinaturas exigidas, a API envia um POST para a URL de webhook configurada, contendo o documento final assinado.

Note

O webhook recebe o binário do arquivo assinado com Content-Type: application/pdf (ou application/xml) e o header X-Flow-Id com o identificador do fluxo.

Fluxo de Assinatura Direta

A assinatura direta permite assinar um documento imediatamente, sem criar um fluxo persistente. O processo envolve iniciar uma sessão, autorizar a identidade e então assinar.

  1. Descobrir identidades — O cliente envia o CPF ou CNPJ e o país (BR) via POST /provider/init. A API retorna um array de identidades disponíveis, cada uma contendo um sessionId e um identityEndpoint.

  2. Autorizar a identidade — O usuário escolhe uma das identidades retornadas e realiza a autorização:

    • Via OAuth: Utiliza o identityEndpoint retornado para autenticar-se no provedor de certificado digital.

    • Via Pix: Utiliza GET /pix/init/{sessionId} para gerar a cobrança e GET /pix/copiaCola/{sessionId} para obter o código Pix Copia e Cola. Ao efetuar o pagamento, o certificado efêmero é emitido automaticamente.

  3. Aguardar sessão pronta — A aplicação monitora o status via GET /sign/ready?sessionId={id}. A sessão só estará pronta (ready: true) após a conclusão bem-sucedida da autorização (OAuth ou pagamento Pix).

  4. Assinar — Com ready: true, o documento é enviado para POST /sign junto com o sessionId, e o binário assinado é retornado imediatamente na resposta.