SDK Python

SDK async-first para Python. Usa async/await para todas las operaciones, con manejo de errores detallado y métodos de conveniencia para todas las operaciones de la API.

PyPI: ecf-dgiiGitHub

Instalación

python
pip install ecf-dgii

Uso rápido

python
from ecf_dgii import EcfClient


async with EcfClient(
  base_url="https://api.test.ecfx.ssd.com.do",
  api_key="tu-api-key"  # o usa la variable ECF_API_KEY
) as client:
  result = await client.send_ecf("rnc-empresa", ecf_data)


  print(result.impresion_url)  # URL del QR
  print(result.cod_sec)        # Código de seguridad
  print(result.fecha_firma)    # Fecha de firma

Opciones de Polling

python
from ecf_dgii import EcfClient, PollingOptions


async with EcfClient(base_url="...", api_key="...") as client:
  result = await client.send_ecf(
      "rnc",
      ecf_data,
      polling=PollingOptions(
          initial_delay=1.0,       # Delay inicial en segundos
          max_delay=10.0,          # Delay máximo en segundos
          max_retries=20,          # Intentos máximos
          backoff_multiplier=1.5,  # Multiplicador de backoff
          timeout=120.0            # Timeout total en segundos
      )
  )

Manejo de errores

El SDK provee excepciones específicas para cada tipo de error:

python
from ecf_dgii import (
  EcfApiError,
  EcfValidationError,
  EcfAuthenticationError,
  EcfProcessingError,
  PollingTimeoutError
)


try:
  result = await client.send_ecf("rnc", ecf_data)
except EcfValidationError as e:
  print(f"Error de validación: {e.details}")
except EcfAuthenticationError:
  print("Token inválido o expirado")
except PollingTimeoutError:
  print("El polling excedió el tiempo máximo")
except EcfApiError as e:
  print(f"Error de API: {e.status_code} - {e.message}")

Cliente Frontend

python
from ecf_dgii import create_frontend_client


frontend = create_frontend_client(
  base_url="https://api.prod.ecfx.ssd.com.do",
  get_token=my_token_provider  # función async que retorna el token
)


# Consultar estado (solo lectura)
status = await frontend.get_ecf_status("track-id")

Métodos de conveniencia

El SDK incluye métodos para: gestión de compañías, certificados, consultas ECF, aprobación comercial, anulación de rangos y consultas DGII.