Cuotas y consumo
Expresa qué puede usar un cliente y cuánto le queda.
Tipos de cuota
| Tipo | Ejemplo |
|---|---|
boolean | Acceso a exportación |
metered | Tokens consumidos por período |
count | Proyectos existentes |
number | Valor numérico de una capacidad |
{
"key": "tokens",
"name": "Tokens",
"type": "metered",
"unit": "tokens",
"reset": {"every": "billing"}
}Asigna el límite en features del plan: {"tokens": 100000}. La clave y el tipo de una cuota no cambian después de crearla.
Consultar y consumir
| Método | Ruta | Acción |
|---|---|---|
| POST / GET | /v1/features | Crear / listar cuotas; la lista admite search (parte del nombre o la clave) y sort |
| GET / PATCH | /v1/features/:key | Consultar / actualizar definición |
| DELETE | /v1/features/:key | Eliminar una cuota que ningún plan incluye (si no, feature_in_use); su clave queda libre y solo su ID la encuentra |
| GET | /v1/customers/:customer/features | Cuotas del cliente |
| GET | /v1/customers/:customer/features/:key | Consultar acceso y uso |
| POST | /v1/customers/:customer/features/:key/usage | Consumo relativo: {"delta": 850} |
| PUT | /v1/customers/:customer/features/:key/usage | Uso absoluto: {"value": 7} |
:key admite la clave de la cuota (tokens) o su ID feat_, igual que el cliente admite su ID de Billete o externalId. Si una clave coincide exactamente con lo enviado, gana la clave. Un consumo que supera el límite devuelve allowed: false sin descontar unidades. Solo count permite delta negativo y uso absoluto. En metered, devolver consumo requiere una operación original (feature_release_requires_operation); fijar uso absoluto devuelve feature_set_not_allowed.
Uso por miembro
Las cuotas metered y count aceptan per: "member" al crearse; por defecto es customer y no cambia después. Envía member (ID mem_ o externo) en el cuerpo del consumo o la consulta GET. Sin miembro, la lista muestra used, reserved y remaining como null; la consulta individual exige member_required. Un miembro quitado devuelve member_removed; uno excedente no consume (member_over_limit) y la consulta devuelve enabled: false, reason: "over_limit".
Reservas de consumo
| Método | Ruta | Cuerpo |
|---|---|---|
| POST | /v1/customers/:customer/features/:key/operations | { operation, amount, member?, expiresInSeconds?, metadata? } |
| GET | /v1/feature-operations/:operation | Consultar estado |
| POST | /v1/feature-operations/:operation/commit | { amount? } |
| POST | /v1/feature-operations/:operation/release | Liberar una reserva |
| POST | /v1/feature-operations/:operation/refund | Devolver consumo confirmado |
Solo las cuotas metered admiten operaciones (feature_operation_not_allowed). operation es tu propio ID del trabajo (por ejemplo, el del job) y es único por negocio y entorno: repetirlo con los mismos datos devuelve la misma operación con created: false y no consume otra vez; cambiarlos produce operation_key_reused. Si no cabe en el límite, la respuesta es allowed: false sin operación. La respuesta incluye allowed, created, operation y feature.
Reservar incrementa used y reserved de inmediato. expiresInSeconds vale 900 por defecto y como máximo 86 400. Confirmar parcialmente devuelve la diferencia (confirmar más de lo reservado es operation_amount_exceeded); liberar, devolver o vencer siempre afecta al periodo en que se reservó, aunque ya haya empezado otro. Confirmar, liberar y devolver son idempotentes: repetirlos sobre una operación que ya llegó a ese estado la devuelve sin cambios. Un estado incompatible devuelve operation_invalid_state.
Una reserva no confirmada a tiempo vence sola y su capacidad vuelve; confirmarla después de su vencimiento devuelve operation_expired. Las operaciones se cierran aunque se quite el miembro, quede fuera de los puestos o baje el plan: la capacidad ya se autorizó al reservar. Para consumir y confirmar en un solo paso, añade operation al POST de uso con delta positivo.
Billete no ejecuta tus trabajos
Billete garantiza que una operación no descuente cuota dos veces y que toda devolución vuelva a su periodo original. Que cada trabajo se ejecute una sola vez es responsabilidad de tu cola. Si la respuesta de una confirmación se pierde, reintenta la misma confirmación o consulta la operación; nunca la liberes por una duda de red.
Autoriza desde el servidor
Consultar el saldo de una cuota y luego ejecutar el trabajo no reserva consumo. Usa la operación de consumo y comprueba allowed antes de ejecutar el trabajo.