← Volver a herramientas

Documentación de la API

🚀 API de CobraBien – Documentación para desarrolladores

Versión API: 1.3.0
Base URL (desarrollo): http://localhost:5000 (o el port que se ocupe)
Base URL (producción): https://api.cobrabien.org

🔐 Autenticación

Todas las rutas excepto:

  • POST /api/auth/register
  • POST /api/auth/login

requieren un token JWT en el header:

Authorization: Bearer <access_token>

📝 Registro

Endpoint:
POST /api/auth/register

Request

{
  "email": "usuario@ejemplo.com",
  "password": "miPassword123"
}

Response (201)

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 1,
    "email": "usuario@ejemplo.com",
    "plan": "free",
    "theme": "light",
    "created_at": "2026-03-02T12:00:00"
  }
}

🔑 Login

Endpoint:
POST /api/auth/login

Mismo request/response que registro.

👤 Obtener perfil

Endpoint:
GET /api/auth/me

Response

{
  "id": 1,
  "email": "usuario@ejemplo.com",
  "plan": "free",
  "theme": "light",
  "created_at": "2026-03-02T12:00:00"
}

🔄 Refrescar token

Endpoint:
POST /api/auth/refresh

(Requiere refresh token)

Response

{
  "access_token": "nuevo_token..."
}

🗒️ Notas

📦 Modelo

{
  "id": 5,
  "text": "Llamar a Juan Pérez",
  "color": "amarillo",
  "order": 1,
  "created_at": "2026-03-02T12:05:00",
  "updated_at": null
}

📚 Endpoints

  • GET /api/notes → Listar notas
  • POST /api/notes → Crear nota
  • GET /api/notes/5 → Obtener por ID
  • PUT /api/notes/5 → Actualizar
  • DELETE /api/notes/5 → Eliminar

Crear / Actualizar – Request

{
  "text": "Llamar a Juan Pérez",
  "color": "amarillo",
  "order": 1
}

🧩 Plantillas del Generador

📦 Modelo

{
  "id": 3,
  "name": "Cobranza amigable",
  "main_template": "Hola {{nombre}}, tu saldo de {{saldo}} está próximo a vencer",
  "additional_templates": [
    {"nombre": "Asunto", "texto": "Recordatorio de pago - {{nombre}}"},
    {"nombre": "SMS", "texto": "Tu saldo de {{saldo}} vence pronto"}
  ],
  "created_at": "2026-03-02T12:10:00",
  "updated_at": null
}

📚 Endpoints

  • GET /api/generator/templates
  • POST /api/generator/templates
  • GET /api/generator/templates/3
  • PUT /api/generator/templates/3
  • DELETE /api/generator/templates/3

Crear – Request

{
  "name": "Cobranza amigable",
  "main_template": "Hola {{nombre}}, tu saldo de {{saldo}} está próximo a vencer",
  "additional_templates": [
    {"nombre": "Asunto", "texto": "Recordatorio de pago - {{nombre}}"}
  ]
}

⚙️ Configuraciones del Generador

📦 Modelo

{
  "id": 2,
  "name": "Cobranza telefónica",
  "variables": {
    "correo": "telefono",
    "nombre": "cliente",
    "adicionales": ["saldo", "fecha_vencimiento"],
    "formatos": {
      "telefono": "ninguno",
      "cliente": "ninguno",
      "saldo": "moneda",
      "fecha_vencimiento": "fecha"
    },
    "correoEsWhatsApp": true
  },
  "main_template": "Hola {{cliente}}, te recuerdo que tu saldo de {{saldo}} vence el {{fecha_vencimiento}}",
  "additional_templates": [
    {"nombre": "WhatsApp corto", "texto": "Saldo: {{saldo}}"}
  ],
  "created_at": "2026-03-02T12:15:00",
  "updated_at": null
}

📚 Endpoints

  • GET /api/generator/configs
  • POST /api/generator/configs
  • GET /api/generator/configs/2
  • PUT /api/generator/configs/2
  • DELETE /api/generator/configs/2

🧰 Plantillas del Index (por herramienta)

📦 Modelo

{
  "id": 2,
  "tool_id": "descuento",
  "name": "Oferta por pronto pago",
  "template": "Hola, te ofrecemos un {{porcentaje}}% de descuento si pagas antes del {{fecha}}",
  "created_at": "2026-03-02T12:20:00",
  "updated_at": null
}

📚 Endpoints

  • GET /api/index/templates
  • GET /api/index/templates?tool=descuento
  • GET /api/index/templates/grouped
  • POST /api/index/templates
  • GET /api/index/templates/2
  • PUT /api/index/templates/2
  • DELETE /api/index/templates/2

Listar agrupadas – Response

{
  "descuento": [
    {"id": 2, "name": "Oferta por pronto pago", "template": "..."}
  ],
  "recordatorio": [
    {"id": 3, "name": "Recordatorio estándar", "template": "..."}
  ]
}

⌨️ Atajos de Teclado

📦 Modelo

{
  "anterior": "ArrowLeft",
  "siguiente": "ArrowRight",
  "copiar_correo": "c",
  "copiar_principal": "v",
  "copiar_adicional1": "x"
}

📚 Endpoints

  • GET /api/user/shortcuts
  • PUT /api/user/shortcuts

Si el usuario no tiene atajos guardados, se crean automáticamente con los valores por defecto.

🔄 Migración de Datos Locales

Endpoint:
POST /api/migrate

Permite subir todos los datos desde localStorage a la nube.

Request

{
  "notes": [
    {"text": "Nota 1", "color": "amarillo", "order": 0},
    {"text": "Nota 2", "color": "verde", "order": 1}
  ],
  "generator_templates": [
    {
      "name": "Plantilla 1",
      "main_template": "Hola {{nombre}}",
      "additional_templates": []
    }
  ],
  "generator_configs": [
    {
      "name": "Config 1",
      "variables": {"correo": "email", "nombre": "cliente"},
      "main_template": "...",
      "additional_templates": []
    }
  ],
  "index_templates": {
    "descuento": [
      {"name": "Mi descuento", "template": "..."}
    ],
    "recordatorio": []
  },
  "shortcuts": {
    "anterior": "ArrowLeft",
    "siguiente": "ArrowRight",
    "copiar_correo": "c",
    "copiar_principal": "v",
    "copiar_adicional1": "x"
  },
  "theme": "dark"
}

Response (200)

{
  "message": "Migración completada",
  "resultados": {
    "notes": {"recibidas": 2, "importadas": 2, "omitidas": 0},
    "generator_templates": {"recibidas": 1, "importadas": 1, "omitidas": 0},
    "generator_configs": {"recibidas": 1, "importadas": 1, "omitidas": 0},
    "index_templates": {"recibidas": 1, "importadas": 1, "omitidas": 0},
    "shortcuts": "actualizado",
    "theme": "actualizado"
  }
}

📊 Límites del Usuario

Endpoint:
GET /api/user/limits

Response

{
  "plan": "free",
  "limits": {
    "notes": {"max": 10, "current": 3},
    "generator_templates": {"max": 10, "current": 2},
    "generator_configs": {"max": 5, "current": 1},
    "index_templates": {
      "descuento": {"max": 5, "current": 2},
      "porcentaje": {"max": 5, "current": 0},
      "monto": {"max": 5, "current": 0},
      "confirmacion": {"max": 5, "current": 0},
      "recordatorio": {"max": 5, "current": 0},
      "descuento-implicito": {"max": 5, "current": 0},
      "intereses": {"max": 5, "current": 0}
    },
    "shortcuts": {"max": 1, "current": 1}
  }
}

❌ Códigos de Error

Código Significado
400 Datos inválidos
401 No autorizado
403 Límite alcanzado
404 Recurso no encontrado
409 Conflicto
500 Error interno del servidor

Ejemplo 403

{
  "error": "Has alcanzado el límite de plantillas para esta herramienta (5)."
}

📦 Límites por Plan

Recurso Free Individual Business
Notas 10 Ilimitado Ilimitado
Plantillas del generador 10 Ilimitado Ilimitado
Configuraciones del generador 5 Ilimitado Ilimitado
Plantillas por herramienta 5 Ilimitado Ilimitado
Atajos 1 conjunto 1 conjunto 1 conjunto

📌 Notas Adicionales

  • Las listas están ordenadas por nombre o fecha.
  • Las fechas se devuelven en formato ISO 8601.
  • El access token dura 1 hora.
  • El refresh token dura 30 días.
  • Para renovar el access token usa:
POST /api/auth/refresh
Authorization: Bearer <refresh_token>