SIFEN — Facturación electrónica Paraguay (DNIT / e-Kuatia)

Descripción

Los nodos SIFEN conectan tus workflows con el sistema de facturación electrónica de Paraguay (SIFEN / e-Kuatia, de la DNIT), mediante integración directa a los Web Services oficiales: no dependés de un proveedor intermediario ni pagás por documento. Floogos arma el XML del Documento Electrónico (DE), calcula su CDC, lo firma digitalmente con tu certificado, lo envía por SOAP con TLS mutuo y genera el KuDE (representación gráfica con QR).

Nodo	Servicio SIFEN	Qué hace
SIFEN: Emitir factura electrónica (`sifenEmitirDE`)	`siRecepDE`	Emite un DE de forma síncrona (factura, NC, ND, remisión, autofactura)
SIFEN: Enviar lote de DE (`sifenEnviarLote`)	`siRecepLoteDE`	Envía hasta 50 DE de una vez (asíncrono)
SIFEN: Consultar lote (`sifenConsultarLote`)	`siResultLoteDE`	Trae el resultado de un lote y reconcilia cada DE
SIFEN: Consultar DE por CDC (`sifenConsultarDE`)	`siConsDE`	Verifica el estado de un DE
SIFEN: Consultar RUC (`sifenConsultarRUC`)	`siConsRUC`	Valida un RUC en el padrón de la DNIT
SIFEN: Cancelar DE (`sifenCancelarDE`)	`siRecepEvento`	Cancela un DE aprobado (evento firmado)
SIFEN: Generar KuDE (PDF/QR) (`sifenKuDE`)	—	Genera la representación gráfica imprimible con QR

Credencial

Los nodos usan una credencial de tipo SIFEN. Creala en Credenciales → Agregar → SIFEN con estos campos:

Campo	Descripción
Certificado (.p12)	Tu certificado digital de firma, en base64. Es el que emite un prestador habilitado por la DNIT.
Contraseña del certificado	La clave del archivo `.p12`. Nunca se muestra en logs.
RUC y DV	El RUC del emisor (sin dígito verificador) y su DV.
Ambiente	`test` (pruebas) o `prod` (producción).
ID CSC y CSC	El Código de Seguridad del Contribuyente y su identificador — necesarios para el hash del QR del KuDE.
Establecimiento y Punto de expedición	Los códigos por defecto del emisor (se pueden sobrescribir por documento).

El mismo certificado se usa para firmar el DE y para autenticarse ante SIFEN por TLS mutuo. Si el certificado está vencido, los nodos de emisión cortan con un mensaje claro.

El flujo completo

Preparás el DE como un objeto JSON (emisor, receptor, operación e ítems). El emisor, el establecimiento y el punto de expedición se completan desde la credencial si no los ponés.
Emitís con Emitir factura electrónica (síncrono) o Enviar lote (varios de una). Floogos calcula el CDC, firma el XML y lo envía.
SIFEN responde con Aprobado o Rechazado. En el lote, consultás el resultado después con Consultar lote.
Generás el KuDE con Generar KuDE para entregar/imprimir el comprobante con su QR.
Si hace falta, cancelás el DE con Cancelar DE dentro del plazo que fija la DNIT.

Emitir un DE

Nodo: SIFEN: Emitir factura electrónica. El documento se toma del campo de (JSON) o de los datos de entrada. Ejemplo de una factura de contado:

{
  "tipoDE": 1,
  "timbrado": "12558946",
  "fechaEmision": "2026-07-29T10:00:00",
  "numero": "0000123",
  "receptor": { "naturaleza": 2, "tipoOperacion": 2, "nombre": "Consumidor Final" },
  "operacion": { "condicionVenta": 1, "moneda": "PYG", "indicadorPresencia": 1 },
  "items": [
    { "codigo": "P1", "descripcion": "Perfume 100ml", "cantidad": 1, "precioUnitario": 110000, "afectacionIVA": 1, "tasaIVA": 10 }
  ]
}

Salida (aprobado):

{
  "cdc": "0180012345600100100001232202607291071136690X",
  "estado": "Aprobado",
  "protocolo": "998877",
  "codigo": "0300"
}

Tipos de documento (`tipoDE`)

`tipoDE`	Documento	Requisitos extra
1	Factura electrónica	—
4	Autofactura electrónica	`vendedor` (datos del vendedor no contribuyente)
5	Nota de crédito	`documentoAsociado` (CDC de la factura original) + `motivoEmision`
6	Nota de débito	igual que la NC
7	Nota de remisión	`transporte` + `motivoRemision` (no lleva importes)

Envío en lote

Para volúmenes altos, Enviar lote de DE firma cada documento, los comprime y los manda juntos (hasta 50). SIFEN responde de inmediato con un protocolo (dProtConsLote); el resultado real de cada DE se obtiene después con Consultar lote, que además reconcilia el estado de cada uno en la base.

{ "documentos": [ { "numero": "0000124", "items": [ /* ... */ ] }, { "numero": "0000125", "items": [ /* ... */ ] } ] }

Consultas

Consultar DE por CDC (sifenConsultarDE): verifica el estado de un documento; útil para reconciliar tras un timeout.
Consultar RUC (sifenConsultarRUC): trae razón social y estado de un RUC en el padrón — ideal para validar el receptor antes de emitir.

Cancelar un DE

Cancelar DE emite un evento firmado de cancelación. Requiere el CDC y un motivo (5 a 500 caracteres), y sólo es válido dentro del plazo que fija la DNIT tras la aprobación.

cdc:    0180012345600100100001232202607291071136690X
motivo: Error en el monto facturado

KuDE (representación gráfica)

Generar KuDE produce el comprobante imprimible en HTML (que el navegador puede exportar a PDF), con el código QR de consulta pública. Podés pasarle el CDC de un DE ya emitido (recupera el XML firmado de la base) o un DE en JSON para previsualizar. El QR incluye el cHashQR, un hash calculado con tu CSC; sin el CSC correcto el QR no valida.

Manejo de errores

Situación	Reintentable	Qué hacer
Rechazo de SIFEN (código en la respuesta)	No	El nodo devuelve el código y el mensaje de SIFEN. Corregí el documento.
Certificado vencido	No	Renová el `.p12` y actualizá la credencial.
Datos inválidos (falta ítem, CDC/motivo mal)	No	El nodo valida antes de enviar y explica qué falta.
Red / Timeout	Sí	Problema pasajero; se reintenta automáticamente.

Ver también

Cola de reintentos (DLQ) — cómo se reintentan las ejecuciones que fallan.
Nodo HTTP — para servicios de SIFEN no cubiertos por estos nodos.