Documentação da API

1. O que é o Finuse Pago?

O Finuse Pago é a melhor infraestrutura internacional de pagamentos com stablecoin. O posicionamento é direto: transformamos stablecoins em infraestrutura financeira utilizável no dia a dia para empresas ou plataformas digitais. Em vez de maquininha, conta bancária e espera de repasse, o comerciante abre o aplicativo, cobra em Pix e recebe em dólar digital.

O fluxo é o mesmo em qualquer operação atendida pela plataforma: o pagador envia um Pix em reais, a venda é reconhecida e a liquidação chega em USDT em segundos, direto na carteira do cliente, totalmente na autocustódia dele. A chave privada nunca sai do titular, e o saldo pode sair de novo por Pix, boleto ou para outra wallet quando ele quiser.

2. O que é a API Finuse Pago?

A API Finuse Pago (Módulo Masters) é uma plataforma multi-tenant de recebíveis digitais, onde cada empresa parceira (chamada de Master Instance) opera com sua própria camada isolada de autenticação, permissões (scopes), webhooks e relatórios.

3. Conceitos & Arquitetura Multi-Tenant Masters

Antes de integrar, é importante entender os 3 pilares da plataforma:

4. Autenticação & Autorização (OAuth2 Client Credentials)

4.1 Visão geral do fluxo de autenticação

Sua aplicação backend                      API Finuse Pago
─────────────────────                      ───────────────
        │                                          │
        │── POST /v1/auth/login ──────────────────▶│
        │   Headers:                                │
        │     X-Master-Key: SUA-MASTER-KEY          │
        │   Body JSON:                              │
        │     { ClientId, ClientSecret }            │
        │                                          │
        │◀── 200 OK + accessToken ─────────────────│
        │        (válido ~4h)                       │
        │                                          │
        │── GET /v1/vendas?take=50 ───────────────▶│
        │   Headers:                                │
        │     X-Master-Key: SUA-MASTER-KEY          │
        │     Authorization: Bearer <token>         │
        │                                          │
        │◀── 200 OK + PagedResponse ───────────────│
        │                                          │

4.2 Endpoint de Login — POST /v1/auth/login

Body (JSON recomendado)

{
  "ClientId": "SUA-CREDENCIAL-CLIENT-ID",
  "ClientSecret": "SUA-CREDENCIAL-CLIENT-SECRET"
}

Alternativa OAuth2 tradicional (snake_case)

{
  "grant_type": "client_credentials",
  "client_id": "SUA-CREDENCIAL-CLIENT-ID",
  "client_secret": "SUA-CREDENCIAL-CLIENT-SECRET"
}

Resposta 200 OK

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 14400,
  "expiresAtUtc": "2026-09-01T23:45:00Z"
}

4.3 Scopes (permissões) suportados pela plataforma

5. Formato do Token JWT

O accessToken retornado no login é um JWT assinado HMAC-SHA256. Claims garantidos:

6. Códigos HTTP e Tratamento de Erros

TODOS os erros de validação/negócio seguem a especificação RFC 7807 ProblemDetails. Sempre inspecione o body JSON em caso de falha.

Exemplo de body de erro 400

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1",
  "title": "Erro de validação",
  "status": 400,
  "detail": "SKU 'plano-mensal' já existe nesta Master",
  "instance": "/v1/produtos",
  "traceId": "00-ea1c105abef731e3512c8d238b7...-00",
  "errors": {
    "sku": ["SKU deve ser único por Master"]
  }
}

7. Paginação

Todos os endpoints de listagem usam o envelope padrão PagedResponse<T>:

{
  "data": [ /* objetos retornados nesta página */ ],
  "totalCount": 350,
  "skip": 0,
  "take": 50,
  "hasMore": true
}

8. Módulo 01 — Vendas

A entidade central da plataforma. Representa uma cobrança a receber do cliente.

8.1 Endpoints disponíveis

8.2 Criar Venda — POST /v1/vendas

Body da requisição

Exemplo de request cURL

curl --request POST \
  --url 'https://api-finuse-pago/v1/vendas' \
  --header 'Content-Type: application/json' \
  --header 'X-Master-Key: SUA-MASTER-KEY' \
  --header 'Authorization: Bearer SEU-JWT-AQUI' \
  --data '{
    "titulo": "Mensalidade Julho/2026",
    "descricao": "Plano Profissional - ref. 07",
    "valorBrl": 299.90,
    "produtoId": 42,
    "clienteId": 7,
    "quantidade": 1,
    "chaveExterna": "pedido-interno-98127"
  }'

Resposta 200 OK (campos do QR Code PIX)

{
  "vendaId": 777,
  "status": "Pendente",
  "criadoEm": "2026-09-01T12:00:00Z",
  "qrCodeEmv": "00020126580014BR.GOV.BCB.PIX0136...",
  "qrCodeBase64Png": "data:image/png;base64,iVBORw0KGgoAAAA...",
  "expiraEm": "2026-09-01T12:15:00Z"
}

8.3 Ciclo de vida — status possíveis de uma Venda

9. Módulo 02 — Produtos

Cataloga SKUs da sua operação (produtos físicos, serviços, planos recorrentes, etc.).

9.1 Campos principais de Produto

10. Módulo 03 — Clientes

CRM interno — cadastra pessoas/empresas compradoras. Tudo isolado por Master.

10.1 Campo chaveExterna (super importante!)

11. Módulo 04 — Webhooks

Webhooks são requisições POST HTTPS ativas que a Finuse envia para a sua aplicação sempre que um evento acontece na sua Master. Use para:

• Atualizar status de pedido no seu ERP em tempo real
• Liberar acesso em plataforma SaaS (após venda.paga)
• Disparar e-mail de comprovante automático

11.1 Eventos disponíveis

11.2 Endpoints de gerenciamento

11.3 Exemplo de body de criação de Subscription

{
  "url": "https://api.seusistema.com/webhooks/finuse-pago",
  "secret": "SUA-SENHA-HMAC-MUITO-FORTE-16-CHARS-MINIMO!!!",
  "eventos": ["venda.criada", "venda.paga", "venda.cancelada"],
  "descricao": "Integracao ERP Principal"
}

• secret = string com mínimo 16 caracteres. Guarde igual guarda Client Secret.
• eventos vazio/omitido = assina TODOS os eventos (*).

11.4 Validando assinatura HMAC (obrigatório!)

Antes de processar QUALQUER webhook no seu backend, valide o header X-Finuse-Signature. Isso garante que a requisição veio da Finuse — não de um atacante forjando eventos falsos.

Headers recebidos pela sua URL

X-Finuse-Signature: sha256=BASE64(HMAC_SHA256(body_JSON, SUA_SECRET))
X-Finuse-Event: venda.paga
X-Finuse-Event-Id: a1b2c3d4-e5f6-1a2b-3c4d-5e6f7a8b9c0d

Pseudocódigo Node.js (TypeScript)

import * as crypto from 'crypto';

function validarAssinatura(
  bodyBrutoString: string,
  headerRecebido: string,
  secret: string
) {
  const [algo, assinaturaBase64] = headerRecebido.split('=', 2);
  if (algo !== 'sha256') throw new Error('Algoritmo inesperado');

  const esperada = crypto
    .createHmac('sha256', secret)
    .update(bodyBrutoString, 'utf8')
    .digest('base64');

  // SEMPRE use timingSafeEqual.
  // Nunca compare strings com '===' (vulnerável a timing attack).
  const ok = crypto.timingSafeEqual(
    Buffer.from(assinaturaBase64),
    Buffer.from(esperada)
  );

  if (!ok) throw new Error('401 Assinatura webhook invalida');
}

11.5 Retry e idempotência

12. Health Check & Monitoramento

13. Swagger UI e OpenAPI por Master

A documentação interativa já vem personalizada para cada Master — ou seja, o Swagger só mostra os endpoints para os quais a sua Master tem scope liberado.

14. Começando Rápido — Checklist de Integração

Use como roteiro para o time de dev da empresa parceira:

15. Suporte e Contato