Sifende CLI

Sifende CLI es un cliente de línea de comandos que envuelve la API REST de Sifende. Sirve para ejecutar los flujos típicos (emitir, consultar estado, descargar KuDE, cancelar e inutilizar) contra https://api.sifende.com.py/api/v1/ sin escribir código.

Va bien para probar tu API key, validar payloads, reproducir bugs y armar scripts puntuales. Solo depende de la stdlib de Python y de requests.

Requisitos

• Python 3.9 o superior
• make (opcional; todo se puede correr con python directo)
• Una API key de Sifende. Si no tenés una, seguí Paso 1: Credenciales

Instalación

Cloná el repositorio y entrá al directorio del CLI:

git clone https://github.com/ithdev/sifende-cli.git
cd sifende-cli

El repo trae un sample_factura.json listo para emitir, así que podés probar todo antes de armar tu propio payload.

Quickstart en 3 comandos

make setup                       # crea venv, instala deps, copia .env.example a .env
nano .env                        # o tu editor preferido; poné tu SIFENDE_API_KEY
make emitir FILE=sample_factura.json

make setup crea un entorno virtual en .venv/, instala las dependencias y copia .env.example a .env si todavía no existe. Después abrís .env y pegás tu SIFENDE_API_KEY.

Si todo salió bien, vas a ver el cdc impreso en consola y un directorio documentos/{cdc}/ con payload.json, response.json y, una vez aprobado, kude.pdf.

Sin Make

python3 -m venv .venv
source .venv/bin/activate        # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env             # editá .env con tu API key
python sifende.py emitir --file sample_factura.json

Configuración

La CLI busca tu API key en este orden (gana el primero que la encuentre):

1. Flag --api-key en la línea de comandos
2. Variable de entorno SIFENDE_API_KEY
3. Archivo .env en el directorio actual
4. Archivo .env en la raíz del paquete CLI

Variables soportadas en .env

Cambiá SIFENDE_BASE_URL solo si te diéramos un ambiente alternativo. Para QA y producción usá el valor por defecto.

Comandos

Cada operación está disponible en dos formas: con make (más corto, ideal para uso interactivo) o con python sifende.py (más explícito, ideal para scripts).

Flags globales

Estos flags funcionan en todos los comandos:

Con make se reenvían como EXTRA="...":

make emitir FILE=factura.json EXTRA="--json --quiet"

Comportamiento al aprobar

Al confirmarse la aprobación de un documento, la CLI guarda automáticamente:

documentos/
└── {cdc}/
    ├── payload.json    # request enviado
    ├── response.json   # respuesta de la API
    └── kude.pdf        # KuDE descargado

Esto te da un audit trail local para cada emisión sin trabajo extra.

Ejemplo: emitir y descargar el KuDE

# 1. Emitir desde el archivo de muestra
make emitir FILE=sample_factura.json

# Salida:
# CDC: 01800123451001001000000122026050910000000001
# Estado: PENDIENTE → APROBADO

# 2. Consultar estado por CDC
make estado CDC=01800123451001001000000122026050910000000001

# 3. Descargar el KuDE PDF
make kude CDC=01800123451001001000000122026050910000000001 OUT=factura.pdf

Ejemplo: cancelar un documento aprobado

make cancelar \
  CDC=01800123451001001000000122026050910000000001 \
  MOTIVO="Error en datos del receptor"

Recordá que cancelar tiene 48 horas de plazo desde la emisión. Pasado ese tiempo, tenés que emitir una Nota de Crédito.

Ejemplo: inutilizar un rango de numeración

Si saltaste números (por ejemplo, una falla puntual te dejó huecos del 5 al 8), inutilizalos antes de seguir emitiendo:

make inutilizar \
  TIPO=1 \
  EST=001 \
  PE=001 \
  TIMBRADO=12345678 \
  DESDE=5 \
  HASTA=8 \
  MOTIVO="Salto de numeración por incidente"

Para entender cuándo y cómo usar este flujo, revisá Inutilizar Numeración.

Estructura del payload

El archivo JSON que pasás a emitir --file es exactamente el mismo cuerpo que envía la API REST. El repositorio incluye sample_factura.json con un caso B2C completo. Para armar otros tipos de documento, ver:

• Modelos: Factura Electrónica
• Endpoint: Emitir

Solución de problemas

Para errores de SIFEN (códigos 1xxx, 2xxx, 3xxx), revisá Rechazos SIFEN.

Recursos

• Repositorio: github.com/ithdev/sifende-cli (código fuente, ejemplos y CHANGELOG.md)
• Issues: reportá bugs o pedí mejoras
• Referencia API: Documentos Electrónicos
• Inicio Rápido: Paso 2: Tu Primera Factura