Descripción General
La API de Pagos te ayuda a rastrear tus retiros y ganancias de empresas prop. Calcula automáticamente las divisiones de beneficios, mantiene totales acumulativos y sincroniza con los saldos de tus cuentas.
URL Base: /api/v1/payouts
Listar Pagos
Recupera tu historial de pagos con filtros opcionales.
GET /api/v1/payouts
Parámetros de Consulta
Respuesta
{
"data": [
{
"id": "uuid",
"user_id": "uuid",
"account_id": "uuid",
"date": "2024-01-15",
"total_amount": 5000.00,
"profit_split": 80,
"traders_share": 4000.00,
"firms_share": 1000.00,
"status": "completed",
"reference": "PAGO-2024-001",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z",
"account_number": "CTA-12345",
"firm_id": "uuid",
"firm_name": "Apex Trader Funding"
}
],
"pagination": {
"total": 15,
"limit": 20,
"offset": 0,
"has_more": false
}
}
Cálculos Acumulativos
Cuando include_cumulative=true, cada pago incluye totales acumulativos:
{
"data": [
{
"id": "uuid",
"total_amount": 5000.00,
"traders_share": 4000.00,
"cumulative_total_amount": 15000.00,
"cumulative_traders_share": 12000.00,
"cumulative_total_amount_by_firm": 10000.00,
"cumulative_traders_share_by_firm": 8000.00,
"cumulative_total_amount_by_account": 5000.00,
"cumulative_traders_share_by_account": 4000.00
}
]
}
Obtener Pago Individual
Recupera detalles de un pago específico.
GET /api/v1/payouts/{id}
Crear Pago
Registra un nuevo pago. La API calcula automáticamente las divisiones de beneficios y actualiza los saldos de las cuentas.
POST /api/v1/payouts
Content-Type: application/json
{
"date": "2024-01-15",
"total_amount": 5000.00,
"account_id": "uuid",
"profit_split": 80,
"status": "completed",
"reference": "PAGO-2024-001"
}
Campos:
- date (requerido): Fecha del pago (AAAA-MM-DD)
- total_amount (requerido): Monto total del pago antes de la división
- account_id (requerido): ID de la cuenta de este pago
- profit_split (requerido): Tu porcentaje de división de beneficios (0-100)
- status (requerido): Estado del pago
- reference (opcional): Número de referencia o nota
Campos calculados automáticamente:
traders_share: Tu porción (total_amount × profit_split / 100)firms_share: Porción de la empresa (total_amount - traders_share)
Actualizar Pago
Actualiza un pago existente.
PUT /api/v1/payouts/{id}
Content-Type: application/json
{
"status": "completed",
"reference": "PAGO-2024-001-ACTUALIZADO"
}
Eliminar Pago
Elimina un pago y actualiza el saldo de la cuenta en consecuencia.
DELETE /api/v1/payouts/{id}
Recalculación de Totales de Cuenta
Eliminar un pago recalculará automáticamente los totales de pagos de la cuenta. Esto asegura que el saldo de la cuenta permanezca preciso después de que se elimine el pago. La respuesta de la API confirmará que los totales de la cuenta se han actualizado.
Estados de Pago
Impacto en el Saldo de la Cuenta
Crear, actualizar o eliminar pagos recalcula automáticamente:
- total_gross_payouts: Suma de todos los total_amounts de pagos
- total_net_payouts: Suma de todos los traders_shares de pagos
- balance: account_size + net_pnl - total_gross_payouts
Esto garantiza que el saldo de tu cuenta siempre refleje los pagos retirados.
Mejores Prácticas
- Registra pagos prontamente - Crea registros de pagos cuando los solicites o recibas
- Usa referencias consistentes - Usa un esquema de nombres como
PAGO-AAAA-MM-XXXpara rastrear - Rastrea cambios de estado - Actualiza el estado a medida que los pagos progresan
- Revisa divisiones de beneficios - Verifica tu porcentaje de división antes de crear pagos
- Monitorea totales acumulativos - Usa datos acumulativos para rastrear tendencias de ganancias