Registrar Transacciones

Este recurso te permite gestionar los movimientos financieros de tu espacio de trabajo en tiempo real.

🔍 1. Listar Transacciones

GET /api/transactions

Obtiene un listado paginado de los movimientos del espacio de trabajo actual, ordenados cronológicamente de forma descendente.

• Scope requerido: transactions:read
• Parámetros de consulta (Query Params):
  • q (Opcional): Búsqueda rápida de texto en conceptos (alias de search, máx 100 caracteres, devuelve máximo 10 resultados).
  • search (Opcional): Búsqueda de texto en conceptos (máx 200 caracteres).
  • page (Opcional): Número de página (Default: 1).
  • pageSize (Opcional): Elementos por página (Default: 25, Máximo: 100).
  • walletId (Opcional): Filtrar movimientos asociados a una cartera específica.
  • categoryId (Opcional): Filtrar por categoría.
  • goalId (Opcional): Filtrar por meta.
  • type (Opcional): Filtrar por tipo (income, expense, transfer, goal_deposit, goal_withdrawal).
  • from (Opcional): Fecha inicial YYYY-MM-DD.
  • to (Opcional): Fecha final YYYY-MM-DD.

Ejemplo de Respuesta (200 OK):

{
  "transactions": [
    {
      "id": "tx_gasto_987",
      "amount": 450.00,
      "type": "expense",
      "description": "Cena de negocios",
      "date": "2026-07-08",
      "walletId": "w_nom_123",
      "categoryId": "c_com_456",
      "createdAt": "2026-07-08T19:00:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 142
  }
}

📝 2. Registrar Transacción

POST /api/transactions

Crea un nuevo ingreso, gasto o transferencia dentro del espacio de trabajo.

• Scope requerido: transactions:write
• Cuerpo de la Petición (JSON):

Ejemplo de Petición (curl):

curl -X POST https://money.depot.center/api/transactions \
  -H "Authorization: Bearer mm_live_xxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "amount": 125.50,
    "type": "expense",
    "walletId": "w_nom_123",
    "categoryId": "c_com_456",
    "description": "Café y snacks",
    "date": "2026-07-08"
  }'

Ejemplo de Respuesta (201 Created):

{
  "transaction": {
    "id": "tx_gasto_988",
    "amount": 125.50,
    "type": "expense",
    "description": "Café y snacks",
    "date": "2026-07-08",
    "walletId": "w_nom_123",
    "categoryId": "c_com_456",
    "createdAt": "2026-07-08T19:05:00Z"
  }
}

✏️ 3. Modificar Transacción

PATCH /api/transactions/[id]

Actualiza los datos de un movimiento financiero existente (monto, concepto, categoría, cartera o fecha) y recalcula automáticamente los saldos de las carteras afectadas.

• Scope requerido: transactions:write
• Cabecera obligatoria: Idempotency-Key

Ejemplo de Petición (curl):

curl -X PATCH https://money.depot.center/api/transactions/tx_gasto_988 \
  -H "Authorization: Bearer mm_live_xxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
  -d '{
    "amount": 150.00,
    "description": "Café y snacks para el equipo"
  }'

Ejemplo de Respuesta (200 OK):

{
  "transaction": {
    "id": "tx_gasto_988",
    "amount": 150.00,
    "type": "expense",
    "description": "Café y snacks para el equipo",
    "date": "2026-07-08",
    "walletId": "w_nom_123",
    "categoryId": "c_com_456",
    "createdAt": "2026-07-08T19:05:00Z"
  }
}

🗑️ 4. Eliminar Transacción

DELETE /api/transactions/[id]

Elimina lógicamente un movimiento financiero y revierte automáticamente los balances correspondientes de la cartera asociada.

• Scope requerido: transactions:write
• Cabecera obligatoria: Idempotency-Key

Ejemplo de Petición:

curl -X DELETE https://money.depot.center/api/transactions/tx_gasto_988 \
  -H "Authorization: Bearer mm_live_xxxxxx" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440002"

Ejemplo de Respuesta (200 OK):

{
  "ok": true
}

📋 Historial de Cambios (Changelog)

• 2026-09-21 (MW9 / MW9b):
  • PATCH /api/transactions/{id} y DELETE /api/transactions/{id} ahora exigen obligatoriamente la cabecera Idempotency-Key para garantizar la idempotencia de las mutaciones.
  • Habilitado soporte en WhatsApp para desambiguar, corregir y eliminar transacciones específicas por ID con confirmación previa.