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.

Endpoint

POST /api/auth/login

Corpo da Requisição

Envie as seguintes informações:

ATRIBUTO	DESCRIÇÃO	TIPO
client_id	ID do cliente (fornecido no cadastro)	string
client_secret	Chave secreta do cliente para autenticação	string

Exemplo de Requisição

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

Resposta

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

Outros endpoints de autenticação (ex.: /api/auth/token) podem ser utilizados para funcionalidades futuras.

Depósito

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

Endpoint

POST /api/payments/deposit

Autorização

É necessário enviar o token JWT no cabeçalho da requisição (Authorization: Bearer seu_token).

Corpo da Requisição

Envie os seguintes atributos:

ATRIBUTO	DESCRIÇÃO	TIPO
amount	Valor do depósito	number
external_id	ID único da transação externa (para controle idempotente)	string
clientCallbackUrl	URL para notificações de status do depósito	string
payer	Dados do pagador	object

O objeto payer deve conter:

ATRIBUTO	DESCRIÇÃO	TIPO
name	Nome completo do pagador	string
email	Email do pagador	string
document	Documento do pagador (CPF ou CNPJ)	string

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

{
  "message": "Deposit created successfully.",
  "qrCodeResponse": {
    "transactionId": "id_da_transacao",
    "status": "PENDING",
    "qrcode": "codigo_qr_base64",
    "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.

Endpoint

POST /api/withdrawals/withdraw

Autorização

Envie o token JWT no cabeçalho (Authorization: Bearer seu_token).

Corpo da Requisição

Os seguintes atributos devem ser enviados:

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

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

{
  "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.

Exemplo de Payload para Depósito

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

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

Exemplo de Payload para Saque

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

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

Tratamento de Erros

A API utiliza códigos HTTP para indicar o resultado das operações. A seguir, os principais:

• 400 Bad Request: Dados inválidos ou campos obrigatórios ausentes.
• 401 Unauthorized: Credenciais inválidas ou token não enviado.
• 403 Forbidden: Acesso negado (ex.: IP não autorizado ou conta banida).
• 404 Not Found: Recurso não encontrado (rota incorreta ou usuário/carteira inexistente).
• 500 Internal Server Error: Erro no servidor durante o processamento.

O servidor registra os erros e utiliza transações para garantir a integridade dos dados mesmo em caso de falhas.