Saltar al contenido principal

Contrato de API (Borrador)

Nota de Arquitectura: Este documento representa un enfoque Design-First. Actualmente sirve como especificación para los desarrolladores. En el futuro, será reemplazado por documentación generada automáticamente (Swagger/OpenAPI) a partir del código fuente.

Estándares Globales​

  • Base URL Nube (Web Portal): https://api.yuruary.com/v1
  • Base URL Local (Desktop Client): http://server-local:3000/v1
  • Autenticación: Header Authorization: Bearer <JWT_TOKEN>

Módulo 1: Public API (Residentes - Cloud)​

Endpoints optimizados para el consumo desde el Portal Web (Mobile First).

Mis Deudas (GET /public/my-debt)​

Retorna el estado de cuenta resumido para la unidad del usuario autenticado.

Response:

{
  "total_pending": 150.00,
  "currency": "USD",
  "details": [
    { "period": "2023-10", "amount": 50.00, "status": "OVERDUE" },
    { "period": "2023-11", "amount": 100.00, "status": "OPEN" }
  ]
}

Reportar Pago (POST /public/payments/report)​

CRÍTICO. Permite al residente notificar una transferencia. La respuesta es asíncrona (Cola), garantizando robustez ante fallos de conexión hacia la BD principal.

Request Body:

{
  "unit_id": "uuid-v4...",
  "amount": 50.00,
  "currency": "USD",
  "method": "ZELLE",
  "reference": "AB123456",
  "proof_url": "https://s3.aws..."
}

Response (202 Accepted):

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "tracking_id": "pay_123456789",
    "queue_position": 5,
    "estimated_processing": "24h"
  }
}

Módulo 2: Internal API (Staff - Local)​

Endpoints de administración exclusivos para la aplicación de escritorio (Electron) dentro de la red del condominio.

Cerrar Periodo (POST /internal/billing/close-period)​

Ejecuta el proceso de cierre de mes, cálculo de alícuotas y generación de nuevos recibos de cobro.

Conciliaciones Pendientes (GET /internal/treasury/pending-reconciliations)​

Busca los reportes de pago (del residente) que el algoritmo sugeridor ha emparejado con una transacción bancaria real.

Response:

[
  {
    "report_id": "pay_123",
    "bank_tx_id": "tx_999",
    "confidence_score": 0.95,
    "match_reason": "Reference & Amount Match"
  }
]

Conciliar (POST /internal/treasury/conciliate)​

Confirma el match manual o automático, convirtiendo el dinero en "Efectivo disponible" y cerrando la deuda de la unidad.

Módulo 3: Sync API (System-to-System)​

Subir Cambios (POST /sync/push-changes)​

Endpoint protegido donde el servidor local sube la data fresca (nuevos pagos procesados, recibos generados) a la nube para que los residentes vean su información actualizada.