# API de Bucli

> Cobros recurrentes sobre Wompi para comercios en Colombia: clientes, productos y precios, suscripciones, cobros, pagos, cupones, reembolsos, checkout hospedado, portal del cliente, derechos y consumo, eventos y webhooks firmados. REST con JSON, al estilo de Stripe Billing.

Versión `2026-11-01` · URL base `https://api.bucli.co/v1` · autenticación `Authorization: Bearer sk_test_…` (pruebas) o `sk_live_…` (producción). Documentación: https://docs.bucli.co/

## Archivos

- [openapi.json](https://docs.bucli.co/openapi.json): OpenAPI 3.1: para Postman, Insomnia o un generador de código.
- [postman.json](https://docs.bucli.co/postman.json): La colección de Postman (v2.1), con cada endpoint y su cuerpo.
- [referencia.json](https://docs.bucli.co/referencia.json): La referencia completa en JSON, la misma que muestra la página.

## Convenciones

- Autenticación: `Authorization: Bearer sk_test_…` (pruebas, sandbox de Wompi) o `sk_live_…` (producción). La llave decide el modo. Las `pk_` solo crean checkouts desde el navegador.
- Ids con prefijo (`cus_`, `prod_`, `price_`, `sub_`, `in_`, `py_`, `pm_`, `evt_`, `we_`) y `object` en cada respuesta.
- `Idempotency-Key` en los POST: la misma clave repite la respuesta guardada (24 h, con `Idempotent-Replayed: true`); con otro cuerpo responde `409 idempotency_key_reused`. No se guardan los errores 5xx, 402, 404 ni 409 (reintentar con la misma clave vuelve a ejecutar la petición). La respuesta guardada no conserva secretos, URL con token ni el documento o el teléfono de tus clientes: esos campos vienen ocultos, y si la respuesta traía un secreto de firma o la URL de una sesión, el replay responde `409 webhook_secret_unavailable_on_replay` o `409 url_unavailable_on_replay`, con el id del objeto en `error.object_id` (y su tipo en `error.object_type`).
- Listas: `limit` (1 a 100, por defecto 10), `starting_after`, `ending_before` → `{object: "list", data, has_more, url}`.
- `expand[]=customer` trae el objeto relacionado completo (en listas, `expand[]=data.customer`): hasta 4 caminos por petición, de hasta 4 niveles.
- El cuerpo de una petición admite hasta 256 KB (`413 request_too_large`).
- Montos en pesos enteros (`89900` = $89.900); fechas ISO 8601 en UTC. `created` y `updated` (último cambio) van en el mismo formato: usa `updated` para no pisar tu copia local con un dato más viejo.
- Versión: `Bucli-Version` (vigente: `2026-11-01`); tu cuenta queda fijada a la de su creación.
- Cada respuesta trae `Request-Id`; cada error, `{error: {type, code, message, param, doc_url, request_id}}`.
- Límite por llave: 100 peticiones por segundo en producción y 25 en pruebas, con cabeceras `RateLimit-*`; además, todas las llaves de tu cuenta juntas: 200 por segundo en producción y 50 en pruebas. Una llave `pk_` cuenta por llave y dirección IP (10 por segundo). Una lista con `expand[]` cuesta `1 + limit × caminos ÷ 20` peticiones.
- Eventos y webhooks: el orden de entrega no está garantizado. Cada evento trae `sequence` (crece con cada evento): compáralo, o vuelve a consultar el objeto, antes de actuar.
- Llaves de producción: en el dashboard las crea, renombra, regenera o revoca solo el propietario o un administrador (`developers.api_keys.manage_live`), confirmando su identidad; el rol Desarrollador gestiona las de pruebas. Cada llave de producción nueva o regenerada se avisa por correo al propietario, y las llaves que creó un miembro se revocan cuando sale del equipo.

## Tu primera suscripción en cuatro pasos

1. Crea el plan (un precio con su producto).
2. Crea un checkout para tu cliente.
3. Redirige al cliente a la `url` del checkout.
4. Recibe `subscription.created` e `invoice.paid` en tu webhook.

```bash
# 1. Crear el plan
curl https://api.bucli.co/v1/prices \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: plan-gold-1" \
  -H "Content-Type: application/json" \
  -d '{"product": {"name": "Plan Gold"}, "amount": 89900, "interval": "month"}'

# 2. Crear el checkout (responde una url)
curl https://api.bucli.co/v1/checkout_sessions \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"price": "price_…", "customer_email": "ana@ejemplo.co",
       "success_url": "https://miapp.co/gracias", "cancel_url": "https://miapp.co/planes"}'

# 3. Redirige a tu cliente a la url recibida.
# 4. Tu servidor recibe subscription.created e invoice.paid en tu webhook.
```

```javascript
const BASE = "https://api.bucli.co/v1";
const headers = {
  Authorization: `Bearer ${process.env.BUCLI_SECRET_KEY}`,
  "Content-Type": "application/json",
};

// 1. Crear el plan
const price = await fetch(`${BASE}/prices`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "plan-gold-1" },
  body: JSON.stringify({ product: { name: "Plan Gold" }, amount: 89900, interval: "month" }),
}).then((r) => r.json());

// 2. Crear el checkout
const session = await fetch(`${BASE}/checkout_sessions`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    price: price.id,
    customer_email: "ana@ejemplo.co",
    success_url: "https://miapp.co/gracias",
    cancel_url: "https://miapp.co/planes",
  }),
}).then((r) => r.json());

// 3. Redirigir (Express)
res.redirect(303, session.url);

// 4. El webhook: ver «Verificar la firma».
```

```python
import os

import requests

BASE = "https://api.bucli.co/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BUCLI_SECRET_KEY']}"}

# 1. Crear el plan
price = requests.post(
    f"{BASE}/prices",
    headers={**HEADERS, "Idempotency-Key": "plan-gold-1"},
    json={"product": {"name": "Plan Gold"}, "amount": 89900, "interval": "month"},
    timeout=30,
).json()

# 2. Crear el checkout
session = requests.post(
    f"{BASE}/checkout_sessions",
    headers=HEADERS,
    json={
        "price": price["id"],
        "customer_email": "ana@ejemplo.co",
        "success_url": "https://miapp.co/gracias",
        "cancel_url": "https://miapp.co/planes",
    },
    timeout=30,
).json()

# 3. Redirigir a session["url"] (Django: return redirect(session["url"])).
# 4. El webhook: ver «Verificar la firma».
```

```php
<?php
$base = 'https://api.bucli.co/v1';
$key = getenv('BUCLI_SECRET_KEY');

function bucli($method, $url, $key, $body, $idempotencyKey = null) {
    $headers = ["Authorization: Bearer $key", 'Content-Type: application/json'];
    if ($idempotencyKey) { $headers[] = "Idempotency-Key: $idempotencyKey"; }
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_POSTFIELDS => json_encode($body),
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $response = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $response;
}

// 1. Crear el plan
$price = bucli('POST', "$base/prices", $key,
    ['product' => ['name' => 'Plan Gold'], 'amount' => 89900, 'interval' => 'month'], 'plan-gold-1');

// 2. Crear el checkout
$session = bucli('POST', "$base/checkout_sessions", $key, [
    'price' => $price['id'],
    'customer_email' => 'ana@ejemplo.co',
    'success_url' => 'https://miapp.co/gracias',
    'cancel_url' => 'https://miapp.co/planes',
]);

// 3. Redirigir
header('Location: ' . $session['url'], true, 303);

// 4. El webhook: ver «Verificar la firma».
```

## Códigos de error

| Código | HTTP | Tipo | Qué significa |
|---|---|---|---|
| `parameter_missing` | 400 | `invalid_request_error` | Falta un parámetro obligatorio (`param` dice cuál). |
| `parameter_invalid` | 400 | `invalid_request_error` | Un parámetro tiene un valor que no sirve. |
| `parameter_unknown` | 400 | `invalid_request_error` | Enviaste un parámetro que no existe en esa ruta. |
| `invalid_json` | 400 | `invalid_request_error` | El cuerpo no es JSON válido. |
| `request_too_large` | 413 | `invalid_request_error` | El cuerpo supera los 256 KB. |
| `resource_missing` | 404 | `invalid_request_error` | No existe ese id en este modo de esta cuenta. |
| `url_invalid` | 400 | `invalid_request_error` | La URL no es HTTPS o apunta a una red interna. |
| `api_version_invalid` | 400 | `invalid_request_error` | La cabecera Bucli-Version no es una versión vigente. |
| `mode_mismatch` | 400 | `invalid_request_error` | La cabecera Bucli-Mode contradice el modo de la llave. |
| `api_key_missing` | 401 | `authentication_error` | No enviaste la cabecera Authorization. |
| `authorization_header_invalid` | 401 | `authentication_error` | Authorization no es «Bearer <llave>». |
| `api_key_invalid` | 401 | `authentication_error` | La llave no existe. |
| `api_key_revoked` | 401 | `authentication_error` | La llave fue revocada o regenerada. |
| `authentication_required` | 401 | `authentication_error` | La sesión del dashboard venció. |
| `no_active_subscription` | 402 | `billing_error` | La cuenta no tiene plan de Bucli. |
| `subscription_read_only` | 402 | `billing_error` | Tu plan de Bucli está en solo lectura: no se escribe. |
| `module_not_active` | 403 | `permission_error` | Tu plan no incluye la API. |
| `feature_not_available` | 403 | `permission_error` | Tu plan no incluye esto (los webhooks: Pro). |
| `secret_key_required` | 403 | `permission_error` | Una llave publicable (pk_) no puede hacer esto. |
| `permission_denied` | 403 | `permission_error` | Tu rol en el equipo no tiene ese permiso (dashboard). |
| `account_forbidden` | 403 | `permission_error` | No eres miembro de esa cuenta (dashboard). |
| `support_read_only` | 403 | `permission_error` | Sesión de soporte de Bucli de solo lectura. |
| `route_not_found` | 404 | `invalid_request_error` | La ruta no existe. |
| `method_not_allowed` | 405 | `invalid_request_error` | Esa ruta no acepta ese método. |
| `resource_already_exists` | 409 | `invalid_request_error` | Ya existe (un cliente con ese correo). |
| `idempotency_key_in_use` | 409 | `idempotency_error` | Otra petición con esa Idempotency-Key sigue en curso. |
| `idempotency_key_reused` | 409 | `idempotency_error` | Esa Idempotency-Key ya se usó con otro cuerpo. |
| `webhook_secret_unavailable_on_replay` | 409 | `invalid_request_error` | La respuesta repetida traía un secreto de firma, que se muestra una sola vez: regenéralo con `roll_secret`. `error.object_id` trae el id del endpoint (`we_…`) y `error.object_type`, `webhook_endpoint`. |
| `url_unavailable_on_replay` | 409 | `invalid_request_error` | La respuesta repetida traía una URL con token. `error.object_id` trae el id de la sesión y `error.object_type` su tipo: una de checkout (`cs_…`) se consulta con `GET /checkout_sessions/{id}`, que trae su `url`; una del portal (`bps_…`) no la vuelve a mostrar: crea otra con una clave nueva. |
| `reauth_failed` | 403 | `permission_error` | Dashboard: falta o no es válida la confirmación de identidad. |
| `code_required` | 403 | `permission_error` | Dashboard: pide el código por correo y envíalo en `code`. |
| `reauth_locked` | 429 | `rate_limit_error` | Dashboard: demasiados intentos de confirmar la identidad. |
| `customer_has_active_subscriptions` | 422 | `invalid_request_error` | El cliente tiene suscripciones en curso. |
| `customer_has_open_charges` | 422 | `invalid_request_error` | El cliente tiene cobros abiertos (una factura por cobrar o una oferta de plazo fijo). |
| `product_has_prices` | 422 | `invalid_request_error` | El producto tiene precios: archívalo. |
| `price_in_use` | 400 | `invalid_request_error` | El precio ya se usa: crea otro y archiva este. |
| `product_inactive` | 422 | `invalid_request_error` | El producto está archivado. |
| `active_subscriptions_limit_reached` | 402 | `billing_error` | Llegaste a las suscripciones activas de tu plan. |
| `price_inactive` | 400 | `invalid_request_error` | El precio está archivado. |
| `customer_deleted` | 400 | `invalid_request_error` | El cliente fue eliminado. |
| `payment_method_unavailable` | 400 | `invalid_request_error` | El método de pago no se puede cobrar. |
| `payment_method_rejected` | 402 | `billing_error` | Wompi rechazó el método de pago. |
| `invalid_metadata` | 400 | `invalid_request_error` | metadata no cumple los límites. |
| `subscription_not_updatable` | 409 | `invalid_request_error` | La suscripción ya terminó o no admite ese cambio. |
| `invalid_cancellation_reason` | 400 | `invalid_request_error` | Motivo de cancelación desconocido. |
| `invoice_not_open` | 409 | `invalid_request_error` | Solo se cobra una factura abierta. |
| `coupon_terms_frozen` | 400 | `invalid_request_error` | El cupón ya se aplicó: sus términos no cambian. |
| `coupon_not_redeemable` | 400 | `invalid_request_error` | El cupón no se puede aplicar (vencido, sin usos…). |
| `discount_missing` | 404 | `invalid_request_error` | La suscripción no tiene un descuento vigente. |
| `payment_not_refundable` | 400 | `invalid_request_error` | Ese pago no tiene nada que reembolsar. |
| `payment_not_voidable` | 400 | `invalid_request_error` | Solo se anula un cobro con tarjeta de hoy, completo. |
| `refund_in_progress` | 409 | `invalid_request_error` | Ya hay un reembolso de ese pago esperando a Wompi. |
| `subscription_not_pausable` | 409 | `invalid_request_error` | Solo se pausa una activa o en prueba al día. |
| `subscription_not_paused` | 409 | `invalid_request_error` | No está pausada ni tiene una pausa pedida. |
| `subscription_not_extendable` | 409 | `invalid_request_error` | Solo se extiende una activa al día. |
| `trial_not_running` | 409 | `invalid_request_error` | La suscripción no está en prueba. |
| `plan_price_required` | 400 | `invalid_request_error` | Ese precio no es de un plan (es de la prueba o de un adicional). |
| `fixed_term_offer_open` | 409 | `invalid_request_error` | Ese cliente ya tiene una oferta esperando el pago. |
| `fixed_term_offer_not_open` | 409 | `invalid_request_error` | Esa oferta ya no espera el pago. |
| `fixed_term_unavailable` | 409 | `invalid_request_error` | Faltan tus llaves de Wompi para crear el link. |
| `fixed_term_not_changeable` | 409 | `invalid_request_error` | Un plan por tiempo fijo no cambia de plan. |
| `manual_payment_reference_used` | 409 | `invalid_request_error` | Esa referencia ya se usó en otro pago manual. |
| `exchange_rate_unavailable` | 503 | `api_error` | No hay una tasa de cambio vigente: inténtalo más tarde. |
| `invoice_payment_in_progress` | 409 | `invalid_request_error` | Ya hay un cobro de esa factura en curso. |
| `invoice_charge_blocked` | 409 | `invalid_request_error` | Un freno de cobros (pausa de Bucli, tus cobros pausados o el tope diario) detiene el cobro; `message` dice cuál. La factura espera y se cobra sola cuando se libere. |
| `invoice_not_voidable` | 409 | `invalid_request_error` | Solo se anula una factura en borrador o abierta. |
| `price_not_recurring` | 400 | `invalid_request_error` | Ese precio es de pago único: no va en una suscripción. |
| `price_not_one_time` | 400 | `invalid_request_error` | Una factura única solo lleva precios de pago único. |
| `price_interval_mismatch` | 400 | `invalid_request_error` | Los ítems de una suscripción comparten intervalo. |
| `price_currency_mismatch` | 400 | `invalid_request_error` | Lo que se cobra junto va en una moneda: no se mezclan pesos y dólares. |
| `subscription_item_duplicate_price` | 400 | `invalid_request_error` | Ese precio ya es un ítem: cambia su cantidad. |
| `subscription_item_last` | 400 | `invalid_request_error` | El último ítem no se quita: cancela la suscripción. |
| `subscription_items_invalid` | 400 | `invalid_request_error` | Una suscripción tiene de 1 a 20 ítems. |
| `subscription_has_multiple_items` | 400 | `invalid_request_error` | Con varios ítems, cambia cada ítem. |
| `quantity_invalid` | 400 | `invalid_request_error` | La cantidad va de 1 a 10.000. |
| `proration_unavailable` | 400 | `invalid_request_error` | `proration_behavior` es `none` o `create_prorations`. |
| `quote_changed` | 409 | `invalid_request_error` | El cambio ya no cuesta lo que dijo la vista previa. |
| `payment_method_required` | 409 | `invalid_request_error` | Es la única tarjeta de una suscripción que se renueva. |
| `payment_method_is_default` | 409 | `invalid_request_error` | Esa tarjeta es la predeterminada. |
| `subscription_update_in_progress` | 409 | `invalid_request_error` | La suscripción tiene un cambio esperando su cobro. |
| `subscription_change_too_complex` | 400 | `invalid_request_error` | Un cambio que baja el valor y agrega precios nuevos va en dos pasos. |
| `billing_cycle_anchor_invalid` | 400 | `invalid_request_error` | El ancla no es futura o pasa de un ciclo. |
| `trial_end_invalid` | 400 | `invalid_request_error` | El fin de la prueba no es futuro o pasa de 730 días. |
| `invoice_lines_invalid` | 400 | `invalid_request_error` | De 1 a 20 líneas, o `amount` con `description`. |
| `invoice_amount_too_small` | 400 | `invalid_request_error` | Wompi no cobra un monto tan pequeño. |
| `customer_payment_method_missing` | 400 | `invalid_request_error` | El cliente no tiene tarjeta para cobrar. |
| `wompi_payment_source_missing` | 404 | `invalid_request_error` | Wompi no tiene esa fuente en tu cuenta. |
| `wompi_payment_source_unavailable` | 400 | `invalid_request_error` | La fuente no está AVAILABLE en Wompi. |
| `wompi_payment_source_unsupported` | 400 | `invalid_request_error` | Solo se importan tarjetas (CARD). |
| `payment_method_attached_elsewhere` | 409 | `invalid_request_error` | Esa fuente ya es de otro cliente. |
| `wompi_credentials_missing` | 409 | `invalid_request_error` | Conecta tus llaves de Wompi de este modo. |
| `wompi_credentials_invalid` | 400 | `invalid_request_error` | Wompi rechazó tus llaves: revísalas y verifícalas. |
| `wompi_unavailable` | 503 | `api_error` | Wompi no respondió: reintenta en unos minutos. |
| `checkout_session_not_expirable` | 409 | `invalid_request_error` | La sesión ya no está abierta o espera un cobro. |
| `webhook_endpoint_limit_reached` | 422 | `invalid_request_error` | Llegaste al máximo de endpoints del modo. |
| `feature_in_use` | 422 | `invalid_request_error` | Un producto, un ajuste o un medidor usa ese derecho. |
| `feature_unknown` | 400 | `invalid_request_error` | Esa clave no existe en tu vocabulario (`/features`). |
| `feature_type_mismatch` | 400 | `invalid_request_error` | Un módulo va en `features` y un límite en `limits`. |
| `limit_invalid` | 400 | `invalid_request_error` | Un límite es un entero ≥ 0, o -1 para ilimitado. |
| `limit_unlimited_not_allowed` | 400 | `invalid_request_error` | Ese límite nunca es ilimitado (-1). |
| `product_rules_invalid` | 400 | `invalid_request_error` | Las reglas o los derechos del producto no son válidos. |
| `trial_product_exists` | 409 | `invalid_request_error` | Ya tienes un producto de prueba activo en este modo. |
| `trial_product_locked` | 422 | `invalid_request_error` | Un producto con precios no cambia `is_trial`. |
| `trial_price_invalid` | 400 | `invalid_request_error` | El precio de prueba es recurrente, de $0 y con días. |
| `product_not_offered` | 400 | `invalid_request_error` | Ese producto es interno: no se vende. |
| `product_coming_soon` | 400 | `invalid_request_error` | Ese producto todavía no está a la venta. |
| `quantity_not_supported` | 400 | `invalid_request_error` | Ese producto no se vende por unidades. |
| `addon_requires_feature` | 400 | `invalid_request_error` | El adicional exige un módulo que la suscripción no tiene. |
| `addon_requires_plan` | 400 | `invalid_request_error` | El adicional solo se vende sobre ciertos planes. |
| `addon_included` | 400 | `invalid_request_error` | El plan ya incluye lo que da el adicional. |
| `addon_not_allowed_during_trial` | 400 | `invalid_request_error` | El adicional no se vende durante la prueba. |
| `trial_product_misused` | 400 | `invalid_request_error` | El producto de prueba va solo, en una suscripción nueva en prueba. |
| `trial_already_used` | 409 | `invalid_request_error` | Ya se dio una prueba con esa `trial_key`. |
| `meter_feature_missing` | 400 | `invalid_request_error` | Crea antes el límite `metered` con la misma clave. |
| `meter_inactive` | 409 | `invalid_request_error` | Ese medidor está apagado. |
| `quota_exhausted` | 402 | `billing_error` | Se acabó el cupo y no hay bolsas con saldo (el detalle viene en el error). |
| `entitlement_access_denied` | 402 | `billing_error` | El cliente no tiene acceso completo: no consume. |
| `usage_report_invalid` | 400 | `invalid_request_error` | `occurred_at` es futuro o demasiado viejo. |
| `usage_idempotency_key_reused` | 409 | `invalid_request_error` | Esa llave ya se usó con otra cantidad. |
| `grant_offer_price_invalid` | 400 | `invalid_request_error` | Una oferta se cobra con un precio `one_time` activo. |
| `grant_offer_unavailable` | 400 | `invalid_request_error` | Esa oferta de bolsa está archivada. |
| `grant_offer_requires_feature` | 400 | `invalid_request_error` | El cliente no tiene los módulos que exige la bolsa. |
| `grant_not_withdrawable` | 409 | `invalid_request_error` | Esa bolsa ya no está vigente. |
| `rate_limited` | 429 | `rate_limit_error` | Demasiadas peticiones: espera `Retry-After` segundos. |
| `internal_error` | 500 | `api_error` | Falló algo de nuestro lado: reintenta con la misma Idempotency-Key. |
| `engine_unavailable` | 503 | `api_error` | El motor de cobros no responde: reintenta en unos minutos. |

## Clientes

Quién paga tus suscripciones.

### El objeto `notice`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `ntc_…` |
| `object` | string | `notice` |
| `customer` | string | Cliente (expandible). |
| `subscription` | string | La suscripción de la que habla, o `null`. |
| `invoice` | string | La factura de la que habla, o `null`. |
| `kind` | enum | Tipo: receipt_activation, receipt_renewal, receipt_change, receipt_purchase, receipt_fixed_term, payment_failed, retries_exhausted, card_replace, payment_method_missing, card_expiring, renewal_upcoming, trial_ending, trial_ended, cancellation_scheduled, canceled, fixed_term_offer, fixed_term_ended. |
| `subject` | string | El asunto del correo. |
| `message` | string | El aviso en una frase (el de WhatsApp). |
| `channels` | object | `{email, whatsapp}`: `sent`, `failed` o `skipped` (sin correo, sin celular…). |
| `sent_at` | datetime | Cuándo terminó de salir. |
| `livemode` | boolean | `true` en producción. |
| `created` | datetime | Cuándo se creó. |

### El objeto `customer`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `cus_…` |
| `object` | string | `customer` |
| `external_id` | string | Tu id del cliente (`org-…`): único por cuenta y modo; `null` si no tiene. Con él, el correo puede repetirse (las empresas de un mismo dueño). |
| `email` | string | Correo; único por cuenta y modo entre los clientes sin `external_id`. |
| `name` | string | Nombre. |
| `phone` | string | Celular. |
| `legal_id_type` | enum | Tipo de documento: CC, CE, NIT, PP, TI, PPT. |
| `legal_id` | string | Número de documento. |
| `fiscal` | object | Datos fiscales para la factura electrónica (integración con Klopi), o `null`: `party_type` (`company` · `person`), `document_type` (`nit`, `cc`, `ce`, `pa`, `ti`, `rc`, `de`, `pep`, `ppt`, `te`, `nit_ext`, `nuip`), `document_number`, `verification_digit` (del NIT), `business_name` (razón social) o `first_name` y `last_name`, `email` (adonde llega la factura; si falta, el `email` del cliente), `address`, `country_code` (ISO-2, `CO` por defecto), `city_code` (DANE, en Colombia) o `city_name` (fuera de Colombia), `department`, `tax_regime` (`ordinary` · `simple`), `is_vat_responsible`, `is_great_contributor` (O-13), `is_self_withholder` (O-15), `rut_responsibilities` (otras, como `O-23`), `final_consumer`, `complete` (alcanza para facturar) y `source` (de dónde vienen: `api`, `import`, `checkout`, `portal` o `dashboard`). |
| `default_payment_method` | string | Método de pago predeterminado (expandible). |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### Crear un cliente

`POST /customers` · permiso `billing.customers.create` · admite `Idempotency-Key`

El correo es único por cuenta y modo: uno repetido responde `409 resource_already_exists`.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `email` | string | sí | Correo del cliente. |
| `external_id` | string | no | Tu id del cliente (hasta 120): único por modo. Con él, varios clientes pueden compartir correo (un cliente por empresa); un checkout público nunca encuentra un cliente con `external_id` por el correo. |
| `name` | string | no | Nombre. |
| `phone` | string | no | Celular. |
| `legal_id_type` | enum | no | Tipo de documento. Valores: `CC`, `CE`, `NIT`, `PP`, `TI`, `PPT`. |
| `legal_id` | string | no | Número de documento. |
| `fiscal` | object | no | Sus datos para la factura electrónica, ENTEROS (reemplazan los anteriores; `null` los quita): `party_type`, `document_type`, `document_number` (un NIT puede venir `900123456-8`), `verification_digit` (si falta, se calcula; si no cuadra, 400), `business_name` (empresa) o `first_name`/`last_name` (persona), `email` (adonde llega la factura), `address` y `city_code` (DANE, obligatorios en Colombia), `country_code` (por defecto `CO`; fuera de Colombia, `city_name`), `tax_regime`, `is_vat_responsible`, `is_great_contributor`, `is_self_withholder` y `rut_responsibilities` (solo con NIT colombiano), o `{"final_consumer": true}` si el comercio lo permite. Llena `legal_id_type`/`legal_id` si no los envías. Son los datos ya llenos que el cliente confirma o corrige en el checkout y el portal: lo que corrija ahí (o el comercio en el panel) ya no lo reemplaza tu `fiscal`, y la respuesta trae los datos vigentes con su `source`. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `customer`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_already_exists`.

```bash
curl -X POST "https://api.bucli.co/v1/customers" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"email": "…"}'
```

### Listar clientes

`GET /customers` · permiso `billing.customers.list`

Del más reciente al más antiguo. Los eliminados no aparecen.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `email` | string | no | Correo exacto (puede haber varios con `external_id`). |
| `external_id` | string | no | Tu id exacto. |
| `metadata[<clave>]` | string | no | Solo los que tienen ese par en su metadata. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`.

```bash
curl "https://api.bucli.co/v1/customers" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un cliente

`GET /customers/{id}` · permiso `billing.customers.retrieve`

Un cliente eliminado responde `{id, object, deleted: true}`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `customer`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/customers/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Actualizar un cliente

`PATCH /customers/{id}` · permiso `billing.customers.update`

Cambia solo lo que envías. Emite `customer.updated` con `previous_attributes`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `email` | string | no | Correo del cliente. |
| `external_id` | string | no | Tu id del cliente (hasta 120): único por modo. Con él, varios clientes pueden compartir correo (un cliente por empresa); un checkout público nunca encuentra un cliente con `external_id` por el correo. |
| `name` | string | no | Nombre. |
| `phone` | string | no | Celular. |
| `legal_id_type` | enum | no | Tipo de documento. Valores: `CC`, `CE`, `NIT`, `PP`, `TI`, `PPT`. |
| `legal_id` | string | no | Número de documento. |
| `fiscal` | object | no | Sus datos para la factura electrónica, ENTEROS (reemplazan los anteriores; `null` los quita): `party_type`, `document_type`, `document_number` (un NIT puede venir `900123456-8`), `verification_digit` (si falta, se calcula; si no cuadra, 400), `business_name` (empresa) o `first_name`/`last_name` (persona), `email` (adonde llega la factura), `address` y `city_code` (DANE, obligatorios en Colombia), `country_code` (por defecto `CO`; fuera de Colombia, `city_name`), `tax_regime`, `is_vat_responsible`, `is_great_contributor`, `is_self_withholder` y `rut_responsibilities` (solo con NIT colombiano), o `{"final_consumer": true}` si el comercio lo permite. Llena `legal_id_type`/`legal_id` si no los envías. Son los datos ya llenos que el cliente confirma o corrige en el checkout y el portal: lo que corrija ahí (o el comercio en el panel) ya no lo reemplaza tu `fiscal`, y la respuesta trae los datos vigentes con su `source`. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `customer`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_invalid`, `resource_already_exists`.

```bash
curl -X PATCH "https://api.bucli.co/v1/customers/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Eliminar un cliente

`DELETE /customers/{id}` · permiso `billing.customers.destroy`

Lo saca de las listas y libera su correo; sus facturas y pagos se conservan. Con suscripciones en curso (o incompletas) responde `422 customer_has_active_subscriptions`; con un cobro abierto (factura por cobrar u oferta de plazo fijo sin pagar) responde `422 customer_has_open_charges`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde `{id, object, deleted: true}`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `customer_has_active_subscriptions`, `customer_has_open_charges`.

```bash
curl -X DELETE "https://api.bucli.co/v1/customers/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Productos

Lo que vendes.

### El objeto `product`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `prod_…` |
| `object` | string | `product` |
| `key` | string | Tu código del producto («pro», «usuario-adicional»): único por modo; `null` si no tiene. |
| `name` | string | Nombre del plan («Plan Gold»). |
| `description` | string | Descripción. |
| `active` | boolean | `false`: archivado, no admite precios nuevos. |
| `entitlements` | object | Lo que da: `features` (claves de módulos de tu vocabulario, `/features`) y `limits` (`{clave: número}`, `-1` = ilimitado). Los derechos de una suscripción son los de sus productos combinados. |
| `is_addon` | boolean | Es un adicional (se vende sobre un plan base). |
| `is_trial` | boolean | Es tu producto de prueba: sus precios son de $0 con días de prueba, y una suscripción solo con él termina (`trial_ended`) al vencer la prueba, sin cobrar. |
| `kind` | enum | Qué es, leído de sus reglas y sus precios: `plan` (de él se hace una suscripción), `addon` (`is_addon`), `one_time` (todos sus precios son de pago único: un paquete) o `trial` (`is_trial`). |
| `active_prices` | array | Sus precios activos, del más barato al más caro (hasta 20): `{id, type, amount, currency, interval, interval_count, trial_days, nickname}`. Lo que una lista muestra de cuánto cuesta; el precio completo es `GET /prices/{id}`. |
| `supports_quantity` | boolean | Se vende por unidades: sus límites se multiplican por la cantidad. `false`: la cantidad es 1. |
| `addon_rules` | object | Reglas de venta de un adicional: `requires_features` (módulos que la suscripción ya debe tener), `allowed_base_products` (solo sobre estos planes), `skip_if_included` (no se vende si el plan ya da todos sus módulos) y `allowed_during_trial`. |
| `prorate_limits_on_add` | boolean | Agregado a mitad de ventana, sus cupos medidos dan la parte proporcional de los días que quedan. |
| `meter_window` | enum | Mientras es el plan base de la suscripción, la ventana en que cuentan los medidores (`subscription_lifetime` para una prueba o un plazo fijo); `null` = la de cada medidor. |
| `availability` | enum | `public` (a la venta), `coming_soon` (se lista apagado, no se vende) o `internal` (nunca se lista ni se vende). |
| `availability_note` | string | Nota de la disponibilidad («llega en enero»). |
| `storefront` | object | Para dibujar tu página de planes: `marketing_features`, `position`, `featured`, `visible_in_pricing`, `placement` (`main`: una tarjeta entre los planes principales; `secondary`: se vende, pero como una línea bajo ellos), `icon` y `group` (libre: `module`, `seats`, `units`…). |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### Crear un producto

`POST /products` · permiso `billing.products.create` · admite `Idempotency-Key`

Lo que vendes («Plan Gold»); el monto va en sus precios. Emite `product.created`.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `name` | string | sí | Nombre. |
| `description` | string | no | Descripción. |
| `active` | boolean | no | Activo (por defecto `true`). |
| `key` | string | no | Tu código del producto, único por modo. |
| `entitlements` | object | no | `{features: [claves], limits: {clave: número}}` de tu vocabulario; `-1` = ilimitado. Se reemplaza entero. |
| `is_addon` | boolean | no | Es un adicional. |
| `is_trial` | boolean | no | Es tu producto de prueba (uno activo por modo); no cambia si ya tiene precios. |
| `supports_quantity` | boolean | no | Se vende por unidades (por defecto `true`). |
| `requires_features` | array | no | Adicional: módulos que la suscripción ya debe tener. |
| `allowed_base_products` | array | no | Adicional: ids de los planes sobre los que se vende (vacío = todos). |
| `skip_if_included` | boolean | no | Adicional: no se vende si el plan ya da todos sus módulos. |
| `allowed_during_trial` | boolean | no | Adicional: se vende durante la prueba (por defecto `false`). |
| `prorate_limits_on_add` | boolean | no | Prorratear sus cupos medidos al agregarlo a mitad de ventana. |
| `meter_window` | enum | no | Mientras sea el plan base de la suscripción, los medidores cuentan en esta ventana y no en la suya (`subscription_lifetime`: la prueba o el plazo fijo de punta a punta). Vacío = la del medidor. Valores: `calendar_month`, `billing_period`, `subscription_lifetime`. |
| `availability` | enum | no | Disponibilidad. Valores: `public`, `coming_soon`, `internal`. |
| `availability_note` | string | no | Nota de disponibilidad. |
| `marketing_features` | array | no | Textos de la vitrina (hasta 30). |
| `position` | integer | no | Orden en la vitrina. |
| `featured` | boolean | no | Destacado. |
| `visible_in_pricing` | boolean | no | Visible en la vitrina (por defecto `true`). |
| `placement` | enum | no | En la vitrina: `main` (por defecto), una tarjeta entre los planes principales; `secondary`, una línea bajo ellos. Valores: `main`, `secondary`. |
| `icon` | string | no | Ícono. |
| `group` | string | no | Grupo libre (`module`, `seats`, `units`…). |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `product`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_already_exists`, `feature_unknown`, `feature_type_mismatch`, `limit_invalid`, `limit_unlimited_not_allowed`, `product_rules_invalid`, `trial_product_exists`.

```bash
curl -X POST "https://api.bucli.co/v1/products" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "…"}'
```

### Listar productos

`GET /products` · permiso `billing.products.list`

Del más reciente al más antiguo.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `active` | boolean | no | Solo activos o archivados. |
| `key` | string | no | Tu código exacto. |
| `availability` | enum | no | Disponibilidad. Valores: `public`, `coming_soon`, `internal`. |
| `is_addon` | boolean | no | Solo adicionales o solo planes. |
| `is_trial` | boolean | no | Solo el producto de prueba. |
| `group` | string | no | Grupo exacto. |
| `visible_in_pricing` | boolean | no | Solo los visibles en la vitrina. |
| `placement` | enum | no | Solo los de esa ubicación en la vitrina. Valores: `main`, `secondary`. |
| `kind` | enum | no | Solo los de ese tipo (`kind`). Valores: `plan`, `addon`, `one_time`, `trial`. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `parameter_invalid`.

```bash
curl "https://api.bucli.co/v1/products" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un producto

`GET /products/{id}` · permiso `billing.products.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `product`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/products/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Actualizar o archivar un producto

`PATCH /products/{id}` · permiso `billing.products.update`

`active: false` lo archiva. Cambiar lo que da (`entitlements`, `supports_quantity`…) recalcula los derechos de todas sus suscripciones y emite `entitlements.updated` a cada una que cambie. Todo cambio emite `product.updated` con `previous_attributes`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `name` | string | no | Nombre. |
| `description` | string | no | Descripción. |
| `active` | boolean | no | Activo (por defecto `true`). |
| `key` | string | no | Tu código del producto, único por modo. |
| `entitlements` | object | no | `{features: [claves], limits: {clave: número}}` de tu vocabulario; `-1` = ilimitado. Se reemplaza entero. |
| `is_addon` | boolean | no | Es un adicional. |
| `is_trial` | boolean | no | Es tu producto de prueba (uno activo por modo); no cambia si ya tiene precios. |
| `supports_quantity` | boolean | no | Se vende por unidades (por defecto `true`). |
| `requires_features` | array | no | Adicional: módulos que la suscripción ya debe tener. |
| `allowed_base_products` | array | no | Adicional: ids de los planes sobre los que se vende (vacío = todos). |
| `skip_if_included` | boolean | no | Adicional: no se vende si el plan ya da todos sus módulos. |
| `allowed_during_trial` | boolean | no | Adicional: se vende durante la prueba (por defecto `false`). |
| `prorate_limits_on_add` | boolean | no | Prorratear sus cupos medidos al agregarlo a mitad de ventana. |
| `meter_window` | enum | no | Mientras sea el plan base de la suscripción, los medidores cuentan en esta ventana y no en la suya (`subscription_lifetime`: la prueba o el plazo fijo de punta a punta). Vacío = la del medidor. Valores: `calendar_month`, `billing_period`, `subscription_lifetime`. |
| `availability` | enum | no | Disponibilidad. Valores: `public`, `coming_soon`, `internal`. |
| `availability_note` | string | no | Nota de disponibilidad. |
| `marketing_features` | array | no | Textos de la vitrina (hasta 30). |
| `position` | integer | no | Orden en la vitrina. |
| `featured` | boolean | no | Destacado. |
| `visible_in_pricing` | boolean | no | Visible en la vitrina (por defecto `true`). |
| `placement` | enum | no | En la vitrina: `main` (por defecto), una tarjeta entre los planes principales; `secondary`, una línea bajo ellos. Valores: `main`, `secondary`. |
| `icon` | string | no | Ícono. |
| `group` | string | no | Grupo libre (`module`, `seats`, `units`…). |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `product`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_invalid`, `resource_already_exists`, `feature_unknown`, `feature_type_mismatch`, `limit_invalid`, `limit_unlimited_not_allowed`, `product_rules_invalid`, `trial_product_exists`, `trial_product_locked`.

```bash
curl -X PATCH "https://api.bucli.co/v1/products/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Eliminar un producto

`DELETE /products/{id}` · permiso `billing.products.destroy`

Solo uno sin precios; si tiene, archívalo (`422 product_has_prices`).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde `{id, object, deleted: true}`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `product_has_prices`.

```bash
curl -X DELETE "https://api.bucli.co/v1/products/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Precios

Cuánto y cada cuánto.

### El objeto `price`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `price_…` |
| `object` | string | `price` |
| `product` | string | Producto (expandible). |
| `nickname` | string | Nombre interno. |
| `type` | enum | `recurring` (se cobra cada ciclo: suscripciones) o `one_time` (pago único: facturas únicas, paquetes). |
| `amount` | integer | En la unidad de la moneda: pesos enteros (`89900` = $89.900) o centavos de dólar (`2900` = US$29). |
| `currency` | enum | `COP` o `USD`. Wompi cobra en pesos: un precio en dólares se convierte en cada cobro con la TRM vigente. |
| `interval` | enum | Cada cuánto: day, week, month, year. `null` en un pago único. |
| `interval_count` | integer | Cuántos intervalos por ciclo (1–36). `null` en un pago único. |
| `trial_days` | integer | Días de prueba gratis (0 en un pago único). |
| `recurring` | object | `interval`, `interval_count` y `trial_days` de un precio recurrente; `null` si es único. |
| `metered_rates` | object | `{clave_del_medidor: {unit_amount, per_units}}`: el excedente de cada límite medido. `{}` = sin excedente. |
| `active` | boolean | `false`: archivado, no admite suscripciones nuevas. |
| `in_use` | boolean | Si ya lo usa algo: una suscripción (o un cambio que espera la renovación), una factura, un enlace de pago, una sesión de checkout, un paquete o un plazo fijo. Mientras sea `false`, sus términos se pueden corregir con `PATCH`; después ya no cambian. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### Crear un precio

`POST /prices` · permiso `billing.prices.create` · admite `Idempotency-Key`

El primer paso: `product` es el id de un producto o `{"name": "Plan Gold"}` para crearlo en el mismo paso. El monto se corrige con `PATCH` mientras nada use el precio (`in_use`); después, para cambiarlo crea otro precio y archiva este.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `product` | string | sí | Id del producto, u objeto `{name, description?, metadata?, is_addon?, is_trial?}` para crearlo en el mismo paso (un `is_trial` lleva un precio recurrente de $0 con días de prueba). |
| `amount` | integer | sí | En la unidad de `currency`: pesos enteros (`89900`) o centavos de dólar (`2900`, mínimo `100`). `0` solo en el producto de prueba, cuyo precio es recurrente y con días de prueba. |
| `currency` | enum | no | `COP` (por defecto) o `USD`. Wompi cobra en pesos: un precio en dólares se convierte en cada cobro con la TRM vigente. Lo que se cobra junto (los ítems de una suscripción, un checkout, una factura única) va en una sola moneda (`400 price_currency_mismatch`). Valores: `COP`, `USD`. |
| `type` | enum | no | `recurring` (por defecto) o `one_time`: un pago único, sin intervalo ni prueba, que se vende en facturas únicas (`POST /invoices`), nunca en suscripciones ni checkouts. Valores: `recurring`, `one_time`. |
| `recurring` | object | no | `{interval, interval_count?, trial_days?}` (la forma de Stripe), en vez de los tres campos planos. |
| `interval` | enum | no | Por defecto `month`. Valores: `day`, `week`, `month`, `year`. |
| `interval_count` | integer | no | Por defecto 1. |
| `trial_days` | integer | no | Días de prueba (por defecto 0). |
| `nickname` | string | no | Nombre interno. |
| `active` | boolean | no | Por defecto `true`. |
| `metered_rates` | object | no | Excedente de un límite medido, solo en un precio recurrente: `{clave_del_medidor: {unit_amount, per_units?}}` — lo que pase del cupo y de las bolsas cuesta `unit_amount` cada `per_units` unidades (por defecto 1), hasta el tope del cliente (`overage_caps` de la suscripción). Sin tarifa, al agotarse responde `402 quota_exhausted`. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `price`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_missing`, `product_inactive`, `trial_price_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/prices" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"product": "…", "amount": 0}'
```

### Listar precios

`GET /prices` · permiso `billing.prices.list`



Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `product` | string | no | Solo los de este producto. |
| `active` | boolean | no | Activos o no. |
| `type` | enum | no | Solo recurrentes o solo únicos. Valores: `recurring`, `one_time`. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `parameter_invalid`.

```bash
curl "https://api.bucli.co/v1/prices" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un precio

`GET /prices/{id}` · permiso `billing.prices.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `price`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/prices/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Actualizar un precio

`PATCH /prices/{id}` · permiso `billing.prices.update`

`nickname`, `active`, `metadata` y `metered_rates` siempre. Los términos (`amount`, `currency`, `type`, el intervalo y la prueba) solo mientras nada use el precio (`in_use: false`); si ya lo usa algo responde `400 price_in_use`: crea otro precio y archiva este. Las suscripciones que ya lo usan nunca cambian.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `nickname` | string | no | Nombre interno. |
| `active` | boolean | no | Archivar o reactivar. |
| `metered_rates` | object | no | Reemplaza las tarifas de excedente. Aplican a las unidades que se tomen desde ahora; cada una conserva la tarifa con la que se tomó. |
| `amount` | integer | no | Solo sin uso. En la unidad de `currency`, como al crearlo. |
| `currency` | enum | no | Solo sin uso, y con `amount` en la unidad de la nueva moneda. Valores: `COP`, `USD`. |
| `type` | enum | no | Solo sin uso. Pasar a `one_time` quita el intervalo, la prueba y las tarifas de excedente; a `recurring`, queda mensual si no dices otro intervalo. Valores: `recurring`, `one_time`. |
| `recurring` | object | no | Solo sin uso. `{interval, interval_count?, trial_days?}`. |
| `interval` | enum | no | Solo sin uso. Valores: `day`, `week`, `month`, `year`. |
| `interval_count` | integer | no | Solo sin uso. |
| `trial_days` | integer | no | Solo sin uso. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `price`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_unknown`, `parameter_invalid`, `parameter_missing`, `price_in_use`, `trial_price_invalid`.

```bash
curl -X PATCH "https://api.bucli.co/v1/prices/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Suscripciones

El contrato recurrente.

### El objeto `subscription_change`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `sc_…` |
| `object` | string | `subscription_change` |
| `subscription` | string | Suscripción (expandible). |
| `invoice` | string | Factura que cobra el cambio (expandible). |
| `status` | enum | `pending` (esperando el cobro), `applied` (pagado y aplicado) o `failed` (no se cobró: nada cambió). |
| `amount` | integer | Lo que se cobra, en `currency`. |
| `currency` | string | La de la suscripción. |
| `quote` | object | La cotización cobrada, como la mostró la vista previa. |
| `applied_at` | datetime | Cuándo se aplicó. |
| `failed_at` | datetime | Cuándo falló. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Creado. |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### El objeto `subscription_action`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `sa_…` |
| `object` | string | `subscription_action` |
| `subscription` | string | La suscripción (`sub_…`). |
| `kind` | enum | `pause`, `resume`, `extend_period`, `extend_trial`, `end_trial`, `apply_coupon`, `remove_discount`, `manual_payment`, `void`, `refund` o `entitlements` (ajustó los derechos: `details` con `features_add`, `features_remove` y `limits` como quedaron, `previous` con los de antes, `cleared` y `keep_current`). |
| `actor` | string | Quién (la llave «nombre» o el correo de la persona). |
| `reason` | string | Por qué. |
| `details` | object | Lo que cambió (fechas antes y después, la factura, el reembolso…). |
| `livemode` | boolean | `true` en producción. |
| `created` | datetime | Cuándo. |

### El objeto `subscription`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `sub_…` |
| `object` | string | `subscription` |
| `status` | enum | Estado: incomplete, incomplete_expired, trialing, active, past_due, canceled, paused. |
| `customer` | string | Cliente (expandible). |
| `price` | string | Precio del primer ítem (expandible). Se conserva por compatibilidad: lo nuevo es `items`. |
| `items` | object | Lista (`{object: list, data, has_more, url}`) de los ítems de la suscripción: plan base, puestos adicionales y demás, cada uno `subscription_item` con su precio completo y su `quantity`. Siempre al menos uno. Cada periodo se factura la suma de todos. |
| `billing_cycle_anchor` | datetime | Desde dónde se cuentan los periodos (el inicio del primer periodo completo); `null` en suscripciones anteriores a este campo. |
| `pending_price` | string | Precio que aplica desde el próximo ciclo (expandible). |
| `default_payment_method` | string | Método con el que se cobra (expandible). |
| `latest_invoice` | string | Última factura (expandible). |
| `start_date` | datetime | Inicio. |
| `current_period_start` | datetime | Inicio del periodo en curso. |
| `current_period_end` | datetime | Fin del periodo en curso. |
| `next_billing_at` | datetime | Próximo cobro. |
| `trial_start` | datetime | Inicio de la prueba. |
| `trial_end` | datetime | Fin de la prueba. |
| `cancel_at_period_end` | boolean | Se cancelará al terminar el periodo. |
| `canceled_at` | datetime | Cuándo se pidió la cancelación. |
| `ended_at` | datetime | Cuándo terminó. |
| `cancellation_details` | object | `reason` y `comment` de la cancelación. |
| `pending_update` | object | El `subscription_change` que espera su cobro, o `null`. |
| `discount` | object | El `discount` vigente (el cupón aplicado), o `null`. |
| `pause_at_period_end` | boolean | `true`: al terminar el periodo pagado queda `paused` (ver «Pausar el cobro»). |
| `paused_at` | datetime | Desde cuándo está pausada, o `null`. |
| `resumes_at` | datetime | Cuándo se reanuda sola, o `null` (a mano). |
| `fixed_term_ends_at` | datetime | Un plan por tiempo fijo: cuándo termina (no renueva ni tiene gracia); `null` en una suscripción normal. |
| `overage_caps` | object | `{clave_del_medidor: valor}`: el tope de excedente que fijó el cliente; un medidor que no esté vale lo que cuesta el plan. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio de la suscripción o de cualquiera de sus ítems (ISO 8601, UTC, como `created`). Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### El objeto `subscription_quote`

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string | `subscription_quote` |
| `subscription` | string | La suscripción (`sub_…`). |
| `direction` | enum | `up`, `down` o `even`. |
| `applies` | enum | `now` (al pagarse, o ya si es gratis) o `renewal`. |
| `amount` | integer | Lo que se cobra ahora, en `currency` (el `expected_amount` del cambio). |
| `currency` | string | La de la suscripción. |
| `lines` | array | `[{description, amount}]`: lo que se cobra y los créditos (negativos). |
| `days_left` | integer | Días que quedan del periodo (hoy incluido). |
| `period_days` | integer | Días del periodo. |
| `restarts_period` | boolean | `true`: un ciclo más largo empieza un periodo hoy. |
| `below_minimum` | boolean | `true`: bajo el mínimo de Wompi, aplica gratis. |
| `period_start` | datetime | Inicio del periodo después del cambio. |
| `period_end` | datetime | Fin del periodo después del cambio. |
| `total_before` | integer | Lo que cuesta cada periodo hoy. |
| `total_after` | integer | Lo que costará cada periodo después del cambio. |

### Crear una suscripción

`POST /subscriptions` · permiso `billing.subscriptions.create` · admite `Idempotency-Key`

Para un cliente con un método de pago guardado. Un precio (`price`, con `quantity`) o varios ítems (`items`: plan base + puestos adicionales + adicionales, todos recurrentes y del mismo intervalo); cada periodo se cobra la suma. Sin prueba queda `incomplete` hasta el primer cobro aprobado. Con `billing_cycle_anchor` (una fecha futura, a no más de un ciclo) nace `active` sin cobrar nada ahora: el periodo actual va hasta esa fecha y ahí es el primer cobro — para migrar a quien ya pagó su periodo en otro sistema. `trial_end` fija el fin de la prueba con una fecha. En producción cuenta para el límite de tu plan (`402 active_subscriptions_limit_reached`): cuenta suscripciones, no ítems. Lo habitual es crearla con un checkout.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `customer` | string | sí | Id del cliente. |
| `price` | string | no | Id de un precio recurrente activo (o envía `items`). |
| `quantity` | integer | no | Cantidad del precio (por defecto 1). |
| `items` | array | no | En vez de `price`: `[{price, quantity?, metadata?}]`, de 1 a 20, sin precios repetidos y con el mismo intervalo. `price` de la suscripción será el del primero. |
| `default_payment_method` | string | no | Id de un método del cliente (por defecto, su predeterminado). |
| `trial_days` | integer | no | Días de prueba (por defecto, los del precio). |
| `trial_end` | datetime | no | Fin de la prueba (ISO 8601 o timestamp Unix): futuro, a no más de 730 días. En vez de `trial_days`. |
| `billing_cycle_anchor` | datetime | no | Fecha del primer cobro (ISO 8601 o timestamp Unix): futura, a no más de un ciclo del precio ni de 730 días. Nace `active`, sin factura ahora. No va con `trial_days` ni `trial_end`. |
| `proration_behavior` | enum | no | Al crear no hay nada que prorratear: `none` o `create_prorations` dan lo mismo. Valores: `none`, `create_prorations`. |
| `trial_key` | string | no | Una prueba por clave (el documento del cliente, un correo): si la suscripción empieza en prueba y la clave ya se usó — aunque sea otro cliente o la anterior ya terminó — responde `409 trial_already_used`. Sin prueba se ignora. |
| `overage_caps` | object | no | Tope de excedente por ventana: `{clave_del_medidor: valor}` (0 = sin excedente). Un medidor que no esté vale lo que cuesta el plan. Lo fija el cliente en tu SaaS. |
| `coupon` | string | no | Id de un cupón: rebaja desde la primera factura de periodo. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `subscription`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `resource_missing`, `parameter_invalid`, `coupon_not_redeemable`, `active_subscriptions_limit_reached`, `product_not_offered`, `product_coming_soon`, `quantity_not_supported`, `addon_requires_feature`, `addon_requires_plan`, `addon_included`, `addon_not_allowed_during_trial`, `trial_product_misused`, `trial_already_used`, `price_inactive`, `price_not_recurring`, `price_interval_mismatch`, `subscription_item_duplicate_price`, `subscription_items_invalid`, `quantity_invalid`, `billing_cycle_anchor_invalid`, `trial_end_invalid`, `proration_unavailable`.

```bash
curl -X POST "https://api.bucli.co/v1/subscriptions" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer": "…"}'
```

### Listar suscripciones

`GET /subscriptions` · permiso `billing.subscriptions.list`



Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `status` | enum | no | Estado. Valores: `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `canceled`, `paused`. |
| `customer` | string | no | Id del cliente. |
| `price` | string | no | Id del precio. |
| `metadata[<clave>]` | string | no | Solo las que tienen ese par en su metadata (`metadata[legacy_id]=123`). |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `parameter_invalid`.

```bash
curl "https://api.bucli.co/v1/subscriptions" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar una suscripción

`GET /subscriptions/{id}` · permiso `billing.subscriptions.retrieve`

Expande `customer`, `price`, `default_payment_method` o `latest_invoice`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `subscription`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/subscriptions/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Actualizar una suscripción

`PATCH /subscriptions/{id}` · permiso `billing.subscriptions.update`

`price` cambia el único ítem; una suscripción de varios ítems los cambia en `/subscription_items` (`400 subscription_has_multiple_items`) o todos a la vez con `items` y `create_prorations` — así cambia de ciclo un plan con adicionales: el primer ítem es el plan y todos van a su intervalo. Con `proration_behavior: none` el precio nuevo aplica desde el siguiente ciclo; con `create_prorations` subir se cobra ya prorrateado (un ciclo más largo empieza un periodo hoy) y aplica cuando se paga — responde `202` con el `subscription_change` mientras espera su cobro; si falla, la suscripción queda como estaba (`subscription.update_failed`) — y bajar (o un ciclo más corto) queda para la renovación.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `price` | string | no | Precio desde el próximo ciclo. |
| `items` | array | no | En vez de `price`, solo con `create_prorations` y `expected_amount`: todos los ítems después del cambio, `[{id?, price, quantity?}]` — `id` es un ítem actual (sin `quantity` conserva la suya); uno que no esté se quita. El ítem del plan va primero, y todos comparten su intervalo (`400 price_interval_mismatch`). |
| `default_payment_method` | string | no | Método con el que se cobra. |
| `cancel_at_period_end` | boolean | no | Cancelar al fin del periodo (o deshacerlo). |
| `proration_behavior` | enum | no | `none` (por defecto): aplica ya y se cobra desde el siguiente periodo. `create_prorations`: lo que sube el valor se cobra ya prorrateado y aplica cuando Wompi aprueba (`202` con el `subscription_change` si espera su cobro); lo que lo baja queda programado para la renovación. Pide antes la vista previa (`POST /subscriptions/{id}/preview`). Valores: `none`, `create_prorations`. |
| `expected_amount` | integer | no | Con `create_prorations`: lo que la vista previa dijo que cuesta ahora. Si ya no cuadra responde `409 quote_changed` con la cotización nueva en `quote`. |
| `overage_caps` | object | no | Cambia los topes de excedente: `{clave_del_medidor: valor}` (0 = sin excedente; `null` = vuelve al valor del plan). Las claves que no envíes quedan como estaban. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `subscription`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_missing`, `parameter_invalid`, `subscription_not_updatable`, `subscription_has_multiple_items`, `price_inactive`, `price_not_recurring`, `price_interval_mismatch`, `price_currency_mismatch`, `subscription_item_duplicate_price`, `subscription_item_last`, `subscription_items_invalid`, `subscription_change_too_complex`, `quantity_invalid`, `proration_unavailable`, `quote_changed`, `subscription_update_in_progress`, `payment_method_required`, `fixed_term_not_changeable`.

```bash
curl -X PATCH "https://api.bucli.co/v1/subscriptions/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Vista previa de un cambio

`POST /subscriptions/{id}/preview` · permiso `billing.subscriptions.update` · admite `Idempotency-Key`

Lo que cuesta AHORA cambiar la suscripción, con el mismo cálculo que hace el cambio con `create_prorations`: días calendario desde hoy hasta el fin del periodo sobre los días del periodo, cada línea redondeada a la unidad de la moneda. `direction`: `up` (se cobra ya y aplica al pagarse), `down` (queda para la renovación, sin cobro ni devolución) o `even` (aplica ya, gratis). Lo que queda bajo el mínimo de Wompi no se cobra (`below_minimum`). En prueba todo aplica ya, gratis. No cambia nada.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `price` | string | no | Cambio de plan de una suscripción de un ítem. |
| `items` | array | no | Todos los ítems después del cambio: `[{id?, price, quantity?}]` — `id` es un ítem actual (sin `quantity` conserva la suya); uno que no esté se quita. El ítem del plan va primero: si cambia de intervalo, todos van al suyo (cambio de ciclo de un plan con adicionales). |

Responde el objeto `subscription_quote`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_invalid`, `price_inactive`, `price_not_recurring`, `price_interval_mismatch`, `price_currency_mismatch`, `subscription_item_duplicate_price`, `product_not_offered`, `product_coming_soon`, `quantity_not_supported`, `addon_requires_feature`, `addon_requires_plan`, `addon_included`, `addon_not_allowed_during_trial`, `trial_product_misused`.

```bash
curl -X POST "https://api.bucli.co/v1/subscriptions/$ID/preview" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Cancelar una suscripción

`POST /subscriptions/{id}/cancel` · permiso `billing.subscriptions.cancel` · admite `Idempotency-Key`

Al instante, o al fin del periodo con `at_period_end: true`. Los reembolsos se hacen en Wompi.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `at_period_end` | boolean | no | Por defecto `false`. |
| `reason` | enum | no | Motivo. Valores: `requested_by_customer`, `requested_by_merchant`, `payment_failed`, `trial_ended`, `refunded`, `fixed_term_ended`. |
| `comment` | string | no | Comentario. |

Responde el objeto `subscription`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `subscription_not_updatable`.

```bash
curl -X POST "https://api.bucli.co/v1/subscriptions/$ID/cancel" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Pausar el cobro

`POST /subscriptions/{id}/pause` · permiso `billing.subscriptions.manage` · admite `Idempotency-Key`

El periodo pagado corre hasta su fin y luego la suscripción queda `paused`: solo lectura (sus derechos), sin deuda ni facturas, hasta que la reanudes — o sola en `resumes_at`. Solo una `active` o `trialing` sin pagos pendientes. Queda en la bitácora (`/actions`).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `resumes_at` | datetime | no | Cuándo se reanuda sola (después del fin del periodo). Sin ella, a mano. |
| `reason` | string | no | Por qué (queda en la bitácora). |

Responde el objeto `subscription`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `subscription_not_pausable`, `subscription_update_in_progress`, `parameter_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/subscriptions/$ID/pause" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Reanudar el cobro

`POST /subscriptions/{id}/resume` · permiso `billing.subscriptions.manage` · admite `Idempotency-Key`

Una pausa pedida que no ha empezado se deshace. Una suscripción `paused` empieza un periodo nuevo hoy (un día de cobro nuevo) y se cobra ya; sin tarjeta, la factura espera una y queda con pago atrasado.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `reason` | string | no | Por qué. |

Responde el objeto `subscription`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `subscription_not_paused`, `subscription_not_updatable`.

```bash
curl -X POST "https://api.bucli.co/v1/subscriptions/$ID/resume" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Extender el periodo

`POST /subscriptions/{id}/extend_period` · permiso `billing.subscriptions.manage` · admite `Idempotency-Key`

Días gratis: el periodo en curso termina después y el día de cobro se mueve con él. Solo una `active` sin pagos pendientes (en prueba, extiende la prueba).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `days` | integer | no | Cuántos días más (o `until`). |
| `until` | datetime | no | Hasta cuándo (o `days`). |
| `reason` | string | no | Por qué. |

Responde el objeto `subscription`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `subscription_not_extendable`, `subscription_update_in_progress`, `parameter_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/subscriptions/$ID/extend_period" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Extender la prueba

`POST /subscriptions/{id}/extend_trial` · permiso `billing.subscriptions.manage` · admite `Idempotency-Key`

La prueba termina en `trial_end` (el primer cobro se mueve con ella). Una prueba más larga se avisa de nuevo tres días antes.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `trial_end` | datetime | sí | Nuevo fin de la prueba. |
| `reason` | string | no | Por qué. |

Responde el objeto `subscription`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `trial_not_running`, `trial_end_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/subscriptions/$ID/extend_trial" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"trial_end": "…"}'
```

### Terminar la prueba

`POST /subscriptions/{id}/end_trial` · permiso `billing.subscriptions.manage` · admite `Idempotency-Key`

La prueba termina ya: se factura y se cobra el primer periodo (o, si solo tiene el producto de prueba y no se envía `price`, termina). Con `price` pasa a ese plan (el mismo control que cambiar el precio; con un cupón del 100 % el periodo queda pagado sin tarjeta).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `price` | string | no | El plan al que pasa (`price_…`): nunca el de la prueba ni el de un adicional. Con varios ítems, cámbialos antes. |
| `reason` | string | no | Por qué. |

Responde el objeto `subscription`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `trial_not_running`, `plan_price_required`, `price_inactive`, `price_not_recurring`, `price_currency_mismatch`, `subscription_has_multiple_items`, `subscription_update_in_progress`, `fixed_term_not_changeable`, `product_not_offered`, `product_coming_soon`, `quantity_not_supported`.

```bash
curl -X POST "https://api.bucli.co/v1/subscriptions/$ID/end_trial" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Aplicar un cupón

`POST /subscriptions/{id}/discount` · permiso `billing.subscriptions.manage` · admite `Idempotency-Key`

Reemplaza el descuento vigente (uno por suscripción). Rebaja el cobro (`invoice`) del periodo que sigue abierto (si no hay un cobro en curso; nunca la sube: emite `invoice.updated`, o la paga si queda en $0 y la suscripción se activa) y las de los periodos que vienen. Un cupón `once` se aplica una vez por suscripción; uno en valor fijo, solo en su moneda.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `coupon` | string | sí | Id del cupón. |
| `reason` | string | no | Por qué. |

Responde el objeto `subscription`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `coupon_not_redeemable`, `subscription_not_updatable`.

```bash
curl -X POST "https://api.bucli.co/v1/subscriptions/$ID/discount" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"coupon": "…"}'
```

### Quitar el descuento

`DELETE /subscriptions/{id}/discount` · permiso `billing.subscriptions.manage`

Los cobros (`invoice`) ya abiertos lo conservan.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `reason` | string | no | Por qué. |

Responde el objeto `subscription`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `discount_missing`.

```bash
curl -X DELETE "https://api.bucli.co/v1/subscriptions/$ID/discount" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Bitácora de la suscripción

`GET /subscriptions/{id}/actions` · permiso `billing.subscriptions.retrieve`

Lo que se hizo a mano (pausa, días gratis, cupones, pagos manuales, reembolsos): quién, por qué y el detalle, de lo más reciente a lo más antiguo.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/subscriptions/$ID/actions" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Ítems de suscripción

Plan base, puestos y adicionales.

### El objeto `subscription_item`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `si_…` (`null` solo un momento después de un despliegue, en una suscripción anterior). |
| `object` | string | `subscription_item` |
| `subscription` | string | Suscripción (expandible). |
| `price` | object | El precio completo (recurrente, con el intervalo de la suscripción). |
| `quantity` | integer | Cantidad (puestos, licencias): se cobra `price.amount × quantity` cada periodo. |
| `scheduled_quantity` | integer | Cantidad desde la renovación (un cambio con `create_prorations` que baja el valor); `0` = se quita. `null` = sin cambio. |
| `scheduled_price` | string | Precio desde la renovación (`price_…`), o `null`. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### Agregar un ítem a una suscripción

`POST /subscription_items` · permiso `billing.subscription_items.create` · admite `Idempotency-Key`

Un precio recurrente × cantidad (un puesto adicional, un adicional), con el intervalo de la suscripción. Con `proration_behavior: none` se cobra desde el SIGUIENTE periodo. Con `create_prorations` se cobra ya por los días que quedan y el ítem llega cuando se paga (`202` con el `subscription_change`); bajo el mínimo de Wompi entra gratis hasta la renovación; agregar uno que estaba por quitarse lo deshace. Emite `subscription.updated` con los ítems anteriores en `previous_attributes.items`.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `subscription` | string | sí | Id de la suscripción. |
| `price` | string | sí | Id de un precio recurrente activo. |
| `quantity` | integer | no | Cantidad (por defecto 1). |
| `proration_behavior` | enum | no | `none` (por defecto): aplica ya y se cobra desde el siguiente periodo. `create_prorations`: lo que sube el valor se cobra ya prorrateado y aplica cuando Wompi aprueba (`202` con el `subscription_change` si espera su cobro); lo que lo baja queda programado para la renovación. Pide antes la vista previa (`POST /subscriptions/{id}/preview`). Valores: `none`, `create_prorations`. |
| `expected_amount` | integer | no | Con `create_prorations`: lo que la vista previa dijo que cuesta ahora. Si ya no cuadra responde `409 quote_changed` con la cotización nueva en `quote`. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `subscription_item`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_missing`, `price_inactive`, `price_not_recurring`, `price_interval_mismatch`, `subscription_item_duplicate_price`, `subscription_items_invalid`, `quantity_invalid`, `subscription_not_updatable`, `proration_unavailable`, `product_not_offered`, `product_coming_soon`, `quantity_not_supported`, `addon_requires_feature`, `addon_requires_plan`, `addon_included`, `addon_not_allowed_during_trial`, `trial_product_misused`.

```bash
curl -X POST "https://api.bucli.co/v1/subscription_items" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"subscription": "…", "price": "…"}'
```

### Listar los ítems de una suscripción

`GET /subscription_items` · permiso `billing.subscription_items.list`

Del más reciente al más antiguo; con `subscription`, solo los de esa suscripción (que ya los trae todos en `items`).

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `subscription` | string | no | Id de la suscripción. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/subscription_items" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un ítem

`GET /subscription_items/{id}` · permiso `billing.subscription_items.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `subscription_item`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/subscription_items/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Cambiar un ítem

`PATCH /subscription_items/{id}` · permiso `billing.subscription_items.update`

La cantidad o el precio (recurrente, mismo intervalo). Con `none`, desde el siguiente periodo; con `create_prorations`, subir se cobra ya prorrateado y bajar queda para la renovación (`scheduled_quantity` / `scheduled_price`). Cambiar el precio del primer ítem reemplaza un `pending_price`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `price` | string | no | Otro precio recurrente del mismo intervalo. |
| `quantity` | integer | no | Cantidad nueva. |
| `proration_behavior` | enum | no | `none` (por defecto): aplica ya y se cobra desde el siguiente periodo. `create_prorations`: lo que sube el valor se cobra ya prorrateado y aplica cuando Wompi aprueba (`202` con el `subscription_change` si espera su cobro); lo que lo baja queda programado para la renovación. Pide antes la vista previa (`POST /subscriptions/{id}/preview`). Valores: `none`, `create_prorations`. |
| `expected_amount` | integer | no | Con `create_prorations`: lo que la vista previa dijo que cuesta ahora. Si ya no cuadra responde `409 quote_changed` con la cotización nueva en `quote`. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `subscription_item`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_invalid`, `price_inactive`, `price_not_recurring`, `price_interval_mismatch`, `subscription_item_duplicate_price`, `quantity_invalid`, `subscription_not_updatable`, `proration_unavailable`, `product_not_offered`, `product_coming_soon`, `quantity_not_supported`, `addon_requires_feature`, `addon_requires_plan`, `addon_included`, `addon_not_allowed_during_trial`, `trial_product_misused`.

```bash
curl -X PATCH "https://api.bucli.co/v1/subscription_items/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Quitar un ítem

`DELETE /subscription_items/{id}` · permiso `billing.subscription_items.destroy`

Deja de cobrarse desde el siguiente periodo, sin reembolso. Con `create_prorations` el ítem se queda hasta la renovación (`scheduled_quantity: 0`) y se responde el ítem; agregarlo antes lo deshace. El último ítem no se quita (`400 subscription_item_last`): cancela la suscripción.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `proration_behavior` | enum | no | `none` (por defecto, se quita ya) o `create_prorations` (se queda hasta la renovación). Valores: `none`, `create_prorations`. |
| `expected_amount` | integer | no | Con `create_prorations`: `0` (quitar nunca cobra). |

Responde `{id, object, deleted: true}`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `subscription_item_last`, `subscription_not_updatable`, `proration_unavailable`.

```bash
curl -X DELETE "https://api.bucli.co/v1/subscription_items/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Métodos de pago

Tarjetas y Nequi guardados en Wompi.

### El objeto `payment_method`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `pm_…` |
| `object` | string | `payment_method` |
| `type` | enum | `card` o `nequi`. |
| `status` | enum | Estado: pending, available, failed, detached, suspended. |
| `customer` | string | Cliente (expandible); `null` si se quitó. |
| `is_default` | boolean | Si es el predeterminado del cliente. |
| `is_backup` | boolean | Si es la de respaldo: se intenta enseguida cuando la predeterminada rechaza. |
| `suspended` | object | `{at, reason}` de un rechazo duro (robada, perdida, vencida…): no se vuelve a cobrar. `null` si no. |
| `card` | object | `brand`, `last4`, `exp_month`, `exp_year` (solo tarjetas). |
| `nequi` | object | `phone_last4` (solo Nequi). |
| `imported` | object | `at` y `wompi_payment_source_id` si se importó de tu cuenta de Wompi (`POST /payment_methods`); `null` si el cliente la guardó en el checkout o el portal. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### Listar los métodos de pago de un cliente

`GET /customers/{id}/payment_methods` · permiso `billing.payment_methods.list`

Las tarjetas y cuentas Nequi que guardó en el checkout o el portal (la API no las crea: PCI).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/customers/$ID/payment_methods" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Importar una fuente de pago de Wompi

`POST /payment_methods` · permiso `billing.payment_methods.create` · admite `Idempotency-Key`

Para migrar a Bucli a un cliente que ya tiene su tarjeta guardada en TU cuenta de Wompi (sin pedírsela otra vez). Bucli consulta la fuente en Wompi con tu llave privada: tiene que existir en tu cuenta, estar `AVAILABLE` y ser `CARD`; guarda la marca, los últimos cuatro, el vencimiento y la evidencia de la importación (cuándo, con qué llave, la respuesta de Wompi). Guarda tu id anterior en `metadata.legacy_id`. Idempotente por fuente: la misma para el mismo cliente responde `200` con el método ya guardado; para otro cliente, `409 payment_method_attached_elsewhere`. Queda predeterminado con `make_default` o si el cliente no tenía uno. Solo con la llave secreta (`sk_`), desde tu servidor. Emite `payment_method.attached`.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `customer` | string | sí | Id del cliente (`cus_…`). |
| `wompi_payment_source_id` | string | sí | Id numérico de la fuente de pago en Wompi. |
| `make_default` | boolean | no | Hacerla la predeterminada (por defecto `false`). |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `payment_method`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_missing`, `customer_deleted`, `secret_key_required`, `wompi_payment_source_missing`, `wompi_payment_source_unavailable`, `wompi_payment_source_unsupported`, `payment_method_attached_elsewhere`, `wompi_credentials_missing`, `wompi_credentials_invalid`, `wompi_unavailable`.

```bash
curl -X POST "https://api.bucli.co/v1/payment_methods" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer": "…", "wompi_payment_source_id": "…"}'
```

### Consultar un método de pago

`GET /payment_methods/{id}` · permiso `billing.payment_methods.list`

Marca, últimos cuatro y vencimiento; nunca el número de la tarjeta.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `payment_method`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/payment_methods/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Hacer predeterminado un método de pago

`POST /payment_methods/{id}/default` · permiso `billing.payment_methods.default` · admite `Idempotency-Key`

Si el cliente tiene una suscripción con pago atrasado, el motor reintenta el cobro.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `payment_method`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `payment_method_unavailable`.

```bash
curl -X POST "https://api.bucli.co/v1/payment_methods/$ID/default" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Hacer de respaldo un método de pago

`POST /payment_methods/{id}/backup` · permiso `billing.payment_methods.default` · admite `Idempotency-Key`

La segunda tarjeta del cliente: en cada ronda de cobro se intenta enseguida después de la predeterminada, y pasa a predeterminada si esa se suspende (un rechazo duro) o se quita. Solo una por cliente.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `payment_method`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `payment_method_unavailable`, `payment_method_is_default`.

```bash
curl -X POST "https://api.bucli.co/v1/payment_methods/$ID/backup" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Quitar un método de pago

`DELETE /payment_methods/{id}` · permiso `billing.payment_methods.destroy`

Responde el método con `customer: null`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `payment_method`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `payment_method_required`.

```bash
curl -X DELETE "https://api.bucli.co/v1/payment_methods/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Cobros (facturas)

Lo que cuesta cada periodo: el objeto `invoice`, que en el panel se llama «cobro». No es la factura electrónica de la DIAN: esa la emite tu facturador (o la integración con Klopi, `fiscal_document`).

### El objeto `invoice_line`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `il_…` |
| `object` | string | `invoice_line` |
| `invoice` | string | Factura (expandible). |
| `description` | string | Qué se cobra («Puesto adicional × 3»). |
| `price` | object | El precio completo, o `null` en un monto libre. |
| `subscription_item` | string | Ítem de la suscripción que la originó, o `null`. |
| `product` | string | El producto de la línea (`prod_…`), o `null` en un monto libre o un excedente. |
| `group` | string | El `group` del producto (para comisiones por plan y adicionales), o `null`. |
| `is_addon` | boolean | `true` si el producto es un adicional. |
| `quantity` | integer | Cantidad. |
| `unit_amount` | integer | Valor unitario, en la moneda de la factura. |
| `amount` | integer | `unit_amount × quantity` (precio de lista). |
| `discount_amount` | integer | Lo que el cupón le rebaja a esta línea. |
| `currency` | string | La de la factura. |
| `period_start` | datetime | Inicio del periodo que cubre (`null` en un pago único). |
| `period_end` | datetime | Fin del periodo que cubre. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |

### El objeto `invoice`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `in_…` |
| `object` | string | `invoice` |
| `number` | string | Consecutivo de la cuenta. |
| `status` | enum | Estado: draft, open, paid, void, uncollectible. |
| `customer` | string | Cliente (expandible). |
| `subscription` | string | Suscripción (expandible). |
| `price` | string | Precio de la primera línea (expandible). |
| `default_payment_method` | string | Método con que se cobra una factura única (expandible); `null`: el de la suscripción o el predeterminado del cliente. |
| `amount` | integer | Lo que se cobra: `subtotal` − `discount_amount`, en la moneda de la factura. |
| `subtotal` | integer | La suma de las líneas a precio de lista. |
| `discount_amount` | integer | Lo que rebajó el cupón (la suma de `discount_amount` de las líneas). |
| `discount` | string | El `discount` que la rebajó (`di_…`), o `null`. |
| `currency` | enum | `COP` o `USD`: la de sus precios. |
| `charged_amount` | integer | Lo que Wompi cobró, en pesos (al pagarse); `null` antes. |
| `exchange_rate` | string | Pesos por unidad de `currency` con que se cobró (`"1"` en pesos); `null` antes de pagarse. |
| `lines` | object | Lista (`{object: list, data, has_more, url}`) de las líneas `invoice_line`: un ítem de la suscripción por periodo, un precio único × cantidad o un monto libre. |
| `retry` | boolean | Si un cobro rechazado se reintenta solo según tu calendario de reintentos. `true` en las facturas de suscripción; en una factura única, lo que enviaste (por defecto `false`). |
| `billing_reason` | enum | Motivo: subscription_create, subscription_cycle, subscription_update, payment_link, manual, fixed_term. |
| `description` | string | Descripción. |
| `period_start` | datetime | Inicio del periodo facturado. |
| `period_end` | datetime | Fin del periodo facturado. |
| `attempt_count` | integer | Intentos de cobro hechos. |
| `next_payment_attempt` | datetime | Próximo reintento. |
| `paid_at` | datetime | Cuándo se pagó. |
| `voided_at` | datetime | Cuándo se anuló. |
| `fiscal_document` | object | La factura electrónica DIAN de una factura pagada, emitida con tu Klopi (Facturación electrónica): `status` (`queued` · `emitting` · `issued` · `rejected` · `failed` · `skipped`), `number`, `cufe`, `pdf_url` y `dian_message` (el motivo de un rechazo). `null` si no tienes la facturación electrónica activa. En modo de pruebas es simulada: número `PRUEBA-…`, sin CUFE. El total de la factura electrónica es exactamente `amount`: el precio incluye el IVA. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio de la factura, de sus líneas o de su factura electrónica (ISO 8601, UTC, como `created`). |

### Crear una factura única (un cobro único)

`POST /invoices` · permiso `billing.invoices.create` · admite `Idempotency-Key`

Un pago único sin suscripción —un paquete, un servicio adicional—: `lines` con precios de pago único (`type: one_time`) × cantidad, o un `amount` con su `description`. Con `auto_charge` (por defecto) se abre y se cobra de una a la tarjeta (`default_payment_method` o la predeterminada del cliente) por el mismo camino de todo cobro: referencia determinista, frenos de cobro, idempotencia. Responde la factura (normalmente `open` con el cobro en curso); el resultado llega con `invoice.paid` o `invoice.payment_failed`. Con `retry: false` (por defecto) un rechazo NO se reintenta solo: la factura queda abierta hasta que la cobres otra vez (`/invoices/{id}/pay`) o la anules. Si un freno de cobros la detiene, se cobra sola cuando se libere. Usa `Idempotency-Key`.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `customer` | string | sí | Id del cliente. |
| `lines` | array | no | `[{price, quantity?, description?, metadata?}]`, de 1 a 20 precios de pago único activos. |
| `amount` | integer | no | Monto libre en vez de `lines` (con `description`), en la unidad de `currency`. |
| `currency` | enum | no | Con `amount`: `COP` (por defecto) o `USD`. Con `lines`, la de sus precios. Valores: `COP`, `USD`. |
| `description` | string | no | Qué se cobra; obligatoria con `amount`. |
| `default_payment_method` | string | no | Id de un método del cliente (por defecto, su predeterminado). |
| `auto_charge` | boolean | no | Cobrarla ya (por defecto `true`); con `false` espera a `/pay`. |
| `retry` | boolean | no | Reintentar un rechazo según tu calendario (por defecto `false`). |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `invoice`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_missing`, `customer_deleted`, `price_inactive`, `price_not_one_time`, `quantity_invalid`, `invoice_lines_invalid`, `invoice_amount_too_small`, `payment_method_unavailable`, `customer_payment_method_missing`.

```bash
curl -X POST "https://api.bucli.co/v1/invoices" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer": "…"}'
```

### Listar las líneas de una factura

`GET /invoices/{id}/lines` · permiso `billing.invoices.retrieve`

Del más reciente al más antiguo. `invoice.lines` ya las trae todas.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/invoices/$ID/lines" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Listar facturas

`GET /invoices` · permiso `billing.invoices.list`



Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `status` | enum | no | Estado. Valores: `draft`, `open`, `paid`, `void`, `uncollectible`. |
| `customer` | string | no | Id del cliente. |
| `subscription` | string | no | Id de la suscripción. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `parameter_invalid`.

```bash
curl "https://api.bucli.co/v1/invoices" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar una factura

`GET /invoices/{id}` · permiso `billing.invoices.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `invoice`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/invoices/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Cobrar una factura ahora

`POST /invoices/{id}/pay` · permiso `billing.invoices.pay` · admite `Idempotency-Key`

Reintenta el cobro de inmediato con el método de la suscripción. Solo facturas `open`. Si un freno de cobros lo detiene responde `409 invoice_charge_blocked` con el motivo, y la factura se cobra sola después.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `invoice`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `invoice_not_open`, `invoice_payment_in_progress`, `invoice_charge_blocked`.

```bash
curl -X POST "https://api.bucli.co/v1/invoices/$ID/pay" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Anular una factura

`POST /invoices/{id}/void` · permiso `billing.invoices.void` · admite `Idempotency-Key`

Solo `draft` u `open`; emite `invoice.voided`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `invoice`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `invoice_not_voidable`, `invoice_payment_in_progress`.

```bash
curl -X POST "https://api.bucli.co/v1/invoices/$ID/void" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Registrar un pago manual

`POST /invoices/{id}/mark_paid` · permiso `billing.invoices.mark_paid` · admite `Idempotency-Key`

La factura se pagó por fuera de Wompi (una transferencia): queda pagada con su referencia (única entre tus pagos manuales), como un pago `source: manual`, y la suscripción sigue como con cualquier pago — paga el periodo debido o activa la suscripción. Su reembolso solo se registra.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `reference` | string | sí | Referencia de la transferencia. |
| `reason` | string | no | Nota (queda en la bitácora). |

Responde el objeto `invoice`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `invoice_not_open`, `invoice_payment_in_progress`, `manual_payment_reference_used`, `exchange_rate_unavailable`.

```bash
curl -X POST "https://api.bucli.co/v1/invoices/$ID/mark_paid" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reference": "…"}'
```

## Pagos

Cada intento de cobro en Wompi.

### El objeto `payment`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `py_…` |
| `object` | string | `payment` |
| `invoice` | string | Factura (expandible). |
| `customer` | string | Cliente (expandible). |
| `payment_method` | string | Método cobrado (expandible). |
| `attempt_number` | integer | Número del intento en la factura. |
| `reference` | string | Referencia enviada a Wompi (`inv_<id>_<n>`). |
| `amount` | integer | Lo enviado a Wompi, en pesos enteros. |
| `currency` | string | `COP` (Wompi solo cobra pesos). |
| `invoice_amount` | integer | El valor de la factura en su moneda cuando se cobró. |
| `invoice_currency` | string | La moneda de la factura. |
| `exchange_rate` | string | Pesos por unidad de la moneda de la factura (la TRM usada); `null` en pesos. |
| `exchange_rate_date` | date | Desde cuándo rige esa tasa; `null` en pesos. |
| `status` | enum | Estado: pending, approved, declined, error, voided. |
| `source` | enum | `wompi` o `manual` (una transferencia registrada con `mark_paid`). |
| `external_reference` | string | La referencia de un pago manual, o `null`. |
| `amount_refunded` | integer | Pesos devueltos (reembolsos y anulaciones). |
| `refunded` | boolean | `true` cuando se devolvió todo. |
| `wompi_transaction_id` | string | Transacción en Wompi. |
| `failure_code` | string | Código del rechazo. |
| `failure_message` | string | Motivo del rechazo, en palabras del banco o de Wompi. |
| `sent_at` | datetime | Cuándo se envió a Wompi. |
| `finalized_at` | datetime | Cuándo se resolvió. |
| `livemode` | boolean | `true` en producción. |
| `created` | datetime | Cuándo se creó. |

### Listar pagos

`GET /payments` · permiso `billing.payments.list`

Cada intento de cobro enviado a Wompi, aprobado o no.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `invoice` | string | no | Id de la factura. |
| `status` | enum | no | Estado. Valores: `pending`, `approved`, `declined`, `error`, `voided`. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `parameter_invalid`.

```bash
curl "https://api.bucli.co/v1/payments" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un pago

`GET /payments/{id}` · permiso `billing.payments.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `payment`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/payments/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Reembolsar un pago

`POST /payments/{id}/refund` · permiso `billing.payments.refund` · admite `Idempotency-Key`

Devuelve `amount` pesos (por defecto todo lo que queda) por Wompi, en tres pasos como todo cobro. Responde el `refund`: `succeeded`, `pending` (Wompi aún no responde: se consulta solo) o `failed` con el motivo. Hecho, emite `charge.refunded`. El reembolso total de una bolsa la retira; el de un adicional no lo quita. `cancel_subscription: true` cancela la suscripción (motivo `refunded`). Un pago manual se reembolsa solo registrado.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `amount` | integer | no | Pesos a devolver (por defecto, todo lo que queda). |
| `reason` | string | no | Motivo. |
| `cancel_subscription` | boolean | no | Cancelar la suscripción al quedar hecho. |

Responde el objeto `refund`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `payment_not_refundable`, `refund_in_progress`, `parameter_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/payments/$ID/refund" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Anular un pago

`POST /payments/{id}/void` · permiso `billing.payments.refund` · admite `Idempotency-Key`

Anula en Wompi un cobro con tarjeta aprobado HOY (hora de Bogotá), completo y sin reembolsos; si no, reembólsalo. El pago y su factura quedan anulados. Responde el `refund` (`kind: void`).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `reason` | string | no | Motivo. |
| `cancel_subscription` | boolean | no | Cancelar la suscripción al quedar hecha. |

Responde el objeto `refund`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `payment_not_refundable`, `payment_not_voidable`, `refund_in_progress`, `parameter_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/payments/$ID/void" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Cupones

Descuentos para tus suscripciones.

### El objeto `discount`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `di_…` |
| `object` | string | `discount` |
| `subscription` | string | La suscripción (`sub_…`). |
| `coupon` | object | El cupón completo. |
| `status` | enum | `active`, `ended` (se gastó) o `removed` (se quitó). |
| `start` | datetime | Desde cuándo. |
| `end` | datetime | Con `repeating`: los periodos que empiezan desde aquí ya no llevan descuento. |
| `ended_at` | datetime | Cuándo terminó o se quitó. |
| `livemode` | boolean | `true` en producción. |
| `created` | datetime | Cuándo se aplicó. |

### El objeto `coupon`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `coupon_…` |
| `object` | string | `coupon` |
| `name` | string | Nombre (se ve en la factura). |
| `percent_off` | string | Porcentaje de descuento (`"20"`, `"12.5"`), o `null`. |
| `amount_off` | integer | Valor de descuento por periodo, en la unidad de `currency`, o `null`. |
| `currency` | string | La moneda de `amount_off`; `null` con `percent_off`. |
| `duration` | enum | `once` (un periodo), `repeating` (N meses) o `forever`. |
| `duration_in_months` | integer | Con `repeating`: cuántos meses desde que se aplica. |
| `applies_to` | enum | `all` (el plan y los adicionales), `plan` o `addons`. |
| `max_redemptions` | integer | A cuántas suscripciones se puede aplicar; `null` = sin tope. |
| `redeem_by` | datetime | Hasta cuándo se puede aplicar; `null` = sin fecha. |
| `times_redeemed` | integer | A cuántas suscripciones se aplicó. Desde la primera, sus términos no cambian. |
| `active` | boolean | `false`: no se aplica a nadie más (los aplicados siguen). |
| `valid` | boolean | Si se puede aplicar ahora (activo, sin vencer y con usos). |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### Crear un cupón

`POST /coupons` · permiso `billing.coupons.create` · admite `Idempotency-Key`

Un porcentaje o un valor fijo por periodo, una vez, N meses o para siempre, sobre el plan, los adicionales o ambos. Rebaja solo las facturas de periodo (la primera y cada renovación, con sus reintentos); los prorrateos, el excedente y los pagos únicos van a precio de lista. Si el total con descuento queda bajo el mínimo de Wompi, el periodo pasa gratis. Una vez aplicado a una suscripción, sus términos no cambian.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `name` | string | sí | Nombre. |
| `percent_off` | number | no | Porcentaje, de 0,01 a 100 (o `amount_off`). |
| `amount_off` | integer | no | Valor por periodo, en la unidad de `currency` (o `percent_off`). |
| `currency` | enum | no | Con `amount_off` (por defecto `COP`). Valores: `COP`, `USD`. |
| `duration` | enum | sí | Duración. Valores: `once`, `repeating`, `forever`. |
| `duration_in_months` | integer | no | Con `repeating`, de 1 a 120. |
| `applies_to` | enum | no | Por defecto `all`. Valores: `all`, `plan`, `addons`. |
| `max_redemptions` | integer | no | Tope de suscripciones. |
| `redeem_by` | datetime | no | Fecha límite para aplicarlo. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `coupon`. Errores: `api_key_invalid`, `rate_limited`, `parameter_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/coupons" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "…", "duration": "once"}'
```

### Listar cupones

`GET /coupons` · permiso `billing.coupons.list`

Los que no se han eliminado, del más reciente al más antiguo.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`.

```bash
curl "https://api.bucli.co/v1/coupons" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un cupón

`GET /coupons/{id}` · permiso `billing.coupons.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `coupon`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/coupons/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Editar un cupón

`PATCH /coupons/{id}` · permiso `billing.coupons.update`

Nombre, `active`, `max_redemptions`, `redeem_by` y metadata. El descuento, la moneda, la duración y `applies_to` solo mientras no se haya aplicado (`coupon_terms_frozen` después: crea otro).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `name` | string | no | Nombre. |
| `active` | boolean | no | `false`: no se aplica a nadie más. |
| `max_redemptions` | integer | no | Tope de suscripciones. |
| `redeem_by` | datetime | no | Fecha límite. |
| `percent_off` | number | no | Solo sin usos. |
| `amount_off` | integer | no | Solo sin usos. |
| `currency` | enum | no | Solo sin usos. Valores: `COP`, `USD`. |
| `duration` | enum | no | Solo sin usos. Valores: `once`, `repeating`, `forever`. |
| `duration_in_months` | integer | no | Solo sin usos. |
| `applies_to` | enum | no | Solo sin usos. Valores: `all`, `plan`, `addons`. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `coupon`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_invalid`, `coupon_terms_frozen`.

```bash
curl -X PATCH "https://api.bucli.co/v1/coupons/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Eliminar un cupón

`DELETE /coupons/{id}` · permiso `billing.coupons.destroy`

No se aplica a nadie más; los descuentos ya aplicados siguen.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde `{id, object, deleted: true}`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl -X DELETE "https://api.bucli.co/v1/coupons/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Reembolsos

El dinero que devuelves.

### El objeto `refund`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `re_…` |
| `object` | string | `refund` |
| `payment` | string | El pago devuelto (expandible). |
| `invoice` | string | Su factura (expandible). |
| `subscription` | string | La suscripción de la factura, o `null`. |
| `kind` | enum | `void` (anulación del cobro completo, el mismo día) o `refund` (total o parcial). |
| `source` | enum | `bucli` (pedido aquí), `external` (anulado desde el panel de Wompi) o `manual` (un pago manual devuelto por fuera: solo se registra). |
| `status` | enum | `pending` (Wompi no ha respondido), `succeeded` o `failed`. |
| `amount` | integer | Pesos devueltos (Wompi devuelve en pesos). |
| `currency` | string | `COP`. |
| `reason` | string | Motivo. |
| `requested_by` | string | Quién lo pidió (la llave o la persona). |
| `cancel_subscription` | boolean | Si cancela la suscripción al quedar hecho (motivo `refunded`). |
| `failure_message` | string | Por qué falló, en palabras de Wompi. |
| `credit_note` | object | La nota crédito electrónica en tu Klopi (`status`: `queued`, `draft` — un borrador que revisas y emites en Klopi —, `issued`, `failed` o `skipped`; `number`; `error`), o `null` si la factura no tenía factura electrónica. |
| `lines` | array | Las líneas `invoice_line` de la factura: lo que se había pagado. |
| `finalized_at` | datetime | Cuándo se resolvió. |
| `livemode` | boolean | `true` en producción. |
| `created` | datetime | Cuándo se pidió. |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### Listar reembolsos

`GET /refunds` · permiso `billing.refunds.list`

Reembolsos y anulaciones, del más reciente al más antiguo.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `payment` | string | no | Id del pago. |
| `invoice` | string | no | Id de la factura. |
| `status` | enum | no | Estado. Valores: `pending`, `succeeded`, `failed`. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `parameter_invalid`.

```bash
curl "https://api.bucli.co/v1/refunds" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un reembolso

`GET /refunds/{id}` · permiso `billing.refunds.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `refund`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/refunds/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Plazo fijo

Un plan pagado una vez, por días.

### El objeto `fixed_term_offer`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `fto_…` |
| `object` | string | `fixed_term_offer` |
| `customer` | string | Cliente (expandible). |
| `name` | string | Nombre. |
| `items` | array | `[{price, quantity}]`. |
| `units` | array | `[{meter, units}]`: unidades para todo el plazo. |
| `days` | integer | Días del plazo. |
| `amount` | integer | Precio en pesos. |
| `currency` | string | `COP`. |
| `status` | enum | `open` (esperando el pago), `paid`, `expired` o `canceled`. |
| `url` | string | El link de pago de Wompi. |
| `link_expires_at` | datetime | Cuándo vence el link. |
| `subscription` | string | La suscripción que empezó al pagarse, o `null`. |
| `paid_at` | datetime | Cuándo se pagó. |
| `livemode` | boolean | `true` en producción. |
| `created` | datetime | Cuándo se creó. |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### Crear una oferta de plazo fijo

`POST /fixed_term_offers` · permiso `billing.fixed_term_offers.create` · admite `Idempotency-Key`

Un paquete único para un cliente: plan base y adicionales (`items`), unidades de medidores para todo el plazo (`units`), `days` y un precio en pesos, pagado una vez con un link de pago de un solo uso de TU cuenta de Wompi, que vence en `link_days` (7 por defecto) y se le envía al cliente por correo. Pagado, la suscripción queda activa esos días con esos derechos (las unidades como bolsas que vencen con el plazo), no renueva ni tiene gracia, y al vencer queda cancelada con `fixed_term_ended`. Un pago que no se puede aplicar (doble, oferta vencida, otro valor) queda «por devolver» y se te avisa. Una oferta abierta por cliente.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `customer` | string | sí | Id del cliente. |
| `items` | array | sí | `[{price, quantity}]`: el plan base primero, luego los adicionales. |
| `units` | array | no | `[{meter, units}]`: la clave del medidor y las unidades para todo el plazo. |
| `days` | integer | sí | Días del plazo. |
| `amount` | integer | sí | Precio en pesos (desde el mínimo de Wompi). |
| `name` | string | no | Nombre (por defecto «<plan> por N días»). |
| `link_days` | integer | no | Días que vive el link de pago, de 1 a 30. |

Responde el objeto `fixed_term_offer`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_invalid`, `invoice_amount_too_small`, `fixed_term_offer_open`, `fixed_term_unavailable`, `active_subscriptions_limit_reached`, `wompi_unavailable`, `product_not_offered`, `product_coming_soon`, `quantity_not_supported`, `addon_requires_feature`, `addon_requires_plan`, `addon_included`, `addon_not_allowed_during_trial`, `trial_product_misused`.

```bash
curl -X POST "https://api.bucli.co/v1/fixed_term_offers" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer": "…", "items": [], "days": 0, "amount": 0}'
```

### Listar ofertas de plazo fijo

`GET /fixed_term_offers` · permiso `billing.fixed_term_offers.list`



Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `customer` | string | no | Id del cliente. |
| `status` | enum | no | Estado. Valores: `open`, `paid`, `expired`, `canceled`. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `parameter_invalid`.

```bash
curl "https://api.bucli.co/v1/fixed_term_offers" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar una oferta de plazo fijo

`GET /fixed_term_offers/{id}` · permiso `billing.fixed_term_offers.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `fixed_term_offer`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/fixed_term_offers/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Cancelar una oferta de plazo fijo

`POST /fixed_term_offers/{id}/cancel` · permiso `billing.fixed_term_offers.cancel` · admite `Idempotency-Key`

Solo una que espera el pago; su link de pago deja de funcionar.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `fixed_term_offer`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `fixed_term_offer_not_open`.

```bash
curl -X POST "https://api.bucli.co/v1/fixed_term_offers/$ID/cancel" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Eventos

Cada cambio, consultable 30 días.

### El objeto `event`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `evt_…` — deduplica con él. |
| `object` | string | `event` |
| `type` | string | Tipo (ver la lista de eventos). |
| `sequence` | integer | Crece con cada evento: de dos eventos del mismo objeto, el de `sequence` mayor es el cambio posterior. No es consecutivo. Las entregas pueden llegar en otro orden: compáralo, o vuelve a consultar el objeto. |
| `api_version` | string | Versión con la que se armó `data`. |
| `data` | object | `object` (el objeto como lo responde la API) y, si cambió, `previous_attributes`. |
| `request` | object | `id` e `idempotency_key` de la petición a la API que lo causó, o `null`. |
| `livemode` | boolean | `true` en producción. |
| `created` | datetime | Cuándo pasó. |

### Listar eventos

`GET /events` · permiso `webhooks.events.list`

Los de los últimos 30 días, del más reciente al más antiguo. Se ordenan por el momento en que se crearon, y un evento puede aparecer en la lista un instante después que otro más reciente (se confirma más tarde). Si sigues los nuevos con `ending_before`, no uses como cursor el último que viste: pide de nuevo desde uno de hace al menos un minuto y descarta los `id` que ya procesaste. Los webhooks entregan cada evento al menos una vez, sin este cuidado.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `type` | string | no | Un tipo (`invoice.paid`) o un grupo (`invoice.*`). |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `parameter_invalid`.

```bash
curl "https://api.bucli.co/v1/events" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un evento

`GET /events/{id}` · permiso `webhooks.events.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `event`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/events/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Reenviar un evento

`POST /events/{id}/resend` · permiso `webhooks.events.resend` · admite `Idempotency-Key`

Lo entrega otra vez, con el mismo `id`, a tus endpoints activos que lo escuchan, o solo a `webhook_endpoint` (aunque esté desactivado). Requiere un plan con webhooks.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `webhook_endpoint` | string | no | Id de un endpoint (`we_…`). |

Responde el objeto `event`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `feature_not_available`.

```bash
curl -X POST "https://api.bucli.co/v1/events/$ID/resend" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Webhooks

Dónde te avisamos de los eventos.

### El objeto `webhook_endpoint`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `we_…` |
| `object` | string | `webhook_endpoint` |
| `url` | string | URL HTTPS pública que recibe los eventos. |
| `description` | string | Para qué es. |
| `enabled_events` | array | Tipos que recibe; `["*"]` = todos. |
| `status` | enum | `enabled` o `disabled`. |
| `disabled_reason` | string | Por qué se desactivó. |
| `api_version` | string | Versión de los eventos que recibe. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |

### Crear un endpoint de webhook

`POST /webhook_endpoints` · permiso `webhooks.webhook_endpoints.create` · admite `Idempotency-Key`

La respuesta trae `secret` (`whsec_…`) **una sola vez**: guárdalo para verificar las firmas (si repites la petición con la misma `Idempotency-Key` responde `409 webhook_secret_unavailable_on_replay`, nunca el secreto). La URL debe ser HTTPS y pública. En producción el propietario de la cuenta recibe un correo con la URL. Desde el dashboard, un endpoint de producción lo crea solo el propietario o un administrador (`webhooks.webhook_endpoints.manage_live`) y pide confirmar la identidad (`password` o `code` en el cuerpo).

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `url` | string | sí | URL HTTPS. |
| `enabled_events` | array | sí | Tipos de evento, o `["*"]`. |
| `description` | string | no | Para qué es. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `webhook_endpoint`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `url_invalid`, `webhook_endpoint_limit_reached`, `webhook_secret_unavailable_on_replay`, `permission_denied`, `reauth_failed`.

```bash
curl -X POST "https://api.bucli.co/v1/webhook_endpoints" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url": "…", "enabled_events": []}'
```

### Listar endpoints de webhook

`GET /webhook_endpoints` · permiso `webhooks.webhook_endpoints.list`



Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`.

```bash
curl "https://api.bucli.co/v1/webhook_endpoints" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un endpoint de webhook

`GET /webhook_endpoints/{id}` · permiso `webhooks.webhook_endpoints.retrieve`

Nunca trae el secreto.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `webhook_endpoint`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/webhook_endpoints/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Actualizar un endpoint de webhook

`PATCH /webhook_endpoints/{id}` · permiso `webhooks.webhook_endpoints.update`

`disabled: true` lo desactiva (sus entregas pendientes se omiten); `false` lo reactiva. Si cambia la `url` de un endpoint de producción, guardamos la anterior y avisamos por correo al propietario; desde el dashboard solo lo hace el propietario o un administrador y pide confirmar la identidad.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `url` | string | no | URL HTTPS. |
| `enabled_events` | array | no | Tipos de evento. |
| `description` | string | no | Para qué es. |
| `disabled` | boolean | no | Desactivar o reactivar. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `webhook_endpoint`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `url_invalid`, `permission_denied`, `reauth_failed`.

```bash
curl -X PATCH "https://api.bucli.co/v1/webhook_endpoints/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Eliminar un endpoint de webhook

`DELETE /webhook_endpoints/{id}` · permiso `webhooks.webhook_endpoints.destroy`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde `{id, object, deleted: true}`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl -X DELETE "https://api.bucli.co/v1/webhook_endpoints/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Regenerar el secreto de firma

`POST /webhook_endpoints/{id}/roll_secret` · permiso `webhooks.webhook_endpoints.roll_secret` · admite `Idempotency-Key`

Responde el secreto nuevo una sola vez. Durante 24 horas cada entrega trae dos firmas `v1` en `Bucli-Signature` —la del secreto anterior y, la última, la del nuevo—: acepta la entrega si cualquiera coincide y despliega el nuevo secreto en ese plazo; después solo firma el nuevo.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `webhook_endpoint`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl -X POST "https://api.bucli.co/v1/webhook_endpoints/$ID/roll_secret" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Cuenta

Tu comercio en la API.

### El objeto `account`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `acct_…` |
| `object` | string | `account` |
| `name` | string | Nombre del comercio. |
| `api_version` | string | Versión fijada de la cuenta (o la pedida con `Bucli-Version`). |
| `livemode` | boolean | Modo de la llave. |
| `default_currency` | string | `COP`. |
| `country` | string | `CO`. |
| `webhooks_enabled` | boolean | Si el plan envía webhooks. |
| `created` | datetime | Cuándo se creó la cuenta. |

### Consultar la cuenta

`GET /account` · permiso `developers.account.retrieve`

Tu comercio como lo ve la API en el modo de la llave.

Responde el objeto `account`. Errores: `api_key_invalid`, `rate_limited`.

```bash
curl "https://api.bucli.co/v1/account" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Checkout

La página de pago hospedada.

### El objeto `checkout.session`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `cs_…` |
| `object` | string | `checkout.session` |
| `status` | enum | `open` (esperando al cliente), `complete` (la suscripción quedó creada) o `expired`. |
| `url` | string | Página de pago hospedada a la que rediriges al cliente; `null` si ya no está abierta. |
| `price` | string | Precio de la primera línea (expandible). Se conserva por compatibilidad: lo nuevo es `line_items`. |
| `line_items` | array | Lo que se suscribe, en orden: `[{object: line_item, price, quantity, amount, currency}]`, con el precio completo y `amount = price.amount × quantity`. Son los ítems de la suscripción que se crea. Una sesión creada con `price` tiene una línea. |
| `amount_total` | integer | Lo que cuesta cada periodo: la suma de las líneas, en su moneda. |
| `currency` | string | `COP` o `USD`: la de sus precios. |
| `subscription_data` | object | `metadata` (la de la suscripción que se crea) y `trial_days` (el mismo valor que `trial_days`). |
| `customer` | string | Cliente (expandible): el que enviaste o el que se creó o encontró al pagar. |
| `customer_email` | string | Correo sugerido (no editable en la página). |
| `customer_fields` | array | Datos que se piden además del correo: `name`, `legal_id`, `phone`. |
| `trial_days` | integer | Días de prueba de esta suscripción; `null` = los del precio. |
| `success_url` | string | A dónde vuelve el cliente al terminar, con `?session_id=cs_…`. |
| `cancel_url` | string | A dónde vuelve si se arrepiente. |
| `client_reference_id` | string | Tu referencia (el id de tu usuario, por ejemplo). |
| `payment_link` | string | Enlace de pago que la abrió (expandible). |
| `subscription` | string | Suscripción creada (expandible). |
| `payment_method` | string | Tarjeta guardada (expandible). |
| `expires_at` | datetime | Vence 24 horas después de creada. |
| `completed_at` | datetime | Cuándo se completó. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### Crear una sesión de checkout

`POST /checkout_sessions` · permiso `checkout.checkout_sessions.create` · admite llave `pk_` · admite `Idempotency-Key`

Responde la `url` de la página de pago hospedada (`pay.bucli.co/c/…`): redirige a tu cliente ahí. Ahí ve el plan con tu marca, acepta los términos de Wompi y escribe la tarjeta, que se tokeniza directo con Wompi (Bucli nunca la ve). Al pagar se crean el cliente, la tarjeta y la suscripción, y vuelve a `success_url` con `?session_id=cs_…`. Vence en 24 horas. Con `line_items` la página muestra cada línea y el total, y la suscripción nace con esos ítems. Una llave publicable (`pk_`) también la crea desde el navegador, pero sin `customer`, `trial_days`, `customer_fields`, `client_reference_id`, `metadata` ni `subscription_data` (`403 secret_key_required`).

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `price` | string | no | Precio que se suscribe (`price_…`); o `line_items`. |
| `quantity` | integer | no | Cantidad del `price` (1–10.000, por defecto 1); no con `line_items`. |
| `line_items` | array | no | `[{price, quantity}]`: el plan base, los puestos y los adicionales, en orden (el primero es el `price` del objeto). Una sola línea con `price` (+ `quantity`, por defecto 1) o varias con `line_items` (como Stripe): de 1 a 20, precios recurrentes del mismo intervalo, cada precio una vez. |
| `success_url` | string | sí | A dónde vuelve al terminar (https en producción). |
| `cancel_url` | string | no | A dónde vuelve si se arrepiente. |
| `customer` | string | no | Cliente existente (`cus_…`); no con una llave `pk_`. |
| `customer_email` | string | no | Correo del cliente, fijo en la página (en vez de `customer`). |
| `customer_fields` | array | no | Datos a pedir además del correo (por defecto `["name"]`). Valores: `name`, `legal_id`, `phone`. |
| `trial_days` | integer | no | Días de prueba (0–730); por defecto los del precio. |
| `client_reference_id` | string | no | Tu referencia, para reconocer la sesión en el webhook. |
| `subscription_data` | object | no | Lo que lleva la suscripción que se crea: `metadata` (hasta 20 pares) y `trial_days` (lo mismo que `trial_days`; si envías los dos deben coincidir). No con una llave `pk_`. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `checkout.session`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_missing`, `price_inactive`, `price_not_recurring`, `price_interval_mismatch`, `subscription_item_duplicate_price`, `subscription_items_invalid`, `quantity_invalid`, `secret_key_required`, `url_unavailable_on_replay`.

```bash
curl -X POST "https://api.bucli.co/v1/checkout_sessions" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"success_url": "…"}'
```

### Consultar una sesión de checkout

`GET /checkout_sessions/{id}` · permiso `checkout.checkout_sessions.retrieve`

Úsala al volver a tu `success_url` para saber qué suscripción quedó creada.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `checkout.session`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/checkout_sessions/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Vencer una sesión de checkout

`POST /checkout_sessions/{id}/expire` · permiso `checkout.checkout_sessions.expire` · admite `Idempotency-Key`

Cierra una sesión abierta: su página ya no recibe pagos y se emite `checkout.session.expired`. Una sesión completada, vencida o con un cobro esperando respuesta de Wompi responde `409 checkout_session_not_expirable`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `checkout.session`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `checkout_session_not_expirable`.

```bash
curl -X POST "https://api.bucli.co/v1/checkout_sessions/$ID/expire" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Enlaces de pago

Vender un plan sin código.

### El objeto `payment_link`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `plink_…` |
| `object` | string | `payment_link` |
| `url` | string | URL pública para compartir: cada visita abre un checkout. |
| `active` | boolean | `false`: el enlace ya no abre checkouts. |
| `price` | string | Precio de la primera línea (expandible). |
| `line_items` | array | Lo que vende, en orden: `[{object: line_item, price, quantity, amount, currency}]` (cada checkout que abre las lleva). |
| `amount_total` | integer | Lo que cuesta cada periodo: la suma de las líneas. |
| `currency` | string | `COP` o `USD`: la de sus precios. |
| `customer_fields` | array | Datos que se piden además del correo: `name`, `legal_id`, `phone`. |
| `trial_days` | integer | Días de prueba; `null` = los del precio. |
| `success_url` | string | A dónde vuelve el cliente al terminar; `null` = la página de Bucli lo confirma. |
| `sessions_count` | integer | Cuántos checkouts abrió. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |

### Crear un enlace de pago

`POST /payment_links` · permiso `checkout.payment_links.create` · admite `Idempotency-Key`

Una URL pública (`pay.bucli.co/l/…`) para vender un plan sin código, por WhatsApp o Instagram: cada visita abre un checkout nuevo con sus líneas (`price` o `line_items`).

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `price` | string | no | Precio que vende (`price_…`); o `line_items`. |
| `quantity` | integer | no | Cantidad del `price` (1–10.000, por defecto 1); no con `line_items`. |
| `line_items` | array | no | `[{price, quantity}]`: el plan base, los puestos y los adicionales, en orden (el primero es el `price` del objeto). Una sola línea con `price` (+ `quantity`, por defecto 1) o varias con `line_items` (como Stripe): de 1 a 20, precios recurrentes del mismo intervalo, cada precio una vez. |
| `customer_fields` | array | no | Datos a pedir además del correo. Valores: `name`, `legal_id`, `phone`. |
| `trial_days` | integer | no | Días de prueba (0–730); por defecto los del precio. |
| `success_url` | string | no | A dónde vuelve el cliente al terminar. |
| `active` | boolean | no | Activo (por defecto `true`). |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `payment_link`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_missing`, `price_inactive`, `price_not_recurring`, `price_interval_mismatch`, `subscription_item_duplicate_price`, `subscription_items_invalid`, `quantity_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/payment_links" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Listar enlaces de pago

`GET /payment_links` · permiso `checkout.payment_links.list`

Del más reciente al más antiguo.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `active` | boolean | no | Solo activos o inactivos. |
| `price` | string | no | Solo de un precio. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`.

```bash
curl "https://api.bucli.co/v1/payment_links" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un enlace de pago

`GET /payment_links/{id}` · permiso `checkout.payment_links.retrieve`

Con cuántos checkouts abrió.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `payment_link`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/payment_links/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Actualizar un enlace de pago

`PATCH /payment_links/{id}` · permiso `checkout.payment_links.update`

Desactívalo (`active: false`) para que deje de abrir checkouts; el precio y las líneas no cambian: crea otro enlace.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `active` | boolean | no | Activo. |
| `customer_fields` | array | no | Datos a pedir además del correo. Valores: `name`, `legal_id`, `phone`. |
| `trial_days` | integer | no | Días de prueba. |
| `success_url` | string | no | A dónde vuelve el cliente al terminar. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `payment_link`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_invalid`.

```bash
curl -X PATCH "https://api.bucli.co/v1/payment_links/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Portal del cliente

Donde tu cliente administra lo suyo.

### El objeto `portal.session`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `bps_…` |
| `object` | string | `portal.session` |
| `customer` | string | Cliente (expandible). |
| `return_url` | string | A dónde vuelve el cliente desde el portal. |
| `url` | string | Portal del cliente; solo en la respuesta de creación (es una credencial): `null` al consultarla. |
| `expires_at` | datetime | Vence una hora después de creada. |
| `livemode` | boolean | `true` en producción. |
| `created` | datetime | Cuándo se creó. |

### Crear una sesión del portal

`POST /portal_sessions` · permiso `checkout.portal_sessions.create` · admite `Idempotency-Key`

Responde la `url` del portal del cliente (`portal.bucli.co/s/…`), válida una hora: ahí ve sus suscripciones y su próximo cobro, cancela al fin del periodo, cambia la tarjeta (si debía, se cobra de inmediato), descarga sus recibos y edita sus datos, según lo que permitas en «Portal y marca». La `url` solo se responde al crearla: si la respuesta se perdió y repites la petición con la misma `Idempotency-Key`, responde `409 url_unavailable_on_replay` (con `error.object_id`); crea otra sesión con una clave nueva.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `customer` | string | sí | Cliente (`cus_…`). |
| `return_url` | string | no | A dónde vuelve; por defecto la de «Portal y marca». |

Responde el objeto `portal.session`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_missing`, `url_unavailable_on_replay`.

```bash
curl -X POST "https://api.bucli.co/v1/portal_sessions" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer": "…"}'
```

### Consultar una sesión del portal

`GET /portal_sessions/{id}` · permiso `checkout.portal_sessions.retrieve`

Para qué cliente es y hasta cuándo vale, **sin la `url`** (`null`): su token es una credencial que solo se responde al crearla y que Bucli no guarda. Si la perdiste, crea otra sesión.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `portal.session`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/portal_sessions/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Derechos

Tu vocabulario de módulos y límites.

### El objeto `feature`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `feat_…` |
| `object` | string | `feature` |
| `key` | string | Tu clave (`einvoicing`, `users`): minúsculas, números y `_`. No cambia. |
| `name` | string | Nombre. |
| `description` | string | Descripción. |
| `type` | enum | `boolean` (un módulo) o `limit` (un número). |
| `limit_kind` | enum | De un límite: `static` (cuántos a la vez: usuarios, GB; lo cuentas tú) o `metered` (cupo por ventana que cuenta el medidor con la misma clave). `null` en un módulo. |
| `allows_unlimited` | boolean | De un límite: `false` = nunca es ilimitado (-1). `null` en un módulo. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### Crear un derecho

`POST /features` · permiso `entitlements.features.create` · admite `Idempotency-Key`

Una clave de tu vocabulario: un módulo (`boolean`) o un límite (`limit`, `static` o `metered`). Bucli no conoce ninguna de antemano: tus productos dicen cuáles dan (`entitlements`).

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `key` | string | sí | Minúsculas, números y `_`, empieza por letra (máximo 50). No cambia. |
| `name` | string | sí | Nombre. |
| `type` | enum | sí | `boolean` o `limit`. Valores: `boolean`, `limit`. |
| `limit_kind` | enum | no | De un límite: `static` o `metered`. Valores: `static`, `metered`. |
| `allows_unlimited` | boolean | no | De un límite: `false` = nunca ilimitado (por defecto `true`). |
| `description` | string | no | Descripción. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `feature`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_already_exists`, `product_rules_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/features" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"key": "…", "name": "…", "type": "boolean"}'
```

### Listar los derechos

`GET /features` · permiso `entitlements.features.list`

Tu vocabulario, por clave.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `type` | enum | no | Solo módulos o solo límites. Valores: `boolean`, `limit`. |
| `key` | string | no | Clave exacta. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `parameter_invalid`.

```bash
curl "https://api.bucli.co/v1/features" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un derecho

`GET /features/{id}` · permiso `entitlements.features.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `feature`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/features/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Actualizar un derecho

`PATCH /features/{id}` · permiso `entitlements.features.update`

El nombre, la descripción, la metadata y si un límite admite ilimitado. La clave, el tipo y la clase no cambian. Apagar `allows_unlimited` con un producto que lo da ilimitado responde `400 limit_unlimited_not_allowed`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `name` | string | no | Nombre. |
| `description` | string | no | Descripción. |
| `allows_unlimited` | boolean | no | Solo de un límite. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `feature`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_invalid`, `parameter_unknown`, `limit_unlimited_not_allowed`.

```bash
curl -X PATCH "https://api.bucli.co/v1/features/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Eliminar un derecho

`DELETE /features/{id}` · permiso `entitlements.features.destroy`

Solo uno que nada usa: ni un producto, ni un ajuste, ni un medidor (`422 feature_in_use`).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde `{id, object, deleted: true}`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `feature_in_use`.

```bash
curl -X DELETE "https://api.bucli.co/v1/features/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Derechos de los clientes

Qué tiene cada cliente y su acceso.

### El objeto `entitlements`

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string | `entitlements` |
| `subscription` | string | Suscripción (expandible). En los de un cliente, la única que habla por él, o `null` si se combinan varias. |
| `customer` | string | Cliente (expandible). |
| `status` | enum | Estado de la suscripción (`null` si se combinan varias). |
| `features` | array | Módulos que tiene, ya con tus ajustes. |
| `limits` | object | `{clave: número}`, ya con tus ajustes; `-1` = ilimitado. |
| `products` | array | `[{product, key, name, group, is_addon, quantity}]`: los productos que los dan (el plan base es el que no es adicional). |
| `access` | enum | Qué puede hacer el cliente: full, read_only, none. |
| `read_only_reason` | enum | Por qué está en solo lectura: trial_ended, canceled, payment_overdue, fixed_term_ended, paused. `null` con acceso completo. |
| `period_end` | datetime | Fin del periodo en curso. |
| `trial_end` | datetime | Fin de la prueba, si está en prueba. |
| `overrides` | object | Tus ajustes a mano: `features_add`, `features_remove`, `limits` (mínimos), `note`, `set_by`, `set_at`; `null` si no hay. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `updated` | datetime | Cuándo cambiaron por última vez. |

### Consultar los derechos de una suscripción

`GET /subscriptions/{id}/entitlements` · permiso `entitlements.entitlements.retrieve`

Lo que dan sus productos combinados (módulos unidos, límites sumados, la cantidad multiplica los de un producto por unidades, `-1` gana), con tus ajustes encima, y el acceso que su estado da: `full` en prueba o activa (y con pago atrasado durante tus días de gracia), `read_only` pausada, cancelada o pasada la gracia (con `read_only_reason`), `none` si nunca se pagó. Cada cambio llega como `entitlements.updated`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `entitlements`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/subscriptions/$ID/entitlements" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Ajustar los derechos de una suscripción

`POST /subscriptions/{id}/entitlement_overrides` · permiso `entitlements.overrides.update` · admite `Idempotency-Key`

Tus ajustes a mano, completos (lo que no envíes se quita; un cuerpo vacío los borra): `features_add`, `features_remove` (gana sobre el plan) y `limits` (un mínimo: se toma el mayor entre el plan y el ajuste; `-1` gana). Se conservan en cada recálculo. Si el cliente compra un producto que da un módulo que quitaste a mano, la compra levanta esa restricción. Con `keep_current: true` y `price` (el plan al que baja; sin él, su `pending_price`) convierte en ajustes lo que hoy tiene de más sobre ese plan: úsalo antes de bajarlo de plan para no quitarle nada. Responde sus derechos ya recalculados.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `features_add` | array | no | Módulos que se suman. |
| `features_remove` | array | no | Módulos que se quitan. |
| `limits` | object | no | `{clave: número}` mínimos; `-1` = ilimitado. |
| `note` | string | no | Por qué (hasta 500 caracteres). |
| `keep_current` | boolean | no | Convertir lo que tiene de más en ajustes (con `price` y `note`). |
| `price` | string | no | Con `keep_current`: el precio del plan al que baja (por defecto su `pending_price`). |

Responde el objeto `entitlements`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_invalid`, `feature_unknown`, `feature_type_mismatch`, `limit_invalid`, `limit_unlimited_not_allowed`, `product_rules_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/subscriptions/$ID/entitlement_overrides" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Consultar los derechos de un cliente

`GET /customers/{id}/entitlements` · permiso `entitlements.entitlements.retrieve`

Sus suscripciones con acceso completo combinadas (módulos unidos, límites sumados); si no tiene ninguna, habla la más reciente en solo lectura; si no tiene suscripciones, `access: none`. Es lo que cuentan los medidores del cliente.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `entitlements`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/customers/$ID/entitlements" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Medidores

Cupos por ventana.

### El objeto `meter`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `mtr_…` |
| `object` | string | `meter` |
| `key` | string | La clave del límite medido que cuenta (la misma de `/features`). En las rutas sirve de id. |
| `name` | string | Nombre. |
| `window` | enum | Cuándo se reinicia el cupo: `calendar_month` (el mes en su zona horaria, también en planes anuales), `billing_period` (el periodo de la suscripción) o `subscription_lifetime` (toda la suscripción: una prueba, un plazo fijo). |
| `timezone` | string | Zona horaria de la ventana (`America/Bogota`). |
| `on_unavailable` | enum | Qué hace tu librería si Bucli no responde: `allow` (deja pasar la unidad y la reporta después con `POST /usage`) o `deny`. |
| `threshold_percent` | integer | Porcentaje del cupo que dispara `meter.threshold_reached`. |
| `active` | boolean | `false`: no admite reservas. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### El objeto `meter_balance`

| Campo | Tipo | Descripción |
|---|---|---|
| `object` | string | `meter_balance` |
| `meter` | string | Clave del medidor. |
| `customer` | string | Cliente (expandible). |
| `window_start` | datetime | Inicio de la ventana. |
| `window_end` | datetime | Fin de la ventana (`null` en una de toda la suscripción). |
| `allowance` | integer | Cupo de la ventana (plan + bloques prorrateados; `-1` ilimitado). |
| `used` | integer | Usado del cupo. |
| `allowance_remaining` | integer | Lo que queda del cupo (`-1` ilimitado). |
| `grants` | array | Bolsas vivas: `[{id, remaining, units, expires_at}]`, la que vence primero primero. |
| `grants_remaining` | integer | Saldo de las bolsas vivas. |
| `remaining` | integer | Lo que puede gastar: cupo + bolsas (`-1` ilimitado). |
| `overage` | integer | Unidades por encima del cupo y las bolsas: el excedente cobrado (si el precio tiene tarifa) y lo reportado tarde. |
| `overage_amount` | integer | Lo que cuesta el excedente de la ventana (en la moneda del precio). |
| `overage_billed_amount` | integer | Lo que de eso ya se cobró en una renovación. |
| `overage_rate` | object | `{unit_amount, per_units}` del plan del cliente, o `null` (sin excedente). |
| `overage_cap` | integer | El tope del cliente por ventana, o `null` (sin excedente). |
| `unbilled` | integer | Registrado sin gastar cupo (`billable: false`). |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `updated` | datetime | Último movimiento. |

### Crear un medidor

`POST /meters` · permiso `entitlements.meters.create` · admite `Idempotency-Key`

Cuenta un límite `metered` de tu vocabulario con la misma `key`: el cupo de cada ventana es ese límite en los derechos del cliente (plan + bloques recurrentes); las bolsas cubren lo que pase de ahí.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `key` | string | sí | Clave del límite medido. |
| `name` | string | sí | Nombre. |
| `window` | enum | no | Por defecto `calendar_month`. No cambia. Valores: `calendar_month`, `billing_period`, `subscription_lifetime`. |
| `timezone` | string | no | Por defecto `America/Bogota`. No cambia. |
| `on_unavailable` | enum | no | Por defecto `deny`. Valores: `allow`, `deny`. |
| `threshold_percent` | integer | no | Aviso al (por defecto 80). |
| `active` | boolean | no | Por defecto `true`. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `meter`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `meter_feature_missing`, `resource_already_exists`, `product_rules_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/meters" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"key": "…", "name": "…"}'
```

### Listar medidores

`GET /meters` · permiso `entitlements.meters.list`



Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`.

```bash
curl "https://api.bucli.co/v1/meters" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un medidor

`GET /meters/{id}` · permiso `entitlements.meters.retrieve`

`{id}` es el id (`mtr_…`) o la clave (`documents`).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `meter`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/meters/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Actualizar un medidor

`PATCH /meters/{id}` · permiso `entitlements.meters.update`

El nombre, `on_unavailable`, el aviso, si está activo y la metadata. La clave, la ventana y la zona no cambian.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `name` | string | no | Nombre. |
| `on_unavailable` | enum | no | `allow` o `deny`. Valores: `allow`, `deny`. |
| `threshold_percent` | integer | no | Aviso al. |
| `active` | boolean | no | Activo. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `meter`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_invalid`, `parameter_unknown`.

```bash
curl -X PATCH "https://api.bucli.co/v1/meters/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar el uso de un cliente

`GET /meters/{id}/summary` · permiso `entitlements.meters.retrieve`

La ventana en curso: cupo, usado, lo que queda y las bolsas vivas con su saldo y vencimiento. Es la pantalla «Uso».

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `customer` | string | sí | Id del cliente. |

Responde el objeto `meter_balance`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_missing`.

```bash
curl "https://api.bucli.co/v1/meters/$ID/summary" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

## Consumo

Reservar, reportar y devolver unidades.

### El objeto `usage_record`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `usg_…` |
| `object` | string | `usage_record` |
| `meter` | string | Clave del medidor. |
| `customer` | string | Cliente (expandible). |
| `quantity` | integer | Unidades. |
| `billable` | boolean | `false`: se registró sin gastar cupo. |
| `source` | enum | De dónde salió: `allowance` (el cupo de la ventana), `grant` (una bolsa), `overage` (excedente: cobrado con la tarifa del plan, o un reporte tardío por encima de todo), `unbilled` o `mixed`. |
| `grant` | string | La bolsa, si salió de una sola (`grt_…`). |
| `allocations` | array | `[{source, units, grant}]`: cada parte, para devolverla a su origen. Una parte `overage` con tarifa trae además `unit_amount` y `per_units`. |
| `remaining` | integer | Lo que le queda al cliente tras esta reserva (cupo + bolsas; `-1` ilimitado). |
| `idempotency_key` | string | Tu llave: la misma devuelve la misma reserva. |
| `reported` | boolean | Se reportó después (`POST /usage`), no se reservó. |
| `window_start` | datetime | Inicio de la ventana en que cuenta. |
| `occurred_at` | datetime | Cuándo ocurrió. |
| `released_at` | datetime | Cuándo se devolvió; `null` si no. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |

### Reservar unidades

`POST /meters/{id}/reserve` · permiso `entitlements.usage.create` · admite `Idempotency-Key`

Justo antes del acto que no se deshace (mandar un documento). Gasta primero el cupo de la ventana y luego la bolsa viva que vence primero; si no alcanza responde `402 quota_exhausted` con `allowance`, `used` y `grants_remaining` en el error. La misma `idempotency_key` devuelve la misma reserva (200; la primera vez 201) — usa el id de tu documento. Con `billable: false` se registra sin gastar cupo. Solo con acceso completo (`402 entitlement_access_denied`). Responde el consumo con `remaining`, el saldo que le queda: guárdalo para negar sin llamar cuando llegue a cero. Una llave ya devuelta (`/usage/{id}/release`) vuelve a tomar sus unidades: el mismo documento enviado otra vez tras un rechazo. Reservar, reportar y devolver siguen abiertos aunque tu plan de Bucli esté en solo lectura: es el consumo de tus clientes.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `customer` | string | sí | Id del cliente. |
| `idempotency_key` | string | sí | Tu llave única por unidad (hasta 255). |
| `quantity` | integer | no | Unidades (por defecto 1). |
| `billable` | boolean | no | `false`: se registra sin gastar cupo. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `usage_record`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_missing`, `meter_inactive`, `quota_exhausted`, `entitlement_access_denied`, `usage_idempotency_key_reused`, `product_rules_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/meters/$ID/reserve" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer": "…", "idempotency_key": "…"}'
```

### Reportar consumo tardío

`POST /usage` · permiso `entitlements.usage.create` · admite `Idempotency-Key`

Lo que tu librería dejó pasar mientras Bucli no respondía (`on_unavailable: allow`): se asienta en la ventana en que ocurrió y nunca se niega; lo que pase de todo queda como `overage`. Idempotente por `idempotency_key`. `occurred_at` no puede ser futuro ni de hace más de 35 días.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `meter` | string | sí | Id o clave del medidor. |
| `customer` | string | sí | Id del cliente. |
| `idempotency_key` | string | sí | La misma llave que habrías usado al reservar. |
| `occurred_at` | datetime | sí | Cuándo pasó. |
| `quantity` | integer | no | Unidades (por defecto 1). |
| `billable` | boolean | no | `false`: sin gastar cupo. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `usage_record`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_missing`, `usage_report_invalid`, `usage_idempotency_key_reused`, `product_rules_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/usage" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"meter": "…", "customer": "…", "idempotency_key": "…", "occurred_at": "…"}'
```

### Listar el consumo

`GET /usage` · permiso `entitlements.usage.list`

Del más reciente al más antiguo.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `meter` | string | no | Clave del medidor. |
| `customer` | string | no | Id del cliente. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`.

```bash
curl "https://api.bucli.co/v1/usage" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar un consumo

`GET /usage/{id}` · permiso `entitlements.usage.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `usage_record`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/usage/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Devolver un consumo

`POST /usage/{id}/release` · permiso `entitlements.usage.release` · admite `Idempotency-Key`

Cada unidad vuelve a SU origen (el cupo de su ventana o la bolsa de la que salió), una sola vez: una segunda llamada responde el consumo tal como está. Para un documento rechazado, un borrador borrado o un envío que no salió.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Responde el objeto `usage_record`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_unknown`.

```bash
curl -X POST "https://api.bucli.co/v1/usage/$ID/release" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Ofertas de bolsas

Paquetes de unidades que vendes.

### El objeto `grant_offer`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `goff_…` |
| `object` | string | `grant_offer` |
| `meter` | string | Clave del medidor. |
| `price` | string | Precio de pago único con que se cobra (expandible). |
| `amount` | integer | Lo que cuesta (el del precio). |
| `currency` | string | `COP` o `USD`: la del precio. |
| `name` | string | Nombre («100 documentos»). |
| `units` | integer | Unidades que da. |
| `validity_months` | integer | Meses de vigencia desde el pago; `null` = no vence. |
| `requires_features` | array | Solo se vende a un cliente que tenga alguno de estos módulos. |
| `active` | boolean | `false`: archivada, no se vende. |
| `position` | integer | Orden en tu vitrina. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### Crear una oferta de bolsa

`POST /grant_offers` · permiso `entitlements.grant_offers.create` · admite `Idempotency-Key`

Un paquete de unidades que vendes (20, 100, 500…), con un precio de pago único (`type: one_time`) de un producto tuyo: así la factura electrónica usa su producto enlazado.

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `meter` | string | sí | Id o clave del medidor. |
| `price` | string | sí | Precio de pago único (`price_…`). |
| `name` | string | sí | Nombre. |
| `units` | integer | sí | Unidades. |
| `validity_months` | integer | no | Vigencia desde el pago (por defecto 12; 0 = no vence). |
| `requires_features` | array | no | Solo para clientes con alguno de estos módulos. |
| `active` | boolean | no | Por defecto `true`. |
| `position` | integer | no | Orden. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `grant_offer`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_missing`, `grant_offer_price_invalid`, `feature_unknown`, `feature_type_mismatch`.

```bash
curl -X POST "https://api.bucli.co/v1/grant_offers" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"meter": "…", "price": "…", "name": "…", "units": 0}'
```

### Listar las ofertas de bolsas

`GET /grant_offers` · permiso `entitlements.grant_offers.list`



Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `meter` | string | no | Clave del medidor. |
| `active` | boolean | no | Activas o no. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `parameter_invalid`.

```bash
curl "https://api.bucli.co/v1/grant_offers" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar una oferta de bolsa

`GET /grant_offers/{id}` · permiso `entitlements.grant_offers.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `grant_offer`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/grant_offers/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Actualizar una oferta de bolsa

`PATCH /grant_offers/{id}` · permiso `entitlements.grant_offers.update`

El nombre, los módulos que exige, el orden, si está activa y la metadata. Unidades, precio y vigencia no cambian: crea otra oferta.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `name` | string | no | Nombre. |
| `requires_features` | array | no | Módulos que exige. |
| `active` | boolean | no | Archivar o reactivar. |
| `position` | integer | no | Orden. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `grant_offer`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `parameter_invalid`, `parameter_unknown`, `feature_unknown`.

```bash
curl -X PATCH "https://api.bucli.co/v1/grant_offers/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Vender una bolsa

`POST /grant_offers/{id}/purchase` · permiso `entitlements.grant_offers.purchase` · admite `Idempotency-Key`

Crea una factura única con el precio de la oferta y la cobra a la tarjeta del cliente por el mismo camino de todo cobro (Wompi confirma antes de aprobar). Responde la factura; la bolsa queda vigente cuando se aprueba (`invoice.paid` y luego `grant.created`), con su vencimiento contado desde el pago. Si la factura se anula, la bolsa no nace. Exige la cabecera `Idempotency-Key` (cobra una tarjeta: un reintento sin ella cobraría dos veces).

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `customer` | string | sí | Id del cliente. |
| `payment_method` | string | no | Tarjeta del cliente (por defecto, la predeterminada). |

Responde el objeto `invoice`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `resource_missing`, `grant_offer_unavailable`, `grant_offer_requires_feature`, `customer_payment_method_missing`, `payment_method_unavailable`, `invoice_amount_too_small`.

```bash
curl -X POST "https://api.bucli.co/v1/grant_offers/$ID/purchase" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer": "…"}'
```

## Bolsas

Unidades prepagadas de cada cliente.

### El objeto `grant`

| Campo | Tipo | Descripción |
|---|---|---|
| `id` | string | `grt_…` |
| `object` | string | `grant` |
| `customer` | string | Cliente (expandible). |
| `meter` | string | Clave del medidor. |
| `offer` | string | Oferta que se compró (`goff_…`); `null` si fue un regalo o se importó. |
| `invoice` | string | Factura que la pagó (expandible). |
| `source` | enum | `purchase`, `staff` o `import`. |
| `status` | enum | Estado: pending, active, expired, withdrawn, canceled. |
| `units` | integer | Unidades que dio. |
| `remaining` | integer | Lo que le queda. |
| `expires_at` | datetime | Cuándo vence; `null` = no vence. |
| `ended_at` | datetime | Cuándo venció, se retiró o se anuló. |
| `note` | string | Nota. |
| `metadata` | object | Tus pares clave-valor. |
| `livemode` | boolean | `true` en producción, `false` en pruebas. |
| `created` | datetime | Cuándo se creó (ISO 8601, UTC). |
| `updated` | datetime | Último cambio del objeto (ISO 8601, UTC, como `created`): se mueve con cada modificación. Compáralo con el de tu copia local antes de pisarla: si la tuya es más nueva, el dato que llegó es viejo. |

### Regalar una bolsa

`POST /grants` · permiso `entitlements.grants.create` · admite `Idempotency-Key`

Unidades que das a un cliente (o que importas de tu sistema anterior con `imported: true` y lo que le queda en `remaining`). Emite `grant.created`.

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `customer` | string | sí | Id del cliente. |
| `meter` | string | sí | Id o clave del medidor. |
| `units` | integer | sí | Unidades. |
| `remaining` | integer | no | Lo que le queda (por defecto todas). |
| `expires_at` | datetime | no | Vencimiento (futuro); sin él no vence. |
| `note` | string | no | Por qué. |
| `imported` | boolean | no | Viene de tu sistema anterior. |
| `metadata` | object | no | Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; `""` borra una clave. |

Responde el objeto `grant`. Errores: `api_key_invalid`, `rate_limited`, `parameter_missing`, `parameter_invalid`, `resource_missing`, `product_rules_invalid`.

```bash
curl -X POST "https://api.bucli.co/v1/grants" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer": "…", "meter": "…", "units": 0}'
```

### Listar las bolsas

`GET /grants` · permiso `entitlements.grants.list`



Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `limit` | integer | no | Cuántos objetos, de 1 a 100 (por defecto 10). |
| `starting_after` | string | no | Id del último objeto de la página anterior: trae la siguiente. |
| `ending_before` | string | no | Id del primer objeto de la página actual: trae la anterior. |
| `expand[]` | array | no | Objetos relacionados a incluir completos (`data.customer`): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso. |
| `customer` | string | no | Id del cliente. |
| `meter` | string | no | Clave del medidor. |
| `status` | enum | no | Estado. Valores: `pending`, `active`, `expired`, `withdrawn`, `canceled`. |

Responde una lista (`object: list`). Errores: `api_key_invalid`, `rate_limited`, `parameter_invalid`.

```bash
curl "https://api.bucli.co/v1/grants" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Consultar una bolsa

`GET /grants/{id}` · permiso `entitlements.grants.retrieve`



Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `expand[]` | array | no | Objetos relacionados a incluir completos (`customer`): hasta 4 caminos de hasta 4 niveles. |

Responde el objeto `grant`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`.

```bash
curl "https://api.bucli.co/v1/grants/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
```

### Retirar una bolsa

`POST /grants/{id}/withdraw` · permiso `entitlements.grants.withdraw` · admite `Idempotency-Key`

Le quita lo que le queda a una bolsa vigente (un reembolso total, un error). Emite `grant.withdrawn`.

Parámetros de ruta:

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `id` | string | sí | Id del objeto (`cus_…`, `sub_…`). |

Cuerpo (JSON):

| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `note` | string | no | Por qué. |

Responde el objeto `grant`. Errores: `api_key_invalid`, `rate_limited`, `resource_missing`, `grant_not_withdrawable`.

```bash
curl -X POST "https://api.bucli.co/v1/grants/$ID/withdraw" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Webhooks

Cada entrega trae la cabecera `Bucli-Signature: t=<timestamp>,v1=<firma>`. Calcula `HMAC-SHA256(secreto, "<t>.<cuerpo crudo>")` en hexadecimal con el secreto `whsec_…` del endpoint, compáralo en tiempo constante con CADA `v1` de la cabecera (durante las 24 horas que siguen a regenerar el secreto llegan dos: la del anterior y, la última, la del nuevo) y acepta si alguna coincide; rechaza un `t` de hace más de 5 minutos. Responde `2xx` rápido (tenemos 10 segundos en total para enviarte el evento y leer tu respuesta) y procesa después; deduplica por el `id` del evento (un reintento trae el mismo). **El orden no está garantizado**: cada entrega viaja sola y los reintentos las reordenan. Usa `sequence` (mayor = cambio posterior del objeto) o vuelve a consultar el objeto con la API antes de actuar. Si fallas, reintentamos a 1 min, 5 min, 30 min, 2 h, 6 h y 24 h (tras muchos fallos seguidos pausamos tu endpoint unos minutos entre intentos); tras 3 días fallando lo desactivamos y te avisamos por correo.

### Eventos

| Evento | Objeto | Cuándo |
|---|---|---|
| `customer.created` | `customer` | Se creó un cliente. |
| `customer.updated` | `customer` | Cambió un cliente. |
| `customer.deleted` | `customer` | Se eliminó un cliente. |
| `product.created` | `product` | Se creó un producto. |
| `product.updated` | `product` | Cambió un producto: su nombre, lo que da, sus reglas, cómo se muestra en la vitrina, o su `kind` porque un precio nuevo lo volvió paquete o plan (`previous_attributes` trae lo que tenía, con la forma del objeto). |
| `subscription.created` | `subscription` | Se creó una suscripción. |
| `subscription.updated` | `subscription` | Cambió una suscripción (estado, precio, método de pago, cancelación programada). |
| `subscription.canceled` | `subscription` | Se canceló una suscripción. |
| `subscription.past_due` | `subscription` | Un cobro de la suscripción fue rechazado y quedó con pago atrasado. |
| `subscription.update_failed` | `subscription` | Falló el cobro de un cambio prorrateado (o se anuló su cobro): la suscripción quedó como estaba. |
| `subscription.trial_will_end` | `subscription` | La prueba gratis termina en 3 días. |
| `invoice.created` | `invoice` | Se creó el cobro (`invoice`) de un periodo. |
| `invoice.paid` | `invoice` | Wompi aprobó un cobro (`invoice`). |
| `invoice.payment_failed` | `invoice` | Wompi rechazó un cobro (`invoice`); se reintentará según el calendario. |
| `invoice.voided` | `invoice` | Se anuló un cobro (`invoice`). |
| `invoice.updated` | `invoice` | Cambió el valor de un cobro (`invoice`) abierto: un cupón aplicado mientras estaba pendiente. |
| `notice.sent` | `notice` | Bucli le envió un aviso a tu cliente (recibo, cobro fallido, tarjeta por vencer…): ponlo en su campana. |
| `charge.refunded` | `refund` | Se devolvió dinero de un pago (reembolso total o parcial, o anulación): el `refund` trae las líneas del cobro. |
| `invoice.fiscal_document.issued` | `invoice` | La DIAN aceptó la factura electrónica de una factura pagada: ya tiene número, CUFE y PDF (`fiscal_document`). |
| `invoice.fiscal_document.rejected` | `invoice` | La DIAN rechazó la factura electrónica de una factura pagada; el motivo está en `fiscal_document.dian_message`. |
| `payment_method.attached` | `payment_method` | El cliente guardó un método de pago (checkout o portal). |
| `payment_method.detached` | `payment_method` | Se quitó un método de pago. |
| `payment_method.suspended` | `payment_method` | Un rechazo duro (robada, perdida, vencida): la tarjeta no se vuelve a cobrar. |
| `payment_method.expiring` | `payment_method` | La tarjeta vence en 30 o en 7 días (`previous_attributes.days`). |
| `checkout.session.completed` | `checkout.session` | El cliente terminó un checkout. |
| `checkout.session.expired` | `checkout.session` | Un checkout venció sin completarse. |
| `entitlements.updated` | `entitlements` | Cambiaron los derechos o el acceso de una suscripción (compra, cambio de plan, renovación, vencimiento, ajuste o edición de un producto). Trae el objeto completo. |
| `meter.threshold_reached` | `meter_balance` | Un cliente usó el porcentaje de aviso de su cupo en la ventana (una vez por ventana). |
| `meter.exhausted` | `meter_balance` | Un cliente gastó su cupo y sus bolsas en la ventana (una vez por ventana). |
| `grant.created` | `grant` | Una bolsa quedó vigente (pagada, regalada o importada). |
| `grant.expired` | `grant` | Una bolsa venció; lo que le quedaba se pierde. |
| `grant.withdrawn` | `grant` | Se retiró lo que le quedaba a una bolsa. |

### Verificar la firma

```python
import hashlib
import hmac
import time

TOLERANCE = 300


def verify(body, header, secret):
    items = [item.split("=", 1) for item in header.split(",") if "=" in item]
    timestamp = int(next((value for key, value in items if key == "t"), "0"))
    if abs(time.time() - timestamp) > TOLERANCE:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest()
    # Tras regenerar el secreto llegan dos v1 durante 24 h: basta con que una coincida.
    return any(hmac.compare_digest(expected, value) for key, value in items if key == "v1")
```

```javascript
const crypto = require("crypto");
const TOLERANCE = 300;

function verify(body, header, secret) {
  const items = header.split(",").map((p) => p.split("="));
  const t = Number((items.find(([k]) => k === "t") || [])[1]);
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE) return false;
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${t}.${body}`).digest("hex"));
  // Tras regenerar el secreto llegan dos v1 durante 24 h: basta con que una coincida.
  return items
    .filter(([k]) => k === "v1")
    .some(([, v]) => Buffer.byteLength(v || "") === expected.length && crypto.timingSafeEqual(expected, Buffer.from(v)));
}
// Express: app.post("/webhooks/bucli", express.raw({ type: "application/json" }), (req, res) => { … })
```

```php
<?php
function verify(string $body, string $header, string $secret): bool {
    $t = 0;
    $signatures = [];
    foreach (explode(',', $header) as $item) {
        [$k, $v] = array_pad(explode('=', $item, 2), 2, '');
        if ($k === 't') { $t = (int) $v; }
        if ($k === 'v1') { $signatures[] = $v; }  // dos durante 24 h tras regenerar el secreto
    }
    if (abs(time() - $t) > 300) { return false; }
    $expected = hash_hmac('sha256', "$t.$body", $secret);
    foreach ($signatures as $signature) {
        if (hash_equals($expected, $signature)) { return true; }
    }
    return false;
}
// $body = file_get_contents('php://input'); $header = $_SERVER['HTTP_BUCLI_SIGNATURE'];
```

```bash
# Para probar tu verificación, firma un cuerpo tú mismo:
t=$(date +%s); body='{"id":"evt_test","type":"invoice.paid"}'
sig=$(printf '%s' "$t.$body" | openssl dgst -sha256 -hmac "$BUCLI_WEBHOOK_SECRET" | sed 's/^.* //')
curl https://miapp.co/webhooks/bucli -H "Bucli-Signature: t=$t,v1=$sig" -H "Content-Type: application/json" -d "$body"
```
