Base URL
| Ambiente | URL |
|---|
| Produção | https://api.pixusglobal.com |
| Staging | https://staging.pixusglobal.com |
O ambiente de Staging está atualmente em manutenção e pode apresentar instabilidades.
Autenticação
Todas as rotas requerem Bearer token no header Authorization:
Authorization: Bearer <token>
Content Negotiation
A API suporta dois formatos de serialização:
| Formato | Content-Type | Accept | Descrição |
|---|
| JSON | application/json | application/json | Padrão, compatível |
| msgpack | application/msgpack | application/msgpack | Binário, mais eficiente |
msgpack é recomendado para integração server-to-server onde performance é prioridade.
Endpoints disponíveis
Cotações
| Método | Rota | Descrição |
|---|
| GET | /client/quote | Gerar cotação de trade |
Cotações expiram em 5 segundos. O quoteId deve ser usado para criar a ordem antes da expiração.
Ordens
| Método | Rota | Descrição |
|---|
| POST | /client/order | Criar ordem de compra |
| GET | /client/orders | Listar ordens com filtros |
| GET | /client/orders/:id | Consultar ordem por ID |
| GET | /client/orders/:id/tracking | Rastrear envio de criptomoedas |
Status das ordens
| Status | Descrição |
|---|
pending | Ordem criada, aguardando pagamento |
partial | Pagamento parcial recebido |
paid | Totalmente paga |
withdrawn | Criptomoedas enviadas para a carteira de destino |
settled | Liquidação completa |
Balanço financeiro
| Método | Rota | Descrição |
|---|
| GET | /client/balance | Consultar resumo financeiro |
- Saldo fiat (BRL) e saldo crypto (USDT)
- Limite de crédito total, utilizado e disponível
- Flag
canWithdraw indicando se pode realizar saques
Webhooks
| Método | Rota | Descrição |
|---|
| POST | /client/webhook/config | Configurar webhook |
| GET | /client/webhook/config | Consultar configuração |
| GET | /client/webhook/:id/logs | Logs de webhook específico |
| GET | /client/webhook/logs | Todos os logs de webhook |
Eventos de webhook
| Evento | Descrição |
|---|
quote | Nova cotação gerada |
order | Nova ordem criada |
deposit_fiat | Depósito fiat (PIX) recebido |
deposit_crypto | Depósito crypto recebido |
withdrawal_fiat | Saque fiat (PIX) enviado |
withdrawal_crypto | Saque crypto enviado para blockchain |
Configuração
Use POST /client/webhook/config para definir a URL de destino e ativar/desativar eventos específicos:
{
"url": "https://seu-servidor.com/webhook",
"webhook": {
"methodId": "id-do-metodo",
"active": true
}
}
Payload recebido
O webhook envia um POST para a URL configurada com o payload do evento:
{
"event": "order",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"amount": 1000,
"symbol": "USDTBRL",
"price": "5.4200",
"side": "BUY",
"timestamp": "2025-01-15T14:30:00.000Z"
}
}
Paginação
As rotas de listagem suportam paginação via query parameters:
| Parâmetro | Tipo | Padrão | Descrição |
|---|
limit | number | 20 | Itens por página |
offset | number | 1 | Página atual |
| Parâmetro | Tipo | Padrão | Descrição |
|---|
page | number | 1 | Página atual |
pageSize | number | 20 | Itens por página |
Códigos de erro comuns
| Código | Descrição |
|---|
400 | Parâmetros inválidos ou cotação expirada |
401 | Token ausente ou inválido |
403 | Sem permissão para o recurso |
404 | Recurso não encontrado |
500 | Erro interno do servidor |
