Governança e autorização patrimonial

A Noviuz não é um banco digital convencional nem um simples aplicativo de ledger: ela opera como um Sistema Operacional Patrimonial (Patrimonial OS).

Enquanto um banco tradicional apenas registra o saldo atual, um OS Patrimonial responde com rastreabilidade auditável:

• Quem possuía legitimidade para agir em nome de qual patrimônio naquela data e hora?
• Com qual autorização e instrumento legal a operação foi fundamentada?
• Qual foi o efeito econômico produzido nos livros contábeis?
• Como retificar ou estornar mantendo a cadeia de custódia imutável?

Para arquitetar integrações robustas e compreender as respostas da API, o desenvolvedor precisa entender os conceitos fundamentais que regem esse ecossistema.

1. Separação de PlanosCopy Anchor Link

No coração do sistema, a arquitetura é estritamente dividida em três planos independentes:

┌────────────────────────────────────────────────────────┐
│ Plano Legal / Evidência                                │
│ Instrumentos jurídicos, contratos, termos de adesão.   │
└───────────────────────────┬────────────────────────────┘
                            │ Fundamenta
                            ▼
┌────────────────────────────────────────────────────────┐
│ Plano Operacional (Autoridade)                         │
│ Mandatos vigentes, capacidade jurídica, permissões.    │
└───────────────────────────┬────────────────────────────┘
                            │ Concede efeito a
                            ▼
┌────────────────────────────────────────────────────────┐
│ Plano Econômico (Ledgers)                              │
│ Position Ledger (onde está o ativo) · IFRS (valor).    │
└────────────────────────────────────────────────────────┘

2. Aplicação de API vs Entidade PatrimonialCopy Anchor Link

Um erro comum em integrações tradicionais é assumir que o token de API (access_token) tem poder absoluto sobre a conta. Na Noviuz, a autorização opera em camadas:

Sua Aplicação (API Token)              Entidade Patrimonial (Entity)
   - Possui escopos técnicos                - Titular soberana da conta
   - Ex: withdrawals:write                  - Possui Mandatos e Capacidade
            │                                             │
            └───────────► [ REGRAS DE GOVERNANÇA ] ◄──────┘
                                     │
                     Ambos precisam estar válidos!
                                     ▼
                          Saque é Autorizado

1. A Aplicação (client_id): Representa o seu sistema de software. O token de acesso concedido a ela possui escopos (ex: accounts:read, pix:write, withdrawals:write), que definem o teto técnico da conexão.
2. A Entidade (Entity): Representa a pessoa física ou jurídica proprietária dos ativos e titular da conta bancária.
3. Checagem de Capacidade (Fail-Closed): Ao solicitar uma operação crítica (como um saque via POST /api/public/v1/withdrawals), a plataforma verifica primeiro se a Entidade possui capacidade jurídica ativa e mandatos sem impedimentos. Se a capacidade for insuficiente ou estiver sob revisão, o saque é bloqueado imediatamente, mesmo que a sua aplicação possua o escopo withdrawals:write.

3. O que é o EUID (Entity Unique Identifier)?Copy Anchor Link

Durante o fluxo de verificação de identidade (KYC), ao atingir o estado approved, a resposta do servidor retorna um identificador chamado euid:

{
  "status": "approved",
  "sessionId": "ses_0192a8b3-...",
  "euid": "euid_0192a8b4-8f12-7000-a1b2-c3d4e5f6a7b8"
}

Características do EUIDCopy Anchor Link

• Identidade Canônica e Soberana: O EUID é o identificador único gerado pela plataforma Noviuz após corroborar documentos oficiais, conformidade cadastral e biometria facial.
• Imutável e Não Repetível: O EUID não muda se o usuário alterar telefone, endereço ou e-mail. Ele representa a pessoa (física ou jurídica) perante o sistema patrimonial.
• Vínculo Entre Sistemas: O EUID é a chave que conecta o cadastro do usuário no seu banco de dados interno aos ativos e contas vinculadas na Noviuz.

Recomendação de Modelagem no ParceiroCopy Anchor Link

-- Exemplo de modelagem recomendada na sua base de dados
ALTER TABLE users ADD COLUMN noviuz_euid VARCHAR(64) UNIQUE;
CREATE INDEX idx_users_noviuz_euid ON users(noviuz_euid);

Armazene o euid na tabela de usuários ou clientes do seu sistema. Ao emitir novas cobranças ou associar contas, utilize o EUID como referência da entidade corroborada.

4. Garantias Arquiteturais e Regras de NegócioCopy Anchor Link

Para garantir rigor contábil e conformidade regulatória (BACEN, CVM, Lei 13.810 e LGPD), a API pública aplica regras estritas:

1. Valores Monetários são Strings Decimais:
   • A API nunca aceita e nunca retorna números em ponto flutuante (float). Todo valor financeiro é uma string decimal com no máximo duas casas decimais (ex: "150.50"). O uso de float em sistemas financeiros introduz erros de arredondamento inaceitáveis.
2. Histórico Imutável e Auditável (Append-Only):
   • Fatos financeiros nunca são alterados ou apagados. Um estorno, falha de saque ou cancelamento gera um novo evento corretivo. A história da conta é estritamente reproduzível.
3. Isolamento e Ocultação Fail-Closed:
   • Consultar uma conta, cobrança ou saque que não pertença à sua aplicação responde invariavelmente 404 OBJECT_NOT_FOUND. O sistema oculta a existência do recurso para evitar ataques de enumeração de dados de terceiros.
4. Idempotência Financeira Obrigatória:
   • Toda criação financeira exige o campo code (string única de até 80 caracteres). Reenviar uma requisição idêntica com o mesmo code após timeout de rede responde 200 OK devolvendo o registro já existente, garantindo que nenhum pagamento ou saque seja duplicado.