Bucli logoBucli

API de Bucli

2026-11-01

Cobra suscripciones con Wompi desde tu sistema: clientes, planes, suscripciones, cobros, checkout hospedado, portal del cliente y webhooks firmados. REST y JSON, al estilo de Stripe Billing.

URL basehttps://api.bucli.co/v1
  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": "[email protected]",
       "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.
  • 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.

Clientes

Quién paga tus suscripciones.

El objeto notice
  • idstring

    ntc_…

  • objectstring

    notice

  • customerstring

    Cliente (expandible).

  • subscriptionstring

    La suscripción de la que habla, o null.

  • invoicestring

    La factura de la que habla, o null.

  • kindenum

    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.

  • subjectstring

    El asunto del correo.

  • messagestring

    El aviso en una frase (el de WhatsApp).

  • channelsobject

    {email, whatsapp}: sent, failed o skipped (sin correo, sin celular…).

  • sent_atdatetime

    Cuándo terminó de salir.

  • livemodeboolean

    true en producción.

  • createddatetime

    Cuándo se creó.

El objeto customer
  • idstring

    cus_…

  • objectstring

    customer

  • external_idstring

    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).

  • emailstring

    Correo; único por cuenta y modo entre los clientes sin external_id.

  • namestring

    Nombre.

  • phonestring

    Celular.

  • legal_id_typeenum

    Tipo de documento: CC, CE, NIT, PP, TI, PPT.

  • legal_idstring

    Número de documento.

  • fiscalobject

    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_methodstring

    Método de pago predeterminado (expandible).

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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

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

Permiso billing.customers.createAdmite Idempotency-Key

Cuerpo (JSON)

  • emailstringobligatorio

    Correo del cliente.

  • external_idstring

    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.

  • namestring

    Nombre.

  • phonestring

    Celular.

  • legal_id_typeenum

    Tipo de documento.

    Valores: CC, CE, NIT, PP, TI, PPT

  • legal_idstring

    Número de documento.

  • fiscalobject

    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.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

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

Permiso billing.customers.list

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • emailstring

    Correo exacto (puede haber varios con external_id).

  • external_idstring

    Tu id exacto.

  • metadata[<clave>]string

    Solo los que tienen ese par en su metadata.

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited

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

Consultar un cliente

GET/customers/{id}

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

Permiso billing.customers.retrieve

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto customer

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Actualizar un cliente

PATCH/customers/{id}

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

Permiso billing.customers.update

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • emailstring

    Correo del cliente.

  • external_idstring

    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.

  • namestring

    Nombre.

  • phonestring

    Celular.

  • legal_id_typeenum

    Tipo de documento.

    Valores: CC, CE, NIT, PP, TI, PPT

  • legal_idstring

    Número de documento.

  • fiscalobject

    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.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

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

Eliminar un cliente

DELETE/customers/{id}

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.

Permiso billing.customers.destroy

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

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

Productos

Lo que vendes.

El objeto product
  • idstring

    prod_…

  • objectstring

    product

  • keystring

    Tu código del producto («pro», «usuario-adicional»): único por modo; null si no tiene.

  • namestring

    Nombre del plan («Plan Gold»).

  • descriptionstring

    Descripción.

  • activeboolean

    false: archivado, no admite precios nuevos.

  • entitlementsobject

    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_addonboolean

    Es un adicional (se vende sobre un plan base).

  • is_trialboolean

    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.

  • kindenum

    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_pricesarray

    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_quantityboolean

    Se vende por unidades: sus límites se multiplican por la cantidad. false: la cantidad es 1.

  • addon_rulesobject

    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_addboolean

    Agregado a mitad de ventana, sus cupos medidos dan la parte proporcional de los días que quedan.

  • meter_windowenum

    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.

  • availabilityenum

    public (a la venta), coming_soon (se lista apagado, no se vende) o internal (nunca se lista ni se vende).

  • availability_notestring

    Nota de la disponibilidad («llega en enero»).

  • storefrontobject

    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…).

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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

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

Permiso billing.products.createAdmite Idempotency-Key

Cuerpo (JSON)

  • namestringobligatorio

    Nombre.

  • descriptionstring

    Descripción.

  • activeboolean

    Activo (por defecto true).

  • keystring

    Tu código del producto, único por modo.

  • entitlementsobject

    {features: [claves], limits: {clave: número}} de tu vocabulario; -1 = ilimitado. Se reemplaza entero.

  • is_addonboolean

    Es un adicional.

  • is_trialboolean

    Es tu producto de prueba (uno activo por modo); no cambia si ya tiene precios.

  • supports_quantityboolean

    Se vende por unidades (por defecto true).

  • requires_featuresarray

    Adicional: módulos que la suscripción ya debe tener.

  • allowed_base_productsarray

    Adicional: ids de los planes sobre los que se vende (vacío = todos).

  • skip_if_includedboolean

    Adicional: no se vende si el plan ya da todos sus módulos.

  • allowed_during_trialboolean

    Adicional: se vende durante la prueba (por defecto false).

  • prorate_limits_on_addboolean

    Prorratear sus cupos medidos al agregarlo a mitad de ventana.

  • meter_windowenum

    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

  • availabilityenum

    Disponibilidad.

    Valores: public, coming_soon, internal

  • availability_notestring

    Nota de disponibilidad.

  • marketing_featuresarray

    Textos de la vitrina (hasta 30).

  • positioninteger

    Orden en la vitrina.

  • featuredboolean

    Destacado.

  • visible_in_pricingboolean

    Visible en la vitrina (por defecto true).

  • placementenum

    En la vitrina: main (por defecto), una tarjeta entre los planes principales; secondary, una línea bajo ellos.

    Valores: main, secondary

  • iconstring

    Ícono.

  • groupstring

    Grupo libre (module, seats, units…).

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

Del más reciente al más antiguo.

Permiso billing.products.list

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • activeboolean

    Solo activos o archivados.

  • keystring

    Tu código exacto.

  • availabilityenum

    Disponibilidad.

    Valores: public, coming_soon, internal

  • is_addonboolean

    Solo adicionales o solo planes.

  • is_trialboolean

    Solo el producto de prueba.

  • groupstring

    Grupo exacto.

  • visible_in_pricingboolean

    Solo los visibles en la vitrina.

  • placementenum

    Solo los de esa ubicación en la vitrina.

    Valores: main, secondary

  • kindenum

    Solo los de ese tipo (kind).

    Valores: plan, addon, one_time, trial

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited, parameter_invalid

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto product

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Actualizar o archivar un producto

PATCH/products/{id}

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.

Permiso billing.products.update

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • namestring

    Nombre.

  • descriptionstring

    Descripción.

  • activeboolean

    Activo (por defecto true).

  • keystring

    Tu código del producto, único por modo.

  • entitlementsobject

    {features: [claves], limits: {clave: número}} de tu vocabulario; -1 = ilimitado. Se reemplaza entero.

  • is_addonboolean

    Es un adicional.

  • is_trialboolean

    Es tu producto de prueba (uno activo por modo); no cambia si ya tiene precios.

  • supports_quantityboolean

    Se vende por unidades (por defecto true).

  • requires_featuresarray

    Adicional: módulos que la suscripción ya debe tener.

  • allowed_base_productsarray

    Adicional: ids de los planes sobre los que se vende (vacío = todos).

  • skip_if_includedboolean

    Adicional: no se vende si el plan ya da todos sus módulos.

  • allowed_during_trialboolean

    Adicional: se vende durante la prueba (por defecto false).

  • prorate_limits_on_addboolean

    Prorratear sus cupos medidos al agregarlo a mitad de ventana.

  • meter_windowenum

    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

  • availabilityenum

    Disponibilidad.

    Valores: public, coming_soon, internal

  • availability_notestring

    Nota de disponibilidad.

  • marketing_featuresarray

    Textos de la vitrina (hasta 30).

  • positioninteger

    Orden en la vitrina.

  • featuredboolean

    Destacado.

  • visible_in_pricingboolean

    Visible en la vitrina (por defecto true).

  • placementenum

    En la vitrina: main (por defecto), una tarjeta entre los planes principales; secondary, una línea bajo ellos.

    Valores: main, secondary

  • iconstring

    Ícono.

  • groupstring

    Grupo libre (module, seats, units…).

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

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

Eliminar un producto

DELETE/products/{id}

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

Permiso billing.products.destroy

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto eliminado

Errores posibles: api_key_invalid, rate_limited, resource_missing, product_has_prices

curl
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
  • idstring

    price_…

  • objectstring

    price

  • productstring

    Producto (expandible).

  • nicknamestring

    Nombre interno.

  • typeenum

    recurring (se cobra cada ciclo: suscripciones) o one_time (pago único: facturas únicas, paquetes).

  • amountinteger

    En la unidad de la moneda: pesos enteros (89900 = $89.900) o centavos de dólar (2900 = US$29).

  • currencyenum

    COP o USD. Wompi cobra en pesos: un precio en dólares se convierte en cada cobro con la TRM vigente.

  • intervalenum

    Cada cuánto: day, week, month, year. null en un pago único.

  • interval_countinteger

    Cuántos intervalos por ciclo (1–36). null en un pago único.

  • trial_daysinteger

    Días de prueba gratis (0 en un pago único).

  • recurringobject

    interval, interval_count y trial_days de un precio recurrente; null si es único.

  • metered_ratesobject

    {clave_del_medidor: {unit_amount, per_units}}: el excedente de cada límite medido. {} = sin excedente.

  • activeboolean

    false: archivado, no admite suscripciones nuevas.

  • in_useboolean

    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.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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

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.

Permiso billing.prices.createAdmite Idempotency-Key

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Cuerpo (JSON)

  • productstringobligatorio

    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).

  • amountintegerobligatorio

    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.

  • currencyenum

    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

  • typeenum

    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

  • recurringobject

    {interval, interval_count?, trial_days?} (la forma de Stripe), en vez de los tres campos planos.

  • intervalenum

    Por defecto month.

    Valores: day, week, month, year

  • interval_countinteger

    Por defecto 1.

  • trial_daysinteger

    Días de prueba (por defecto 0).

  • nicknamestring

    Nombre interno.

  • activeboolean

    Por defecto true.

  • metered_ratesobject

    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.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • productstring

    Solo los de este producto.

  • activeboolean

    Activos o no.

  • typeenum

    Solo recurrentes o solo únicos.

    Valores: recurring, one_time

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited, parameter_invalid

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto price

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Actualizar un precio

PATCH/prices/{id}

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.

Permiso billing.prices.update

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • nicknamestring

    Nombre interno.

  • activeboolean

    Archivar o reactivar.

  • metered_ratesobject

    Reemplaza las tarifas de excedente. Aplican a las unidades que se tomen desde ahora; cada una conserva la tarifa con la que se tomó.

  • amountinteger

    Solo sin uso. En la unidad de currency, como al crearlo.

  • currencyenum

    Solo sin uso, y con amount en la unidad de la nueva moneda.

    Valores: COP, USD

  • typeenum

    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

  • recurringobject

    Solo sin uso. {interval, interval_count?, trial_days?}.

  • intervalenum

    Solo sin uso.

    Valores: day, week, month, year

  • interval_countinteger

    Solo sin uso.

  • trial_daysinteger

    Solo sin uso.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

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

Suscripciones

El contrato recurrente.

El objeto subscription_change
  • idstring

    sc_…

  • objectstring

    subscription_change

  • subscriptionstring

    Suscripción (expandible).

  • invoicestring

    Factura que cobra el cambio (expandible).

  • statusenum

    pending (esperando el cobro), applied (pagado y aplicado) o failed (no se cobró: nada cambió).

  • amountinteger

    Lo que se cobra, en currency.

  • currencystring

    La de la suscripción.

  • quoteobject

    La cotización cobrada, como la mostró la vista previa.

  • applied_atdatetime

    Cuándo se aplicó.

  • failed_atdatetime

    Cuándo falló.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Creado.

  • updateddatetime

    Ú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
  • idstring

    sa_…

  • objectstring

    subscription_action

  • subscriptionstring

    La suscripción (sub_…).

  • kindenum

    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).

  • actorstring

    Quién (la llave «nombre» o el correo de la persona).

  • reasonstring

    Por qué.

  • detailsobject

    Lo que cambió (fechas antes y después, la factura, el reembolso…).

  • livemodeboolean

    true en producción.

  • createddatetime

    Cuándo.

El objeto subscription
  • idstring

    sub_…

  • objectstring

    subscription

  • statusenum

    Estado: incomplete, incomplete_expired, trialing, active, past_due, canceled, paused.

  • customerstring

    Cliente (expandible).

  • pricestring

    Precio del primer ítem (expandible). Se conserva por compatibilidad: lo nuevo es items.

  • itemsobject

    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_anchordatetime

    Desde dónde se cuentan los periodos (el inicio del primer periodo completo); null en suscripciones anteriores a este campo.

  • pending_pricestring

    Precio que aplica desde el próximo ciclo (expandible).

  • default_payment_methodstring

    Método con el que se cobra (expandible).

  • latest_invoicestring

    Última factura (expandible).

  • start_datedatetime

    Inicio.

  • current_period_startdatetime

    Inicio del periodo en curso.

  • current_period_enddatetime

    Fin del periodo en curso.

  • next_billing_atdatetime

    Próximo cobro.

  • trial_startdatetime

    Inicio de la prueba.

  • trial_enddatetime

    Fin de la prueba.

  • cancel_at_period_endboolean

    Se cancelará al terminar el periodo.

  • canceled_atdatetime

    Cuándo se pidió la cancelación.

  • ended_atdatetime

    Cuándo terminó.

  • cancellation_detailsobject

    reason y comment de la cancelación.

  • pending_updateobject

    El subscription_change que espera su cobro, o null.

  • discountobject

    El discount vigente (el cupón aplicado), o null.

  • pause_at_period_endboolean

    true: al terminar el periodo pagado queda paused (ver «Pausar el cobro»).

  • paused_atdatetime

    Desde cuándo está pausada, o null.

  • resumes_atdatetime

    Cuándo se reanuda sola, o null (a mano).

  • fixed_term_ends_atdatetime

    Un plan por tiempo fijo: cuándo termina (no renueva ni tiene gracia); null en una suscripción normal.

  • overage_capsobject

    {clave_del_medidor: valor}: el tope de excedente que fijó el cliente; un medidor que no esté vale lo que cuesta el plan.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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
  • objectstring

    subscription_quote

  • subscriptionstring

    La suscripción (sub_…).

  • directionenum

    up, down o even.

  • appliesenum

    now (al pagarse, o ya si es gratis) o renewal.

  • amountinteger

    Lo que se cobra ahora, en currency (el expected_amount del cambio).

  • currencystring

    La de la suscripción.

  • linesarray

    [{description, amount}]: lo que se cobra y los créditos (negativos).

  • days_leftinteger

    Días que quedan del periodo (hoy incluido).

  • period_daysinteger

    Días del periodo.

  • restarts_periodboolean

    true: un ciclo más largo empieza un periodo hoy.

  • below_minimumboolean

    true: bajo el mínimo de Wompi, aplica gratis.

  • period_startdatetime

    Inicio del periodo después del cambio.

  • period_enddatetime

    Fin del periodo después del cambio.

  • total_beforeinteger

    Lo que cuesta cada periodo hoy.

  • total_afterinteger

    Lo que costará cada periodo después del cambio.

Crear una suscripción

POST/subscriptions

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.

Permiso billing.subscriptions.createAdmite Idempotency-Key

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Cuerpo (JSON)

  • customerstringobligatorio

    Id del cliente.

  • pricestring

    Id de un precio recurrente activo (o envía items).

  • quantityinteger

    Cantidad del precio (por defecto 1).

  • itemsarray

    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_methodstring

    Id de un método del cliente (por defecto, su predeterminado).

  • trial_daysinteger

    Días de prueba (por defecto, los del precio).

  • trial_enddatetime

    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_anchordatetime

    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_behaviorenum

    Al crear no hay nada que prorratear: none o create_prorations dan lo mismo.

    Valores: none, create_prorations

  • trial_keystring

    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_capsobject

    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.

  • couponstring

    Id de un cupón: rebaja desde la primera factura de periodo.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • statusenum

    Estado.

    Valores: incomplete, incomplete_expired, trialing, active, past_due, canceled, paused

  • customerstring

    Id del cliente.

  • pricestring

    Id del precio.

  • metadata[<clave>]string

    Solo las que tienen ese par en su metadata (metadata[legacy_id]=123).

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited, parameter_invalid

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

Consultar una suscripción

GET/subscriptions/{id}

Expande customer, price, default_payment_method o latest_invoice.

Permiso billing.subscriptions.retrieve

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto subscription

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Actualizar una suscripción

PATCH/subscriptions/{id}

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.

Permiso billing.subscriptions.update

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • pricestring

    Precio desde el próximo ciclo.

  • itemsarray

    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_methodstring

    Método con el que se cobra.

  • cancel_at_period_endboolean

    Cancelar al fin del periodo (o deshacerlo).

  • proration_behaviorenum

    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_amountinteger

    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_capsobject

    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.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

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.

Permiso billing.subscriptions.updateAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • pricestring

    Cambio de plan de una suscripción de un ítem.

  • itemsarray

    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).

curl
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

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

Permiso billing.subscriptions.cancelAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • at_period_endboolean

    Por defecto false.

  • reasonenum

    Motivo.

    Valores: requested_by_customer, requested_by_merchant, payment_failed, trial_ended, refunded, fixed_term_ended

  • commentstring

    Comentario.

Responde: El objeto subscription

Errores posibles: api_key_invalid, rate_limited, resource_missing, subscription_not_updatable

curl
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

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).

Permiso billing.subscriptions.manageAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • resumes_atdatetime

    Cuándo se reanuda sola (después del fin del periodo). Sin ella, a mano.

  • reasonstring

    Por qué (queda en la bitácora).

curl
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

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.

Permiso billing.subscriptions.manageAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • reasonstring

    Por qué.

curl
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

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).

Permiso billing.subscriptions.manageAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • daysinteger

    Cuántos días más (o until).

  • untildatetime

    Hasta cuándo (o days).

  • reasonstring

    Por qué.

curl
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

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.

Permiso billing.subscriptions.manageAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • trial_enddatetimeobligatorio

    Nuevo fin de la prueba.

  • reasonstring

    Por qué.

Responde: El objeto subscription

Errores posibles: api_key_invalid, rate_limited, resource_missing, trial_not_running, trial_end_invalid

curl
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

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).

Permiso billing.subscriptions.manageAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • pricestring

    El plan al que pasa (price_…): nunca el de la prueba ni el de un adicional. Con varios ítems, cámbialos antes.

  • reasonstring

    Por qué.

curl
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

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.

Permiso billing.subscriptions.manageAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • couponstringobligatorio

    Id del cupón.

  • reasonstring

    Por qué.

curl
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

Los cobros (invoice) ya abiertos lo conservan.

Permiso billing.subscriptions.manage

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • reasonstring

    Por qué.

Responde: El objeto subscription

Errores posibles: api_key_invalid, rate_limited, resource_missing, discount_missing

curl
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

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.

Permiso billing.subscriptions.retrieve

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    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 paginada

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
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
  • idstring

    si_… (null solo un momento después de un despliegue, en una suscripción anterior).

  • objectstring

    subscription_item

  • subscriptionstring

    Suscripción (expandible).

  • priceobject

    El precio completo (recurrente, con el intervalo de la suscripción).

  • quantityinteger

    Cantidad (puestos, licencias): se cobra price.amount × quantity cada periodo.

  • scheduled_quantityinteger

    Cantidad desde la renovación (un cambio con create_prorations que baja el valor); 0 = se quita. null = sin cambio.

  • scheduled_pricestring

    Precio desde la renovación (price_…), o null.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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

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.

Permiso billing.subscription_items.createAdmite Idempotency-Key

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Cuerpo (JSON)

  • subscriptionstringobligatorio

    Id de la suscripción.

  • pricestringobligatorio

    Id de un precio recurrente activo.

  • quantityinteger

    Cantidad (por defecto 1).

  • proration_behaviorenum

    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_amountinteger

    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.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

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

Permiso billing.subscription_items.list

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • subscriptionstring

    Id de la suscripción.

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto subscription_item

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Cambiar un ítem

PATCH/subscription_items/{id}

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.

Permiso billing.subscription_items.update

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • pricestring

    Otro precio recurrente del mismo intervalo.

  • quantityinteger

    Cantidad nueva.

  • proration_behaviorenum

    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_amountinteger

    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.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

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

Quitar un ítem

DELETE/subscription_items/{id}

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.

Permiso billing.subscription_items.destroy

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • proration_behaviorenum

    none (por defecto, se quita ya) o create_prorations (se queda hasta la renovación).

    Valores: none, create_prorations

  • expected_amountinteger

    Con create_prorations: 0 (quitar nunca cobra).

curl
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
  • idstring

    pm_…

  • objectstring

    payment_method

  • typeenum

    card o nequi.

  • statusenum

    Estado: pending, available, failed, detached, suspended.

  • customerstring

    Cliente (expandible); null si se quitó.

  • is_defaultboolean

    Si es el predeterminado del cliente.

  • is_backupboolean

    Si es la de respaldo: se intenta enseguida cuando la predeterminada rechaza.

  • suspendedobject

    {at, reason} de un rechazo duro (robada, perdida, vencida…): no se vuelve a cobrar. null si no.

  • cardobject

    brand, last4, exp_month, exp_year (solo tarjetas).

  • nequiobject

    phone_last4 (solo Nequi).

  • importedobject

    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.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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

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

Permiso billing.payment_methods.list

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    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 paginada

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
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

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.

Permiso billing.payment_methods.createAdmite Idempotency-Key

Cuerpo (JSON)

  • customerstringobligatorio

    Id del cliente (cus_…).

  • wompi_payment_source_idstringobligatorio

    Id numérico de la fuente de pago en Wompi.

  • make_defaultboolean

    Hacerla la predeterminada (por defecto false).

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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}

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

Permiso billing.payment_methods.list

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto payment_method

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
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

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

Permiso billing.payment_methods.defaultAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto payment_method

Errores posibles: api_key_invalid, rate_limited, resource_missing, payment_method_unavailable

curl
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

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.

Permiso billing.payment_methods.defaultAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

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

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
  • idstring

    il_…

  • objectstring

    invoice_line

  • invoicestring

    Factura (expandible).

  • descriptionstring

    Qué se cobra («Puesto adicional × 3»).

  • priceobject

    El precio completo, o null en un monto libre.

  • subscription_itemstring

    Ítem de la suscripción que la originó, o null.

  • productstring

    El producto de la línea (prod_…), o null en un monto libre o un excedente.

  • groupstring

    El group del producto (para comisiones por plan y adicionales), o null.

  • is_addonboolean

    true si el producto es un adicional.

  • quantityinteger

    Cantidad.

  • unit_amountinteger

    Valor unitario, en la moneda de la factura.

  • amountinteger

    unit_amount × quantity (precio de lista).

  • discount_amountinteger

    Lo que el cupón le rebaja a esta línea.

  • currencystring

    La de la factura.

  • period_startdatetime

    Inicio del periodo que cubre (null en un pago único).

  • period_enddatetime

    Fin del periodo que cubre.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

El objeto invoice
  • idstring

    in_…

  • objectstring

    invoice

  • numberstring

    Consecutivo de la cuenta.

  • statusenum

    Estado: draft, open, paid, void, uncollectible.

  • customerstring

    Cliente (expandible).

  • subscriptionstring

    Suscripción (expandible).

  • pricestring

    Precio de la primera línea (expandible).

  • default_payment_methodstring

    Método con que se cobra una factura única (expandible); null: el de la suscripción o el predeterminado del cliente.

  • amountinteger

    Lo que se cobra: subtotal − discount_amount, en la moneda de la factura.

  • subtotalinteger

    La suma de las líneas a precio de lista.

  • discount_amountinteger

    Lo que rebajó el cupón (la suma de discount_amount de las líneas).

  • discountstring

    El discount que la rebajó (di_…), o null.

  • currencyenum

    COP o USD: la de sus precios.

  • charged_amountinteger

    Lo que Wompi cobró, en pesos (al pagarse); null antes.

  • exchange_ratestring

    Pesos por unidad de currency con que se cobró ("1" en pesos); null antes de pagarse.

  • linesobject

    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.

  • retryboolean

    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_reasonenum

    Motivo: subscription_create, subscription_cycle, subscription_update, payment_link, manual, fixed_term.

  • descriptionstring

    Descripción.

  • period_startdatetime

    Inicio del periodo facturado.

  • period_enddatetime

    Fin del periodo facturado.

  • attempt_countinteger

    Intentos de cobro hechos.

  • next_payment_attemptdatetime

    Próximo reintento.

  • paid_atdatetime

    Cuándo se pagó.

  • voided_atdatetime

    Cuándo se anuló.

  • fiscal_documentobject

    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.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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

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.

Permiso billing.invoices.createAdmite Idempotency-Key

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Cuerpo (JSON)

  • customerstringobligatorio

    Id del cliente.

  • linesarray

    [{price, quantity?, description?, metadata?}], de 1 a 20 precios de pago único activos.

  • amountinteger

    Monto libre en vez de lines (con description), en la unidad de currency.

  • currencyenum

    Con amount: COP (por defecto) o USD. Con lines, la de sus precios.

    Valores: COP, USD

  • descriptionstring

    Qué se cobra; obligatoria con amount.

  • default_payment_methodstring

    Id de un método del cliente (por defecto, su predeterminado).

  • auto_chargeboolean

    Cobrarla ya (por defecto true); con false espera a /pay.

  • retryboolean

    Reintentar un rechazo según tu calendario (por defecto false).

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

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

Permiso billing.invoices.retrieve

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    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 paginada

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
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

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • statusenum

    Estado.

    Valores: draft, open, paid, void, uncollectible

  • customerstring

    Id del cliente.

  • subscriptionstring

    Id de la suscripción.

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited, parameter_invalid

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto invoice

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Cobrar una factura ahora

POST/invoices/{id}/pay

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.

Permiso billing.invoices.payAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

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

Registrar un pago manual

POST/invoices/{id}/mark_paid

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.

Permiso billing.invoices.mark_paidAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • referencestringobligatorio

    Referencia de la transferencia.

  • reasonstring

    Nota (queda en la bitácora).

curl
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
  • idstring

    py_…

  • objectstring

    payment

  • invoicestring

    Factura (expandible).

  • customerstring

    Cliente (expandible).

  • payment_methodstring

    Método cobrado (expandible).

  • attempt_numberinteger

    Número del intento en la factura.

  • referencestring

    Referencia enviada a Wompi (inv_<id>_<n>).

  • amountinteger

    Lo enviado a Wompi, en pesos enteros.

  • currencystring

    COP (Wompi solo cobra pesos).

  • invoice_amountinteger

    El valor de la factura en su moneda cuando se cobró.

  • invoice_currencystring

    La moneda de la factura.

  • exchange_ratestring

    Pesos por unidad de la moneda de la factura (la TRM usada); null en pesos.

  • exchange_rate_datedate

    Desde cuándo rige esa tasa; null en pesos.

  • statusenum

    Estado: pending, approved, declined, error, voided.

  • sourceenum

    wompi o manual (una transferencia registrada con mark_paid).

  • external_referencestring

    La referencia de un pago manual, o null.

  • amount_refundedinteger

    Pesos devueltos (reembolsos y anulaciones).

  • refundedboolean

    true cuando se devolvió todo.

  • wompi_transaction_idstring

    Transacción en Wompi.

  • failure_codestring

    Código del rechazo.

  • failure_messagestring

    Motivo del rechazo, en palabras del banco o de Wompi.

  • sent_atdatetime

    Cuándo se envió a Wompi.

  • finalized_atdatetime

    Cuándo se resolvió.

  • livemodeboolean

    true en producción.

  • createddatetime

    Cuándo se creó.

Listar pagos

GET/payments

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

Permiso billing.payments.list

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • invoicestring

    Id de la factura.

  • statusenum

    Estado.

    Valores: pending, approved, declined, error, voided

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited, parameter_invalid

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto payment

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Reembolsar un pago

POST/payments/{id}/refund

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.

Permiso billing.payments.refundAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • amountinteger

    Pesos a devolver (por defecto, todo lo que queda).

  • reasonstring

    Motivo.

  • cancel_subscriptionboolean

    Cancelar la suscripción al quedar hecho.

curl
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

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).

Permiso billing.payments.refundAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • reasonstring

    Motivo.

  • cancel_subscriptionboolean

    Cancelar la suscripción al quedar hecha.

curl
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
  • idstring

    di_…

  • objectstring

    discount

  • subscriptionstring

    La suscripción (sub_…).

  • couponobject

    El cupón completo.

  • statusenum

    active, ended (se gastó) o removed (se quitó).

  • startdatetime

    Desde cuándo.

  • enddatetime

    Con repeating: los periodos que empiezan desde aquí ya no llevan descuento.

  • ended_atdatetime

    Cuándo terminó o se quitó.

  • livemodeboolean

    true en producción.

  • createddatetime

    Cuándo se aplicó.

El objeto coupon
  • idstring

    coupon_…

  • objectstring

    coupon

  • namestring

    Nombre (se ve en la factura).

  • percent_offstring

    Porcentaje de descuento ("20", "12.5"), o null.

  • amount_offinteger

    Valor de descuento por periodo, en la unidad de currency, o null.

  • currencystring

    La moneda de amount_off; null con percent_off.

  • durationenum

    once (un periodo), repeating (N meses) o forever.

  • duration_in_monthsinteger

    Con repeating: cuántos meses desde que se aplica.

  • applies_toenum

    all (el plan y los adicionales), plan o addons.

  • max_redemptionsinteger

    A cuántas suscripciones se puede aplicar; null = sin tope.

  • redeem_bydatetime

    Hasta cuándo se puede aplicar; null = sin fecha.

  • times_redeemedinteger

    A cuántas suscripciones se aplicó. Desde la primera, sus términos no cambian.

  • activeboolean

    false: no se aplica a nadie más (los aplicados siguen).

  • validboolean

    Si se puede aplicar ahora (activo, sin vencer y con usos).

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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

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.

Permiso billing.coupons.createAdmite Idempotency-Key

Cuerpo (JSON)

  • namestringobligatorio

    Nombre.

  • percent_offnumber

    Porcentaje, de 0,01 a 100 (o amount_off).

  • amount_offinteger

    Valor por periodo, en la unidad de currency (o percent_off).

  • currencyenum

    Con amount_off (por defecto COP).

    Valores: COP, USD

  • durationenumobligatorio

    Duración.

    Valores: once, repeating, forever

  • duration_in_monthsinteger

    Con repeating, de 1 a 120.

  • applies_toenum

    Por defecto all.

    Valores: all, plan, addons

  • max_redemptionsinteger

    Tope de suscripciones.

  • redeem_bydatetime

    Fecha límite para aplicarlo.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

Responde: El objeto coupon

Errores posibles: api_key_invalid, rate_limited, parameter_invalid

curl
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

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

Permiso billing.coupons.list

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    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 paginada

Errores posibles: api_key_invalid, rate_limited

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto coupon

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Editar un cupón

PATCH/coupons/{id}

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).

Permiso billing.coupons.update

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • namestring

    Nombre.

  • activeboolean

    false: no se aplica a nadie más.

  • max_redemptionsinteger

    Tope de suscripciones.

  • redeem_bydatetime

    Fecha límite.

  • percent_offnumber

    Solo sin usos.

  • amount_offinteger

    Solo sin usos.

  • currencyenum

    Solo sin usos.

    Valores: COP, USD

  • durationenum

    Solo sin usos.

    Valores: once, repeating, forever

  • duration_in_monthsinteger

    Solo sin usos.

  • applies_toenum

    Solo sin usos.

    Valores: all, plan, addons

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

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

Eliminar un cupón

DELETE/coupons/{id}

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

Permiso billing.coupons.destroy

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto eliminado

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Reembolsos

El dinero que devuelves.

El objeto refund
  • idstring

    re_…

  • objectstring

    refund

  • paymentstring

    El pago devuelto (expandible).

  • invoicestring

    Su factura (expandible).

  • subscriptionstring

    La suscripción de la factura, o null.

  • kindenum

    void (anulación del cobro completo, el mismo día) o refund (total o parcial).

  • sourceenum

    bucli (pedido aquí), external (anulado desde el panel de Wompi) o manual (un pago manual devuelto por fuera: solo se registra).

  • statusenum

    pending (Wompi no ha respondido), succeeded o failed.

  • amountinteger

    Pesos devueltos (Wompi devuelve en pesos).

  • currencystring

    COP.

  • reasonstring

    Motivo.

  • requested_bystring

    Quién lo pidió (la llave o la persona).

  • cancel_subscriptionboolean

    Si cancela la suscripción al quedar hecho (motivo refunded).

  • failure_messagestring

    Por qué falló, en palabras de Wompi.

  • credit_noteobject

    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.

  • linesarray

    Las líneas invoice_line de la factura: lo que se había pagado.

  • finalized_atdatetime

    Cuándo se resolvió.

  • livemodeboolean

    true en producción.

  • createddatetime

    Cuándo se pidió.

  • updateddatetime

    Ú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

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

Permiso billing.refunds.list

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • paymentstring

    Id del pago.

  • invoicestring

    Id de la factura.

  • statusenum

    Estado.

    Valores: pending, succeeded, failed

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited, parameter_invalid

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto refund

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
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
  • idstring

    fto_…

  • objectstring

    fixed_term_offer

  • customerstring

    Cliente (expandible).

  • namestring

    Nombre.

  • itemsarray

    [{price, quantity}].

  • unitsarray

    [{meter, units}]: unidades para todo el plazo.

  • daysinteger

    Días del plazo.

  • amountinteger

    Precio en pesos.

  • currencystring

    COP.

  • statusenum

    open (esperando el pago), paid, expired o canceled.

  • urlstring

    El link de pago de Wompi.

  • link_expires_atdatetime

    Cuándo vence el link.

  • subscriptionstring

    La suscripción que empezó al pagarse, o null.

  • paid_atdatetime

    Cuándo se pagó.

  • livemodeboolean

    true en producción.

  • createddatetime

    Cuándo se creó.

  • updateddatetime

    Ú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

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.

Permiso billing.fixed_term_offers.createAdmite Idempotency-Key

Cuerpo (JSON)

  • customerstringobligatorio

    Id del cliente.

  • itemsarrayobligatorio

    [{price, quantity}]: el plan base primero, luego los adicionales.

  • unitsarray

    [{meter, units}]: la clave del medidor y las unidades para todo el plazo.

  • daysintegerobligatorio

    Días del plazo.

  • amountintegerobligatorio

    Precio en pesos (desde el mínimo de Wompi).

  • namestring

    Nombre (por defecto «<plan> por N días»).

  • link_daysinteger

    Días que vive el link de pago, de 1 a 30.

curl
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

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • customerstring

    Id del cliente.

  • statusenum

    Estado.

    Valores: open, paid, expired, canceled

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited, parameter_invalid

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto fixed_term_offer

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
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

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

Permiso billing.fixed_term_offers.cancelAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto fixed_term_offer

Errores posibles: api_key_invalid, rate_limited, resource_missing, fixed_term_offer_not_open

curl
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
  • idstring

    evt_… — deduplica con él.

  • objectstring

    event

  • typestring

    Tipo (ver la lista de eventos).

  • sequenceinteger

    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_versionstring

    Versión con la que se armó data.

  • dataobject

    object (el objeto como lo responde la API) y, si cambió, previous_attributes.

  • requestobject

    id e idempotency_key de la petición a la API que lo causó, o null.

  • livemodeboolean

    true en producción.

  • createddatetime

    Cuándo pasó.

Listar eventos

GET/events

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.

Permiso webhooks.events.list

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • typestring

    Un tipo (invoice.paid) o un grupo (invoice.*).

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited, parameter_invalid

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto event

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Reenviar un evento

POST/events/{id}/resend

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.

Permiso webhooks.events.resendAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • webhook_endpointstring

    Id de un endpoint (we_…).

Responde: El objeto event

Errores posibles: api_key_invalid, rate_limited, resource_missing, feature_not_available

curl
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
  • idstring

    we_…

  • objectstring

    webhook_endpoint

  • urlstring

    URL HTTPS pública que recibe los eventos.

  • descriptionstring

    Para qué es.

  • enabled_eventsarray

    Tipos que recibe; ["*"] = todos.

  • statusenum

    enabled o disabled.

  • disabled_reasonstring

    Por qué se desactivó.

  • api_versionstring

    Versión de los eventos que recibe.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

Crear un endpoint de webhook

POST/webhook_endpoints

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).

Permiso webhooks.webhook_endpoints.createAdmite Idempotency-Key

Cuerpo (JSON)

  • urlstringobligatorio

    URL HTTPS.

  • enabled_eventsarrayobligatorio

    Tipos de evento, o ["*"].

  • descriptionstring

    Para qué es.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    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 paginada

Errores posibles: api_key_invalid, rate_limited

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

Consultar un endpoint de webhook

GET/webhook_endpoints/{id}

Nunca trae el secreto.

Permiso webhooks.webhook_endpoints.retrieve

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto webhook_endpoint

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Actualizar un endpoint de webhook

PATCH/webhook_endpoints/{id}

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.

Permiso webhooks.webhook_endpoints.update

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • urlstring

    URL HTTPS.

  • enabled_eventsarray

    Tipos de evento.

  • descriptionstring

    Para qué es.

  • disabledboolean

    Desactivar o reactivar.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

Responde: El objeto webhook_endpoint

Errores posibles: api_key_invalid, rate_limited, resource_missing, url_invalid, permission_denied, reauth_failed

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto eliminado

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
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

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.

Permiso webhooks.webhook_endpoints.roll_secretAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto webhook_endpoint

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
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
  • idstring

    acct_…

  • objectstring

    account

  • namestring

    Nombre del comercio.

  • api_versionstring

    Versión fijada de la cuenta (o la pedida con Bucli-Version).

  • livemodeboolean

    Modo de la llave.

  • default_currencystring

    COP.

  • countrystring

    CO.

  • webhooks_enabledboolean

    Si el plan envía webhooks.

  • createddatetime

    Cuándo se creó la cuenta.

Consultar la cuenta

GET/account

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

Permiso developers.account.retrieve

Responde: El objeto account

Errores posibles: api_key_invalid, rate_limited

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

Checkout

La página de pago hospedada.

El objeto checkout.session
  • idstring

    cs_…

  • objectstring

    checkout.session

  • statusenum

    open (esperando al cliente), complete (la suscripción quedó creada) o expired.

  • urlstring

    Página de pago hospedada a la que rediriges al cliente; null si ya no está abierta.

  • pricestring

    Precio de la primera línea (expandible). Se conserva por compatibilidad: lo nuevo es line_items.

  • line_itemsarray

    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_totalinteger

    Lo que cuesta cada periodo: la suma de las líneas, en su moneda.

  • currencystring

    COP o USD: la de sus precios.

  • subscription_dataobject

    metadata (la de la suscripción que se crea) y trial_days (el mismo valor que trial_days).

  • customerstring

    Cliente (expandible): el que enviaste o el que se creó o encontró al pagar.

  • customer_emailstring

    Correo sugerido (no editable en la página).

  • customer_fieldsarray

    Datos que se piden además del correo: name, legal_id, phone.

  • trial_daysinteger

    Días de prueba de esta suscripción; null = los del precio.

  • success_urlstring

    A dónde vuelve el cliente al terminar, con ?session_id=cs_….

  • cancel_urlstring

    A dónde vuelve si se arrepiente.

  • client_reference_idstring

    Tu referencia (el id de tu usuario, por ejemplo).

  • payment_linkstring

    Enlace de pago que la abrió (expandible).

  • subscriptionstring

    Suscripción creada (expandible).

  • payment_methodstring

    Tarjeta guardada (expandible).

  • expires_atdatetime

    Vence 24 horas después de creada.

  • completed_atdatetime

    Cuándo se completó.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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

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).

Permiso checkout.checkout_sessions.createAdmite llave publicable (pk_)Admite Idempotency-Key

Cuerpo (JSON)

  • pricestring

    Precio que se suscribe (price_…); o line_items.

  • quantityinteger

    Cantidad del price (1–10.000, por defecto 1); no con line_items.

  • line_itemsarray

    [{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_urlstringobligatorio

    A dónde vuelve al terminar (https en producción).

  • cancel_urlstring

    A dónde vuelve si se arrepiente.

  • customerstring

    Cliente existente (cus_…); no con una llave pk_.

  • customer_emailstring

    Correo del cliente, fijo en la página (en vez de customer).

  • customer_fieldsarray

    Datos a pedir además del correo (por defecto ["name"]).

    Valores: name, legal_id, phone

  • trial_daysinteger

    Días de prueba (0–730); por defecto los del precio.

  • client_reference_idstring

    Tu referencia, para reconocer la sesión en el webhook.

  • subscription_dataobject

    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_.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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}

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

Permiso checkout.checkout_sessions.retrieve

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto checkout.session

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
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

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.

Permiso checkout.checkout_sessions.expireAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto checkout.session

Errores posibles: api_key_invalid, rate_limited, resource_missing, checkout_session_not_expirable

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

Vender un plan sin código.

POST/payment_links

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).

Permiso checkout.payment_links.createAdmite Idempotency-Key

Cuerpo (JSON)

  • pricestring

    Precio que vende (price_…); o line_items.

  • quantityinteger

    Cantidad del price (1–10.000, por defecto 1); no con line_items.

  • line_itemsarray

    [{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_fieldsarray

    Datos a pedir además del correo.

    Valores: name, legal_id, phone

  • trial_daysinteger

    Días de prueba (0–730); por defecto los del precio.

  • success_urlstring

    A dónde vuelve el cliente al terminar.

  • activeboolean

    Activo (por defecto true).

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

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

Del más reciente al más antiguo.

Permiso checkout.payment_links.list

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • activeboolean

    Solo activos o inactivos.

  • pricestring

    Solo de un precio.

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited

curl
curl "https://api.bucli.co/v1/payment_links" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
GET/payment_links/{id}

Con cuántos checkouts abrió.

Permiso checkout.payment_links.retrieve

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto payment_link

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
curl "https://api.bucli.co/v1/payment_links/$ID" \
  -H "Authorization: Bearer $BUCLI_SECRET_KEY"
PATCH/payment_links/{id}

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

Permiso checkout.payment_links.update

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • activeboolean

    Activo.

  • customer_fieldsarray

    Datos a pedir además del correo.

    Valores: name, legal_id, phone

  • trial_daysinteger

    Días de prueba.

  • success_urlstring

    A dónde vuelve el cliente al terminar.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

Responde: El objeto payment_link

Errores posibles: api_key_invalid, rate_limited, resource_missing, parameter_invalid

curl
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
  • idstring

    bps_…

  • objectstring

    portal.session

  • customerstring

    Cliente (expandible).

  • return_urlstring

    A dónde vuelve el cliente desde el portal.

  • urlstring

    Portal del cliente; solo en la respuesta de creación (es una credencial): null al consultarla.

  • expires_atdatetime

    Vence una hora después de creada.

  • livemodeboolean

    true en producción.

  • createddatetime

    Cuándo se creó.

Crear una sesión del portal

POST/portal_sessions

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.

Permiso checkout.portal_sessions.createAdmite Idempotency-Key

Cuerpo (JSON)

  • customerstringobligatorio

    Cliente (cus_…).

  • return_urlstring

    A dónde vuelve; por defecto la de «Portal y marca».

curl
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}

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.

Permiso checkout.portal_sessions.retrieve

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto portal.session

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
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
  • idstring

    feat_…

  • objectstring

    feature

  • keystring

    Tu clave (einvoicing, users): minúsculas, números y _. No cambia.

  • namestring

    Nombre.

  • descriptionstring

    Descripción.

  • typeenum

    boolean (un módulo) o limit (un número).

  • limit_kindenum

    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_unlimitedboolean

    De un límite: false = nunca es ilimitado (-1). null en un módulo.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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

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).

Permiso entitlements.features.createAdmite Idempotency-Key

Cuerpo (JSON)

  • keystringobligatorio

    Minúsculas, números y _, empieza por letra (máximo 50). No cambia.

  • namestringobligatorio

    Nombre.

  • typeenumobligatorio

    boolean o limit.

    Valores: boolean, limit

  • limit_kindenum

    De un límite: static o metered.

    Valores: static, metered

  • allows_unlimitedboolean

    De un límite: false = nunca ilimitado (por defecto true).

  • descriptionstring

    Descripción.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

Tu vocabulario, por clave.

Permiso entitlements.features.list

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • typeenum

    Solo módulos o solo límites.

    Valores: boolean, limit

  • keystring

    Clave exacta.

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited, parameter_invalid

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto feature

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Actualizar un derecho

PATCH/features/{id}

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.

Permiso entitlements.features.update

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • namestring

    Nombre.

  • descriptionstring

    Descripción.

  • allows_unlimitedboolean

    Solo de un límite.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

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

Eliminar un derecho

DELETE/features/{id}

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

Permiso entitlements.features.destroy

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto eliminado

Errores posibles: api_key_invalid, rate_limited, resource_missing, feature_in_use

curl
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
  • objectstring

    entitlements

  • subscriptionstring

    Suscripción (expandible). En los de un cliente, la única que habla por él, o null si se combinan varias.

  • customerstring

    Cliente (expandible).

  • statusenum

    Estado de la suscripción (null si se combinan varias).

  • featuresarray

    Módulos que tiene, ya con tus ajustes.

  • limitsobject

    {clave: número}, ya con tus ajustes; -1 = ilimitado.

  • productsarray

    [{product, key, name, group, is_addon, quantity}]: los productos que los dan (el plan base es el que no es adicional).

  • accessenum

    Qué puede hacer el cliente: full, read_only, none.

  • read_only_reasonenum

    Por qué está en solo lectura: trial_ended, canceled, payment_overdue, fixed_term_ended, paused. null con acceso completo.

  • period_enddatetime

    Fin del periodo en curso.

  • trial_enddatetime

    Fin de la prueba, si está en prueba.

  • overridesobject

    Tus ajustes a mano: features_add, features_remove, limits (mínimos), note, set_by, set_at; null si no hay.

  • livemodeboolean

    true en producción, false en pruebas.

  • updateddatetime

    Cuándo cambiaron por última vez.

Consultar los derechos de una suscripción

GET/subscriptions/{id}/entitlements

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.

Permiso entitlements.entitlements.retrieve

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto entitlements

Errores posibles: api_key_invalid, rate_limited, resource_missing

curl
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

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.

Permiso entitlements.overrides.updateAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • features_addarray

    Módulos que se suman.

  • features_removearray

    Módulos que se quitan.

  • limitsobject

    {clave: número} mínimos; -1 = ilimitado.

  • notestring

    Por qué (hasta 500 caracteres).

  • keep_currentboolean

    Convertir lo que tiene de más en ajustes (con price y note).

  • pricestring

    Con keep_current: el precio del plan al que baja (por defecto su pending_price).

curl
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

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.

Permiso entitlements.entitlements.retrieve

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto entitlements

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Medidores

Cupos por ventana.

El objeto meter
  • idstring

    mtr_…

  • objectstring

    meter

  • keystring

    La clave del límite medido que cuenta (la misma de /features). En las rutas sirve de id.

  • namestring

    Nombre.

  • windowenum

    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).

  • timezonestring

    Zona horaria de la ventana (America/Bogota).

  • on_unavailableenum

    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_percentinteger

    Porcentaje del cupo que dispara meter.threshold_reached.

  • activeboolean

    false: no admite reservas.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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
  • objectstring

    meter_balance

  • meterstring

    Clave del medidor.

  • customerstring

    Cliente (expandible).

  • window_startdatetime

    Inicio de la ventana.

  • window_enddatetime

    Fin de la ventana (null en una de toda la suscripción).

  • allowanceinteger

    Cupo de la ventana (plan + bloques prorrateados; -1 ilimitado).

  • usedinteger

    Usado del cupo.

  • allowance_remaininginteger

    Lo que queda del cupo (-1 ilimitado).

  • grantsarray

    Bolsas vivas: [{id, remaining, units, expires_at}], la que vence primero primero.

  • grants_remaininginteger

    Saldo de las bolsas vivas.

  • remaininginteger

    Lo que puede gastar: cupo + bolsas (-1 ilimitado).

  • overageinteger

    Unidades por encima del cupo y las bolsas: el excedente cobrado (si el precio tiene tarifa) y lo reportado tarde.

  • overage_amountinteger

    Lo que cuesta el excedente de la ventana (en la moneda del precio).

  • overage_billed_amountinteger

    Lo que de eso ya se cobró en una renovación.

  • overage_rateobject

    {unit_amount, per_units} del plan del cliente, o null (sin excedente).

  • overage_capinteger

    El tope del cliente por ventana, o null (sin excedente).

  • unbilledinteger

    Registrado sin gastar cupo (billable: false).

  • livemodeboolean

    true en producción, false en pruebas.

  • updateddatetime

    Último movimiento.

Crear un medidor

POST/meters

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í.

Permiso entitlements.meters.createAdmite Idempotency-Key

Cuerpo (JSON)

  • keystringobligatorio

    Clave del límite medido.

  • namestringobligatorio

    Nombre.

  • windowenum

    Por defecto calendar_month. No cambia.

    Valores: calendar_month, billing_period, subscription_lifetime

  • timezonestring

    Por defecto America/Bogota. No cambia.

  • on_unavailableenum

    Por defecto deny.

    Valores: allow, deny

  • threshold_percentinteger

    Aviso al (por defecto 80).

  • activeboolean

    Por defecto true.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    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 paginada

Errores posibles: api_key_invalid, rate_limited

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

Consultar un medidor

GET/meters/{id}

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

Permiso entitlements.meters.retrieve

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto meter

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Actualizar un medidor

PATCH/meters/{id}

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

Permiso entitlements.meters.update

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • namestring

    Nombre.

  • on_unavailableenum

    allow o deny.

    Valores: allow, deny

  • threshold_percentinteger

    Aviso al.

  • activeboolean

    Activo.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

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

Permiso entitlements.meters.retrieve

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • customerstringobligatorio

    Id del cliente.

Responde: El objeto meter_balance

Errores posibles: api_key_invalid, rate_limited, resource_missing, parameter_missing

curl
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
  • idstring

    usg_…

  • objectstring

    usage_record

  • meterstring

    Clave del medidor.

  • customerstring

    Cliente (expandible).

  • quantityinteger

    Unidades.

  • billableboolean

    false: se registró sin gastar cupo.

  • sourceenum

    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.

  • grantstring

    La bolsa, si salió de una sola (grt_…).

  • allocationsarray

    [{source, units, grant}]: cada parte, para devolverla a su origen. Una parte overage con tarifa trae además unit_amount y per_units.

  • remaininginteger

    Lo que le queda al cliente tras esta reserva (cupo + bolsas; -1 ilimitado).

  • idempotency_keystring

    Tu llave: la misma devuelve la misma reserva.

  • reportedboolean

    Se reportó después (POST /usage), no se reservó.

  • window_startdatetime

    Inicio de la ventana en que cuenta.

  • occurred_atdatetime

    Cuándo ocurrió.

  • released_atdatetime

    Cuándo se devolvió; null si no.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

Reservar unidades

POST/meters/{id}/reserve

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.

Permiso entitlements.usage.createAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • customerstringobligatorio

    Id del cliente.

  • idempotency_keystringobligatorio

    Tu llave única por unidad (hasta 255).

  • quantityinteger

    Unidades (por defecto 1).

  • billableboolean

    false: se registra sin gastar cupo.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

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.

Permiso entitlements.usage.createAdmite Idempotency-Key

Cuerpo (JSON)

  • meterstringobligatorio

    Id o clave del medidor.

  • customerstringobligatorio

    Id del cliente.

  • idempotency_keystringobligatorio

    La misma llave que habrías usado al reservar.

  • occurred_atdatetimeobligatorio

    Cuándo pasó.

  • quantityinteger

    Unidades (por defecto 1).

  • billableboolean

    false: sin gastar cupo.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

Del más reciente al más antiguo.

Permiso entitlements.usage.list

Parámetros de consulta

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • meterstring

    Clave del medidor.

  • customerstring

    Id del cliente.

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto usage_record

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Devolver un consumo

POST/usage/{id}/release

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ó.

Permiso entitlements.usage.releaseAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Responde: El objeto usage_record

Errores posibles: api_key_invalid, rate_limited, resource_missing, parameter_unknown

curl
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
  • idstring

    goff_…

  • objectstring

    grant_offer

  • meterstring

    Clave del medidor.

  • pricestring

    Precio de pago único con que se cobra (expandible).

  • amountinteger

    Lo que cuesta (el del precio).

  • currencystring

    COP o USD: la del precio.

  • namestring

    Nombre («100 documentos»).

  • unitsinteger

    Unidades que da.

  • validity_monthsinteger

    Meses de vigencia desde el pago; null = no vence.

  • requires_featuresarray

    Solo se vende a un cliente que tenga alguno de estos módulos.

  • activeboolean

    false: archivada, no se vende.

  • positioninteger

    Orden en tu vitrina.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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

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.

Permiso entitlements.grant_offers.createAdmite Idempotency-Key

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Cuerpo (JSON)

  • meterstringobligatorio

    Id o clave del medidor.

  • pricestringobligatorio

    Precio de pago único (price_…).

  • namestringobligatorio

    Nombre.

  • unitsintegerobligatorio

    Unidades.

  • validity_monthsinteger

    Vigencia desde el pago (por defecto 12; 0 = no vence).

  • requires_featuresarray

    Solo para clientes con alguno de estos módulos.

  • activeboolean

    Por defecto true.

  • positioninteger

    Orden.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • meterstring

    Clave del medidor.

  • activeboolean

    Activas o no.

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited, parameter_invalid

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto grant_offer

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Actualizar una oferta de bolsa

PATCH/grant_offers/{id}

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

Permiso entitlements.grant_offers.update

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • namestring

    Nombre.

  • requires_featuresarray

    Módulos que exige.

  • activeboolean

    Archivar o reactivar.

  • positioninteger

    Orden.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

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).

Permiso entitlements.grant_offers.purchaseAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • customerstringobligatorio

    Id del cliente.

  • payment_methodstring

    Tarjeta del cliente (por defecto, la predeterminada).

curl
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
  • idstring

    grt_…

  • objectstring

    grant

  • customerstring

    Cliente (expandible).

  • meterstring

    Clave del medidor.

  • offerstring

    Oferta que se compró (goff_…); null si fue un regalo o se importó.

  • invoicestring

    Factura que la pagó (expandible).

  • sourceenum

    purchase, staff o import.

  • statusenum

    Estado: pending, active, expired, withdrawn, canceled.

  • unitsinteger

    Unidades que dio.

  • remaininginteger

    Lo que le queda.

  • expires_atdatetime

    Cuándo vence; null = no vence.

  • ended_atdatetime

    Cuándo venció, se retiró o se anuló.

  • notestring

    Nota.

  • metadataobject

    Tus pares clave-valor.

  • livemodeboolean

    true en producción, false en pruebas.

  • createddatetime

    Cuándo se creó (ISO 8601, UTC).

  • updateddatetime

    Ú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

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.

Permiso entitlements.grants.createAdmite Idempotency-Key

Cuerpo (JSON)

  • customerstringobligatorio

    Id del cliente.

  • meterstringobligatorio

    Id o clave del medidor.

  • unitsintegerobligatorio

    Unidades.

  • remaininginteger

    Lo que le queda (por defecto todas).

  • expires_atdatetime

    Vencimiento (futuro); sin él no vence.

  • notestring

    Por qué.

  • importedboolean

    Viene de tu sistema anterior.

  • metadataobject

    Hasta 20 pares de texto (claves ≤ 40, valores ≤ 500). En un PATCH se combinan; "" borra una clave.

curl
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

  • limitinteger

    Cuántos objetos, de 1 a 100 (por defecto 10).

  • starting_afterstring

    Id del último objeto de la página anterior: trae la siguiente.

  • ending_beforestring

    Id del primer objeto de la página actual: trae la anterior.

  • expand[]array

    Objetos relacionados a incluir completos (data.customer): hasta 4 caminos de hasta 4 niveles; cuentan más en el límite de uso.

  • customerstring

    Id del cliente.

  • meterstring

    Clave del medidor.

  • statusenum

    Estado.

    Valores: pending, active, expired, withdrawn, canceled

Responde: Una lista paginada

Errores posibles: api_key_invalid, rate_limited, parameter_invalid

curl
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

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Parámetros de consulta

  • expand[]array

    Objetos relacionados a incluir completos (customer): hasta 4 caminos de hasta 4 niveles.

Responde: El objeto grant

Errores posibles: api_key_invalid, rate_limited, resource_missing

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

Retirar una bolsa

POST/grants/{id}/withdraw

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

Permiso entitlements.grants.withdrawAdmite Idempotency-Key

Parámetros de ruta

  • idstringobligatorio

    Id del objeto (cus_…, sub_…).

Cuerpo (JSON)

  • notestring

    Por qué.

Responde: El objeto grant

Errores posibles: api_key_invalid, rate_limited, resource_missing, grant_not_withdrawable

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

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.

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"

Eventos

EventoObjetoCuándo
customer.createdcustomerSe creó un cliente.
customer.updatedcustomerCambió un cliente.
customer.deletedcustomerSe eliminó un cliente.
product.createdproductSe creó un producto.
product.updatedproductCambió 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.createdsubscriptionSe creó una suscripción.
subscription.updatedsubscriptionCambió una suscripción (estado, precio, método de pago, cancelación programada).
subscription.canceledsubscriptionSe canceló una suscripción.
subscription.past_duesubscriptionUn cobro de la suscripción fue rechazado y quedó con pago atrasado.
subscription.update_failedsubscriptionFalló el cobro de un cambio prorrateado (o se anuló su cobro): la suscripción quedó como estaba.
subscription.trial_will_endsubscriptionLa prueba gratis termina en 3 días.
invoice.createdinvoiceSe creó el cobro (invoice) de un periodo.
invoice.paidinvoiceWompi aprobó un cobro (invoice).
invoice.payment_failedinvoiceWompi rechazó un cobro (invoice); se reintentará según el calendario.
invoice.voidedinvoiceSe anuló un cobro (invoice).
invoice.updatedinvoiceCambió el valor de un cobro (invoice) abierto: un cupón aplicado mientras estaba pendiente.
notice.sentnoticeBucli le envió un aviso a tu cliente (recibo, cobro fallido, tarjeta por vencer…): ponlo en su campana.
charge.refundedrefundSe devolvió dinero de un pago (reembolso total o parcial, o anulación): el refund trae las líneas del cobro.
invoice.fiscal_document.issuedinvoiceLa DIAN aceptó la factura electrónica de una factura pagada: ya tiene número, CUFE y PDF (fiscal_document).
invoice.fiscal_document.rejectedinvoiceLa DIAN rechazó la factura electrónica de una factura pagada; el motivo está en fiscal_document.dian_message.
payment_method.attachedpayment_methodEl cliente guardó un método de pago (checkout o portal).
payment_method.detachedpayment_methodSe quitó un método de pago.
payment_method.suspendedpayment_methodUn rechazo duro (robada, perdida, vencida): la tarjeta no se vuelve a cobrar.
payment_method.expiringpayment_methodLa tarjeta vence en 30 o en 7 días (previous_attributes.days).
checkout.session.completedcheckout.sessionEl cliente terminó un checkout.
checkout.session.expiredcheckout.sessionUn checkout venció sin completarse.
entitlements.updatedentitlementsCambiaron 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_reachedmeter_balanceUn cliente usó el porcentaje de aviso de su cupo en la ventana (una vez por ventana).
meter.exhaustedmeter_balanceUn cliente gastó su cupo y sus bolsas en la ventana (una vez por ventana).
grant.createdgrantUna bolsa quedó vigente (pagada, regalada o importada).
grant.expiredgrantUna bolsa venció; lo que le quedaba se pierde.
grant.withdrawngrantSe retiró lo que le quedaba a una bolsa.

Códigos de error

Cada error responde {error: {type, code, message, param, doc_url, request_id}}: decide por code, que nunca cambia de nombre.

CódigoHTTPTipoQué significa
parameter_missing400invalid_request_errorFalta un parámetro obligatorio (param dice cuál).
parameter_invalid400invalid_request_errorUn parámetro tiene un valor que no sirve.
parameter_unknown400invalid_request_errorEnviaste un parámetro que no existe en esa ruta.
invalid_json400invalid_request_errorEl cuerpo no es JSON válido.
request_too_large413invalid_request_errorEl cuerpo supera los 256 KB.
resource_missing404invalid_request_errorNo existe ese id en este modo de esta cuenta.
url_invalid400invalid_request_errorLa URL no es HTTPS o apunta a una red interna.
api_version_invalid400invalid_request_errorLa cabecera Bucli-Version no es una versión vigente.
mode_mismatch400invalid_request_errorLa cabecera Bucli-Mode contradice el modo de la llave.
api_key_missing401authentication_errorNo enviaste la cabecera Authorization.
authorization_header_invalid401authentication_errorAuthorization no es «Bearer <llave>».
api_key_invalid401authentication_errorLa llave no existe.
api_key_revoked401authentication_errorLa llave fue revocada o regenerada.
authentication_required401authentication_errorLa sesión del dashboard venció.
no_active_subscription402billing_errorLa cuenta no tiene plan de Bucli.
subscription_read_only402billing_errorTu plan de Bucli está en solo lectura: no se escribe.
module_not_active403permission_errorTu plan no incluye la API.
feature_not_available403permission_errorTu plan no incluye esto (los webhooks: Pro).
secret_key_required403permission_errorUna llave publicable (pk_) no puede hacer esto.
permission_denied403permission_errorTu rol en el equipo no tiene ese permiso (dashboard).
account_forbidden403permission_errorNo eres miembro de esa cuenta (dashboard).
support_read_only403permission_errorSesión de soporte de Bucli de solo lectura.
route_not_found404invalid_request_errorLa ruta no existe.
method_not_allowed405invalid_request_errorEsa ruta no acepta ese método.
resource_already_exists409invalid_request_errorYa existe (un cliente con ese correo).
idempotency_key_in_use409idempotency_errorOtra petición con esa Idempotency-Key sigue en curso.
idempotency_key_reused409idempotency_errorEsa Idempotency-Key ya se usó con otro cuerpo.
webhook_secret_unavailable_on_replay409invalid_request_errorLa 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_replay409invalid_request_errorLa 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_failed403permission_errorDashboard: falta o no es válida la confirmación de identidad.
code_required403permission_errorDashboard: pide el código por correo y envíalo en code.
reauth_locked429rate_limit_errorDashboard: demasiados intentos de confirmar la identidad.
customer_has_active_subscriptions422invalid_request_errorEl cliente tiene suscripciones en curso.
customer_has_open_charges422invalid_request_errorEl cliente tiene cobros abiertos (una factura por cobrar o una oferta de plazo fijo).
product_has_prices422invalid_request_errorEl producto tiene precios: archívalo.
price_in_use400invalid_request_errorEl precio ya se usa: crea otro y archiva este.
product_inactive422invalid_request_errorEl producto está archivado.
active_subscriptions_limit_reached402billing_errorLlegaste a las suscripciones activas de tu plan.
price_inactive400invalid_request_errorEl precio está archivado.
customer_deleted400invalid_request_errorEl cliente fue eliminado.
payment_method_unavailable400invalid_request_errorEl método de pago no se puede cobrar.
payment_method_rejected402billing_errorWompi rechazó el método de pago.
invalid_metadata400invalid_request_errormetadata no cumple los límites.
subscription_not_updatable409invalid_request_errorLa suscripción ya terminó o no admite ese cambio.
invalid_cancellation_reason400invalid_request_errorMotivo de cancelación desconocido.
invoice_not_open409invalid_request_errorSolo se cobra una factura abierta.
coupon_terms_frozen400invalid_request_errorEl cupón ya se aplicó: sus términos no cambian.
coupon_not_redeemable400invalid_request_errorEl cupón no se puede aplicar (vencido, sin usos…).
discount_missing404invalid_request_errorLa suscripción no tiene un descuento vigente.
payment_not_refundable400invalid_request_errorEse pago no tiene nada que reembolsar.
payment_not_voidable400invalid_request_errorSolo se anula un cobro con tarjeta de hoy, completo.
refund_in_progress409invalid_request_errorYa hay un reembolso de ese pago esperando a Wompi.
subscription_not_pausable409invalid_request_errorSolo se pausa una activa o en prueba al día.
subscription_not_paused409invalid_request_errorNo está pausada ni tiene una pausa pedida.
subscription_not_extendable409invalid_request_errorSolo se extiende una activa al día.
trial_not_running409invalid_request_errorLa suscripción no está en prueba.
plan_price_required400invalid_request_errorEse precio no es de un plan (es de la prueba o de un adicional).
fixed_term_offer_open409invalid_request_errorEse cliente ya tiene una oferta esperando el pago.
fixed_term_offer_not_open409invalid_request_errorEsa oferta ya no espera el pago.
fixed_term_unavailable409invalid_request_errorFaltan tus llaves de Wompi para crear el link.
fixed_term_not_changeable409invalid_request_errorUn plan por tiempo fijo no cambia de plan.
manual_payment_reference_used409invalid_request_errorEsa referencia ya se usó en otro pago manual.
exchange_rate_unavailable503api_errorNo hay una tasa de cambio vigente: inténtalo más tarde.
invoice_payment_in_progress409invalid_request_errorYa hay un cobro de esa factura en curso.
invoice_charge_blocked409invalid_request_errorUn 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_voidable409invalid_request_errorSolo se anula una factura en borrador o abierta.
price_not_recurring400invalid_request_errorEse precio es de pago único: no va en una suscripción.
price_not_one_time400invalid_request_errorUna factura única solo lleva precios de pago único.
price_interval_mismatch400invalid_request_errorLos ítems de una suscripción comparten intervalo.
price_currency_mismatch400invalid_request_errorLo que se cobra junto va en una moneda: no se mezclan pesos y dólares.
subscription_item_duplicate_price400invalid_request_errorEse precio ya es un ítem: cambia su cantidad.
subscription_item_last400invalid_request_errorEl último ítem no se quita: cancela la suscripción.
subscription_items_invalid400invalid_request_errorUna suscripción tiene de 1 a 20 ítems.
subscription_has_multiple_items400invalid_request_errorCon varios ítems, cambia cada ítem.
quantity_invalid400invalid_request_errorLa cantidad va de 1 a 10.000.
proration_unavailable400invalid_request_errorproration_behavior es none o create_prorations.
quote_changed409invalid_request_errorEl cambio ya no cuesta lo que dijo la vista previa.
payment_method_required409invalid_request_errorEs la única tarjeta de una suscripción que se renueva.
payment_method_is_default409invalid_request_errorEsa tarjeta es la predeterminada.
subscription_update_in_progress409invalid_request_errorLa suscripción tiene un cambio esperando su cobro.
subscription_change_too_complex400invalid_request_errorUn cambio que baja el valor y agrega precios nuevos va en dos pasos.
billing_cycle_anchor_invalid400invalid_request_errorEl ancla no es futura o pasa de un ciclo.
trial_end_invalid400invalid_request_errorEl fin de la prueba no es futuro o pasa de 730 días.
invoice_lines_invalid400invalid_request_errorDe 1 a 20 líneas, o amount con description.
invoice_amount_too_small400invalid_request_errorWompi no cobra un monto tan pequeño.
customer_payment_method_missing400invalid_request_errorEl cliente no tiene tarjeta para cobrar.
wompi_payment_source_missing404invalid_request_errorWompi no tiene esa fuente en tu cuenta.
wompi_payment_source_unavailable400invalid_request_errorLa fuente no está AVAILABLE en Wompi.
wompi_payment_source_unsupported400invalid_request_errorSolo se importan tarjetas (CARD).
payment_method_attached_elsewhere409invalid_request_errorEsa fuente ya es de otro cliente.
wompi_credentials_missing409invalid_request_errorConecta tus llaves de Wompi de este modo.
wompi_credentials_invalid400invalid_request_errorWompi rechazó tus llaves: revísalas y verifícalas.
wompi_unavailable503api_errorWompi no respondió: reintenta en unos minutos.
checkout_session_not_expirable409invalid_request_errorLa sesión ya no está abierta o espera un cobro.
webhook_endpoint_limit_reached422invalid_request_errorLlegaste al máximo de endpoints del modo.
feature_in_use422invalid_request_errorUn producto, un ajuste o un medidor usa ese derecho.
feature_unknown400invalid_request_errorEsa clave no existe en tu vocabulario (/features).
feature_type_mismatch400invalid_request_errorUn módulo va en features y un límite en limits.
limit_invalid400invalid_request_errorUn límite es un entero ≥ 0, o -1 para ilimitado.
limit_unlimited_not_allowed400invalid_request_errorEse límite nunca es ilimitado (-1).
product_rules_invalid400invalid_request_errorLas reglas o los derechos del producto no son válidos.
trial_product_exists409invalid_request_errorYa tienes un producto de prueba activo en este modo.
trial_product_locked422invalid_request_errorUn producto con precios no cambia is_trial.
trial_price_invalid400invalid_request_errorEl precio de prueba es recurrente, de $0 y con días.
product_not_offered400invalid_request_errorEse producto es interno: no se vende.
product_coming_soon400invalid_request_errorEse producto todavía no está a la venta.
quantity_not_supported400invalid_request_errorEse producto no se vende por unidades.
addon_requires_feature400invalid_request_errorEl adicional exige un módulo que la suscripción no tiene.
addon_requires_plan400invalid_request_errorEl adicional solo se vende sobre ciertos planes.
addon_included400invalid_request_errorEl plan ya incluye lo que da el adicional.
addon_not_allowed_during_trial400invalid_request_errorEl adicional no se vende durante la prueba.
trial_product_misused400invalid_request_errorEl producto de prueba va solo, en una suscripción nueva en prueba.
trial_already_used409invalid_request_errorYa se dio una prueba con esa trial_key.
meter_feature_missing400invalid_request_errorCrea antes el límite metered con la misma clave.
meter_inactive409invalid_request_errorEse medidor está apagado.
quota_exhausted402billing_errorSe acabó el cupo y no hay bolsas con saldo (el detalle viene en el error).
entitlement_access_denied402billing_errorEl cliente no tiene acceso completo: no consume.
usage_report_invalid400invalid_request_erroroccurred_at es futuro o demasiado viejo.
usage_idempotency_key_reused409invalid_request_errorEsa llave ya se usó con otra cantidad.
grant_offer_price_invalid400invalid_request_errorUna oferta se cobra con un precio one_time activo.
grant_offer_unavailable400invalid_request_errorEsa oferta de bolsa está archivada.
grant_offer_requires_feature400invalid_request_errorEl cliente no tiene los módulos que exige la bolsa.
grant_not_withdrawable409invalid_request_errorEsa bolsa ya no está vigente.
rate_limited429rate_limit_errorDemasiadas peticiones: espera Retry-After segundos.
internal_error500api_errorFalló algo de nuestro lado: reintenta con la misma Idempotency-Key.
engine_unavailable503api_errorEl motor de cobros no responde: reintenta en unos minutos.