folyo 0.2.2__tar.gz → 0.3.0__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.2
3
+ Version: 0.3.0
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
@@ -140,6 +140,12 @@ encolada = folyo.dte.emitir(req)
140
140
  print(encolada.job_id) # resuelve luego via webhook dte.emitido o polling
141
141
  ```
142
142
 
143
+ El `folio` de `encolada` es referencial (el proximo libre al encolar) y puede
144
+ repetirse entre documentos en proceso. El del documento es `job.folio` (igual a
145
+ `job.result.folio`) con el job `completed`, y `data.folio` del webhook
146
+ `dte.emitido`. El webhook `dte.fallido` informa `data.folio` en `0`, porque el
147
+ documento no llego a tener folio: correlaciona por `job_id`.
148
+
143
149
  ## Impuestos adicionales y retenciones por linea
144
150
 
145
151
  Una linea puede llevar `impuestos` con el codigo del impuesto adicional del
@@ -267,6 +273,7 @@ for doc in folyo.dte.listar_documentos(limite=1):
267
273
  from folyo import (
268
274
  Folyo,
269
275
  FolyoAuthError,
276
+ FolyoConflictError,
270
277
  FolyoQuotaError,
271
278
  FolyoRateLimitError,
272
279
  FolyoValidationError,
@@ -285,8 +292,12 @@ except FolyoValidationError as e:
285
292
  print("Datos invalidos:", e.message)
286
293
  for field in e.field_errors:
287
294
  print(field.field, field.message, field.max, field.actual)
295
+ except FolyoConflictError as e:
296
+ # Rechazo del portal de timbraje al solicitar folios (FOLIOS_RECHAZADOS_SII,
297
+ # FOLIOS_BOLETA_SISTEMA_SII, TIMBRAJE_NO_AUTORIZADO): e.message trae el motivo del SII.
298
+ print("El SII rechazo la solicitud de folios:", e.code, e.message)
288
299
  except FolyoSiiUnavailableError:
289
- print("El SII no esta disponible, reintenta mas tarde")
300
+ print("El SII no esta disponible, reintenta mas tarde") # o PDF_BUSY
290
301
  ```
291
302
 
292
303
  Para límites de DTE, `FolyoValidationError.field_errors` es una tupla de
@@ -296,7 +307,16 @@ la request.
296
307
 
297
308
  El SDK reintenta automaticamente (con backoff exponencial y respetando
298
309
  `Retry-After`) ante `429` y `503` en operaciones seguras: peticiones `GET` y
299
- emisiones con `Idempotency-Key`.
310
+ emisiones con `Idempotency-Key`. Las descargas (`descargar_pdf`, `descargar_xml`)
311
+ entran en esa regla, incluido el `503 PDF_BUSY`.
312
+
313
+ ### Limite de descargas
314
+
315
+ `GET /v1/dte/pdf`, `GET /v1/dte/xml` y `POST .../regenerate` comparten un limite
316
+ propio de **20 peticiones por ventana de 4 segundos por cuenta**, ademas del
317
+ limite general de 50 por segundo. Guarda el archivo cuando lo descargues; no
318
+ vuelvas a pedirlo en cada vista ni recorras todo tu historial en bucle. El `429`
319
+ llega como `FolyoRateLimitError` con `retry_after`.
300
320
 
301
321
  ## Recursos disponibles
302
322
 
@@ -104,6 +104,12 @@ encolada = folyo.dte.emitir(req)
104
104
  print(encolada.job_id) # resuelve luego via webhook dte.emitido o polling
105
105
  ```
106
106
 
107
+ El `folio` de `encolada` es referencial (el proximo libre al encolar) y puede
108
+ repetirse entre documentos en proceso. El del documento es `job.folio` (igual a
109
+ `job.result.folio`) con el job `completed`, y `data.folio` del webhook
110
+ `dte.emitido`. El webhook `dte.fallido` informa `data.folio` en `0`, porque el
111
+ documento no llego a tener folio: correlaciona por `job_id`.
112
+
107
113
  ## Impuestos adicionales y retenciones por linea
108
114
 
109
115
  Una linea puede llevar `impuestos` con el codigo del impuesto adicional del
@@ -231,6 +237,7 @@ for doc in folyo.dte.listar_documentos(limite=1):
231
237
  from folyo import (
232
238
  Folyo,
233
239
  FolyoAuthError,
240
+ FolyoConflictError,
234
241
  FolyoQuotaError,
235
242
  FolyoRateLimitError,
236
243
  FolyoValidationError,
@@ -249,8 +256,12 @@ except FolyoValidationError as e:
249
256
  print("Datos invalidos:", e.message)
250
257
  for field in e.field_errors:
251
258
  print(field.field, field.message, field.max, field.actual)
259
+ except FolyoConflictError as e:
260
+ # Rechazo del portal de timbraje al solicitar folios (FOLIOS_RECHAZADOS_SII,
261
+ # FOLIOS_BOLETA_SISTEMA_SII, TIMBRAJE_NO_AUTORIZADO): e.message trae el motivo del SII.
262
+ print("El SII rechazo la solicitud de folios:", e.code, e.message)
252
263
  except FolyoSiiUnavailableError:
253
- print("El SII no esta disponible, reintenta mas tarde")
264
+ print("El SII no esta disponible, reintenta mas tarde") # o PDF_BUSY
254
265
  ```
255
266
 
256
267
  Para límites de DTE, `FolyoValidationError.field_errors` es una tupla de
@@ -260,7 +271,16 @@ la request.
260
271
 
261
272
  El SDK reintenta automaticamente (con backoff exponencial y respetando
262
273
  `Retry-After`) ante `429` y `503` en operaciones seguras: peticiones `GET` y
263
- emisiones con `Idempotency-Key`.
274
+ emisiones con `Idempotency-Key`. Las descargas (`descargar_pdf`, `descargar_xml`)
275
+ entran en esa regla, incluido el `503 PDF_BUSY`.
276
+
277
+ ### Limite de descargas
278
+
279
+ `GET /v1/dte/pdf`, `GET /v1/dte/xml` y `POST .../regenerate` comparten un limite
280
+ propio de **20 peticiones por ventana de 4 segundos por cuenta**, ademas del
281
+ limite general de 50 por segundo. Guarda el archivo cuando lo descargues; no
282
+ vuelvas a pedirlo en cada vista ni recorras todo tu historial en bucle. El `429`
283
+ llega como `FolyoRateLimitError` con `retry_after`.
264
284
 
265
285
  ## Recursos disponibles
266
286
 
@@ -39,7 +39,7 @@ from .resources import (
39
39
  WebhooksResource,
40
40
  )
41
41
 
42
- __version__ = "0.2.2"
42
+ __version__ = "0.3.0"
43
43
 
44
44
  DEFAULT_BASE_URL = "https://api.folyo.cl"
45
45
  USER_AGENT = f"folyo-sdk-python/{__version__}"
@@ -279,6 +279,11 @@ class Folyo:
279
279
  request_id=request_id,
280
280
  retry_after=retry_after,
281
281
  )
282
+ # Por codigo antes que por status: PLAN_LIMIT y PLAN_REQUIRED llegan
283
+ # como 403 y son de cuota, no de credenciales (antes caian en
284
+ # FolyoAuthError, contradiciendo la documentacion).
285
+ if code in ("PLAN_LIMIT", "PLAN_REQUIRED", "PAYMENT_REQUIRED"):
286
+ raise FolyoQuotaError(message, status=status, code=code, request_id=request_id)
282
287
  if status in (401, 403):
283
288
  raise FolyoAuthError(message, status=status, code=code, request_id=request_id)
284
289
  if status == 402:
@@ -296,11 +301,6 @@ class Folyo:
296
301
  field_errors=field_errors,
297
302
  )
298
303
 
299
- # PLAN_LIMIT/PLAN_REQUIRED pueden llegar como 403 (ya cubierto) pero por
300
- # si el server cambia, mapeamos por codigo a quota.
301
- if code in ("PLAN_LIMIT", "PLAN_REQUIRED", "PAYMENT_REQUIRED"):
302
- raise FolyoQuotaError(message, status=status, code=code, request_id=request_id)
303
-
304
304
  raise FolyoError(message, status=status, code=code, request_id=request_id)
305
305
 
306
306
  @staticmethod
@@ -92,7 +92,9 @@ class FolyoAuthError(FolyoError):
92
92
  class FolyoQuotaError(FolyoError):
93
93
  """Limite de plan o pago requerido (402/403).
94
94
 
95
- Cubre ``PLAN_LIMIT``, ``PLAN_REQUIRED`` y ``PAYMENT_REQUIRED``.
95
+ Cubre ``PLAN_LIMIT``, ``PLAN_REQUIRED`` y ``PAYMENT_REQUIRED``. ``PLAN_LIMIT``
96
+ tambien llega al solicitar o cargar folios de boleta (tipos 39 y 41) en un
97
+ plan que no incluye boletas: la API lo responde sin contactar al SII.
96
98
  """
97
99
 
98
100
 
@@ -126,7 +128,12 @@ class FolyoConflictError(FolyoError):
126
128
  """Conflicto (409).
127
129
 
128
130
  Incluye ``IDEMPOTENCY_KEY_CONFLICT`` (misma Idempotency-Key con cuerpo
129
- distinto) y ``TIMBRAJE_NO_AUTORIZADO``.
131
+ distinto) y los rechazos del portal de timbraje del SII al solicitar
132
+ folios, con el motivo del SII en ``message``: ``FOLIOS_RECHAZADOS_SII``
133
+ (glosa o codigo crudo, por ejemplo ST-RS-DTE-15-1),
134
+ ``FOLIOS_BOLETA_SISTEMA_SII`` (la empresa emite boletas con el sistema
135
+ gratuito del SII) y ``TIMBRAJE_NO_AUTORIZADO`` (folios sin usar o situacion
136
+ pendiente). Reintentar sin cambiar nada en el SII devuelve el mismo error.
130
137
  """
131
138
 
132
139
 
@@ -153,8 +160,10 @@ class FolyoSiiUnavailableError(FolyoError):
153
160
  """SII o un servicio aguas abajo no disponible (502/503/504).
154
161
 
155
162
  Cubre ``SII_UNAVAILABLE``, ``SII_TIMEOUT``, ``SII_AUTH_FAILED``,
156
- ``SII_ERROR``, ``SII_CAPTCHA_REQUIRED``, ``FOLIOS_REQUESTING`` y
157
- ``QUEUE_UNAVAILABLE``. Expone ``retry_after`` cuando el server lo entrega.
163
+ ``SII_ERROR``, ``SII_CAPTCHA_REQUIRED``, ``FOLIOS_REQUESTING``,
164
+ ``QUEUE_UNAVAILABLE`` y ``PDF_BUSY`` (generacion de PDF saturada; los
165
+ documentos cuyo PDF ya existe siguen descargandose). Expone ``retry_after``
166
+ cuando el server lo entrega.
158
167
  """
159
168
 
160
169
  def __init__(
@@ -519,6 +519,10 @@ class EmisionResult(_FromDict):
519
519
  monto_total: Optional[int] = None
520
520
  fecha_emision: Optional[str] = None
521
521
  xml_firmado: Optional[str] = None
522
+ #: Elemento ``<TED>`` (timbre electronico) tal como va dentro de
523
+ #: ``xml_firmado``, para dibujar el PDF417 al imprimir por cuenta propia.
524
+ #: ``None`` en los jobs completados antes de que el servidor lo entregara.
525
+ ted: Optional[str] = None
522
526
  #: Desglose de impuestos adicionales y retenciones (un elemento por
523
527
  #: ``<ImptoReten>``). Vacio en documentos sin impuestos.
524
528
  impuestos: List[ImpuestoTotal] = field(default_factory=list)
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "folyo"
7
- version = "0.2.2"
7
+ version = "0.3.0"
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