Skip to main content

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.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for smartdocpy 0.3.0
File Size Uploaded Provenance Actions
smartdocpy-0.3.0.tar.gz 96.0 MB Without provenance Details for smartdocpy-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for smartdocpy 0.3.0
File Interpreter ABI Platform Actions
smartdocpy-0.3.0-py3-none-any.whl Python 3 none any Details for smartdocpy-0.3.0-py3-none-any.whl

Total release size: 96.1 MB

Release files / smartdocpy-0.3.0.tar.gz

Download URL smartdocpy-0.3.0.tar.gz
Size 96.0 MB
Tags Source
SHA-256 checksum
How to use checksums
31203eb98b3b9c47d4e2d39695479cdcd50eea850fd316310815e57f6add4cf8
BLAKE2b-256 checksum
How to use checksums
99449b84d8c2693265bdc2869f153b71542ff9eb68e9bf5485cbf14ad6519ec2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.14

Release files / smartdocpy-0.3.0-py3-none-any.whl

Download URL smartdocpy-0.3.0-py3-none-any.whl
Size 154.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
58615cb2a5cfb7577c74681554f70e24e6deb5fa031ed765ad3a10f26e52ac68
BLAKE2b-256 checksum
How to use checksums
750cce5d41d22e5e279dca48c4a012de248866a835a506d3186d31aeb7273fc0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.14

Security for smartdocpy 0.3.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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page