Clientes

Crear un clienteCopiar enlace

curl https://api.billete.run/v1/customers \
  -H "Authorization: Bearer $BILLETE_API_KEY" \
  -H "Billete-Version: 2026-10-24" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: customer-example-001" \
  -d '{"email":"cliente@example.com","name":"Cliente de ejemplo","externalId":"user_123"}'

email es obligatorio. externalId permite enlazar el cliente con el identificador de tu aplicación. Los campos opcionales incluyen name, phone, address y metadata.

Con externalId, esa es la identidad única del cliente dentro del negocio y entorno; dos organizaciones pueden compartir correo. Sin externalId, solo se deduplican los clientes anónimos del mismo correo. Enviar un ID externo nuevo nunca adopta otro cliente por su correo. En altas explícitas, un conflicto devuelve customer_exists con param: "externalId" o "email".

Identificar un clienteCopiar enlace

:customer admite el ID de Billete (cus_) o tu externalId en todas las rutas, igual que el filtro customer de suscripciones y las cuotas. Si no existe, la respuesta es 404 con customer_not_found, también en las rutas de miembros y en los filtros: un filtro por un cliente inexistente no devuelve una lista vacía.

POST /v1/customers no reutiliza un cliente existente: con un externalId ya registrado devuelve customer_exists. Para crearlo solo si falta, consúltalo por externalId y créalo ante customer_not_found; si otra solicitud se adelanta y recibes customer_exists, vuelve a consultarlo. Los checkouts y POST /v1/subscriptions también aceptan customer como objeto con externalId y lo crean o reutilizan por ese identificador.

Miembros del clienteCopiar enlace

:member admite mem_ o el identificador externo; los miembros no requieren correo. Un miembro inexistente devuelve 404 con member_not_found; si falta el cliente, customer_not_found. La lista acepta status, search, cursor y limit, y devuelve capacity, enabledCount, data y nextCursor. capacity: null significa ilimitado.

Los miembros son las personas de una organización (el cliente) que ocupan sus puestos. La capacidad es la suma de los puestos de todas las suscripciones vigentes del cliente: los incluidos de cada plan o los comprados en los planes por puesto; si alguna es ilimitada, la capacidad también. Cada miembro dice si tiene puesto en enabled.

Agregar un ID externo activo es idempotente y devuelve el miembro existente, así que no hace falta consultarlo antes de agregarlo. Volver a agregar uno quitado conserva su ID y consumo, y renueva activeSince. Las altas respetan los puestos contratados, también una reducción ya programada (seat_limit_reached). Si baja la capacidad (una reducción, el plan de respaldo, una suscripción que termina), conservan su puesto primero los miembros con priority: true (por ejemplo, quien administra la organización) y luego los activos más antiguos; los demás quedan sin puesto (enabled: false) sin borrarse, y al subir la capacidad se habilitan de nuevo. Cambiar priority reordena los puestos en el acto.

En el dashboard, el detalle del cliente lista sus miembros con sus puestos y permite agregarlos, quitarlos, reactivarlos y darles prioridad.

Sesiones de cliente · Portal alojado