folyo 0.2.1__tar.gz → 0.2.2__tar.gz

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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: folyo
3
- Version: 0.2.1
3
+ Version: 0.2.2
4
4
  Summary: SDK oficial de Python para la API de Folyo (facturacion electronica chilena, DTE + SII).
5
5
  Project-URL: Homepage, https://folyo.cl
6
6
  Project-URL: Documentation, https://docs.folyo.cl/sdks
@@ -283,10 +283,17 @@ except FolyoAuthError:
283
283
  print("Credenciales invalidas o sin permisos")
284
284
  except FolyoValidationError as e:
285
285
  print("Datos invalidos:", e.message)
286
+ for field in e.field_errors:
287
+ print(field.field, field.message, field.max, field.actual)
286
288
  except FolyoSiiUnavailableError:
287
289
  print("El SII no esta disponible, reintenta mas tarde")
288
290
  ```
289
291
 
292
+ Para límites de DTE, `FolyoValidationError.field_errors` es una tupla de
293
+ `FolyoFieldError` con `field`, `message`, `max` y `actual`. Está vacía cuando
294
+ la API no identifica un campo y nunca conserva el valor enviado ni el body de
295
+ la request.
296
+
290
297
  El SDK reintenta automaticamente (con backoff exponencial y respetando
291
298
  `Retry-After`) ante `429` y `503` en operaciones seguras: peticiones `GET` y
292
299
  emisiones con `Idempotency-Key`.
@@ -307,6 +314,16 @@ emisiones con `Idempotency-Key`.
307
314
  Algunos endpoints (clientes, RCV, listado de documentos) requieren "panel
308
315
  operativo" y responden `403` en planes solo-API.
309
316
 
317
+ ### Forma de pago en compras
318
+
319
+ En `folyo.rcv.periodo`, cada documento trae `forma_pago`: `1` contado, `2`
320
+ credito, `3` sin costo y `0` no informado. El RCV del SII no informa este dato,
321
+ asi que en compras solo viene con valor cuando Folyo recibio el XML del
322
+ documento en la casilla de intercambio de la empresa, y desde el plan Starter
323
+ (en planes gratuitos siempre es `0`). Es lo que declara el proveedor en el DTE:
324
+ sirve para clasificar cuentas por pagar, no determina el credito fiscal. Trata
325
+ el `0` como "sin dato", no como contado.
326
+
310
327
  ## Seguridad
311
328
 
312
329
  - La API key y el JWT nunca se incluyen en `repr(cliente)` ni en los errores.
@@ -247,10 +247,17 @@ except FolyoAuthError:
247
247
  print("Credenciales invalidas o sin permisos")
248
248
  except FolyoValidationError as e:
249
249
  print("Datos invalidos:", e.message)
250
+ for field in e.field_errors:
251
+ print(field.field, field.message, field.max, field.actual)
250
252
  except FolyoSiiUnavailableError:
251
253
  print("El SII no esta disponible, reintenta mas tarde")
252
254
  ```
253
255
 
256
+ Para límites de DTE, `FolyoValidationError.field_errors` es una tupla de
257
+ `FolyoFieldError` con `field`, `message`, `max` y `actual`. Está vacía cuando
258
+ la API no identifica un campo y nunca conserva el valor enviado ni el body de
259
+ la request.
260
+
254
261
  El SDK reintenta automaticamente (con backoff exponencial y respetando
255
262
  `Retry-After`) ante `429` y `503` en operaciones seguras: peticiones `GET` y
256
263
  emisiones con `Idempotency-Key`.
@@ -271,6 +278,16 @@ emisiones con `Idempotency-Key`.
271
278
  Algunos endpoints (clientes, RCV, listado de documentos) requieren "panel
272
279
  operativo" y responden `403` en planes solo-API.
273
280
 
281
+ ### Forma de pago en compras
282
+
283
+ En `folyo.rcv.periodo`, cada documento trae `forma_pago`: `1` contado, `2`
284
+ credito, `3` sin costo y `0` no informado. El RCV del SII no informa este dato,
285
+ asi que en compras solo viene con valor cuando Folyo recibio el XML del
286
+ documento en la casilla de intercambio de la empresa, y desde el plan Starter
287
+ (en planes gratuitos siempre es `0`). Es lo que declara el proveedor en el DTE:
288
+ sirve para clasificar cuentas por pagar, no determina el credito fiscal. Trata
289
+ el `0` como "sin dato", no como contado.
290
+
274
291
  ## Seguridad
275
292
 
276
293
  - La API key y el JWT nunca se incluyen en `repr(cliente)` ni en los errores.
@@ -27,6 +27,7 @@ from .errors import (
27
27
  FolyoConflictError,
28
28
  FolyoConnectionError,
29
29
  FolyoError,
30
+ FolyoFieldError,
30
31
  FolyoNotFoundError,
31
32
  FolyoQuotaError,
32
33
  FolyoRateLimitError,
@@ -75,6 +76,7 @@ __all__ = [
75
76
  "redact",
76
77
  # Errores
77
78
  "FolyoError",
79
+ "FolyoFieldError",
78
80
  "FolyoAuthError",
79
81
  "FolyoQuotaError",
80
82
  "FolyoValidationError",
@@ -11,7 +11,7 @@ from __future__ import annotations
11
11
  import random
12
12
  import time
13
13
  from types import TracebackType
14
- from typing import Any, Dict, Mapping, NoReturn, Optional, Type
14
+ from typing import Any, Dict, List, Mapping, NoReturn, Optional, Tuple, Type
15
15
 
16
16
  import httpx
17
17
 
@@ -21,6 +21,7 @@ from .errors import (
21
21
  FolyoConflictError,
22
22
  FolyoConnectionError,
23
23
  FolyoError,
24
+ FolyoFieldError,
24
25
  FolyoNotFoundError,
25
26
  FolyoQuotaError,
26
27
  FolyoRateLimitError,
@@ -38,7 +39,7 @@ from .resources import (
38
39
  WebhooksResource,
39
40
  )
40
41
 
41
- __version__ = "0.2.1"
42
+ __version__ = "0.2.2"
42
43
 
43
44
  DEFAULT_BASE_URL = "https://api.folyo.cl"
44
45
  USER_AGENT = f"folyo-sdk-python/{__version__}"
@@ -260,6 +261,7 @@ class Folyo:
260
261
  message = f"La API respondio con HTTP {status}."
261
262
 
262
263
  retry_after = self._parse_retry_after(response)
264
+ field_errors = self._safe_field_errors(body)
263
265
 
264
266
  if status == 429:
265
267
  raise FolyoRateLimitError(
@@ -286,7 +288,13 @@ class Folyo:
286
288
  if status == 409:
287
289
  raise FolyoConflictError(message, status=status, code=code, request_id=request_id)
288
290
  if status in (400, 422):
289
- raise FolyoValidationError(message, status=status, code=code, request_id=request_id)
291
+ raise FolyoValidationError(
292
+ message,
293
+ status=status,
294
+ code=code,
295
+ request_id=request_id,
296
+ field_errors=field_errors,
297
+ )
290
298
 
291
299
  # PLAN_LIMIT/PLAN_REQUIRED pueden llegar como 403 (ya cubierto) pero por
292
300
  # si el server cambia, mapeamos por codigo a quota.
@@ -294,3 +302,34 @@ class Folyo:
294
302
  raise FolyoQuotaError(message, status=status, code=code, request_id=request_id)
295
303
 
296
304
  raise FolyoError(message, status=status, code=code, request_id=request_id)
305
+
306
+ @staticmethod
307
+ def _safe_field_errors(body: Optional[Any]) -> Tuple[FolyoFieldError, ...]:
308
+ """Extrae solo `field_errors` públicos, sin retener el envelope HTTP."""
309
+ if not isinstance(body, dict):
310
+ return ()
311
+ raw_errors = body.get("field_errors")
312
+ if not isinstance(raw_errors, list):
313
+ return ()
314
+
315
+ field_errors: List[FolyoFieldError] = []
316
+ for raw_error in raw_errors:
317
+ if not isinstance(raw_error, dict):
318
+ continue
319
+ field = raw_error.get("field")
320
+ message = raw_error.get("message")
321
+ if not isinstance(field, str) or not isinstance(message, str):
322
+ continue
323
+ raw_max = raw_error.get("max")
324
+ raw_actual = raw_error.get("actual")
325
+ max_value = raw_max if isinstance(raw_max, int) and not isinstance(raw_max, bool) and raw_max >= 0 else None
326
+ actual_value = raw_actual if isinstance(raw_actual, int) and not isinstance(raw_actual, bool) and raw_actual >= 0 else None
327
+ field_errors.append(
328
+ FolyoFieldError(
329
+ field=field,
330
+ message=message,
331
+ max=max_value,
332
+ actual=actual_value,
333
+ )
334
+ )
335
+ return tuple(field_errors)
@@ -8,10 +8,12 @@ el codigo estable, el status HTTP y el request id (si el servidor lo entrega).
8
8
 
9
9
  from __future__ import annotations
10
10
 
11
- from typing import Optional
11
+ from dataclasses import dataclass
12
+ from typing import Optional, Tuple
12
13
 
13
14
  __all__ = [
14
15
  "FolyoError",
16
+ "FolyoFieldError",
15
17
  "FolyoAuthError",
16
18
  "FolyoQuotaError",
17
19
  "FolyoValidationError",
@@ -23,6 +25,16 @@ __all__ = [
23
25
  ]
24
26
 
25
27
 
28
+ @dataclass(frozen=True)
29
+ class FolyoFieldError:
30
+ """Detalle seguro de un campo rechazado por la validación de la API."""
31
+
32
+ field: str
33
+ message: str
34
+ max: Optional[int] = None
35
+ actual: Optional[int] = None
36
+
37
+
26
38
  class FolyoError(Exception):
27
39
  """Error base de todos los errores del SDK.
28
40
 
@@ -93,6 +105,18 @@ class FolyoValidationError(FolyoError):
93
105
  libera al validarla en certificacion). En ambos casos no se asigna folio.
94
106
  """
95
107
 
108
+ def __init__(
109
+ self,
110
+ message: str,
111
+ *,
112
+ status: Optional[int] = None,
113
+ code: Optional[str] = None,
114
+ request_id: Optional[str] = None,
115
+ field_errors: Tuple[FolyoFieldError, ...] = (),
116
+ ) -> None:
117
+ super().__init__(message, status=status, code=code, request_id=request_id)
118
+ self.field_errors = field_errors
119
+
96
120
 
97
121
  class FolyoNotFoundError(FolyoError):
98
122
  """Recurso no encontrado (404)."""
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "folyo"
7
- version = "0.2.1"
7
+ version = "0.2.2"
8
8
  description = "SDK oficial de Python para la API de Folyo (facturacion electronica chilena, DTE + SII)."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.9"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes