API de CuotaPaga para desarrolladores

Conectá tu sistema contable, tu web o un asistente de IA con CuotaPaga: consultá socios y deuda, registrá pagos, emití las cuotas del mes y recibí avisos firmados cuando algo cambia. Disponible en el plan Profesional.

Cómo empezar

• El dueño de la organización crea una clave en Configuración → API e integraciones, eligiendo rol (Administrador o Cobrador) y permisos. La clave se muestra una sola vez.
• Cada solicitud lleva Authorization: Bearer cp_live_…. Las claves cp_test_ son de ambientes de prueba.
• Referencia completa en OpenAPI 3.1: /api/v1/openapi.json (importala en Postman, Insomnia o tu generador de clientes).

curl -s "https://cuotapaga.net/api/v1/socios?conDeuda=true&limite=20" \
  -H "Authorization: Bearer $CUOTAPAGA_CLAVE"

Convenciones

• Importes en centavos enteros: "importeCentavos": 3990000 son $ 39.900,00. Con ?formato=texto cada importe trae al lado su texto (importeTexto).
• Fechas AAAA-MM-DD, períodos AAAA-MM e instantes ISO 8601.
• Deuda vencida son las cuotas vencidas impagas; a cobrar, las emitidas que todavía no vencieron. Son las mismas cifras que la ficha, el tablero y el portal del socio.
• Listados paginados por cursor: limite (hasta 200) y cursor con el siguienteCursor de la respuesta anterior; null indica la última página.
• Errores uniformes en español: { "error": { "code": "datos_invalidos", "message": "Revisá los datos marcados.", "campos": { … } } }.
• Límite por clave: 120 solicitudes por minuto. Los headers RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset informan el estado; al pasarte, 429 con Retry-After.
• Toda escritura queda en la auditoría de la organización a nombre de la clave. Nada se borra: los pagos se anulan con motivo.

Idempotencia

Los POST que crean dinero o documentos (pagos, socios, suscripciones y liquidaciones) exigen el header Idempotency-Key. Reintentar con la misma clave y el mismo cuerpo devuelve la misma respuesta (Idempotent-Replayed: true) sin duplicar nada; la misma clave con otro cuerpo responde 409. Usá una clave nueva (por ejemplo, un UUID) por cada operación.

curl -s -X POST "https://cuotapaga.net/api/v1/pagos" \
  -H "Authorization: Bearer $CUOTAPAGA_CLAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d2c9e-8a7b-4c3d-9e2f-1a2b3c4d5e6f" \
  -d '{ "socioId": "…", "importeCentavos": 1500000, "medio": "efectivo", "imputacion": "automatica" }'

Emitir una liquidación

Igual que en la app: primero la previa, después la emisión con confirmación explícita. confirmar tiene que ser el mismo período. La emisión responde 202 y se procesa en segundo plano; el resultado se consulta en GET /liquidaciones/{id} o llega por el webhook liquidacion.emitida. Reintentar no duplica cuotas.

curl -s "https://cuotapaga.net/api/v1/liquidaciones/previa?periodo=2026-11" -H "Authorization: Bearer $CUOTAPAGA_CLAVE"

curl -s -X POST "https://cuotapaga.net/api/v1/liquidaciones" \
  -H "Authorization: Bearer $CUOTAPAGA_CLAVE" -H "Content-Type: application/json" \
  -H "Idempotency-Key: liquidacion-2026-11" \
  -d '{ "periodo": "2026-11", "confirmar": "2026-11" }'

Operaciones

Permisos

Cada clave tiene un rol y una lista de permisos; el acceso efectivo es la intersección. Una clave nunca puede cambiar la configuración de cobro, los usuarios ni el plan, ni ver datos de salud. Con rol Cobrador solo se ven socios y deuda y se registran pagos.

• socios:read: Ver socios. Listado, ficha y grupo familiar (sin datos de salud).
• socios:write: Crear y editar socios. Alta y modificación de socios y de su ficha.
• cuotas:read: Ver cuotas y deuda. Cuotas, estado de cuenta y avisos de pago.
• pagos:read: Ver pagos. Pagos, imputaciones y recibos.
• pagos:write: Registrar y anular pagos. Pagos manuales; anular requiere rol Administrador.
• conceptos:read: Ver conceptos. Conceptos que se cobran y su precio vigente.
• suscripciones:write: Gestionar suscripciones. Suscribir socios a conceptos y finalizar suscripciones.
• liquidaciones:read: Ver liquidaciones. Previa de un período y resultado de cada liquidación.
• liquidaciones:write: Emitir liquidaciones. Emitir las cuotas de un período, con confirmación.
• reportes:read: Ver el tablero. Deuda vencida, a cobrar, cobrado y morosidad.
• inscripciones:read: Ver inscripciones. Solicitudes de inscripción online pendientes.
• webhooks:manage: Gestionar webhooks. Crear y desactivar endpoints de webhooks.

Webhooks

Configurá una URL HTTPS pública y elegí los eventos. Cada aviso es un POST JSON { "id", "tipo", "creadoAt", "datos" } con el header CuotaPaga-Firma: t=<unix>,v1=<hex>: HMAC-SHA256 con el secreto del endpoint sobre `${t}.${cuerpo}`. Rechazá firmas inválidas o con más de 5 minutos. Si tu sistema no responde 2xx, reintentamos con espera creciente (1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h). El id del evento sirve para descartar duplicados.

• pago.registrado: Pago registrado (manual u online).
• pago.anulado: Pago anulado.
• cuota.emitida: Cuota emitida (liquidación o alta de suscripción).
• socio.creado: Socio creado.
• inscripcion.recibida: Inscripción online recibida.
• liquidacion.emitida: Liquidación terminada.

import { createHmac, timingSafeEqual } from "node:crypto";

function firmaValida(secreto, header, cuerpoCrudo) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // replay
  const esperada = createHmac("sha256", secreto).update(`${t}.${cuerpoCrudo}`).digest();
  const recibida = Buffer.from(v1 ?? "", "hex");
  return recibida.length === esperada.length && timingSafeEqual(recibida, esperada);
}

Servidor MCP (asistentes de IA)

CuotaPaga expone las mismas operaciones como herramientas MCP en https://cuotapaga.net/api/mcp (Streamable HTTP, sin estado), con la misma clave y los mismos permisos: buscar_socios, ver_socio, estado_de_cuenta, registrar_pago, listar_cuotas, previa_liquidacion, emitir_liquidacion, tablero, crear_socio y más. Incluye el prompt resumen_morosidad. Recomendación: una clave con rol Cobrador o solo permisos de lectura para empezar.

claude mcp add --transport http cuotapaga https://cuotapaga.net/api/mcp \
  --header "Authorization: Bearer cp_live_…"

{
  "mcpServers": {
    "cuotapaga": {
      "type": "http",
      "url": "https://cuotapaga.net/api/mcp",
      "headers": { "Authorization": "Bearer ${CUOTAPAGA_CLAVE}" }
    }
  }
}

{
  "mcpServers": {
    "cuotapaga": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cuotapaga.net/api/mcp", "--header", "Authorization:${CUOTAPAGA_AUTH}"],
      "env": { "CUOTAPAGA_AUTH": "Bearer cp_live_…" }
    }
  }
}

Soporte

Cada respuesta trae el header CuotaPaga-Solicitud: mandalo junto con tu consulta a contacto@develone.com. ¿Todavía no usás CuotaPaga? Empezá gratis.