API de Clientes

{parte_del_cliente}@{username_de_tu_empresa}

Por ejemplo, si tu empresa tiene el username mitienda y creas el nick jperez, el identificador completo de inicio de sesión será jperez@mitienda.

Acceso B2B2B y reportes por cliente

Los endpoints públicos de integración requieren JWT o API key (appKey o Authorization: Bearer). El titular administra clientes y asigna cuentas usando client_owner_id. Al iniciar sesión un cliente, Pabilo fija ese campo automáticamente y solo permite operar con sus propias cuentas.

El login POST /auth/login recibe user y password. En sesiones de cliente devuelve client, los tokens y un perfil limitado en user; no devuelve el saldo ni la API key del titular. El portal permite agregar y consultar cuentas y crear llaves propias. En Pabilo Notificaciones se utiliza una llave de ese mismo cliente.

El dueño puede activar white_label: true al crear o actualizar el cliente. Entonces el portal y notificaciones presentan su company_name. No concede permisos adicionales.

curl -X POST https://api.pabilo.app/auth/api-key -H "Authorization: Bearer JWT_DEL_CLIENTE" -H "Content-Type: application/json" -d '{"name":"Mi integración"}'

La llave hereda únicamente bank_accounts y bank_pay_notifications, sobre los recursos del cliente. No acepta un catálogo de permisos editable. GET /me/api-keys lista solo las llaves del cliente. GET /me/usersbank lista solo sus cuentas. El cliente no accede a créditos, otros clientes, empleados ni al secreto de webhook del titular.

Créditos consumidos durante un mes

Consulta del titular o una integración con lectura de credit_movements. El cliente debe pertenecer al titular autenticado. month usa YYYY-MM y, si se omite, el mes actual de Caracas.

curl "https://api.pabilo.app/v1/clients/CLIENT_ID/credit-consumption?month=2026-09" -H "appKey: API_KEY_DEL_TITULAR"

{
  "client_id": "CLIENT_ID",
  "month": "2026-09",
  "timezone": "America/Caracas",
  "consumed": 12.5,
  "operations": 25,
  "monthly_credit_limit": 100,
  "quota_used": 12.5,
  "remaining": 87.5
}

consumed suma los débitos SUBTRACT atribuidos al cliente; operations cuenta esos movimientos, incluyendo los de costo cero. No es el saldo del dueño ni necesariamente el número de pagos exitosos. El rango va desde el inicio del mes hasta el inicio del siguiente, exclusivo.

Movimientos y Excel por cliente

curl -X POST https://api.pabilo.app/me/credit-movements -H "appKey: API_KEY_DEL_TITULAR" -H "Content-Type: application/json" -d '{"page":1,"limit":20,"client_id":"CLIENT_ID","type":"SUBTRACT"}'

curl -X POST https://api.pabilo.app/me/credit-movements/export -H "appKey: API_KEY_DEL_TITULAR" -H "Content-Type: application/json" -d '{"from":"2026-09-01","to":"2026-09-30","client_id":"CLIENT_ID"}' -o movimientos-cliente.xlsx

La lista responde movements, total, page y limit. Excel es binario XLSX y tiene un límite de 50.000 filas; el cálculo mensual no usa ese límite. Un ID mal formado responde 400 y un cliente ajeno, 404.

La atribución se guarda en whoCalled.client_id. Desde esta versión las verificaciones del dueño sobre cuentas de cliente también la guardan, conservando el actor real. Los movimientos antiguos sin atribución no se asignan retroactivamente; los reportes históricos reflejan solamente lo registrado.

B2B2B: crear clientes, consultar consumo y limitar créditos

El titular administra cada cliente desde Clientes → Créditos: elige un mes para consultar su consumo y configura el tope mensual. Al crear un cliente también puede fijar el límite. En Movimientos puede filtrar por cliente y exportar su actividad.

Por API, usa una llave del titular o un JWT de titular/empleado. Crear clientes y modificar su límite requieren clients con escritura; consultar consumo requiere credit_movements con lectura. Una llave propia de cliente no puede crear otros clientes, consultar estos reportes ni modificar su límite.

1. Crear un cliente con acceso y límite

curl -X POST https://api.pabilo.app/v1/clients/create -H "appKey: API_KEY_DEL_TITULAR" -H "Content-Type: application/json" -d '{"name":"Sucursal Centro","phone":"+584141234567","email":"[email protected]","nickname":"centro","white_label":true,"company_name":"Mi comercio","monthly_credit_limit":100}'

La respuesta incluye client.id para las siguientes peticiones. Si proporcionas nickname, requiere correo y devuelve el nickname completo y una contraseña generada, que también se envía por correo. Asigna las cuentas del cliente mediante client_owner_id. Sus sesiones web y Flutter conservarán esa identidad: no reciben la llave, el saldo ni los datos del plan del titular.

2. Configurar o quitar el límite

curl -X PUT https://api.pabilo.app/v1/clients/CLIENT_ID/credit-limit -H "appKey: API_KEY_DEL_TITULAR" -H "Content-Type: application/json" -d '{"monthly_credit_limit":250}'

curl -X PUT https://api.pabilo.app/v1/clients/CLIENT_ID/credit-limit -H "appKey: API_KEY_DEL_TITULAR" -H "Content-Type: application/json" -d '{"monthly_credit_limit":null}'

{
  "client_id": "CLIENT_ID",
  "monthly_credit_limit": 250
}

monthly_credit_limit es obligatorio en este PUT: un número finito igual o mayor que cero, o null. En la creación, omitirlo equivale a sin límite. El PUT general de perfil no cambia el límite; usa este endpoint específico.

• null: sin tope por cliente. 0: rechaza nuevos cargos positivos; operaciones gratuitas siguen permitidas.
• Mes calendario de America/Caracas, sin acumulación del cupo sobrante. Aumentar o reducir el límite no borra el consumo del mes; si lo bajas por debajo de lo utilizado, se bloquean nuevos cargos.
• El tope se aplica a los cargos atribuidos al cliente, también cuando quien verifica es el titular o su integración. El saldo y la disponibilidad del plan del titular siguen siendo necesarios para operar, aunque el cliente no vea sus detalles.
• Una solicitud que excedería el cupo falla con HTTP 403 y código CLIENT_MONTHLY_CREDIT_LIMIT_EXCEEDED, antes de descontar créditos. En verificaciones batch, el error corresponde al ítem afectado.

3. Consultar el mes

curl "https://api.pabilo.app/v1/clients/CLIENT_ID/credit-consumption?month=2026-09" -H "appKey: API_KEY_DEL_TITULAR"

consumed y operations describen los débitos registrados. monthly_credit_limit es la configuración vigente, incluso al consultar meses pasados; no es un histórico de límites. quota_used incluye reservas y remaining es el máximo entre cero y límite menos cuota utilizada; es null cuando no hay límite.

Las reservas se comprueban de forma atómica entre procesos. Si hay un fallo de almacenamiento después de reservar, el cupo se conserva por seguridad: podría haberse aplicado el cargo. En ese caso quota_used puede superar consumed y requiere revisar la operación antes de corregir el cupo. Los débitos históricos que ya tengan cliente asociado se incluyen al iniciar el contador; los antiguos sin atribución no pueden reconstruirse.