Pagos

Endpoints para gestionar pagos.

Modelos de Datos

Los siguientes modelos de Prisma pertenecen al schema payments:

Payment

model Payment {
  id            String        @id @default(cuid())
  userProfileId String        @map("user_profile_id")
  amount        Float
  method        PaymentMethod
  status        PaymentStatus @default(PENDING)
  description   String?
  transactionId String?       @map("transaction_id")

  userProfile UserProfile @relation(fields: [userProfileId], references: [id], onDelete: Cascade)

  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")

  @@map("payments")
  @@schema("payments")
}

PaymentStatus (Enum)

enum PaymentStatus {
  PENDING
  COMPLETED
  FAILED
  REFUNDED

  @@schema("payments")
}

PaymentMethod (Enum)

enum PaymentMethod {
  CASH
  CREDIT_CARD
  DEBIT_CARD
  BANK_TRANSFER
  PAYPAL

  @@schema("payments")
}

Endpoints

Obtener Pagos

Obtener todos los pagos (Admin/Staff ven todos, Members ven los propios).

• URL: /api/v1/payments
• Método: GET
• Autenticación Requerida: Sí

Descripción Interna

Este endpoint obtiene pagos con filtrado:

1. Filtros disponibles:

   • userProfileId: Filtrar por usuario (Automático para Members)
   • status: Estado (PENDING, COMPLETED, FAILED, REFUNDED)
   • method: Método de pago (CASH, CREDIT_CARD, etc.)
   • minAmount / maxAmount: Rango de montos
   • startDate / endDate: Rango de fechas de creación

2. Permisos:

   • Members: Solo ven sus propios pagos (se fuerza userProfileId = payload.pid)
   • Admin/Staff: Pueden ver pagos de cualquiera

3. Incluye userProfile con nombre y email

4. Paginación estándar

Parámetros de Consulta de Solicitud

• status: Filtrar por status
• method: Filtrar por método
• userProfileId: Filtrar por usuario
• startDate: Filtrar desde fecha (ISO)
• endDate: Filtrar hasta fecha (ISO)
• minAmount: Monto mínimo
• maxAmount: Monto máximo
• page: Número de página
• limit: Resultados por página

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.payments.$get({
  query: {
    status: 'COMPLETED'
  }
})

---

Obtener Detalles de Pago

Obtener pago específico por ID.

• URL: /api/v1/payments/:id
• Método: GET
• Autenticación Requerida: Sí

Descripción Interna

Este endpoint obtiene un pago por su ID.

1. Permisos:

   • Members: Solo pueden ver el pago si userProfileId coincide con su perfil
   • Admin/Staff: Pueden ver cualquier pago

2. Incluye información del usuario asociado.

Respuesta

{
  "data": {
    "id": "...",
    "userProfileId": "...",
    "amount": 50,
    "method": "CREDIT_CARD",
    "status": "COMPLETED",
    "description": "Mensualidad",
    "createdAt": "2023-10-01T00:00:00Z"
  }
}

---

Crear Pago (Admin/Staff)

Crear un nuevo registro de pago.

• URL: /api/v1/payments
• Método: POST
• Autenticación Requerida: Sí Admin Staff

Descripción Interna

Este endpoint registra un nuevo pago manualmente.

1. Validación:

   • Verifica que el userProfileId exista.
   • Monto debe ser positivo.

2. Creación:

   • Crea el registro en la tabla payments.
   • Estado por defecto: PENDING si no se especifica.

Cuerpo de Solicitud

{
  "userProfileId": "user_id",
  "amount": 50,
  "method": "CASH",
  "status": "COMPLETED",
  "description": "Pago en efectivo membresía mensual"
}

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.payments.$post({
  json: {
    userProfileId: 'user_id',
    amount: 50,
    method: 'CASH',
    status: 'COMPLETED',
    description: 'Pago mensualidad'
  }
})

---

Actualizar Pago (Admin/Staff)

Actualizar un pago existente.

• URL: /api/v1/payments/:id
• Método: PATCH
• Autenticación Requerida: Sí Admin Staff

Descripción Interna

Este endpoint actualiza un pago existente.

1. Campos actualizables:
   • status: Cambiar estado (e.g. PENDING -> COMPLETED)
   • description: Actualizar descripción
   • transactionId: Añadir ID de transacción externa

Cuerpo de Solicitud

{
  "status": "REFUNDED",
  "description": "Reembolso por error"
}

---

Eliminar Pago (Admin)

Eliminar un registro de pago.

• URL: /api/v1/payments/:id
• Método: DELETE
• Autenticación Requerida: Sí Admin

Descripción Interna

Elimina físicamente un registro de pago.

1. Permisos: Admin