folyo 0.2.2__tar.gz → 0.3.1__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.1
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,63 @@ 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
+
149
+ ## Guia de despacho por courier (sin datos del transporte)
150
+
151
+ Desde la activacion de la Res. Ex. SII 154/2025 (por defecto el 1 de noviembre
152
+ de 2026; la fecha efectiva la publica `folyo.dte.reglas()`) toda guia de
153
+ despacho (52) exige `tipo_despacho` y el bloque `transporte` completo:
154
+ `rut_transportista`, `patente`, `rut_chofer`, `nombre_chofer`, `dir_destino`,
155
+ `cmna_destino`, `fecha_salida`, `hora_salida` (`HH:MM:SS`) y `fecha_llegada`.
156
+ Si el traslado lo hace un courier y no conoces la patente, el remolque ni el
157
+ chofer, declara `sin_datos_transporte=True` con el RUT del courier: la API
158
+ exime esos cinco datos y el XML lleva la declaracion expresa que exige el SII.
159
+
160
+ ```python
161
+ import uuid
162
+ from folyo import Folyo, DTERequest, Receptor, DetalleLinea, Transporte
163
+
164
+ with Folyo(api_key="<tu-api-key>") as folyo:
165
+ reglas = folyo.dte.reglas()
166
+ print(reglas.transporte.obligatorio, reglas.transporte.obligatorio_desde)
167
+
168
+ req = DTERequest(
169
+ tipo_dte=52, # Guia de Despacho
170
+ ind_traslado=1, # operacion constituye venta
171
+ tipo_despacho=2, # por cuenta del emisor, a instalaciones del cliente
172
+ receptor=Receptor(rut="12.345.678-9", razon_social="Cliente SpA", giro="Comercio"),
173
+ detalle=[DetalleLinea(nombre="Repuestos", cantidad=4, precio=25000, monto=100000)],
174
+ transporte=Transporte(
175
+ sin_datos_transporte=True, # no se conoce patente, remolque ni chofer
176
+ rut_transportista="76.543.210-3", # RUT del courier: siempre se conoce
177
+ dir_destino="Av. Siempre Viva 742",
178
+ cmna_destino="Providencia",
179
+ fecha_salida="2026-11-02",
180
+ hora_salida="08:30:00",
181
+ fecha_llegada="2026-11-03",
182
+ ),
183
+ )
184
+ job = folyo.dte.emitir_y_esperar(req, idempotency_key=str(uuid.uuid4()))
185
+
186
+ # Avisos no bloqueantes, estructurados (tambien en encolada.advertencias_detalle).
187
+ if job.result is not None:
188
+ for aviso in job.result.advertencias_detalle:
189
+ print(aviso.codigo, aviso.campos, aviso.mensaje)
190
+ ```
191
+
192
+ Antes de la fecha efectiva, los campos que falten llegan como advertencia
193
+ `TRANSPORTE_INCOMPLETO` en `advertencias_detalle` y la guia se emite igual;
194
+ despues, la API responde 400 `TRANSPORTE_INCOMPLETO` (`FolyoValidationError`
195
+ con un `field_errors` por campo, por ejemplo `transporte.patente`). Con el flag
196
+ y sin `rut_transportista` la emision sigue con `TRANSPORTISTA_NO_INFORMADO`. Las
197
+ facturas 33 y 34 aceptan el mismo bloque de forma opcional; en 46, 56 y 61 la
198
+ API responde `TRANSPORTE_NO_SOPORTADO`.
199
+
143
200
  ## Impuestos adicionales y retenciones por linea
144
201
 
145
202
  Una linea puede llevar `impuestos` con el codigo del impuesto adicional del
@@ -267,6 +324,7 @@ for doc in folyo.dte.listar_documentos(limite=1):
267
324
  from folyo import (
268
325
  Folyo,
269
326
  FolyoAuthError,
327
+ FolyoConflictError,
270
328
  FolyoQuotaError,
271
329
  FolyoRateLimitError,
272
330
  FolyoValidationError,
@@ -285,8 +343,12 @@ except FolyoValidationError as e:
285
343
  print("Datos invalidos:", e.message)
286
344
  for field in e.field_errors:
287
345
  print(field.field, field.message, field.max, field.actual)
346
+ except FolyoConflictError as e:
347
+ # Rechazo del portal de timbraje al solicitar folios (FOLIOS_RECHAZADOS_SII,
348
+ # FOLIOS_BOLETA_SISTEMA_SII, TIMBRAJE_NO_AUTORIZADO): e.message trae el motivo del SII.
349
+ print("El SII rechazo la solicitud de folios:", e.code, e.message)
288
350
  except FolyoSiiUnavailableError:
289
- print("El SII no esta disponible, reintenta mas tarde")
351
+ print("El SII no esta disponible, reintenta mas tarde") # o PDF_BUSY
290
352
  ```
291
353
 
292
354
  Para límites de DTE, `FolyoValidationError.field_errors` es una tupla de
@@ -296,7 +358,16 @@ la request.
296
358
 
297
359
  El SDK reintenta automaticamente (con backoff exponencial y respetando
298
360
  `Retry-After`) ante `429` y `503` en operaciones seguras: peticiones `GET` y
299
- emisiones con `Idempotency-Key`.
361
+ emisiones con `Idempotency-Key`. Las descargas (`descargar_pdf`, `descargar_xml`)
362
+ entran en esa regla, incluido el `503 PDF_BUSY`.
363
+
364
+ ### Limite de descargas
365
+
366
+ `GET /v1/dte/pdf`, `GET /v1/dte/xml` y `POST .../regenerate` comparten un limite
367
+ propio de **20 peticiones por ventana de 4 segundos por cuenta**, ademas del
368
+ limite general de 50 por segundo. Guarda el archivo cuando lo descargues; no
369
+ vuelvas a pedirlo en cada vista ni recorras todo tu historial en bucle. El `429`
370
+ llega como `FolyoRateLimitError` con `retry_after`.
300
371
 
301
372
  ## Recursos disponibles
302
373
 
@@ -104,6 +104,63 @@ 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
+
113
+ ## Guia de despacho por courier (sin datos del transporte)
114
+
115
+ Desde la activacion de la Res. Ex. SII 154/2025 (por defecto el 1 de noviembre
116
+ de 2026; la fecha efectiva la publica `folyo.dte.reglas()`) toda guia de
117
+ despacho (52) exige `tipo_despacho` y el bloque `transporte` completo:
118
+ `rut_transportista`, `patente`, `rut_chofer`, `nombre_chofer`, `dir_destino`,
119
+ `cmna_destino`, `fecha_salida`, `hora_salida` (`HH:MM:SS`) y `fecha_llegada`.
120
+ Si el traslado lo hace un courier y no conoces la patente, el remolque ni el
121
+ chofer, declara `sin_datos_transporte=True` con el RUT del courier: la API
122
+ exime esos cinco datos y el XML lleva la declaracion expresa que exige el SII.
123
+
124
+ ```python
125
+ import uuid
126
+ from folyo import Folyo, DTERequest, Receptor, DetalleLinea, Transporte
127
+
128
+ with Folyo(api_key="<tu-api-key>") as folyo:
129
+ reglas = folyo.dte.reglas()
130
+ print(reglas.transporte.obligatorio, reglas.transporte.obligatorio_desde)
131
+
132
+ req = DTERequest(
133
+ tipo_dte=52, # Guia de Despacho
134
+ ind_traslado=1, # operacion constituye venta
135
+ tipo_despacho=2, # por cuenta del emisor, a instalaciones del cliente
136
+ receptor=Receptor(rut="12.345.678-9", razon_social="Cliente SpA", giro="Comercio"),
137
+ detalle=[DetalleLinea(nombre="Repuestos", cantidad=4, precio=25000, monto=100000)],
138
+ transporte=Transporte(
139
+ sin_datos_transporte=True, # no se conoce patente, remolque ni chofer
140
+ rut_transportista="76.543.210-3", # RUT del courier: siempre se conoce
141
+ dir_destino="Av. Siempre Viva 742",
142
+ cmna_destino="Providencia",
143
+ fecha_salida="2026-11-02",
144
+ hora_salida="08:30:00",
145
+ fecha_llegada="2026-11-03",
146
+ ),
147
+ )
148
+ job = folyo.dte.emitir_y_esperar(req, idempotency_key=str(uuid.uuid4()))
149
+
150
+ # Avisos no bloqueantes, estructurados (tambien en encolada.advertencias_detalle).
151
+ if job.result is not None:
152
+ for aviso in job.result.advertencias_detalle:
153
+ print(aviso.codigo, aviso.campos, aviso.mensaje)
154
+ ```
155
+
156
+ Antes de la fecha efectiva, los campos que falten llegan como advertencia
157
+ `TRANSPORTE_INCOMPLETO` en `advertencias_detalle` y la guia se emite igual;
158
+ despues, la API responde 400 `TRANSPORTE_INCOMPLETO` (`FolyoValidationError`
159
+ con un `field_errors` por campo, por ejemplo `transporte.patente`). Con el flag
160
+ y sin `rut_transportista` la emision sigue con `TRANSPORTISTA_NO_INFORMADO`. Las
161
+ facturas 33 y 34 aceptan el mismo bloque de forma opcional; en 46, 56 y 61 la
162
+ API responde `TRANSPORTE_NO_SOPORTADO`.
163
+
107
164
  ## Impuestos adicionales y retenciones por linea
108
165
 
109
166
  Una linea puede llevar `impuestos` con el codigo del impuesto adicional del
@@ -231,6 +288,7 @@ for doc in folyo.dte.listar_documentos(limite=1):
231
288
  from folyo import (
232
289
  Folyo,
233
290
  FolyoAuthError,
291
+ FolyoConflictError,
234
292
  FolyoQuotaError,
235
293
  FolyoRateLimitError,
236
294
  FolyoValidationError,
@@ -249,8 +307,12 @@ except FolyoValidationError as e:
249
307
  print("Datos invalidos:", e.message)
250
308
  for field in e.field_errors:
251
309
  print(field.field, field.message, field.max, field.actual)
310
+ except FolyoConflictError as e:
311
+ # Rechazo del portal de timbraje al solicitar folios (FOLIOS_RECHAZADOS_SII,
312
+ # FOLIOS_BOLETA_SISTEMA_SII, TIMBRAJE_NO_AUTORIZADO): e.message trae el motivo del SII.
313
+ print("El SII rechazo la solicitud de folios:", e.code, e.message)
252
314
  except FolyoSiiUnavailableError:
253
- print("El SII no esta disponible, reintenta mas tarde")
315
+ print("El SII no esta disponible, reintenta mas tarde") # o PDF_BUSY
254
316
  ```
255
317
 
256
318
  Para límites de DTE, `FolyoValidationError.field_errors` es una tupla de
@@ -260,7 +322,16 @@ la request.
260
322
 
261
323
  El SDK reintenta automaticamente (con backoff exponencial y respetando
262
324
  `Retry-After`) ante `429` y `503` en operaciones seguras: peticiones `GET` y
263
- emisiones con `Idempotency-Key`.
325
+ emisiones con `Idempotency-Key`. Las descargas (`descargar_pdf`, `descargar_xml`)
326
+ entran en esa regla, incluido el `503 PDF_BUSY`.
327
+
328
+ ### Limite de descargas
329
+
330
+ `GET /v1/dte/pdf`, `GET /v1/dte/xml` y `POST .../regenerate` comparten un limite
331
+ propio de **20 peticiones por ventana de 4 segundos por cuenta**, ademas del
332
+ limite general de 50 por segundo. Guarda el archivo cuando lo descargues; no
333
+ vuelvas a pedirlo en cada vista ni recorras todo tu historial en bucle. El `429`
334
+ llega como `FolyoRateLimitError` con `retry_after`.
264
335
 
265
336
  ## Recursos disponibles
266
337
 
@@ -38,6 +38,7 @@ from .models import (
38
38
  IMPUESTOS_ADICIONALES,
39
39
  IMPUESTOS_DTE,
40
40
  AcuseRequest,
41
+ AdvertenciaDTE,
41
42
  ApiKey,
42
43
  ApiKeyCreated,
43
44
  AuthTokens,
@@ -63,6 +64,8 @@ from .models import (
63
64
  RebajaBaseImponible,
64
65
  Receptor,
65
66
  Referencia,
67
+ ReglasDTE,
68
+ ReglasTransporte,
66
69
  Transporte,
67
70
  Webhook,
68
71
  WebhookCreated,
@@ -98,6 +101,9 @@ __all__ = [
98
101
  "RebajaBaseImponible",
99
102
  "Referencia",
100
103
  "Transporte",
104
+ "AdvertenciaDTE",
105
+ "ReglasDTE",
106
+ "ReglasTransporte",
101
107
  "EmisionEncolada",
102
108
  "ImpuestoTotal",
103
109
  "EmisionResult",
@@ -39,7 +39,7 @@ from .resources import (
39
39
  WebhooksResource,
40
40
  )
41
41
 
42
- __version__ = "0.2.2"
42
+ __version__ = "0.3.1"
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__(
@@ -28,6 +28,7 @@ __all__ = [
28
28
  "Referencia",
29
29
  "Transporte",
30
30
  "DTERequest",
31
+ "AdvertenciaDTE",
31
32
  "EmisionEncolada",
32
33
  "ImpuestoTotal",
33
34
  "EmisionResult",
@@ -47,6 +48,8 @@ __all__ = [
47
48
  "ApiKeyCreated",
48
49
  "AcuseRequest",
49
50
  "AuthTokens",
51
+ "ReglasTransporte",
52
+ "ReglasDTE",
50
53
  ]
51
54
 
52
55
  _T = TypeVar("_T", bound="_FromDict")
@@ -353,9 +356,32 @@ class Referencia:
353
356
 
354
357
 
355
358
  @dataclass
356
- class Transporte:
357
- """Datos de despacho para Guia de Despacho (tipo 52)."""
359
+ class Transporte(_FromDict):
360
+ """Datos del traslado: Guia de Despacho (52) y, como bloque opcional, las
361
+ facturas 33 y 34 que amparan traslado de bienes.
362
+
363
+ Desde la activacion de la Res. Ex. SII 154/2025 (fecha efectiva en
364
+ ``Folyo.dte.reglas()``, por defecto 2026-11-01 hora de Chile) toda guia 52
365
+ exige ``tipo_despacho`` y ``rut_transportista``, ``patente``, ``rut_chofer``,
366
+ ``nombre_chofer``, ``dir_destino``, ``cmna_destino``, ``fecha_salida``,
367
+ ``hora_salida`` y ``fecha_llegada``; ``patente_remolque`` y
368
+ ``ciudad_destino`` son opcionales siempre. Antes de esa fecha los
369
+ faltantes llegan como advertencia ``TRANSPORTE_INCOMPLETO`` en
370
+ ``advertencias_detalle``; despues la API responde 400 con el mismo codigo.
371
+
372
+ ``sin_datos_transporte=True`` declara que al emitir no se cuenta con los
373
+ datos del vehiculo ni del chofer (despacho por courier): exime exactamente
374
+ ``patente``, ``patente_remolque``, ``rut_transportista``, ``rut_chofer`` y
375
+ ``nombre_chofer``, y el XML lleva la declaracion expresa que exige el SII en
376
+ la descripcion de la primera linea. Informe ``rut_transportista`` con el
377
+ RUT del courier; si falta, la emision sigue con la advertencia
378
+ ``TRANSPORTISTA_NO_INFORMADO``. Lo que venga informado se emite igual.
379
+
380
+ ``from_dict`` permite reconstruir el bloque que devuelve el servidor (por
381
+ ejemplo en el ``request`` de un borrador de factura de guias).
382
+ """
358
383
 
384
+ sin_datos_transporte: Optional[bool] = None
359
385
  patente: Optional[str] = None
360
386
  patente_remolque: Optional[str] = None # patente del remolque/acoplado
361
387
  rut_transportista: Optional[str] = None
@@ -371,6 +397,7 @@ class Transporte:
371
397
  def to_dict(self) -> Dict[str, Any]:
372
398
  return _drop_none(
373
399
  {
400
+ "sin_datos_transporte": self.sin_datos_transporte,
374
401
  "patente": self.patente,
375
402
  "patente_remolque": self.patente_remolque,
376
403
  "rut_transportista": self.rut_transportista,
@@ -464,6 +491,42 @@ class DTERequest:
464
491
  # ---------------------------------------------------------------------------
465
492
 
466
493
 
494
+ @dataclass
495
+ class AdvertenciaDTE(_FromDict):
496
+ """Aviso no bloqueante de la validacion local de un DTE, estructurado.
497
+
498
+ Viaja en ``advertencias_detalle`` del 202 de ``POST /v1/dte/emitir``, del
499
+ resultado del job y de cada documento del lote, en el mismo orden que la
500
+ lista de textos ``advertencias``. ``campos`` usa las rutas JSON publicas
501
+ (``tipo_despacho``, ``transporte.patente``) y nunca trae los valores.
502
+
503
+ Codigos: ``TRANSPORTE_INCOMPLETO`` (faltan campos que la Res. Ex. SII
504
+ 154/2025 exige en la guia 52; antes de la activacion es aviso, despues es
505
+ 400), ``TRANSPORTISTA_NO_INFORMADO`` (``sin_datos_transporte`` sin
506
+ ``rut_transportista``) y ``TRASLADO_PROLONGADO`` (llegada posterior a la
507
+ salida sin glosa del traslado en el detalle).
508
+ """
509
+
510
+ codigo: str = ""
511
+ mensaje: str = ""
512
+ campos: List[str] = field(default_factory=list)
513
+
514
+
515
+ def _advertencias_detalle(kwargs: Dict[str, Any]) -> None:
516
+ """Convierte ``advertencias_detalle`` en ``AdvertenciaDTE`` dentro de kwargs.
517
+
518
+ Una clave ausente o ``None`` queda como lista vacia para que el integrador
519
+ pueda iterar sin comprobar.
520
+ """
521
+ detalle = kwargs.get("advertencias_detalle")
522
+ if isinstance(detalle, list):
523
+ kwargs["advertencias_detalle"] = [
524
+ AdvertenciaDTE.from_dict(a) if isinstance(a, dict) else a for a in detalle
525
+ ]
526
+ else:
527
+ kwargs.pop("advertencias_detalle", None)
528
+
529
+
467
530
  @dataclass
468
531
  class EmisionEncolada(_FromDict):
469
532
  """Respuesta de ``POST /v1/dte/emitir`` (202, o 200 si idempotente completed)."""
@@ -474,6 +537,18 @@ class EmisionEncolada(_FromDict):
474
537
  estado: Optional[str] = None # pending | completed
475
538
  mensaje: Optional[str] = None
476
539
  advertencias: List[str] = field(default_factory=list)
540
+ #: Los mismos avisos que ``advertencias``, estructurados (codigo, campos,
541
+ #: mensaje). Vacio cuando no hay.
542
+ advertencias_detalle: List[AdvertenciaDTE] = field(default_factory=list)
543
+
544
+ @classmethod
545
+ def from_dict(cls, data: Dict[str, Any]) -> "EmisionEncolada":
546
+ known = {f.name for f in fields(cls)}
547
+ kwargs = {k: v for k, v in data.items() if k in known}
548
+ if kwargs.get("advertencias") is None:
549
+ kwargs.pop("advertencias", None)
550
+ _advertencias_detalle(kwargs)
551
+ return cls(**kwargs)
477
552
 
478
553
 
479
554
  @dataclass
@@ -519,12 +594,20 @@ class EmisionResult(_FromDict):
519
594
  monto_total: Optional[int] = None
520
595
  fecha_emision: Optional[str] = None
521
596
  xml_firmado: Optional[str] = None
597
+ #: Elemento ``<TED>`` (timbre electronico) tal como va dentro de
598
+ #: ``xml_firmado``, para dibujar el PDF417 al imprimir por cuenta propia.
599
+ #: ``None`` en los jobs completados antes de que el servidor lo entregara.
600
+ ted: Optional[str] = None
522
601
  #: Desglose de impuestos adicionales y retenciones (un elemento por
523
602
  #: ``<ImptoReten>``). Vacio en documentos sin impuestos.
524
603
  impuestos: List[ImpuestoTotal] = field(default_factory=list)
525
604
  #: IVA no retenido (``<IVANoRet>``) de una retencion parcial. ``None``
526
605
  #: cuando no aplica (sin retencion o retencion total).
527
606
  iva_no_retenido: Optional[int] = None
607
+ #: Avisos no bloqueantes que ya viajaron en el 202 y se replican en el
608
+ #: resultado del job: texto legible y la misma lista estructurada.
609
+ advertencias: List[str] = field(default_factory=list)
610
+ advertencias_detalle: List[AdvertenciaDTE] = field(default_factory=list)
528
611
 
529
612
  @classmethod
530
613
  def from_dict(cls, data: Dict[str, Any]) -> "EmisionResult":
@@ -537,6 +620,9 @@ class EmisionResult(_FromDict):
537
620
  ]
538
621
  elif impuestos is None:
539
622
  kwargs.pop("impuestos", None)
623
+ if kwargs.get("advertencias") is None:
624
+ kwargs.pop("advertencias", None)
625
+ _advertencias_detalle(kwargs)
540
626
  return cls(**kwargs)
541
627
 
542
628
 
@@ -569,6 +655,38 @@ class EmisionJob(_FromDict):
569
655
  return self.estado in ("completed", "failed")
570
656
 
571
657
 
658
+ @dataclass
659
+ class ReglasTransporte(_FromDict):
660
+ """Obligatoriedad de la informacion de transporte en la guia 52 (Res. Ex.
661
+ SII 154/2025), tal como la publica ``GET /v1/dte/reglas``.
662
+
663
+ ``obligatorio_desde`` es el instante (RFC 3339, hora de Chile) desde el
664
+ cual faltar un campo responde 400 ``TRANSPORTE_INCOMPLETO``; ``obligatorio``
665
+ dice si ya rige. ``flag`` es el nombre del booleano de ``transporte`` que
666
+ exime los datos del vehiculo y del chofer (``sin_datos_transporte``).
667
+ """
668
+
669
+ obligatorio_desde: str = ""
670
+ obligatorio: bool = False
671
+ flag: str = "sin_datos_transporte"
672
+ campos_obligatorios: List[str] = field(default_factory=list)
673
+ campos_eximibles: List[str] = field(default_factory=list)
674
+
675
+
676
+ @dataclass
677
+ class ReglasDTE(_FromDict):
678
+ """Respuesta de ``GET /v1/dte/reglas`` (``Folyo.dte.reglas()``)."""
679
+
680
+ transporte: ReglasTransporte = field(default_factory=ReglasTransporte)
681
+
682
+ @classmethod
683
+ def from_dict(cls, data: Dict[str, Any]) -> "ReglasDTE":
684
+ transporte = data.get("transporte")
685
+ if isinstance(transporte, dict):
686
+ return cls(transporte=ReglasTransporte.from_dict(transporte))
687
+ return cls()
688
+
689
+
572
690
  @dataclass
573
691
  class Documento(_FromDict):
574
692
  """Item de la lista de documentos emitidos (``GET /v1/documentos``)."""
@@ -28,6 +28,7 @@ from .models import (
28
28
  FacturarGuiasRequest,
29
29
  FoliosInfo,
30
30
  GuiaEmitida,
31
+ ReglasDTE,
31
32
  Webhook,
32
33
  WebhookCreated,
33
34
  )
@@ -79,6 +80,19 @@ class DteResource(_BaseResource):
79
80
  )
80
81
  return EmisionEncolada.from_dict(cast(Dict[str, Any], data))
81
82
 
83
+ def reglas(self) -> ReglasDTE:
84
+ """Reglas de emision con fecha de activacion.
85
+
86
+ Hoy publica la obligatoriedad de la informacion de transporte en la
87
+ guia de despacho (Res. Ex. SII 154/2025): desde cuando rige, si ya
88
+ rige, el flag que exime los datos del vehiculo y del chofer y las
89
+ listas de campos obligatorios y eximibles. No consume cuota.
90
+
91
+ ``operationId: reglasDte`` -> ``GET /v1/dte/reglas``.
92
+ """
93
+ data = self._c._request("GET", "/v1/dte/reglas")
94
+ return ReglasDTE.from_dict(cast(Dict[str, Any], data))
95
+
82
96
  def get_emision(self, job_id: str) -> EmisionJob:
83
97
  """Consulta el estado de un job de emision (polling).
84
98
 
@@ -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.1"
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