Clientes

Los clientes son los destinatarios finales que registrás bajo tu PaymentHub. Cada cliente recibe un CVU dedicado — un número de cuenta bancaria argentino que mapea exclusivamente a ese cliente. Cuando llega una transferencia a ese CVU, Basilic identifica automáticamente al cliente y puede enviar un webhook a la URL de callback que configuraste.

Qué podés hacer

• Crear clientes y provisionar un CVU dedicado en una sola llamada a la API.
• Actualizar datos del cliente, incluyendo la URL de callback para notificaciones de transferencias entrantes.
• Ver el historial de transacciones — cada acreditación y débito registrado para el cliente — con paginación y filtros.
• Consultar el saldo del cliente — obtené el saldo a favor y la deuda del cliente, más totales informativos (acreditado, debitado, facturado), independientemente de la paginación de transacciones.
• Crear y actualizar facturas asignadas a cada cliente para registrar lo que deben.

Provisionamiento del CVU dedicado

Cuando creás un cliente, Basilic provisiona automáticamente un par CVU/alias específico para ese cliente. El provisionamiento ocurre en línea — la respuesta incluye el CVU y el alias una vez que están disponibles.

Tu llamada → POST /api/v1/clients
                        ↓
              Basilic crea la fila en billing_clients
                        ↓
              Basilic provisiona el CVU/alias
                        ↓
              Respuesta: cliente + cvu + alias

El campo cvuStatus refleja el estado actual del provisionamiento del CVU:

Estado	Significado
not_provisioned	Todavía no se solicitó el CVU
provisioning	La solicitud del CVU está en proceso
active	El CVU está listo para recibir transferencias
provisioning_failed	Falló la solicitud del CVU; contactá a soporte
disabled	El CVU está deshabilitado

Callback de acreditación (cash-in)

Configurá un cashinCallbackUrl en el cliente para recibir una notificación POST cada vez que llegue una transferencia al CVU de ese cliente.

Modelo de entrega:

• Hasta 3 intentos de entrega con reintentos en caso de falla.
• El evento se registra en el log interno de Basilic con estado pending → retrying → delivered / failed.

Payload del webhook:

{
  "eventId": "uuid",
  "clientId": "uuid",
  "eventType": "client.cashin",
  "taxId": "30-12345678-9",
  "amount": 4970.00,
  "total": 5000.00,
  "totalWithoutTaxes": 4970.00,
  "taxes": 30.00,
  "currency": "ARS",
  "cvu": "0000726100000000014782",
  "alias": "ACMESA.HUB1",
  "operationId": "internal-op-id",
  "createdAt": "2026-05-18T12:00:00Z"
}

Campos de impuestos:

Campo	Descripción
amount	Monto neto acreditado después de impuestos (lo que efectivamente recibió el cliente)
total	Monto bruto antes de impuestos
totalWithoutTaxes	Igual que amount — monto neto después de retenciones, disponible para mayor claridad
taxes	Monto de impuestos retenidos por el proveedor. total - taxes = amount

En la mayoría de las transferencias no hay retenciones y total === amount con taxes === 0. Para transferencias argentinas que incluyen retenciones impositivas, estos campos contienen el desglose.

Headers enviados por Basilic:

Header	Valor
Content-Type	application/json
User-Agent	Basilic-Client-Callback/1.0
X-Basilic-Event-Id	UUID del evento
X-Basilic-Event-Type	client.cashin

Tu endpoint debe devolver HTTP 2xx para confirmar la entrega.

Resumen financiero

GET /api/v1/clients/{id}/balance devuelve el saldo a favor y la deuda del cliente, independientemente de la paginación de transacciones:

Campo	Fórmula
creditBalance	Transferencias brutas del cliente, menos los montos ya aplicados a facturas, menos los débitos
debt	Suma de los montos pendientes de las facturas abiertas del cliente
balance	creditBalance - debt
totalCashIn	Informativo: suma de todas las entradas cash_in (montos positivos)
totalCashOut	Informativo: suma absoluta de todas las entradas debit (montos negativos)
totalInvoiced	Informativo: suma del total_amount de todas las facturas del cliente

creditBalance y debt nunca se compensan entre sí antes de que este endpoint los calcule: un cliente puede tener a la vez un saldo a favor y una deuda. Un parámetro de consulta opcional hubId acota creditBalance a un PaymentHub; debt siempre cubre todas las facturas abiertas del cliente, en toda la empresa. Para el historial paginado de movimientos, usá GET /api/v1/clients/{id}/transactions.

Requisitos

• El PaymentHub debe tener CVUs de clientes dedicados habilitados (dedicated_client_cvus_enabled = true).
• Cada cliente puede tener como máximo un CVU por PaymentHub (relación 1:1 aplicada a nivel de API).
• El taxId (CUIT) del cliente debe ser único dentro de tu cuenta.