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``: .. code-block:: bash # Via API Key curl --location 'https://rubrix.lat/core/api/auth/me' \ --header 'X-Api-Key: ' # Via Bearer Token (JWT) curl --location 'https://rubrix.lat/core/api/auth/me' \ --header 'Authorization: Bearer ' .. 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: .. list-table:: :header-rows: 1 :widths: 20 80 * - 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``): .. list-table:: :header-rows: 1 :widths: 15 85 * - 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.