Saltar a contenido

SDK de Python para SmartDoc

Cliente de Python para SmartDoc, el sistema de facturación electrónica para Paraguay. Cubre su API pública v2 y la recepción de sus webhooks.

import smartdoc

sd = smartdoc.Client(api_key="pk_...")

factura = sd.invoices.create(
    recipient=smartdoc.Recipient.entity(ruc="80012345-1", social_name="Cliente S.A."),
    items=[smartdoc.Item("Consultoría", quantity=1, unit_amount=1100000)],
)

factura = sd.invoices.wait_until_final(factura.id)
print(factura.status, factura.cdc)

Eso alcanza para emitir una factura. Los datos del emisor, el timbrado, el establecimiento, el punto de expedición, la clave de idempotencia, el monto total y el desglose de IVA los completa el SDK.

Qué incluye

  • Los seis tipos de documento electrónico —factura, recibo, nota de crédito, nota de débito, nota de remisión y autofactura— con sus acciones: anular, reenviar, confirmar o descartar borradores.
  • Cálculo de totales y desglose de IVA, con Decimal. La API rechaza el documento si el monto no cuadra con los ítems, así que el SDK lo arma.
  • Los catálogos de SIFEN completos, con validación local: un valor inválido falla antes de salir a la red, no después de emitir.
  • El catálogo geográfico de Paraguay embebido —18 departamentos, 270 distritos, 6419 ciudades—, que la API pública no expone. Una búsqueda por nombre resuelve los seis campos que pide un documento con dirección.
  • Recepción de webhooks: verificación de firma, ruteo por tipo de evento y adaptadores para Flask, FastAPI y Django.
  • Cliente asíncrono con la misma superficie que el síncrono.
  • Manejo del límite de tasa, reintentos con backoff, paginación por cursor y claves de idempotencia, sin que haya que pensarlos.

Instalación

pip install smartdocpy

Se instala como smartdocpy y se importa como smartdoc.

Requiere Python 3.10 o superior. La única dependencia es httpx.

Por dónde seguir

  • Primeros pasos — de cero a una factura emitida, con una cuenta demo y sin contratar el servicio.
  • Cómo integrar — las tres piezas que hay que implementar, con el código de cada operación.
  • Adaptar tu sistema — cómo traducir tu modelo de datos y qué revisar antes de producción.
  • Documentos — qué pide cada tipo y qué acciones acepta.
  • Webhooks — recibir eventos y verificar la firma.
  • Catálogos SIFEN — los valores válidos de cada campo.
  • Errores — la jerarquía de excepciones y qué hacer con cada una.