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/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