v1.0 · REST API

API de Integración

La API REST de BellezaCRM te permite conectar de forma segura los datos de cuentas y cobros de tu salón con sistemas de facturación electrónica externos (Alegra, Factura PA, QuickBooks, etc.). Extrae la información de clientes, servicios realizados y pagos registrados en tiempo real para emitir tus comprobantes fiscales automáticamente.

La API responde exclusivamente en formato JSON y utiliza códigos de estado HTTP estándar.

Autenticación

Todas las rutas de la API están protegidas mediante API Keys. Puedes generar o revocar tu llave desde el panel de Integraciones en tu cuenta de administrador.

Incluye tu llave en el header X-API-Key de cada petición. Cada llave está asociada exclusivamente a tu salón — no se requiere ningún parámetro adicional para identificarlo.

Mantén tu API Key en secreto. No la expongas en código del lado del cliente ni en repositorios públicos. Si se compromete, regénérala de inmediato desde el panel.
Ejemplo de petición autenticada
curl https://api.bellezacrm.com/api/integration/invoices \
  -H "X-API-Key: bcrm_live_xxxxxxxxxxxxxxxxx"

Códigos de Error

Cuando ocurre un error, la API devuelve un objeto JSON con el campo error descriptivo.

Código
Significado
401
API Key ausente, inválida o revocada.
404
El recurso solicitado no existe o no pertenece a tu salón.
429
Límite de peticiones excedido. Espera antes de reintentar.
500
Error interno del servidor. Contacta a soporte si persiste.

Listar Cuentas GET

Devuelve las cuentas (invoices) registradas en tu salón, ordenadas de la más reciente a la más antigua. Ideal para que tu sistema externo detecte periódicamente qué nuevas cuentas necesitan ser procesadas.

GET/api/integration/invoices

Parámetros Query

Parámetro
Descripción
status
Opcional. Filtra por estado: PENDING · PARTIAL · PAID

Respuesta

200 OK · application/json
{
  "success": true,
  "count": 1,
  "data": [
    {
      "id": "inv_123abc",
      "status": "PAID",
      "createdAt": "2026-05-14T10:00:00Z",
      "customer": {
        "name": "María González",
        "taxId": "8-234-567",
        "dv": "3",
        "email": "maria@example.com",
        "address": "Calle 50, Panamá",
        "type": "NATURAL"
      },
      "financials": {
        "totalAmount": 95.00,
        "paidAmount": 95.00,
        "currency": "USD"
      },
      "payments": [
        {
          "paymentId": "pay_999xyz",
          "amount": 95.00,
          "method": "YAPPY",
          "date": "2026-05-14T10:05:00Z"
        }
      ]
    }
  ]
}

Detalle de Cuenta GET

Recupera el detalle completo de una cuenta, incluyendo el desglose de servicios realizados. Usa este endpoint para obtener los ítems necesarios al emitir el comprobante fiscal detallado.

GET/api/integration/invoices/:id

Parámetros de Ruta

Parámetro
Descripción
:idreq
ID único de la cuenta (campo id de la respuesta anterior).

Respuesta

200 OK · application/json
{
  "success": true,
  "data": {
    "id": "inv_123abc",
    "status": "PAID",
    "customer": {
      "name": "María González",
      "taxId": "8-234-567",
      "dv": "3",
      "email": "maria@example.com",
      "address": "Calle 50, Panamá",
      "type": "NATURAL"
    },
    "financials": {
      "totalAmount": 95.00,
      "paidAmount": 95.00,
      "currency": "USD"
    },
    "payments": [ { ... } ],
    "items": [
      {
        "description": "Coloración completa con mechas",
        "price": 60.00,
        "quantity": 1
      },
      {
        "description": "Tratamiento de keratina",
        "price": 35.00,
        "quantity": 1
      }
    ]
  }
}