smartdoc
SDK de Python para SmartDoc, el sistema de facturación electrónica para Paraguay. Cubre la API pública v2 y la recepción de sus webhooks.
Instalación
pip install smartdocpy
El paquete se instala como smartdocpy y se importa como smartdoc.
Requiere Python 3.10 o superior. La única dependencia es httpx.
Emitir un documento
import smartdoc
sd = smartdoc.Client() # toma la API Key del entorno
factura = sd.invoices.create(
recipient=smartdoc.Recipient.entity(
ruc="80012345-1",
social_name="Cliente Ejemplo S.A.",
email="facturas@cliente.com.py",
),
items=[
smartdoc.Item("Consultoría de octubre", quantity=1, unit_amount=1100000),
],
)
factura = sd.invoices.wait_until_final(factura.id)
print(factura.status, factura.cdc)
El SDK completa los datos del emisor, la clave de idempotencia y el desglose de IVA. En Paraguay el IVA va incluido en el precio: sobre ese ejemplo emite 1.000.000 de base gravada y 100.000 de IVA.
Están los seis tipos de documento electrónico, cada uno con sus acciones:
| Recurso | Documento |
|---|---|
sd.invoices |
Factura |
sd.receipts |
Recibo |
sd.credit_notes |
Nota de crédito |
sd.debit_notes |
Nota de débito |
sd.remission_notes |
Nota de remisión |
sd.auto_invoices |
Autofactura |
Hay un cliente asíncrono con la misma superficie:
sd = smartdoc.AsyncClient()
factura = await sd.invoices.create(recipient=..., items=[...])
Configuración
La API Key sale de SMARTDOC_API_KEY. La URL apunta a la instancia de
producción; solo hace falta SMARTDOC_BASE_URL con una instancia propia.
export SMARTDOC_API_KEY="pk_..."
Con más de un establecimiento o punto de expedición hay que decir cuál, porque el SDK no elige por su cuenta:
sd = smartdoc.Client(establishment="001", dispatch_point="001")
o por llamada, si emitís desde varias sucursales:
sd.invoices.create(..., establishment="002", dispatch_point="001")
Idempotencia
Cada create() va con una clave nueva que genera el SDK, así que reintentar
nunca emite dos veces. Si preferís que la clave venga de tu sistema:
factura = sd.invoices.create(..., idempotency_key=f"venta-{venta.id}")
Repetir la llamada con la misma clave devuelve el documento ya creado.
Errores
try:
sd.invoices.create(recipient=..., items=[...])
except smartdoc.ValidationError as e:
... # datos mal armados; no sirve reintentar
except (smartdoc.RateLimitError, smartdoc.ServerError) as e:
... # transitorio; el SDK ya reintentó
Todos heredan de SmartDocError. Las validaciones que el SDK puede hacer sin red
—largos, catálogos cerrados, campos condicionales— fallan antes de salir, con el
mensaje de qué corregir.
Webhooks
En producción conviene escuchar los eventos en vez de hacer polling.
webhooks = smartdoc.Webhooks(secret=os.environ["SMARTDOC_WEBHOOK_SECRET"])
@webhooks.on("invoice.approved")
def factura_aprobada(evento):
marcar_aprobada(evento.entity_id, evento.cdc)
@webhooks.on_any_error()
def algo_falló(evento):
avisar(f"{evento.event_type}: {evento.error_code} {evento.error_message}")
El SDK verifica la firma HMAC, descarta las entregas repetidas y trae adaptadores
para los tres frameworks —webhooks.fastapi_route(), webhooks.flask_view(),
webhooks.django_view()— más un webhooks.serve() para desarrollo. No hace falta
tener ninguno de los tres instalado.
Para identificar el documento va el par (entity_type, entity_id), porque el id
se numera por tipo: el recibo 20 y la nota de débito 20 existen a la vez.
entidad, numero = evento.document_key # ("receipt", 20)
Catálogos
Los catálogos de SIFEN, centralizados y con validación local.
import smartdoc
smartdoc.Iva.TEN # "10_percent", etiqueta "10%"
smartdoc.SaleType.CASH # "cash"
smartdoc.MeasureUnit.UNIT # 77
smartdoc.TransactionType.SERVICES # 2
smartdoc.Iva.TEN.rate # 0.10
smartdoc.SaleType.labels() # {"cash": "Contado", "credit": "Crédito"}
Los catálogos numéricos de SIFEN son abiertos: aceptan cualquier código del catálogo oficial de la DNIT aunque el SDK no lo liste, así que un código nuevo no obliga a esperar una versión del paquete.
smartdoc.TransactionType.coerce(99) # pasa
Los catálogos propios de SmartDoc son cerrados, y un valor inválido falla antes de salir a la red, con las opciones disponibles:
smartdoc.SaleType.coerce("Contado")
# ValidationError: 'Contado' no es un valor válido de SaleType.
# ¿Quisiste decir 'cash'? Valores válidos: 'cash', 'credit'.
Geografía
Todo documento cuyo receptor lleve dirección necesita seis campos —departamento, distrito y ciudad, cada uno con su código y su descripción—. El SDK embebe el catálogo, así que una búsqueda por nombre los resuelve.
ciudad = smartdoc.geo.find_city("Asunción")
ciudad.code # 1
ciudad.district.name # "ASUNCION (DISTRITO)"
ciudad.department.name # "CAPITAL"
Cuando el nombre es ambiguo no se elige uno: la ciudad queda impresa en el documento, así que el SDK lista las opciones y pide desempatar.
smartdoc.geo.find_city("Concepción")
# ValidationError: 'Concepción' es ambiguo: hay 3 ciudades con ese nombre...
smartdoc.geo.find_city("Concepción", department="Misiones") # listo
Estados
Los seis tipos de documento comparten el mismo vocabulario de estados, pero no todos alcanzan los mismos.
smartdoc.is_terminal("recoverable_error") # False
smartdoc.is_terminal("generated", smartdoc.DocumentType.RECEIPT) # True
smartdoc.is_terminal("generated", smartdoc.DocumentType.INVOICE) # False
El recibo no se envía a la DNIT, así que nunca llega a approved_by_set: su
estado final de éxito es generated, que para los demás documentos es un paso
intermedio.
Emitir es asíncrono: create() vuelve enseguida y la aprobación llega después.
wait_until_final consulta hasta que el documento llegue a un estado final, con
un plazo holgado por omisión porque cada salto lo da una pasada del planificador
del servidor. Las acciones —cancel, resend_email, resend_to_set,
nominate— tampoco devuelven el documento, porque la API responde
identificadores: hay que releerlo.
Documentación
La documentación completa está en docs/: primeros pasos, un tutorial
de integración de punta a punta, la guía de cada tipo de documento, webhooks,
manejo de errores y la referencia de la API.
pip install -e ".[docs]"
mkdocs serve
Desarrollo
pip install -e ".[dev]"
pytest
Licencia
MIT
Metadata
Release files for smartdocpy 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| smartdocpy-0.2.0.tar.gz | 65.8 MB | Without provenance | Details for smartdocpy-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| smartdocpy-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for smartdocpy-0.2.0-py3-none-any.whl |
Total release size: 65.9 MB
Release files / smartdocpy-0.2.0.tar.gz
| Download URL | smartdocpy-0.2.0.tar.gz |
|---|---|
| Size | 65.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
822652042f1d2ab7e96d4c182874cb251ea18b73994b622af3ef60e61100c6fa
|
|
BLAKE2b-256 checksum How to use checksums |
5cd750fe8adf3d4a1199e85c71f8f0c888b77e84c6229d582ef7193e2f7c15bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Release files / smartdocpy-0.2.0-py3-none-any.whl
| Download URL | smartdocpy-0.2.0-py3-none-any.whl |
|---|---|
| Size | 154.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5a8130bd52fa1b804101605e36b6c9575e2a9cc8110f3936a819e61fed76ce40
|
|
BLAKE2b-256 checksum How to use checksums |
5c29805a837708ae0c66e155b4fbafba3945ce30b0c811ee2ddb555f1f0f5b08
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Security for smartdocpy 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.