bucli 0.6.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- bucli/__init__.py +52 -0
- bucli/_version.py +1 -0
- bucli/client.py +274 -0
- bucli/constants.py +92 -0
- bucli/contrib/__init__.py +1 -0
- bucli/contrib/django/__init__.py +6 -0
- bucli/contrib/django/access.py +99 -0
- bucli/contrib/django/admin.py +19 -0
- bucli/contrib/django/apps.py +8 -0
- bucli/contrib/django/conf.py +140 -0
- bucli/contrib/django/exceptions.py +17 -0
- bucli/contrib/django/management/__init__.py +0 -0
- bucli/contrib/django/management/commands/__init__.py +0 -0
- bucli/contrib/django/management/commands/bucli_flush_usage.py +18 -0
- bucli/contrib/django/management/commands/bucli_sync.py +66 -0
- bucli/contrib/django/metering.py +137 -0
- bucli/contrib/django/migrations/0001_initial.py +102 -0
- bucli/contrib/django/migrations/0002_billingaccount_bucli_updated_at.py +15 -0
- bucli/contrib/django/migrations/0003_pendingusage.py +40 -0
- bucli/contrib/django/migrations/__init__.py +0 -0
- bucli/contrib/django/models.py +122 -0
- bucli/contrib/django/services.py +617 -0
- bucli/contrib/django/signals.py +22 -0
- bucli/contrib/django/urls.py +11 -0
- bucli/contrib/django/views.py +50 -0
- bucli/contrib/django/webhooks.py +236 -0
- bucli/errors.py +193 -0
- bucli/keys.py +18 -0
- bucli/metering.py +331 -0
- bucli/objects.py +168 -0
- bucli/py.typed +0 -0
- bucli/resources.py +1002 -0
- bucli/webhook.py +136 -0
- bucli-0.6.0.dist-info/METADATA +541 -0
- bucli-0.6.0.dist-info/RECORD +37 -0
- bucli-0.6.0.dist-info/WHEEL +4 -0
- bucli-0.6.0.dist-info/licenses/LICENSE +21 -0
bucli/resources.py
ADDED
|
@@ -0,0 +1,1002 @@
|
|
|
1
|
+
"""The resources of ``/v1``, one class per resource, one method per documented endpoint.
|
|
2
|
+
|
|
3
|
+
Only what Bucli's API documentation registry documents is here:
|
|
4
|
+
``@route`` declares the method + path each method calls, and
|
|
5
|
+
``tests/test_contract.py`` checks every declared (and every actually sent)
|
|
6
|
+
route against that registry. Updates are ``PATCH`` (Bucli's choice), actions
|
|
7
|
+
are ``POST /{id}/<action>``.
|
|
8
|
+
|
|
9
|
+
Every method takes the API's own parameter names as keyword arguments
|
|
10
|
+
(``customers.create(email=..., metadata={...})``); ``None`` values are not sent.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from collections.abc import Callable, Iterable
|
|
16
|
+
from typing import TYPE_CHECKING, Any, TypeVar
|
|
17
|
+
from urllib.parse import quote
|
|
18
|
+
|
|
19
|
+
from bucli.errors import InvalidRequestError
|
|
20
|
+
from bucli.keys import reserve_request_key
|
|
21
|
+
from bucli.objects import BucliObject, ListObject
|
|
22
|
+
|
|
23
|
+
if TYPE_CHECKING:
|
|
24
|
+
from bucli.client import Bucli
|
|
25
|
+
|
|
26
|
+
F = TypeVar("F", bound=Callable[..., Any])
|
|
27
|
+
|
|
28
|
+
#: Every (method, path template) this library calls: ``("GET", "/customers/{id}")``.
|
|
29
|
+
ROUTES: list[tuple[str, str, str]] = []
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def route(method: str, template: str) -> Callable[[F], F]:
|
|
33
|
+
"""Declares the endpoint a resource method calls (read by the contract test)."""
|
|
34
|
+
|
|
35
|
+
def decorate(fn: F) -> F:
|
|
36
|
+
fn.__bucli_route__ = (method, template) # type: ignore[attr-defined]
|
|
37
|
+
ROUTES.append((method, template, fn.__qualname__))
|
|
38
|
+
return fn
|
|
39
|
+
|
|
40
|
+
return decorate
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _id(value: str) -> str:
|
|
44
|
+
if not isinstance(value, str) or not value.strip():
|
|
45
|
+
raise ValueError("Falta el id del objeto (cus_…, sub_…).")
|
|
46
|
+
return quote(value.strip(), safe="")
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class Resource:
|
|
50
|
+
path = ""
|
|
51
|
+
|
|
52
|
+
def __init__(self, client: Bucli) -> None:
|
|
53
|
+
self._client = client
|
|
54
|
+
|
|
55
|
+
def _item(self, object_id: str, suffix: str = "") -> str:
|
|
56
|
+
return f"{self.path}/{_id(object_id)}{suffix}"
|
|
57
|
+
|
|
58
|
+
def _post(
|
|
59
|
+
self,
|
|
60
|
+
path: str,
|
|
61
|
+
params: dict[str, Any],
|
|
62
|
+
*,
|
|
63
|
+
idempotency_key: str | None = None,
|
|
64
|
+
expand: Iterable[str] | None = None,
|
|
65
|
+
) -> BucliObject:
|
|
66
|
+
return self._client.request("POST", path, body=params, idempotency_key=idempotency_key, expand=expand)
|
|
67
|
+
|
|
68
|
+
def _patch(self, path: str, params: dict[str, Any], expand: Iterable[str] | None = None) -> BucliObject:
|
|
69
|
+
return self._client.request("PATCH", path, body=params, expand=expand)
|
|
70
|
+
|
|
71
|
+
def _get(self, path: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
72
|
+
return self._client.request("GET", path, expand=expand)
|
|
73
|
+
|
|
74
|
+
def _delete(self, path: str, body: dict[str, Any] | None = None) -> BucliObject:
|
|
75
|
+
# A body only on ``DELETE /subscription_items/{id}`` and ``/subscriptions/{id}/discount``.
|
|
76
|
+
return self._client.request("DELETE", path, body=body)
|
|
77
|
+
|
|
78
|
+
def _list(self, path: str, params: dict[str, Any], expand: Iterable[str] | None = None) -> ListObject:
|
|
79
|
+
if expand:
|
|
80
|
+
params = {**params, "expand[]": list(expand)}
|
|
81
|
+
return self._client._get_list(path, params)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
# ---------------------------------------------------------------------------
|
|
85
|
+
# Account
|
|
86
|
+
# ---------------------------------------------------------------------------
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
class Account(Resource):
|
|
90
|
+
path = "/account"
|
|
91
|
+
|
|
92
|
+
@route("GET", "/account")
|
|
93
|
+
def retrieve(self) -> BucliObject:
|
|
94
|
+
"""Tu comercio como lo ve la API en el modo de la llave."""
|
|
95
|
+
return self._get(self.path)
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
# ---------------------------------------------------------------------------
|
|
99
|
+
# Customers
|
|
100
|
+
# ---------------------------------------------------------------------------
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
class Customers(Resource):
|
|
104
|
+
path = "/customers"
|
|
105
|
+
|
|
106
|
+
@route("POST", "/customers")
|
|
107
|
+
def create(self, *, idempotency_key: str | None = None, **params: Any) -> BucliObject:
|
|
108
|
+
"""``email`` (obligatorio), ``external_id`` (tu id: un cliente por empresa; con él el correo puede
|
|
109
|
+
repetirse), ``name``, ``phone``, ``fiscal`` (sus datos para la factura electrónica, enteros), ``legal_id_type``,
|
|
110
|
+
``legal_id``, ``metadata``. Un ``external_id`` o, sin él, un correo repetido responde
|
|
111
|
+
``409 resource_already_exists``."""
|
|
112
|
+
return self._post(self.path, params, idempotency_key=idempotency_key)
|
|
113
|
+
|
|
114
|
+
@route("GET", "/customers")
|
|
115
|
+
def list(self, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
116
|
+
"""``limit``, ``starting_after``, ``ending_before``, ``email``, ``external_id``."""
|
|
117
|
+
return self._list(self.path, params, expand)
|
|
118
|
+
|
|
119
|
+
@route("GET", "/customers/{id}")
|
|
120
|
+
def retrieve(self, customer_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
121
|
+
return self._get(self._item(customer_id), expand=expand)
|
|
122
|
+
|
|
123
|
+
@route("PATCH", "/customers/{id}")
|
|
124
|
+
def update(self, customer_id: str, **params: Any) -> BucliObject:
|
|
125
|
+
"""Lo que envías; ``fiscal`` va entero (reemplaza el anterior)."""
|
|
126
|
+
return self._patch(self._item(customer_id), params)
|
|
127
|
+
|
|
128
|
+
@route("DELETE", "/customers/{id}")
|
|
129
|
+
def delete(self, customer_id: str) -> BucliObject:
|
|
130
|
+
"""Responde ``{id, object, deleted: true}``; con suscripciones en curso, ``422``."""
|
|
131
|
+
return self._delete(self._item(customer_id))
|
|
132
|
+
|
|
133
|
+
@route("GET", "/customers/{id}/entitlements")
|
|
134
|
+
def entitlements(self, customer_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
135
|
+
"""Sus suscripciones con acceso completo combinadas: ``features``, ``limits``, ``access``,
|
|
136
|
+
``read_only_reason``, ``period_end``, ``trial_end``. Es lo que cuentan sus medidores."""
|
|
137
|
+
return self._get(self._item(customer_id, "/entitlements"), expand=expand)
|
|
138
|
+
|
|
139
|
+
@route("GET", "/customers/{id}/payment_methods")
|
|
140
|
+
def list_payment_methods(
|
|
141
|
+
self, customer_id: str, *, expand: Iterable[str] | None = None, **params: Any
|
|
142
|
+
) -> ListObject:
|
|
143
|
+
return self._list(self._item(customer_id, "/payment_methods"), params, expand)
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
# ---------------------------------------------------------------------------
|
|
147
|
+
# Products and prices
|
|
148
|
+
# ---------------------------------------------------------------------------
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
class Products(Resource):
|
|
152
|
+
path = "/products"
|
|
153
|
+
|
|
154
|
+
@route("POST", "/products")
|
|
155
|
+
def create(self, *, idempotency_key: str | None = None, **params: Any) -> BucliObject:
|
|
156
|
+
"""``name`` (obligatorio), ``description``, ``active``, ``metadata``."""
|
|
157
|
+
return self._post(self.path, params, idempotency_key=idempotency_key)
|
|
158
|
+
|
|
159
|
+
@route("GET", "/products")
|
|
160
|
+
def list(self, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
161
|
+
"""``active`` además de la paginación."""
|
|
162
|
+
return self._list(self.path, params, expand)
|
|
163
|
+
|
|
164
|
+
@route("GET", "/products/{id}")
|
|
165
|
+
def retrieve(self, product_id: str) -> BucliObject:
|
|
166
|
+
return self._get(self._item(product_id))
|
|
167
|
+
|
|
168
|
+
@route("PATCH", "/products/{id}")
|
|
169
|
+
def update(self, product_id: str, **params: Any) -> BucliObject:
|
|
170
|
+
"""``active=False`` lo archiva."""
|
|
171
|
+
return self._patch(self._item(product_id), params)
|
|
172
|
+
|
|
173
|
+
@route("DELETE", "/products/{id}")
|
|
174
|
+
def delete(self, product_id: str) -> BucliObject:
|
|
175
|
+
"""Solo un producto sin precios (``422 product_has_prices``)."""
|
|
176
|
+
return self._delete(self._item(product_id))
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
class Prices(Resource):
|
|
180
|
+
path = "/prices"
|
|
181
|
+
|
|
182
|
+
@route("POST", "/prices")
|
|
183
|
+
def create(
|
|
184
|
+
self, *, idempotency_key: str | None = None, expand: Iterable[str] | None = None, **params: Any
|
|
185
|
+
) -> BucliObject:
|
|
186
|
+
"""``product`` (id u objeto ``{name}``), ``amount`` (pesos enteros), ``type``
|
|
187
|
+
(``recurring`` por defecto u ``one_time``), ``recurring={interval, interval_count, trial_days}``
|
|
188
|
+
o ``interval``/``interval_count``/``trial_days`` planos, ``nickname``, ``active``, ``metadata``."""
|
|
189
|
+
return self._post(self.path, params, idempotency_key=idempotency_key, expand=expand)
|
|
190
|
+
|
|
191
|
+
@route("GET", "/prices")
|
|
192
|
+
def list(self, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
193
|
+
"""``product``, ``active``, ``type`` además de la paginación."""
|
|
194
|
+
return self._list(self.path, params, expand)
|
|
195
|
+
|
|
196
|
+
@route("GET", "/prices/{id}")
|
|
197
|
+
def retrieve(self, price_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
198
|
+
return self._get(self._item(price_id), expand=expand)
|
|
199
|
+
|
|
200
|
+
@route("PATCH", "/prices/{id}")
|
|
201
|
+
def update(self, price_id: str, **params: Any) -> BucliObject:
|
|
202
|
+
"""Solo ``nickname``, ``active`` y ``metadata``: el monto no se edita nunca."""
|
|
203
|
+
return self._patch(self._item(price_id), params)
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
# ---------------------------------------------------------------------------
|
|
207
|
+
# Subscriptions and their items
|
|
208
|
+
# ---------------------------------------------------------------------------
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
class Subscriptions(Resource):
|
|
212
|
+
path = "/subscriptions"
|
|
213
|
+
|
|
214
|
+
@route("POST", "/subscriptions")
|
|
215
|
+
def create(
|
|
216
|
+
self, *, idempotency_key: str | None = None, expand: Iterable[str] | None = None, **params: Any
|
|
217
|
+
) -> BucliObject:
|
|
218
|
+
"""``customer`` (obligatorio) y ``price`` (+ ``quantity``) o ``items=[{price, quantity}]``;
|
|
219
|
+
``default_payment_method``, ``trial_days`` o ``trial_end``, ``trial_key`` (una prueba por
|
|
220
|
+
clave: ``409 trial_already_used``), ``billing_cycle_anchor`` (fecha futura: nace ``active``
|
|
221
|
+
sin cobrar ahora), ``coupon``, ``overage_caps``, ``metadata``.
|
|
222
|
+
Las fechas pueden ir como ``datetime`` con zona horaria, ISO 8601 o timestamp Unix."""
|
|
223
|
+
return self._post(self.path, params, idempotency_key=idempotency_key, expand=expand)
|
|
224
|
+
|
|
225
|
+
@route("GET", "/subscriptions")
|
|
226
|
+
def list(self, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
227
|
+
"""``status``, ``customer``, ``price`` además de la paginación."""
|
|
228
|
+
return self._list(self.path, params, expand)
|
|
229
|
+
|
|
230
|
+
@route("GET", "/subscriptions/{id}")
|
|
231
|
+
def retrieve(self, subscription_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
232
|
+
return self._get(self._item(subscription_id), expand=expand)
|
|
233
|
+
|
|
234
|
+
@route("PATCH", "/subscriptions/{id}")
|
|
235
|
+
def update(self, subscription_id: str, **params: Any) -> BucliObject:
|
|
236
|
+
"""``price``, ``default_payment_method``, ``cancel_at_period_end`` (``False`` deshace una
|
|
237
|
+
cancelación programada), ``overage_caps``, ``metadata``.
|
|
238
|
+
|
|
239
|
+
``proration_behavior="none"`` (por defecto): el cambio aplica ya y se cobra desde el
|
|
240
|
+
siguiente periodo. ``"create_prorations"`` con ``expected_amount`` (lo que dijo
|
|
241
|
+
``preview``): lo que sube se cobra ya, prorrateado, y aplica cuando Wompi lo aprueba
|
|
242
|
+
(``subscription.updated``; si falla, ``subscription.update_failed``); lo que baja espera
|
|
243
|
+
la renovación. Si el valor cambió: ``409 quote_changed`` con la cotización nueva en
|
|
244
|
+
``error.quote``. Mientras el cambio espera su cobro responde ``202`` con el
|
|
245
|
+
``subscription_change`` en vez de la suscripción.
|
|
246
|
+
|
|
247
|
+
``items=[{"id": "si_…", "price": "price_…", "quantity": 2}, …]`` (en vez de ``price``, solo
|
|
248
|
+
con ``create_prorations``): todos los ítems después del cambio; el primero es el plan y
|
|
249
|
+
todos van a su intervalo. Así cambia de ciclo un plan con adicionales."""
|
|
250
|
+
return self._patch(self._item(subscription_id), params)
|
|
251
|
+
|
|
252
|
+
@route("POST", "/subscriptions/{id}/preview")
|
|
253
|
+
def preview(
|
|
254
|
+
self,
|
|
255
|
+
subscription_id: str,
|
|
256
|
+
*,
|
|
257
|
+
price: str | None = None,
|
|
258
|
+
items: list[dict[str, Any]] | None = None,
|
|
259
|
+
idempotency_key: str | None = None,
|
|
260
|
+
) -> BucliObject:
|
|
261
|
+
"""Lo que cuesta AHORA un cambio (``subscription_quote``), el mismo cálculo que cobra el
|
|
262
|
+
cambio con ``create_prorations``: ``price`` (suscripción de un ítem) o ``items`` (todos los
|
|
263
|
+
ítems después del cambio: ``[{id?, price, quantity?}]``; uno actual que no esté se quita).
|
|
264
|
+
No cambia nada. Envía su ``amount`` como ``expected_amount``."""
|
|
265
|
+
body = {"price": price, "items": items}
|
|
266
|
+
return self._post(self._item(subscription_id, "/preview"), body, idempotency_key=idempotency_key)
|
|
267
|
+
|
|
268
|
+
@route("POST", "/subscriptions/{id}/cancel")
|
|
269
|
+
def cancel(
|
|
270
|
+
self,
|
|
271
|
+
subscription_id: str,
|
|
272
|
+
*,
|
|
273
|
+
at_period_end: bool | None = None,
|
|
274
|
+
reason: str | None = None,
|
|
275
|
+
comment: str | None = None,
|
|
276
|
+
idempotency_key: str | None = None,
|
|
277
|
+
) -> BucliObject:
|
|
278
|
+
"""Al instante, o al fin del periodo con ``at_period_end=True``."""
|
|
279
|
+
body = {"at_period_end": at_period_end, "reason": reason, "comment": comment}
|
|
280
|
+
return self._post(self._item(subscription_id, "/cancel"), body, idempotency_key=idempotency_key)
|
|
281
|
+
|
|
282
|
+
@route("POST", "/subscriptions/{id}/pause")
|
|
283
|
+
def pause(
|
|
284
|
+
self,
|
|
285
|
+
subscription_id: str,
|
|
286
|
+
*,
|
|
287
|
+
resumes_at: Any = None,
|
|
288
|
+
reason: str | None = None,
|
|
289
|
+
idempotency_key: str | None = None,
|
|
290
|
+
) -> BucliObject:
|
|
291
|
+
"""Pausa el cobro al terminar el periodo pagado (``pause_at_period_end``); con ``resumes_at``
|
|
292
|
+
(después del fin del periodo) se reanuda sola."""
|
|
293
|
+
body = {"resumes_at": resumes_at, "reason": reason}
|
|
294
|
+
return self._post(self._item(subscription_id, "/pause"), body, idempotency_key=idempotency_key)
|
|
295
|
+
|
|
296
|
+
@route("POST", "/subscriptions/{id}/resume")
|
|
297
|
+
def resume(
|
|
298
|
+
self, subscription_id: str, *, reason: str | None = None, idempotency_key: str | None = None
|
|
299
|
+
) -> BucliObject:
|
|
300
|
+
"""Deshace una pausa programada, o reanuda una suscripción ``paused`` (abre su periodo y lo cobra)."""
|
|
301
|
+
return self._post(self._item(subscription_id, "/resume"), {"reason": reason}, idempotency_key=idempotency_key)
|
|
302
|
+
|
|
303
|
+
@route("POST", "/subscriptions/{id}/extend_period")
|
|
304
|
+
def extend_period(
|
|
305
|
+
self,
|
|
306
|
+
subscription_id: str,
|
|
307
|
+
*,
|
|
308
|
+
days: int | None = None,
|
|
309
|
+
until: Any = None,
|
|
310
|
+
reason: str | None = None,
|
|
311
|
+
idempotency_key: str | None = None,
|
|
312
|
+
) -> BucliObject:
|
|
313
|
+
"""Días gratis: corre el fin del periodo (``days`` o ``until``) sin cobrar."""
|
|
314
|
+
body = {"days": days, "until": until, "reason": reason}
|
|
315
|
+
return self._post(self._item(subscription_id, "/extend_period"), body, idempotency_key=idempotency_key)
|
|
316
|
+
|
|
317
|
+
@route("POST", "/subscriptions/{id}/extend_trial")
|
|
318
|
+
def extend_trial(
|
|
319
|
+
self,
|
|
320
|
+
subscription_id: str,
|
|
321
|
+
*,
|
|
322
|
+
trial_end: Any,
|
|
323
|
+
reason: str | None = None,
|
|
324
|
+
idempotency_key: str | None = None,
|
|
325
|
+
) -> BucliObject:
|
|
326
|
+
"""Alarga la prueba hasta ``trial_end``."""
|
|
327
|
+
body = {"trial_end": trial_end, "reason": reason}
|
|
328
|
+
return self._post(self._item(subscription_id, "/extend_trial"), body, idempotency_key=idempotency_key)
|
|
329
|
+
|
|
330
|
+
@route("POST", "/subscriptions/{id}/end_trial")
|
|
331
|
+
def end_trial(
|
|
332
|
+
self, subscription_id: str, *, reason: str | None = None, idempotency_key: str | None = None
|
|
333
|
+
) -> BucliObject:
|
|
334
|
+
"""Termina la prueba ya: abre el primer periodo y lo cobra."""
|
|
335
|
+
return self._post(
|
|
336
|
+
self._item(subscription_id, "/end_trial"), {"reason": reason}, idempotency_key=idempotency_key
|
|
337
|
+
)
|
|
338
|
+
|
|
339
|
+
@route("POST", "/subscriptions/{id}/discount")
|
|
340
|
+
def apply_discount(
|
|
341
|
+
self,
|
|
342
|
+
subscription_id: str,
|
|
343
|
+
*,
|
|
344
|
+
coupon: str,
|
|
345
|
+
reason: str | None = None,
|
|
346
|
+
idempotency_key: str | None = None,
|
|
347
|
+
) -> BucliObject:
|
|
348
|
+
"""Aplica un cupón (``coupon_…``): rebaja las facturas de periodo desde la próxima."""
|
|
349
|
+
body = {"coupon": coupon, "reason": reason}
|
|
350
|
+
return self._post(self._item(subscription_id, "/discount"), body, idempotency_key=idempotency_key)
|
|
351
|
+
|
|
352
|
+
@route("DELETE", "/subscriptions/{id}/discount")
|
|
353
|
+
def delete_discount(self, subscription_id: str, *, reason: str | None = None) -> BucliObject:
|
|
354
|
+
"""Quita el descuento: las facturas ya abiertas lo conservan."""
|
|
355
|
+
return self._delete(self._item(subscription_id, "/discount"), {"reason": reason})
|
|
356
|
+
|
|
357
|
+
@route("GET", "/subscriptions/{id}/actions")
|
|
358
|
+
def list_actions(self, subscription_id: str, **params: Any) -> ListObject:
|
|
359
|
+
"""La bitácora de lo que se hizo a mano (pausa, días, cupón, pago manual, devolución…)."""
|
|
360
|
+
return self._list(self._item(subscription_id, "/actions"), params)
|
|
361
|
+
|
|
362
|
+
@route("GET", "/subscriptions/{id}/entitlements")
|
|
363
|
+
def entitlements(self, subscription_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
364
|
+
"""Lo que dan sus productos con tus ajustes, y su ``access`` (``full``, ``read_only``, ``none``)."""
|
|
365
|
+
return self._get(self._item(subscription_id, "/entitlements"), expand=expand)
|
|
366
|
+
|
|
367
|
+
@route("POST", "/subscriptions/{id}/entitlement_overrides")
|
|
368
|
+
def set_entitlement_overrides(
|
|
369
|
+
self, subscription_id: str, *, idempotency_key: str | None = None, **params: Any
|
|
370
|
+
) -> BucliObject:
|
|
371
|
+
"""Tus ajustes completos: ``features_add``, ``features_remove``, ``limits`` (mínimos), ``note``;
|
|
372
|
+
o ``keep_current=True`` (con ``note``) antes de bajar de plan. Sin parámetros los borra."""
|
|
373
|
+
return self._post(
|
|
374
|
+
self._item(subscription_id, "/entitlement_overrides"), params, idempotency_key=idempotency_key
|
|
375
|
+
)
|
|
376
|
+
|
|
377
|
+
|
|
378
|
+
class SubscriptionItems(Resource):
|
|
379
|
+
path = "/subscription_items"
|
|
380
|
+
|
|
381
|
+
@route("POST", "/subscription_items")
|
|
382
|
+
def create(
|
|
383
|
+
self, *, idempotency_key: str | None = None, expand: Iterable[str] | None = None, **params: Any
|
|
384
|
+
) -> BucliObject:
|
|
385
|
+
"""``subscription``, ``price`` (obligatorios), ``quantity``, ``metadata``. Con
|
|
386
|
+
``proration_behavior="create_prorations"`` y ``expected_amount`` se cobra ya, prorrateado
|
|
387
|
+
(ver ``subscriptions.update``); por defecto, desde el siguiente periodo."""
|
|
388
|
+
return self._post(self.path, params, idempotency_key=idempotency_key, expand=expand)
|
|
389
|
+
|
|
390
|
+
@route("GET", "/subscription_items")
|
|
391
|
+
def list(self, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
392
|
+
"""``subscription`` además de la paginación."""
|
|
393
|
+
return self._list(self.path, params, expand)
|
|
394
|
+
|
|
395
|
+
@route("GET", "/subscription_items/{id}")
|
|
396
|
+
def retrieve(self, item_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
397
|
+
return self._get(self._item(item_id), expand=expand)
|
|
398
|
+
|
|
399
|
+
@route("PATCH", "/subscription_items/{id}")
|
|
400
|
+
def update(self, item_id: str, **params: Any) -> BucliObject:
|
|
401
|
+
"""``price`` y/o ``quantity``; ``proration_behavior`` y ``expected_amount`` como en
|
|
402
|
+
``subscriptions.update``."""
|
|
403
|
+
return self._patch(self._item(item_id), params)
|
|
404
|
+
|
|
405
|
+
@route("DELETE", "/subscription_items/{id}")
|
|
406
|
+
def delete(
|
|
407
|
+
self, item_id: str, *, proration_behavior: str | None = None, expected_amount: int | None = None
|
|
408
|
+
) -> BucliObject:
|
|
409
|
+
"""``none`` (por defecto) lo quita ya; ``create_prorations`` (con ``expected_amount=0``) lo deja
|
|
410
|
+
hasta la renovación. El último ítem no se quita (``400 subscription_item_last``)."""
|
|
411
|
+
body = {"proration_behavior": proration_behavior, "expected_amount": expected_amount}
|
|
412
|
+
return self._delete(self._item(item_id), body)
|
|
413
|
+
|
|
414
|
+
|
|
415
|
+
# ---------------------------------------------------------------------------
|
|
416
|
+
# Payment methods
|
|
417
|
+
# ---------------------------------------------------------------------------
|
|
418
|
+
|
|
419
|
+
|
|
420
|
+
class PaymentMethods(Resource):
|
|
421
|
+
path = "/payment_methods"
|
|
422
|
+
|
|
423
|
+
@route("POST", "/payment_methods")
|
|
424
|
+
def create(self, *, idempotency_key: str | None = None, **params: Any) -> BucliObject:
|
|
425
|
+
"""Importa una fuente de pago que ya existe en TU cuenta de Wompi:
|
|
426
|
+
``customer``, ``wompi_payment_source_id`` (obligatorios), ``make_default``, ``metadata``
|
|
427
|
+
(guarda ahí tu ``legacy_id``). Idempotente por fuente."""
|
|
428
|
+
return self._post(self.path, params, idempotency_key=idempotency_key)
|
|
429
|
+
|
|
430
|
+
def import_wompi_source(
|
|
431
|
+
self,
|
|
432
|
+
*,
|
|
433
|
+
customer: str,
|
|
434
|
+
wompi_payment_source_id: str | int,
|
|
435
|
+
make_default: bool | None = None,
|
|
436
|
+
metadata: dict[str, str] | None = None,
|
|
437
|
+
idempotency_key: str | None = None,
|
|
438
|
+
) -> BucliObject:
|
|
439
|
+
"""Lo mismo que ``create``, con los nombres explícitos."""
|
|
440
|
+
return self.create(
|
|
441
|
+
customer=customer,
|
|
442
|
+
wompi_payment_source_id=str(wompi_payment_source_id),
|
|
443
|
+
make_default=make_default,
|
|
444
|
+
metadata=metadata,
|
|
445
|
+
idempotency_key=idempotency_key,
|
|
446
|
+
)
|
|
447
|
+
|
|
448
|
+
@route("GET", "/payment_methods/{id}")
|
|
449
|
+
def retrieve(self, payment_method_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
450
|
+
return self._get(self._item(payment_method_id), expand=expand)
|
|
451
|
+
|
|
452
|
+
@route("POST", "/payment_methods/{id}/default")
|
|
453
|
+
def set_default(self, payment_method_id: str, *, idempotency_key: str | None = None) -> BucliObject:
|
|
454
|
+
"""Lo hace predeterminado; si el cliente debía, el motor reintenta el cobro."""
|
|
455
|
+
return self._post(self._item(payment_method_id, "/default"), {}, idempotency_key=idempotency_key)
|
|
456
|
+
|
|
457
|
+
@route("POST", "/payment_methods/{id}/backup")
|
|
458
|
+
def set_backup(self, payment_method_id: str, *, idempotency_key: str | None = None) -> BucliObject:
|
|
459
|
+
"""La tarjeta de respaldo: si el banco rechaza la predeterminada, se intenta con esta."""
|
|
460
|
+
return self._post(self._item(payment_method_id, "/backup"), {}, idempotency_key=idempotency_key)
|
|
461
|
+
|
|
462
|
+
@route("DELETE", "/payment_methods/{id}")
|
|
463
|
+
def delete(self, payment_method_id: str) -> BucliObject:
|
|
464
|
+
"""Lo quita del cliente: responde el método con ``customer: null``."""
|
|
465
|
+
return self._delete(self._item(payment_method_id))
|
|
466
|
+
|
|
467
|
+
detach = delete
|
|
468
|
+
|
|
469
|
+
def list(self, *, customer: str, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
470
|
+
"""Los métodos de un cliente (``GET /customers/{id}/payment_methods``)."""
|
|
471
|
+
return self._client.customers.list_payment_methods(customer, expand=expand, **params)
|
|
472
|
+
|
|
473
|
+
|
|
474
|
+
# ---------------------------------------------------------------------------
|
|
475
|
+
# Invoices and payments
|
|
476
|
+
# ---------------------------------------------------------------------------
|
|
477
|
+
|
|
478
|
+
|
|
479
|
+
class Invoices(Resource):
|
|
480
|
+
path = "/invoices"
|
|
481
|
+
|
|
482
|
+
@route("POST", "/invoices")
|
|
483
|
+
def create(
|
|
484
|
+
self, *, idempotency_key: str | None = None, expand: Iterable[str] | None = None, **params: Any
|
|
485
|
+
) -> BucliObject:
|
|
486
|
+
"""Una factura única (un cobro único): ``customer`` y ``lines=[{price, quantity}]`` con precios
|
|
487
|
+
``one_time``, o ``amount`` + ``description``; ``default_payment_method``, ``auto_charge``
|
|
488
|
+
(por defecto ``True``), ``retry`` (por defecto ``False``), ``metadata``."""
|
|
489
|
+
return self._post(self.path, params, idempotency_key=idempotency_key, expand=expand)
|
|
490
|
+
|
|
491
|
+
@route("GET", "/invoices")
|
|
492
|
+
def list(self, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
493
|
+
"""``status``, ``customer``, ``subscription`` además de la paginación."""
|
|
494
|
+
return self._list(self.path, params, expand)
|
|
495
|
+
|
|
496
|
+
@route("GET", "/invoices/{id}")
|
|
497
|
+
def retrieve(self, invoice_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
498
|
+
return self._get(self._item(invoice_id), expand=expand)
|
|
499
|
+
|
|
500
|
+
@route("GET", "/invoices/{id}/lines")
|
|
501
|
+
def list_lines(self, invoice_id: str, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
502
|
+
return self._list(self._item(invoice_id, "/lines"), params, expand)
|
|
503
|
+
|
|
504
|
+
@route("POST", "/invoices/{id}/pay")
|
|
505
|
+
def pay(self, invoice_id: str, *, idempotency_key: str | None = None) -> BucliObject:
|
|
506
|
+
"""Cobra ya una factura ``open`` (``409 invoice_charge_blocked`` si un freno lo detiene)."""
|
|
507
|
+
return self._post(self._item(invoice_id, "/pay"), {}, idempotency_key=idempotency_key)
|
|
508
|
+
|
|
509
|
+
@route("POST", "/invoices/{id}/void")
|
|
510
|
+
def void(self, invoice_id: str, *, idempotency_key: str | None = None) -> BucliObject:
|
|
511
|
+
"""Anula una factura ``draft`` u ``open``."""
|
|
512
|
+
return self._post(self._item(invoice_id, "/void"), {}, idempotency_key=idempotency_key)
|
|
513
|
+
|
|
514
|
+
@route("POST", "/invoices/{id}/mark_paid")
|
|
515
|
+
def mark_paid(
|
|
516
|
+
self,
|
|
517
|
+
invoice_id: str,
|
|
518
|
+
*,
|
|
519
|
+
reference: str,
|
|
520
|
+
reason: str | None = None,
|
|
521
|
+
idempotency_key: str | None = None,
|
|
522
|
+
) -> BucliObject:
|
|
523
|
+
"""Pagada fuera de Wompi (una transferencia): ``reference`` de la transferencia, ``reason``."""
|
|
524
|
+
body = {"reference": reference, "reason": reason}
|
|
525
|
+
return self._post(self._item(invoice_id, "/mark_paid"), body, idempotency_key=idempotency_key)
|
|
526
|
+
|
|
527
|
+
|
|
528
|
+
class Payments(Resource):
|
|
529
|
+
path = "/payments"
|
|
530
|
+
|
|
531
|
+
@route("GET", "/payments")
|
|
532
|
+
def list(self, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
533
|
+
"""Cada intento de cobro enviado a Wompi: ``invoice``, ``status``."""
|
|
534
|
+
return self._list(self.path, params, expand)
|
|
535
|
+
|
|
536
|
+
@route("GET", "/payments/{id}")
|
|
537
|
+
def retrieve(self, payment_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
538
|
+
return self._get(self._item(payment_id), expand=expand)
|
|
539
|
+
|
|
540
|
+
@route("POST", "/payments/{id}/refund")
|
|
541
|
+
def refund(
|
|
542
|
+
self,
|
|
543
|
+
payment_id: str,
|
|
544
|
+
*,
|
|
545
|
+
amount: int | None = None,
|
|
546
|
+
reason: str | None = None,
|
|
547
|
+
cancel_subscription: bool | None = None,
|
|
548
|
+
idempotency_key: str | None = None,
|
|
549
|
+
) -> BucliObject:
|
|
550
|
+
"""Devuelve dinero de un pago aprobado (todo lo que queda, o ``amount``). Responde el
|
|
551
|
+
``refund``: ``pending`` hasta que Wompi lo confirme (``charge.refunded``)."""
|
|
552
|
+
body = {"amount": amount, "reason": reason, "cancel_subscription": cancel_subscription}
|
|
553
|
+
return self._post(self._item(payment_id, "/refund"), body, idempotency_key=idempotency_key)
|
|
554
|
+
|
|
555
|
+
@route("POST", "/payments/{id}/void")
|
|
556
|
+
def void(
|
|
557
|
+
self,
|
|
558
|
+
payment_id: str,
|
|
559
|
+
*,
|
|
560
|
+
reason: str | None = None,
|
|
561
|
+
cancel_subscription: bool | None = None,
|
|
562
|
+
idempotency_key: str | None = None,
|
|
563
|
+
) -> BucliObject:
|
|
564
|
+
"""Anula un cobro con tarjeta del mismo día (Bogotá). Responde el ``refund`` (``kind: void``)."""
|
|
565
|
+
body = {"reason": reason, "cancel_subscription": cancel_subscription}
|
|
566
|
+
return self._post(self._item(payment_id, "/void"), body, idempotency_key=idempotency_key)
|
|
567
|
+
|
|
568
|
+
|
|
569
|
+
class Refunds(Resource):
|
|
570
|
+
path = "/refunds"
|
|
571
|
+
|
|
572
|
+
@route("GET", "/refunds")
|
|
573
|
+
def list(self, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
574
|
+
"""``payment``, ``invoice``, ``status`` además de la paginación."""
|
|
575
|
+
return self._list(self.path, params, expand)
|
|
576
|
+
|
|
577
|
+
@route("GET", "/refunds/{id}")
|
|
578
|
+
def retrieve(self, refund_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
579
|
+
return self._get(self._item(refund_id), expand=expand)
|
|
580
|
+
|
|
581
|
+
|
|
582
|
+
# ---------------------------------------------------------------------------
|
|
583
|
+
# Coupons and fixed-term offers
|
|
584
|
+
# ---------------------------------------------------------------------------
|
|
585
|
+
|
|
586
|
+
|
|
587
|
+
class Coupons(Resource):
|
|
588
|
+
path = "/coupons"
|
|
589
|
+
|
|
590
|
+
@route("POST", "/coupons")
|
|
591
|
+
def create(self, *, idempotency_key: str | None = None, **params: Any) -> BucliObject:
|
|
592
|
+
"""``name``, ``percent_off`` o ``amount_off`` (+ ``currency``), ``duration`` (``once``,
|
|
593
|
+
``repeating`` con ``duration_in_months``, ``forever``), ``applies_to`` (``all``, ``plan``,
|
|
594
|
+
``addons``), ``max_redemptions``, ``redeem_by``, ``metadata``. Solo rebaja facturas de periodo."""
|
|
595
|
+
return self._post(self.path, params, idempotency_key=idempotency_key)
|
|
596
|
+
|
|
597
|
+
@route("GET", "/coupons")
|
|
598
|
+
def list(self, **params: Any) -> ListObject:
|
|
599
|
+
return self._list(self.path, params)
|
|
600
|
+
|
|
601
|
+
@route("GET", "/coupons/{id}")
|
|
602
|
+
def retrieve(self, coupon_id: str) -> BucliObject:
|
|
603
|
+
return self._get(self._item(coupon_id))
|
|
604
|
+
|
|
605
|
+
@route("PATCH", "/coupons/{id}")
|
|
606
|
+
def update(self, coupon_id: str, **params: Any) -> BucliObject:
|
|
607
|
+
"""``name``, ``active``, ``max_redemptions``, ``redeem_by``, ``metadata``; los términos solo sin usos."""
|
|
608
|
+
return self._patch(self._item(coupon_id), params)
|
|
609
|
+
|
|
610
|
+
@route("DELETE", "/coupons/{id}")
|
|
611
|
+
def delete(self, coupon_id: str) -> BucliObject:
|
|
612
|
+
"""No se aplica a nadie más; los descuentos vigentes siguen."""
|
|
613
|
+
return self._delete(self._item(coupon_id))
|
|
614
|
+
|
|
615
|
+
|
|
616
|
+
class FixedTermOffers(Resource):
|
|
617
|
+
path = "/fixed_term_offers"
|
|
618
|
+
|
|
619
|
+
@route("POST", "/fixed_term_offers")
|
|
620
|
+
def create(
|
|
621
|
+
self, *, idempotency_key: str | None = None, expand: Iterable[str] | None = None, **params: Any
|
|
622
|
+
) -> BucliObject:
|
|
623
|
+
"""Un plan por tiempo fijo pagado de una vez con un link de Wompi: ``customer``,
|
|
624
|
+
``items=[{price, quantity}]``, ``days``, ``amount``, ``units=[{meter, units}]``, ``name``,
|
|
625
|
+
``link_days``. Pagado, la suscripción corre esos días y termina sin renovar."""
|
|
626
|
+
return self._post(self.path, params, idempotency_key=idempotency_key, expand=expand)
|
|
627
|
+
|
|
628
|
+
@route("GET", "/fixed_term_offers")
|
|
629
|
+
def list(self, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
630
|
+
"""``customer``, ``status`` además de la paginación."""
|
|
631
|
+
return self._list(self.path, params, expand)
|
|
632
|
+
|
|
633
|
+
@route("GET", "/fixed_term_offers/{id}")
|
|
634
|
+
def retrieve(self, offer_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
635
|
+
return self._get(self._item(offer_id), expand=expand)
|
|
636
|
+
|
|
637
|
+
@route("POST", "/fixed_term_offers/{id}/cancel")
|
|
638
|
+
def cancel(self, offer_id: str, *, idempotency_key: str | None = None) -> BucliObject:
|
|
639
|
+
"""Su link de pago deja de funcionar."""
|
|
640
|
+
return self._post(self._item(offer_id, "/cancel"), {}, idempotency_key=idempotency_key)
|
|
641
|
+
|
|
642
|
+
|
|
643
|
+
# ---------------------------------------------------------------------------
|
|
644
|
+
# Events and webhook endpoints
|
|
645
|
+
# ---------------------------------------------------------------------------
|
|
646
|
+
|
|
647
|
+
|
|
648
|
+
class Events(Resource):
|
|
649
|
+
path = "/events"
|
|
650
|
+
|
|
651
|
+
@route("GET", "/events")
|
|
652
|
+
def list(self, **params: Any) -> ListObject:
|
|
653
|
+
"""Los de los últimos 30 días: ``type`` (``invoice.paid`` o ``invoice.*``)."""
|
|
654
|
+
return self._list(self.path, params)
|
|
655
|
+
|
|
656
|
+
@route("GET", "/events/{id}")
|
|
657
|
+
def retrieve(self, event_id: str) -> BucliObject:
|
|
658
|
+
return self._get(self._item(event_id))
|
|
659
|
+
|
|
660
|
+
@route("POST", "/events/{id}/resend")
|
|
661
|
+
def resend(
|
|
662
|
+
self, event_id: str, *, webhook_endpoint: str | None = None, idempotency_key: str | None = None
|
|
663
|
+
) -> BucliObject:
|
|
664
|
+
"""Lo entrega otra vez, con el mismo id (a un ``webhook_endpoint`` o a todos los que lo escuchan)."""
|
|
665
|
+
body = {"webhook_endpoint": webhook_endpoint}
|
|
666
|
+
return self._post(self._item(event_id, "/resend"), body, idempotency_key=idempotency_key)
|
|
667
|
+
|
|
668
|
+
|
|
669
|
+
class WebhookEndpoints(Resource):
|
|
670
|
+
path = "/webhook_endpoints"
|
|
671
|
+
|
|
672
|
+
@route("POST", "/webhook_endpoints")
|
|
673
|
+
def create(self, *, idempotency_key: str | None = None, **params: Any) -> BucliObject:
|
|
674
|
+
"""``url`` (HTTPS pública), ``enabled_events`` (obligatorios), ``description``, ``metadata``.
|
|
675
|
+
La respuesta trae ``secret`` (``whsec_…``) UNA sola vez: guárdalo."""
|
|
676
|
+
return self._post(self.path, params, idempotency_key=idempotency_key)
|
|
677
|
+
|
|
678
|
+
@route("GET", "/webhook_endpoints")
|
|
679
|
+
def list(self, **params: Any) -> ListObject:
|
|
680
|
+
return self._list(self.path, params)
|
|
681
|
+
|
|
682
|
+
@route("GET", "/webhook_endpoints/{id}")
|
|
683
|
+
def retrieve(self, endpoint_id: str) -> BucliObject:
|
|
684
|
+
return self._get(self._item(endpoint_id))
|
|
685
|
+
|
|
686
|
+
@route("PATCH", "/webhook_endpoints/{id}")
|
|
687
|
+
def update(self, endpoint_id: str, **params: Any) -> BucliObject:
|
|
688
|
+
"""``url``, ``enabled_events``, ``description``, ``disabled``, ``metadata``."""
|
|
689
|
+
return self._patch(self._item(endpoint_id), params)
|
|
690
|
+
|
|
691
|
+
@route("DELETE", "/webhook_endpoints/{id}")
|
|
692
|
+
def delete(self, endpoint_id: str) -> BucliObject:
|
|
693
|
+
return self._delete(self._item(endpoint_id))
|
|
694
|
+
|
|
695
|
+
@route("POST", "/webhook_endpoints/{id}/roll_secret")
|
|
696
|
+
def roll_secret(self, endpoint_id: str, *, idempotency_key: str | None = None) -> BucliObject:
|
|
697
|
+
"""Secreto nuevo (una sola vez). Durante 24 h cada entrega trae dos firmas ``v1``."""
|
|
698
|
+
return self._post(self._item(endpoint_id, "/roll_secret"), {}, idempotency_key=idempotency_key)
|
|
699
|
+
|
|
700
|
+
|
|
701
|
+
# ---------------------------------------------------------------------------
|
|
702
|
+
# Entitlements and metering
|
|
703
|
+
# ---------------------------------------------------------------------------
|
|
704
|
+
|
|
705
|
+
|
|
706
|
+
class Features(Resource):
|
|
707
|
+
"""Tu vocabulario de derechos: módulos (``boolean``) y límites (``limit``)."""
|
|
708
|
+
|
|
709
|
+
path = "/features"
|
|
710
|
+
|
|
711
|
+
@route("POST", "/features")
|
|
712
|
+
def create(self, *, idempotency_key: str | None = None, **params: Any) -> BucliObject:
|
|
713
|
+
"""``key``, ``name``, ``type`` (``boolean``/``limit``); de un límite ``limit_kind``
|
|
714
|
+
(``static``/``metered``) y ``allows_unlimited``; ``description``, ``metadata``."""
|
|
715
|
+
return self._post(self.path, params, idempotency_key=idempotency_key)
|
|
716
|
+
|
|
717
|
+
@route("GET", "/features")
|
|
718
|
+
def list(self, **params: Any) -> ListObject:
|
|
719
|
+
"""``type``, ``key`` además de la paginación."""
|
|
720
|
+
return self._list(self.path, params)
|
|
721
|
+
|
|
722
|
+
@route("GET", "/features/{id}")
|
|
723
|
+
def retrieve(self, feature_id: str) -> BucliObject:
|
|
724
|
+
return self._get(self._item(feature_id))
|
|
725
|
+
|
|
726
|
+
@route("PATCH", "/features/{id}")
|
|
727
|
+
def update(self, feature_id: str, **params: Any) -> BucliObject:
|
|
728
|
+
"""``name``, ``description``, ``allows_unlimited``, ``metadata`` (la clave no cambia)."""
|
|
729
|
+
return self._patch(self._item(feature_id), params)
|
|
730
|
+
|
|
731
|
+
@route("DELETE", "/features/{id}")
|
|
732
|
+
def delete(self, feature_id: str) -> BucliObject:
|
|
733
|
+
"""Solo uno que nada usa (``422 feature_in_use``)."""
|
|
734
|
+
return self._delete(self._item(feature_id))
|
|
735
|
+
|
|
736
|
+
|
|
737
|
+
class Meters(Resource):
|
|
738
|
+
"""Cupos por ventana. ``meter`` es el id (``mtr_…``) o la clave (``documents``)."""
|
|
739
|
+
|
|
740
|
+
path = "/meters"
|
|
741
|
+
|
|
742
|
+
@route("POST", "/meters")
|
|
743
|
+
def create(self, *, idempotency_key: str | None = None, **params: Any) -> BucliObject:
|
|
744
|
+
"""``key`` (un límite ``metered`` de tu vocabulario), ``name``, ``window``, ``timezone``,
|
|
745
|
+
``on_unavailable`` (``allow``/``deny``), ``threshold_percent``, ``active``, ``metadata``."""
|
|
746
|
+
return self._post(self.path, params, idempotency_key=idempotency_key)
|
|
747
|
+
|
|
748
|
+
@route("GET", "/meters")
|
|
749
|
+
def list(self, **params: Any) -> ListObject:
|
|
750
|
+
return self._list(self.path, params)
|
|
751
|
+
|
|
752
|
+
@route("GET", "/meters/{id}")
|
|
753
|
+
def retrieve(self, meter: str) -> BucliObject:
|
|
754
|
+
return self._get(self._item(meter))
|
|
755
|
+
|
|
756
|
+
@route("PATCH", "/meters/{id}")
|
|
757
|
+
def update(self, meter: str, **params: Any) -> BucliObject:
|
|
758
|
+
return self._patch(self._item(meter), params)
|
|
759
|
+
|
|
760
|
+
@route("GET", "/meters/{id}/summary")
|
|
761
|
+
def summary(self, meter: str, *, customer: str) -> BucliObject:
|
|
762
|
+
"""La ventana en curso: ``allowance``, ``used``, ``remaining`` y las bolsas vivas."""
|
|
763
|
+
return self._client.request("GET", self._item(meter, "/summary"), params={"customer": customer})
|
|
764
|
+
|
|
765
|
+
@route("POST", "/meters/{id}/reserve")
|
|
766
|
+
def reserve(
|
|
767
|
+
self,
|
|
768
|
+
meter: str,
|
|
769
|
+
*,
|
|
770
|
+
customer: str,
|
|
771
|
+
idempotency_key: str,
|
|
772
|
+
quantity: int | None = None,
|
|
773
|
+
billable: bool | None = None,
|
|
774
|
+
metadata: dict[str, Any] | None = None,
|
|
775
|
+
timeout: float | None = None,
|
|
776
|
+
max_retries: int | None = None,
|
|
777
|
+
) -> BucliObject:
|
|
778
|
+
"""Toma unidades ahora o lanza ``BillingError`` con ``code == "quota_exhausted"``. La misma
|
|
779
|
+
``idempotency_key`` (el id de tu documento) devuelve la misma reserva. Para el modo
|
|
780
|
+
``allow`` usa ``bucli.metering.UsageGuard``."""
|
|
781
|
+
body = {
|
|
782
|
+
"customer": customer,
|
|
783
|
+
"idempotency_key": idempotency_key,
|
|
784
|
+
"quantity": quantity,
|
|
785
|
+
"billable": billable,
|
|
786
|
+
"metadata": metadata,
|
|
787
|
+
}
|
|
788
|
+
return self._client.request(
|
|
789
|
+
"POST",
|
|
790
|
+
self._item(meter, "/reserve"),
|
|
791
|
+
body=body,
|
|
792
|
+
idempotency_key=reserve_request_key(meter, customer, idempotency_key),
|
|
793
|
+
timeout=timeout,
|
|
794
|
+
max_retries=max_retries,
|
|
795
|
+
)
|
|
796
|
+
|
|
797
|
+
|
|
798
|
+
class Usage(Resource):
|
|
799
|
+
"""El consumo: reportes tardíos y devoluciones."""
|
|
800
|
+
|
|
801
|
+
path = "/usage"
|
|
802
|
+
|
|
803
|
+
@route("POST", "/usage")
|
|
804
|
+
def report(
|
|
805
|
+
self,
|
|
806
|
+
*,
|
|
807
|
+
meter: str,
|
|
808
|
+
customer: str,
|
|
809
|
+
idempotency_key: str,
|
|
810
|
+
occurred_at: Any,
|
|
811
|
+
quantity: int | None = None,
|
|
812
|
+
billable: bool | None = None,
|
|
813
|
+
metadata: dict[str, Any] | None = None,
|
|
814
|
+
) -> BucliObject:
|
|
815
|
+
"""Lo que dejaste pasar mientras Bucli no respondía. ``idempotency_key`` es la de la unidad
|
|
816
|
+
(la misma que habrías usado al reservar); nunca se niega."""
|
|
817
|
+
body = {
|
|
818
|
+
"meter": meter,
|
|
819
|
+
"customer": customer,
|
|
820
|
+
"idempotency_key": idempotency_key,
|
|
821
|
+
"occurred_at": occurred_at,
|
|
822
|
+
"quantity": quantity,
|
|
823
|
+
"billable": billable,
|
|
824
|
+
"metadata": metadata,
|
|
825
|
+
}
|
|
826
|
+
return self._post(self.path, body, idempotency_key=f"report:{idempotency_key}")
|
|
827
|
+
|
|
828
|
+
@route("GET", "/usage")
|
|
829
|
+
def list(self, **params: Any) -> ListObject:
|
|
830
|
+
"""``meter``, ``customer`` además de la paginación."""
|
|
831
|
+
return self._list(self.path, params)
|
|
832
|
+
|
|
833
|
+
@route("GET", "/usage/{id}")
|
|
834
|
+
def retrieve(self, usage_id: str) -> BucliObject:
|
|
835
|
+
return self._get(self._item(usage_id))
|
|
836
|
+
|
|
837
|
+
@route("POST", "/usage/{id}/release")
|
|
838
|
+
def release(self, usage_id: str, *, idempotency_key: str | None = None) -> BucliObject:
|
|
839
|
+
"""Cada unidad vuelve a su origen, una sola vez (un documento rechazado, un borrador borrado)."""
|
|
840
|
+
return self._post(self._item(usage_id, "/release"), {}, idempotency_key=idempotency_key)
|
|
841
|
+
|
|
842
|
+
|
|
843
|
+
class GrantOffers(Resource):
|
|
844
|
+
"""Las bolsas que vendes."""
|
|
845
|
+
|
|
846
|
+
path = "/grant_offers"
|
|
847
|
+
|
|
848
|
+
@route("POST", "/grant_offers")
|
|
849
|
+
def create(self, *, idempotency_key: str | None = None, **params: Any) -> BucliObject:
|
|
850
|
+
"""``meter``, ``price`` (pago único), ``name``, ``units``, ``validity_months``,
|
|
851
|
+
``requires_features``, ``active``, ``position``, ``metadata``."""
|
|
852
|
+
return self._post(self.path, params, idempotency_key=idempotency_key)
|
|
853
|
+
|
|
854
|
+
@route("GET", "/grant_offers")
|
|
855
|
+
def list(self, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
856
|
+
"""``meter``, ``active`` además de la paginación."""
|
|
857
|
+
return self._list(self.path, params, expand)
|
|
858
|
+
|
|
859
|
+
@route("GET", "/grant_offers/{id}")
|
|
860
|
+
def retrieve(self, offer_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
861
|
+
return self._get(self._item(offer_id), expand=expand)
|
|
862
|
+
|
|
863
|
+
@route("PATCH", "/grant_offers/{id}")
|
|
864
|
+
def update(self, offer_id: str, **params: Any) -> BucliObject:
|
|
865
|
+
return self._patch(self._item(offer_id), params)
|
|
866
|
+
|
|
867
|
+
@route("POST", "/grant_offers/{id}/purchase")
|
|
868
|
+
def purchase(
|
|
869
|
+
self, offer_id: str, *, customer: str, payment_method: str | None = None, idempotency_key: str | None = None
|
|
870
|
+
) -> BucliObject:
|
|
871
|
+
"""Cobra la bolsa a la tarjeta del cliente. Responde la factura; la bolsa llega con
|
|
872
|
+
``invoice.paid`` y ``grant.created``."""
|
|
873
|
+
body = {"customer": customer, "payment_method": payment_method}
|
|
874
|
+
return self._post(self._item(offer_id, "/purchase"), body, idempotency_key=idempotency_key)
|
|
875
|
+
|
|
876
|
+
|
|
877
|
+
class Grants(Resource):
|
|
878
|
+
"""Las bolsas de los clientes."""
|
|
879
|
+
|
|
880
|
+
path = "/grants"
|
|
881
|
+
|
|
882
|
+
@route("POST", "/grants")
|
|
883
|
+
def create(self, *, idempotency_key: str | None = None, **params: Any) -> BucliObject:
|
|
884
|
+
"""Un regalo: ``customer``, ``meter``, ``units``, ``expires_at``, ``note``; para importar,
|
|
885
|
+
``imported=True`` y ``remaining``."""
|
|
886
|
+
return self._post(self.path, params, idempotency_key=idempotency_key)
|
|
887
|
+
|
|
888
|
+
@route("GET", "/grants")
|
|
889
|
+
def list(self, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
890
|
+
"""``customer``, ``meter``, ``status`` además de la paginación."""
|
|
891
|
+
return self._list(self.path, params, expand)
|
|
892
|
+
|
|
893
|
+
@route("GET", "/grants/{id}")
|
|
894
|
+
def retrieve(self, grant_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
895
|
+
return self._get(self._item(grant_id), expand=expand)
|
|
896
|
+
|
|
897
|
+
@route("POST", "/grants/{id}/withdraw")
|
|
898
|
+
def withdraw(self, grant_id: str, *, note: str | None = None, idempotency_key: str | None = None) -> BucliObject:
|
|
899
|
+
return self._post(self._item(grant_id, "/withdraw"), {"note": note}, idempotency_key=idempotency_key)
|
|
900
|
+
|
|
901
|
+
|
|
902
|
+
# ---------------------------------------------------------------------------
|
|
903
|
+
# Checkout, payment links and the portal
|
|
904
|
+
# ---------------------------------------------------------------------------
|
|
905
|
+
|
|
906
|
+
#: A replayed POST whose first answer carried a URL with a token answers this
|
|
907
|
+
#: 409 instead of the URL (Bucli never stores it).
|
|
908
|
+
URL_UNAVAILABLE_ON_REPLAY = "url_unavailable_on_replay"
|
|
909
|
+
|
|
910
|
+
|
|
911
|
+
class CheckoutSessions(Resource):
|
|
912
|
+
path = "/checkout_sessions"
|
|
913
|
+
|
|
914
|
+
@route("POST", "/checkout_sessions")
|
|
915
|
+
def create(
|
|
916
|
+
self, *, idempotency_key: str | None = None, expand: Iterable[str] | None = None, **params: Any
|
|
917
|
+
) -> BucliObject:
|
|
918
|
+
"""``success_url`` (obligatorio) y ``price`` (+ ``quantity``) o ``line_items=[{price, quantity}]``
|
|
919
|
+
(plan base, puestos, adicionales: mismo intervalo, recurrentes); ``cancel_url``, ``customer`` o
|
|
920
|
+
``customer_email``, ``customer_fields``, ``trial_days``, ``client_reference_id``, ``metadata`` y
|
|
921
|
+
``subscription_data={metadata, trial_days}`` (la ``metadata`` va a la suscripción que se crea).
|
|
922
|
+
Redirige a ``url``.
|
|
923
|
+
|
|
924
|
+
Si un reintento de red repite la petición y Bucli ya la había hecho, el replay no trae la URL
|
|
925
|
+
(``409 url_unavailable_on_replay``, con el id en ``error.object_id``): la librería consulta la
|
|
926
|
+
sesión por ese id para recuperarla."""
|
|
927
|
+
try:
|
|
928
|
+
return self._post(self.path, params, idempotency_key=idempotency_key, expand=expand)
|
|
929
|
+
except InvalidRequestError as error:
|
|
930
|
+
session_id = _replayed_id(error, "checkout.session")
|
|
931
|
+
if session_id is None:
|
|
932
|
+
raise
|
|
933
|
+
return self.retrieve(session_id, expand=expand)
|
|
934
|
+
|
|
935
|
+
@route("GET", "/checkout_sessions/{id}")
|
|
936
|
+
def retrieve(self, session_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
937
|
+
"""Al volver a ``success_url``: qué suscripción quedó creada (no actives el plan con esto
|
|
938
|
+
sin mirar el estado de la suscripción)."""
|
|
939
|
+
return self._get(self._item(session_id), expand=expand)
|
|
940
|
+
|
|
941
|
+
@route("POST", "/checkout_sessions/{id}/expire")
|
|
942
|
+
def expire(self, session_id: str, *, idempotency_key: str | None = None) -> BucliObject:
|
|
943
|
+
return self._post(self._item(session_id, "/expire"), {}, idempotency_key=idempotency_key)
|
|
944
|
+
|
|
945
|
+
|
|
946
|
+
class PaymentLinks(Resource):
|
|
947
|
+
path = "/payment_links"
|
|
948
|
+
|
|
949
|
+
@route("POST", "/payment_links")
|
|
950
|
+
def create(self, *, idempotency_key: str | None = None, **params: Any) -> BucliObject:
|
|
951
|
+
"""``price`` (+ ``quantity``) o ``line_items=[{price, quantity}]``; ``customer_fields``, ``trial_days``,
|
|
952
|
+
``success_url``, ``active``, ``metadata``. Cada visita abre un checkout con esas líneas."""
|
|
953
|
+
return self._post(self.path, params, idempotency_key=idempotency_key)
|
|
954
|
+
|
|
955
|
+
@route("GET", "/payment_links")
|
|
956
|
+
def list(self, *, expand: Iterable[str] | None = None, **params: Any) -> ListObject:
|
|
957
|
+
"""``active``, ``price`` además de la paginación."""
|
|
958
|
+
return self._list(self.path, params, expand)
|
|
959
|
+
|
|
960
|
+
@route("GET", "/payment_links/{id}")
|
|
961
|
+
def retrieve(self, link_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
962
|
+
return self._get(self._item(link_id), expand=expand)
|
|
963
|
+
|
|
964
|
+
@route("PATCH", "/payment_links/{id}")
|
|
965
|
+
def update(self, link_id: str, **params: Any) -> BucliObject:
|
|
966
|
+
"""``active=False`` lo desactiva; el precio no cambia (crea otro enlace)."""
|
|
967
|
+
return self._patch(self._item(link_id), params)
|
|
968
|
+
|
|
969
|
+
|
|
970
|
+
class PortalSessions(Resource):
|
|
971
|
+
path = "/portal_sessions"
|
|
972
|
+
|
|
973
|
+
@route("POST", "/portal_sessions")
|
|
974
|
+
def create(
|
|
975
|
+
self, *, customer: str, return_url: str | None = None, idempotency_key: str | None = None
|
|
976
|
+
) -> BucliObject:
|
|
977
|
+
"""La ``url`` del portal del cliente, válida una hora. Solo se responde al crearla: si un
|
|
978
|
+
reintento cae en el replay (``409 url_unavailable_on_replay``) se crea otra con una clave nueva
|
|
979
|
+
(``retrieve`` no la vuelve a mostrar)."""
|
|
980
|
+
body = {"customer": customer, "return_url": return_url}
|
|
981
|
+
try:
|
|
982
|
+
return self._post(self.path, body, idempotency_key=idempotency_key)
|
|
983
|
+
except InvalidRequestError as error:
|
|
984
|
+
if error.code != URL_UNAVAILABLE_ON_REPLAY:
|
|
985
|
+
raise
|
|
986
|
+
return self._post(self.path, body)
|
|
987
|
+
|
|
988
|
+
@route("GET", "/portal_sessions/{id}")
|
|
989
|
+
def retrieve(self, session_id: str, *, expand: Iterable[str] | None = None) -> BucliObject:
|
|
990
|
+
"""Para qué cliente es y hasta cuándo vale, SIN la ``url`` (``None``): es una credencial que
|
|
991
|
+
solo se responde al crearla."""
|
|
992
|
+
return self._get(self._item(session_id), expand=expand)
|
|
993
|
+
|
|
994
|
+
|
|
995
|
+
def _replayed_id(error: InvalidRequestError, object_type: str) -> str | None:
|
|
996
|
+
"""The id a ``url_unavailable_on_replay`` names in ``error.object_id``
|
|
997
|
+
when the replayed object is an ``object_type``, or ``None``."""
|
|
998
|
+
if error.code != URL_UNAVAILABLE_ON_REPLAY or not error.object_id:
|
|
999
|
+
return None
|
|
1000
|
+
if error.object_type not in (None, object_type):
|
|
1001
|
+
return None
|
|
1002
|
+
return error.object_id
|