Sobre o BaaS

Documentação do produto BaaS (Banking as a Service) da Nuvende API v2. Rotas sob /api/v2/baas/....

Contextos de autenticação

Dentro do BaaS existem dois contextos de operação. Não misture tokens nem hmac_secret entre plataforma e conta.

Login: POST /api/v2/auth/login (referência), sem HMAC no pedido. O que muda é o par de credenciais no Basic Auth e os scopes.

Fluxo resumido

Plataforma (onboarding):

1. Login com credenciais do parceiro
2. POST /api/v2/baas/onboardings/proposals (referência)
3. Cadastro PF/PJ na proposta conforme o guia de onboarding
4. POST /api/v2/baas/seller-webhooks para eventos da plataforma (referência)

Conta titular (operação):

1. Login com credenciais da conta
2. Operações em /api/v2/baas/balances, Pix, boletos (sempre com HMAC)
3. POST /api/v2/baas/webhooks para eventos da conta (referência)

Duas áreas do produto BaaS

BaaS/
├── Plataforma BaaS (parceiro)     … você opera o produto como integrador
│   ├── Status
│   ├── Onboarding (propostas, PF, PJ)
│   ├── Webhooks da plataforma       … /baas/seller-webhooks (Nuvende → você)
│   └── Contratos (catálogo)         … GET /baas/contracts
│
└── Conta BaaS (titular)             … você opera a conta que o BaaS criou
    ├── Saldo e extrato
    ├── Chaves Pix, cash-in, cash-out
    ├── Boletos, limites, encerramento
    ├── Contrato da conta
    └── Webhooks da conta            … /baas/webhooks (eventos Pix, etc.)

Regra: webhooks da plataforma (seller-webhooks) ficam com onboarding e contratos. Webhooks da conta (/baas/webhooks) ficam com Pix e saldo. Não intercale os dois grupos na implementação.

Guias por área: Plataforma BaaS · Conta BaaS.

URL e ambiente

Pedidos: {{base_url}}/api/v2/...

Variáveis de ambiente

Use no Postman, Insomnia ou CI:

Detalhe do algoritmo HMAC: Assinatura HMAC.

Scopes BaaS

Scopes são prefixados com baas. e solicitados no login como string separada por espaços.

Plataforma BaaS (parceiro)

baas.onboarding-proposals.read baas.onboarding-proposals.write
baas.onboarding-natural-persons.read baas.onboarding-natural-persons.write
baas.onboarding-legal-persons.read baas.onboarding-legal-persons.write
baas.seller-webhooks.read baas.seller-webhooks.write
baas.contracts.read

Conta BaaS (titular)

Inclua conforme o que for testar:

baas.balances.read baas.statements.read
baas.key-managements.read baas.key-managements.write
baas.pix-payments.write baas.pix-cash-in.read baas.pix-cash-in.write
baas.bankslip-payments.read baas.bankslip-payments.write
baas.charges.bankslips.read baas.charges.bankslips.write
baas.accounts.read baas.accounts.write
baas.contracts.read
baas.webhooks.read baas.webhooks.write

Scope ausente no JWT → 403 no endpoint, mesmo com login 200. Após alterar scopes, faça login de novo.

Guia passo a passo

1. Integração inicial (plataforma BaaS)

Valide conectividade antes do onboarding.

1. Login plataforma, POST /api/v2/auth/login com credenciais do parceiro e scopes da plataforma. Guarde access_token. Ver Autenticação da plataforma BaaS.
2. Configurar hmac_secret no ambiente (valor do onboarding Nuvende).
3. Status, GET /api/v2/baas/status com só Bearer (sem HMAC). Confirma URL e token.
4. GET assinado, ex.: GET /api/v2/baas/onboardings/proposals com Bearer + HMAC. Corpo na assinatura: [].

2. Onboarding de conta

Fluxo stateful: guarde proposalId e personId. Consulte o recurso (GET) antes de cada PATCH.

1. POST proposta → PATCH proposta (pacote completo com senha e OTP) → titular criado.
2. POST PF ou PJ → PATCH com dados, endereço e files[] + accepted_terms_at.
3. Análise assíncrona → conta criada com chave Pix EVP → webhook AccountCredentials.

Guia completo: Onboarding.

3. Webhooks da plataforma

Cadastre antes ou durante o onboarding, para receber credenciais da conta:

POST /api/v2/baas/seller-webhooks com entity: AccountCredentials, event_type: created.

Guia: Webhooks da plataforma.

4. Operação da conta BaaS

Após webhook AccountCredentials:

1. Login com credenciais da conta (Autenticação da conta BaaS).
2. Saldo → Chaves Pix → Cash-in → Cash-out → Boletos → Extrato e limites → Webhooks da conta.

Jornada detalhada: Conta BaaS.

Ordem de teste recomendada

Plataforma BaaS

Login parceiro → hmac_secret → Status → GET assinado (propostas) → onboarding → seller webhooks

Conta BaaS (após AccountCredentials)

Login conta → hmac_secret da conta → Saldo → Chaves → Pix cash-in → Pix cash-out → Extrato

Referência rápida

Mapa de endpoints separado por plataforma e conta: Mapa de endpoints BaaS.

Erros frequentes: Resolução de problemas BaaS.

Próximos passos

1. Autenticação da plataforma BaaS
2. Plataforma BaaS
3. Conta BaaS