Documentación API REST CuñaPay

API completa para gestionar transacciones de USDT en la red TRON, compras de USDT con Bolivianos (BS), staking centralizado, y noticias económicas.

Base URL: http://localhost:5000

Introducción

La API de CuñaPay es una plataforma RESTful desarrollada en ASP.NET Core que permite gestionar transacciones de USDT en la red TRON, compras de USDT con Bolivianos (BS), staking centralizado, y noticias económicas.

Características Principales

  • Autenticación JWT: Sistema de autenticación basado en tokens JWT
  • Gestión de Wallets: Creación y gestión de wallets TRON para usuarios
  • Compras USDT/BS: Sistema de compra de USDT con Bolivianos usando precios de Binance P2P
  • Staking Centralizado: Sistema de staking donde los fondos se transfieren a la wallet del admin
  • Gestión de Noticias: Sistema de noticias económicas con categorías
  • Roles: Sistema de roles (User y Admin) con permisos diferenciados

Formato de Respuesta: Todas las respuestas exitosas devuelven JSON. Los errores también se devuelven en formato JSON con un campo error o ok: false.

Autenticación

La mayoría de los endpoints requieren autenticación mediante JWT. El token debe enviarse en el header Authorization con el formato: 

Authorization: Bearer <token>
POST /auth/register

Registra un nuevo usuario y crea automáticamente su wallet TRON.

Request Body: 
{
  "email": "usuario@example.com",
  "password": "password123",
  "firstName": "Juan",
  "lastName": "Pérez"
}
Response (200 OK): 
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "usuario@example.com",
    "firstName": "Juan",
    "lastName": "Pérez",
    "role": "User"
  },
  "wallet": {
    "id": "507f1f77bcf86cd799439012",
    "address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf"
  }
}
POST /auth/login

Autentica un usuario y devuelve un token JWT.

Request Body: 
{
  "email": "usuario@example.com",
  "password": "password123"
}
Response (200 OK): 
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "usuario@example.com",
    "firstName": "Juan",
    "lastName": "Pérez",
    "role": "User"
  }
}

Errores: 401 Unauthorized (credenciales inválidas), 400 Bad Request (email o password faltantes)

Endpoints de Usuarios

Todos los endpoints de usuarios requieren autenticación (header Authorization: Bearer <token>).

GET /api/me

Obtiene la información del usuario autenticado.

Response (200 OK): 
{
  "id": "507f1f77bcf86cd799439011",
  "email": "usuario@example.com",
  "firstName": "Juan",
  "lastName": "Pérez"
}
GET /api/me/wallet

Obtiene la información de la wallet TRON del usuario.

Response (200 OK): 
{
  "id": "507f1f77bcf86cd799439012",
  "address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
  "userId": "507f1f77bcf86cd799439011"
}
GET /api/me/balance

Obtiene el balance completo del usuario (TRX, USDT, locked en staking, disponible).

Response (200 OK): 
{
  "trx": 100.5,
  "usdt": 500.25,
  "lockedInStaking": 100.0,
  "available": 400.25
}
POST /api/me/send

Envía USDT desde la wallet del usuario a otra dirección TRON.

Request Body: 
{
  "to": "TABC123def456ghi789jkl012mno345pqr678stu901vwx234yz",
  "amount": "100.5"
}
Headers Opcionales:

Idempotency-Key: Clave única para evitar duplicados (opcional)

Response (200 OK): 
{
  "ok": true,
  "txid": "abc123def456...",
  "status": "SUCCESS"
}

Errores: 400 Bad Request, 429 Too Many Requests (rate limiting: 3 requests por 30 segundos), 404 Not Found

POST /api/me/stakes

Crea un nuevo stake. El USDT se transfiere automáticamente a la wallet del admin.

Request Body: 
{
  "amountUsdt": 100.0
}

Nota: El dailyRateBp (tasa diaria en basis points) viene configurado en el backend. El USDT se transfiere inmediatamente a la wallet del admin.

POST /api/purchases

Crea una nueva solicitud de compra de USDT con BS. El estado inicial es "waiting_payment".

Request Body: 
{
  "amountUsdt": 100.0
}
GET /api/p2p/usdt/buy/avg

Obtiene el precio promedio de compra de USDT en Binance P2P. Este endpoint es público y no requiere autenticación.

Response (200 OK): 
{
  "ok": true,
  "promedio_precio": "36.50",
  "precio": 36.5,
  "asset": "USDT",
  "fiat": "BOB",
  "rows": 10
}

Códigos de Estado HTTP

Código Significado Descripción
200 OK Solicitud exitosa
201 Created Recurso creado exitosamente
400 Bad Request Solicitud inválida (datos faltantes o incorrectos)
401 Unauthorized No autenticado o token inválido
403 Forbidden No tiene permisos (rol incorrecto)
404 Not Found Recurso no encontrado
429 Too Many Requests Límite de rate limiting alcanzado
500 Internal Server Error Error interno del servidor

Manejo de Errores

Todas las respuestas de error siguen este formato: 

{
  "ok": false,
  "error": "Mensaje de error descriptivo"
}

401 Unauthorized

{
  "error": "User ID not found in token"
}

Solución: Verifica que el token JWT sea válido y esté en el header Authorization.

403 Forbidden

{
  "error": "Access denied. Admin role required."
}

Solución: El usuario no tiene el rol Admin requerido.

429 Too Many Requests

{
  "error": "Too many requests. Try again later."
}

Solución: Espera unos segundos antes de intentar nuevamente. El límite es de 3 requests por 30 segundos para el endpoint de envío.

Notas Importantes

Autenticación

Los tokens JWT expiran según la configuración en appsettings.json (por defecto 12 horas). El token debe incluirse en todas las solicitudes autenticadas: Authorization: Bearer <token>

Staking

El sistema de staking es centralizado: los fondos se transfieren a la wallet del admin. El usuario puede cerrar su stake en cualquier momento y recibirá el principal + recompensas acumuladas. Las recompensas se calculan en tiempo real basándose en la tasa diaria configurada.

Compras USDT/BS

El precio se calcula como: Precio de Compra de Binance (BOB) + 0.13 BS. El estado inicial de una compra es "waiting_payment". El admin debe aprobar la compra para que se transfiera el USDT al usuario.

Wallets

Cada usuario tiene una wallet TRON única creada automáticamente al registrarse. El admin tiene una wallet de custodia (custody wallet) que se usa para aprobar compras y gestionar staking. Las direcciones TRON tienen el formato: T seguido de 33 caracteres alfanuméricos.

Rate Limiting

El endpoint de envío (POST /api/me/send) tiene rate limiting: 3 requests por 30 segundos por usuario/IP.

Idempotencia

El endpoint de envío soporta idempotencia mediante el header Idempotency-Key. Si se envía la misma clave, se devuelve la respuesta cacheada en lugar de ejecutar la transacción nuevamente.

Colecciones de Postman

Para facilitar las pruebas, se incluyen dos colecciones de Postman:

  • CuñaPay_API_Usuarios.postman_collection.json: Endpoints para usuarios normales
  • CuñaPay_API_Admin.postman_collection.json: Endpoints para administradores

Variables de Entorno en Postman

Configura las siguientes variables en Postman:

  • base_url: http://localhost:5000
  • token: Se guarda automáticamente después del login
  • admin_token: Se guarda automáticamente después del login de admin