Introdução

Bem-vindo à documentação completa da nossa API. Esta API foi desenvolvida para facilitar a integração com nosso sistema de pagamentos e saques utilizando PIX, possibilitando a criação de depósitos e solicitações de saque com callbacks para notificações em tempo real.

URL Base: https://app.suitmoney.com/api

Recursos Disponíveis

Autenticação: Geração de token JWT para acesso seguro aos endpoints
Depósito: Criação de depósitos com geração de QR Code PIX
Saque: Solicitação de saques utilizando chaves PIX e cálculo de taxas
Webhooks: Notificações de callback para informar o status das transações

Autenticação

O endpoint de autenticação permite que os usuários façam login utilizando suas credenciais, recebendo um token JWT que deverá ser enviado no cabeçalho das requisições protegidas.

POST /api/auth/login

Parâmetros

Atributo	Tipo	Descrição
client_id	string	ID do cliente fornecido no cadastro
client_secret	string	Chave secreta do cliente para autenticação

Exemplo de Requisição

{
  "client_id": "seu_cliente_id",
  "client_secret": "seu_cliente_secreto"
}

Resposta de Sucesso

{
  "message": "Authentication successful.",
  "token": "seu_token_jwt",
  "user": {
    "id": 1,
    "name": "Nome do Usuário",
    "email": "email@exemplo.com",
    "client_id": "seu_cliente_id"
  }
}

Depósito

Este endpoint permite criar um depósito e gerar um QR Code PIX para efetuar o pagamento.

POST /api/payments/deposit

Requer autenticação: Authorization: Bearer {token}

Parâmetros

Atributo	Tipo	Descrição
amount	number	Valor do depósito
external_id	string	ID único da transação externa (para controle idempotente)
clientCallbackUrl	string	URL para notificações de status do depósito
payer	object	Dados do pagador

Objeto Payer

Atributo	Tipo	Descrição
name	string	Nome completo do pagador
email	string	Email do pagador
document	string	Documento do pagador (CPF ou CNPJ)

Exemplo de Requisição

{
  "amount": 100.00,
  "external_id": "id_unico_12345",
  "clientCallbackUrl": "https://seuservidor.com/callback",
  "payer": {
    "name": "João da Silva",
    "email": "joao@example.com",
    "document": "12345678901"
  }
}

Resposta de Sucesso

{
  "message": "Deposit created successfully.",
  "qrCodeResponse": {
    "transactionId": "id_da_transacao",
    "status": "PENDING",
    "qrcode": "00020101021226930014br.gov.bcb.pix2571qrcode-h.pix...",
    "amount": 100.00
  }
}

Saque

Este endpoint permite solicitar saque utilizando uma chave PIX, com verificação de saldo, cálculo de taxas e atualização do status da transação.

POST /api/withdrawals/withdraw

Requer autenticação: Authorization: Bearer {token}

Parâmetros

Atributo	Tipo	Descrição
amount	number	Valor do saque
external_id	string	ID único da transação externa
pix_key	string	Chave PIX do destinatário
key_type	string	Tipo da chave (EMAIL, CPF, CNPJ ou PHONE)
description	string	Descrição opcional do saque
clientCallbackUrl	string	URL para notificações de status do saque

Exemplo de Requisição

{
  "amount": 50.00,
  "external_id": "external-12345",
  "pix_key": "exemplo@pix.com",
  "key_type": "EMAIL",
  "description": "Saque referente ao pedido #123",
  "clientCallbackUrl": "https://seuservidor.com/callback"
}

Resposta de Sucesso

{
  "transaction_id": "transaction-67890",
  "status": "PENDING",
  "amount": 50.00,
  "fee": 2.50
}

Webhooks

Os webhooks permitem que seu sistema receba notificações em tempo real sobre atualizações no status das transações (depósito e saque). Utilize a URL de callback (clientCallbackUrl) para receber os updates.

Webhook de Depósito

Payload - Status PENDING

{
  "transaction_id": "id_da_transacao",
  "status": "PENDING",
  "amount": 100.00,
  "type": "Deposit"
}

Payload - Status COMPLETED

{
  "transaction_id": "id_da_transacao",
  "status": "COMPLETED",
  "amount": 100.00,
  "type": "Deposit"
}

Webhook de Saque

Payload - Status PENDING

{
  "transaction_id": "transaction-67890",
  "status": "PENDING",
  "amount": 50.00,
  "type": "Withdraw"
}

Payload - Status COMPLETED

{
  "transaction_id": "transaction-67890",
  "status": "COMPLETED",
  "amount": 50.00,
  "type": "Withdraw"
}

Códigos de Erro

A API utiliza códigos HTTP padrão para indicar o resultado das operações. A seguir, os principais códigos de erro e suas descrições.

200

OK

Requisição processada com sucesso

400

Bad Request

Dados inválidos ou campos obrigatórios ausentes

401

Unauthorized

Credenciais inválidas ou token não enviado

404

Not Found

Recurso não encontrado ou rota incorreta

500

Internal Server Error

Erro no servidor durante o processamento

Exemplo de Resposta de Erro

{
  "error": "Validation failed",
  "message": "Os campos fornecidos são inválidos",
  "details": {
    "amount": ["O campo amount é obrigatório"],
    "payer.email": ["O email deve ser válido"]
  }
}