Referencia

Autenticación

Cada request a la API requiere dos campos obligatorios de identificación en el body JSON. No se usan headers de autorización — ambos van dentro del body.

tenant string · 40 chars hex

Es el hash de cliente provisto por el administrador. Permanece fijo para toda la integración.

3a8f2b9d1c4e7f025b6f8d1d9f3a1b4c7d0e5f2a

token string

Identifica al contribuyente emisor. Es el token configurado por empresa en el panel admin.

Si el tenant no se envía o no es reconocido, la API devuelve 401 antes de ejecutar ninguna lógica. Si el token no existe en esa base, devuelve 401 o 400 según el endpoint.

Estructura base de todo request

{
  "tenant": "HASH_40_CHARS_DEL_CLIENTE",
  "token":  "TOKEN_DEL_CONTRIBUYENTE",
  ...resto del body según el endpoint
}

Factura electrónica

Generar factura electrónica

Genera, firma digitalmente y envía a SIFEN una factura electrónica. Retorna el CDC y el código QR para el KuDE. Los totales y cálculos de IVA por ítem son calculados automáticamente — no es necesario enviarlos.

Endpoint

POST https://factura-facil.com.py/api/signDocument

Headers

Header	Valor
Content-Type	application/json

Request body

Campos auto-calculados: no es necesario enviar totalItem, basGravIVA, liqIVAItem ni el objeto totales — la API los calcula desde los ítems.

{
  "tenant": "HASH_40_CHARS_DEL_CLIENTE",
  "token": "TOKEN_DEL_CONTRIBUYENTE",
  "datosDocumento": {
    "tipoDocumento": 1,
    "establecimiento": "001",
    "punto": "001",
    "numero": "0000123",
    "codigoSeguridadAleatorio": "845732198",
    "descripcion": "Factura de venta de productos",
    "observacion": "Gracias por su compra",
    "condicion": 1,
    "fecha": "2026-05-09T09:01:00",
    "tipoEmision": 1,
    "tipoTransaccion": 1,
    "tipoImpuesto": 1,
    "moneda": "PYG",
    "condicionAnticipo": 1,
    "condicionTipoCambio": 1,
    "descuentoGlobal": 0,
    "anticipoGlobal": 0,
    "cambio": 1,

    "cliente": {
      "contribuyente": true,
      "ruc": "80012345-6",
      "razonSocial": "Comercial Demo S.A.",
      "nombreFantasia": "Comercial Demo",
      "tipoOperacion": 1,
      "direccion": "Avda. Mariscal López",
      "numeroCasa": 1200,
      "departamento": 11,
      "departamentoDescripcion": "CENTRAL",
      "distrito": 145,
      "distritoDescripcion": "SAN LORENZO",
      "ciudad": 145,
      "ciudadDescripcion": "SAN LORENZO",
      "pais": "PRY",
      "paisDescripcion": "Paraguay",
      "tipoContribuyente": 1,
      "documentoTipo": 1,
      "documentoNumero": "1234567",
      "telefono": "021555444",
      "celular": "0981123456",
      "email": "cliente@demo.com",
      "codigo": "CLI-001"
    },

    "factura": {
      "presencia": 1
    },

    "items": [
      {
        "codigo": "PRD-001",
        "descripcion": "Servicio de implementación",
        "observacion": "",
        "unidadMedida": 77,
        "unidadMedidaDesc": "UNI",
        "cantidad": 1,
        "precioUnitario": 350000,
        "descuento": 0,
        "descuentoGlobal": 0,
        "anticipo": 0,
        "anticipoGlobal": 0,
        "ivaTipo": 1,
        "ivaBase": 100,
        "iva": 10
      }
    ]
  }
}

Parámetros raíz

Campo	Tipo	Descripción
tenant*	string	Hash de 40 chars que identifica la base de datos del cliente
token*	string	Token del contribuyente emisor dentro de esa base
datosDocumento*	object	Datos del documento a generar

Parámetros — datosDocumento

Campo	Tipo	Descripción
tipoDocumento*	integer	Tipo de documento. Factura = 1
establecimiento*	string	Código del establecimiento. Ej: 001
punto*	string	Punto de expedición. Ej: 001
numero*	string	Número de documento. Ej: 0000123
codigoSeguridadAleatorio*	string	Código de seguridad de 9 dígitos único por documento
condicion*	integer	Condición de pago: 1 = contado, 2 = crédito
fecha*	datetime	Fecha y hora de emisión en formato ISO. Ej: 2026-05-09T09:01:00
moneda*	string	Moneda del documento. Guaraníes = PYG
tipoEmision*	integer	Tipo de emisión. Normal = 1
tipoTransaccion*	integer	Tipo de transacción comercial
tipoImpuesto*	integer	Tipo de impuesto aplicado
totalesauto	object	Calculado automáticamente desde los ítems. No enviar.

Parámetros — items[]

Campo	Tipo	Descripción
codigo*	string	Código interno del producto o servicio
descripcion*	string	Descripción del producto o servicio
unidadMedida*	integer	Código de unidad de medida SIFEN. Unidad = 77
cantidad*	decimal	Cantidad facturada
precioUnitario*	decimal	Precio unitario
iva*	integer	Porcentaje de IVA: 10, 5 o 0
ivaTipo*	integer	Tipo de IVA
ivaBase*	integer	Base del IVA. Normalmente 100
descuentoopc	decimal	Descuento por ítem en valor monetario
totalItemauto	decimal	Calculado: `(cantidad × precioUnitario) − descuentos`
basGravIVAauto	decimal	Calculado: base gravada según tasa de IVA
liqIVAItemauto	decimal	Calculado: monto de IVA del ítem

Respuesta exitosa

{
  "success": true,
  "fecha": "2026-05-09 14:27:59",
  "cdc": "01046029001001001000000512026050915579455768",
  "dCarQR": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=0104...",
  "respuesta_xml": "<ns2:rResEnviLoteDe>...</ns2:rResEnviLoteDe>"
}

Un "success": true con código SIFEN 0300 significa que el lote fue recibido por SIFEN pero aún está en procesamiento. Consultá el CDC para obtener el estado final de aprobación.

Campos de respuesta

Campo	Descripción
success	Indica si el lote fue enviado sin errores
fecha	Fecha y hora local del procesamiento
cdc	Código de Control del Documento (44 dígitos)
dCarQR	URL del QR oficial de SIFEN para el KuDE
respuesta_xml	XML completo de respuesta de SIFEN

Ejemplo cURL

curl --location 'https://factura-facil.com.py/api/signDocument' \
--header 'Content-Type: application/json' \
--data '{
  "tenant": "HASH_40_CHARS_DEL_CLIENTE",
  "token": "TOKEN_DEL_CONTRIBUYENTE",
  "datosDocumento": {
    "tipoDocumento": 1,
    "establecimiento": "001",
    "punto": "001",
    "numero": "0000123",
    "codigoSeguridadAleatorio": "845732198",
    "condicion": 1,
    "fecha": "2026-05-09T09:01:00",
    "tipoEmision": 1,
    "tipoTransaccion": 1,
    "tipoImpuesto": 1,
    "moneda": "PYG",
    "condicionAnticipo": 1,
    "condicionTipoCambio": 1,
    "descuentoGlobal": 0,
    "anticipoGlobal": 0,
    "cambio": 1,
    "cliente": {
      "contribuyente": true,
      "ruc": "80012345-6",
      "razonSocial": "Comercial Demo S.A.",
      "tipoOperacion": 1,
      "direccion": "Avda. Mariscal López",
      "numeroCasa": 1200,
      "departamento": 11,
      "departamentoDescripcion": "CENTRAL",
      "distrito": 145,
      "distritoDescripcion": "SAN LORENZO",
      "ciudad": 145,
      "ciudadDescripcion": "SAN LORENZO",
      "pais": "PRY",
      "paisDescripcion": "Paraguay",
      "tipoContribuyente": 1,
      "documentoTipo": 1,
      "documentoNumero": "1234567"
    },
    "factura": { "presencia": 1 },
    "items": [{
      "codigo": "PRD-001",
      "descripcion": "Servicio de implementación",
      "unidadMedida": 77,
      "cantidad": 1,
      "precioUnitario": 350000,
      "descuento": 0,
      "descuentoGlobal": 0,
      "anticipo": 0,
      "anticipoGlobal": 0,
      "ivaTipo": 1,
      "ivaBase": 100,
      "iva": 10
    }]
  }
}'

Factura electrónica

Consultar estado por CDC

Consulta el estado actual de un documento electrónico directamente en SIFEN usando su CDC. Actualiza el registro interno con el resultado.

Endpoint

POST https://factura-facil.com.py/api/consultarCDC

Request body

{
  "tenant": "HASH_40_CHARS_DEL_CLIENTE",
  "token": "TOKEN_DEL_CONTRIBUYENTE",
  "cdc": "01046029001001001000000512026050915579455768"
}

Campo	Tipo	Descripción
tenant*	string	Hash de 40 chars del cliente
token*	string	Token del contribuyente
cdc*	string	CDC del documento a consultar (44 dígitos numéricos)

Respuesta exitosa (aprobado)

{
  "success": true,
  "cdc": "01046029001001001000000512026050915579455768",
  "fecha": "2026-05-09 14:28:13",
  "codigo": "0422",
  "mensaje": "Consulta realizada con éxito",
  "fechaSifen": "2026-05-09T09:27:59-03:00",
  "estado": "APROBADO",
  "xmlDocumento": "<DE Id=\"0104...\">...</DE>",
  "history_id": 16,
  "registros_actualizados": 1
}

Respuesta — no encontrado

{
  "success": false,
  "cdc": "01046029001001001000000512026050915579455768",
  "fecha": "2026-05-09 14:28:13",
  "codigo": "0420",
  "mensaje": "Documento no existe o no está aprobado",
  "estado": "NO_ENCONTRADO_O_RECHAZADO",
  "history_id": 17,
  "registros_actualizados": 0
}

Códigos de respuesta SIFEN

Código	Estado	Descripción
0422	APROBADO	Documento encontrado y aprobado por SIFEN. Se incluye el XML completo del DE.
0420	NO_ENCONTRADO_O_RECHAZADO	El CDC no existe en SIFEN o fue rechazado.

Ejemplo cURL

curl --location 'https://factura-facil.com.py/api/consultarCDC' \
--header 'Content-Type: application/json' \
--data '{
  "tenant": "HASH_40_CHARS_DEL_CLIENTE",
  "token": "TOKEN_DEL_CONTRIBUYENTE",
  "cdc": "01046029001001001000000512026050915579455768"
}'

Factura electrónica

Anular documento electrónico

Registra el evento de anulación de un documento electrónico ante SIFEN. Aplica tanto para facturas como para notas de crédito. El documento debe estar aprobado y dentro de las primeras 48 horas desde su emisión.

Endpoint

POST https://factura-facil.com.py/api/cancellationElectronicDocument

Request body

{
  "tenant": "HASH_40_CHARS_DEL_CLIENTE",
  "token": "TOKEN_DEL_CONTRIBUYENTE",
  "cdc": "01046029001001001000000512026050915579455768",
  "motivo": "Error en datos del cliente."
}

Campo	Tipo	Descripción
tenant*	string	Hash de 40 chars del cliente
token*	string	Token del contribuyente
cdc*	string	CDC del documento a anular (44 dígitos numéricos)
motivo*	string	Motivo de la anulación. Entre 5 y 500 caracteres.

Respuesta exitosa

{
  "success": true,
  "cancellation_id": 4,
  "cdc": "01046029001001001000000512026050915579455768",
  "document_type": "factura",
  "motivo": "Error en datos del cliente.",
  "numero_lote": "",
  "codigo": "0260",
  "mensaje": "Evento registrado correctamente",
  "estado": "Aprobado",
  "estado_interpretado": "APROBADA",
  "fecha_sifen": "2026-05-09T10:29:02-03:00",
  "fecha_local": "2026-05-09 13:29:02",
  "signed_document_id": 38
}

Campos de respuesta

Campo	Descripción
success	Indica si la anulación fue aprobada por SIFEN
cancellation_id	ID interno del registro de anulación
document_type	Tipo de documento: factura o nota_credito
codigo	Código de respuesta SIFEN. 0260 = aprobado
estado_interpretado	APROBADA o RECHAZADA
fecha_sifen	Fecha y hora registrada por SIFEN
fecha_local	Fecha y hora registrada localmente

Ejemplo cURL

curl --location 'https://factura-facil.com.py/api/cancellationElectronicDocument' \
--header 'Content-Type: application/json' \
--data '{
  "tenant": "HASH_40_CHARS_DEL_CLIENTE",
  "token": "TOKEN_DEL_CONTRIBUYENTE",
  "cdc": "01046029001001001000000512026050915579455768",
  "motivo": "Error en datos del cliente."
}'

Nota de crédito

Crear nota de crédito electrónica

Genera y firma una nota de crédito (tipoDocumento = 5) asociada a una factura electrónica previamente aprobada por SIFEN. Los totales son calculados automáticamente desde los ítems — no es necesario enviar el objeto totales.

Endpoint

POST https://factura-facil.com.py/api/signCreditNote

Request body

El campo cdc_referencia es el CDC de la factura que origina la nota de crédito.

Campos auto-calculados: no es necesario enviar totalItem, basGravIVA, liqIVAItem ni el objeto totales.

{
  "tenant": "HASH_40_CHARS_DEL_CLIENTE",
  "token": "TOKEN_DEL_CONTRIBUYENTE",
  "cdc_referencia": "01046029001001001000000412026050816313211444",
  "datosDocumento": {
    "establecimiento": "001",
    "punto": "001",
    "numero": "0000001",
    "codigoSeguridadAleatorio": "987654321",
    "fecha": "2026-05-09T10:30:00",
    "moneda": "PYG",
    "cambio": 0,
    "descripcion": "Nota de crédito",
    "observacion": "Devolución por error en la factura",

    "cliente": {
      "contribuyente": true,
      "ruc": "80012345-6",
      "razonSocial": "Comercial Demo S.A.",
      "nombreFantasia": "Comercial Demo",
      "tipoOperacion": 1,
      "direccion": "Avda. Mariscal López",
      "numeroCasa": 1200,
      "departamento": 11,
      "departamentoDescripcion": "CENTRAL",
      "distrito": 145,
      "distritoDescripcion": "SAN LORENZO",
      "ciudad": 145,
      "ciudadDescripcion": "SAN LORENZO",
      "pais": "PRY",
      "paisDescripcion": "Paraguay",
      "tipoContribuyente": 1,
      "documentoTipo": 1,
      "documentoNumero": "1234567",
      "telefono": "021555444",
      "celular": "0981123456",
      "email": "cliente@demo.com",
      "codigo": "CLI-001"
    },

    "items": [
      {
        "codigo": "PRD-001",
        "descripcion": "Servicio de implementación",
        "unidadMedida": 77,
        "unidadMedidaDesc": "UNI",
        "cantidad": 1,
        "precioUnitario": 350000,
        "descuento": 0,
        "descuentoGlobal": 0,
        "anticipo": 0,
        "anticipoGlobal": 0,
        "ivaTipo": 1,
        "ivaBase": 100,
        "iva": 10
      }
    ],

    "motivo": {
      "motivo": 2,
      "descripcionMotivo": "Devolución"
    }
  }
}

Parámetros raíz

Campo	Tipo	Descripción
tenant*	string	Hash de 40 chars del cliente
token*	string	Token del contribuyente emisor
cdc_referencia*	string	CDC de la factura afectada (44 dígitos)
datosDocumento*	object	Datos de la nota de crédito

Parámetros — datosDocumento

Campo	Tipo	Descripción
establecimiento*	string	Código del establecimiento
punto*	string	Punto de expedición
numero*	string	Número del documento
cliente*	object	Datos del receptor
items*	array	Ítems de la nota de crédito (mismo esquema que factura)
motivo*	object	Motivo de emisión. Ver tabla de motivos.
fechaopc	datetime	Fecha de emisión. Default: ahora
codigoSeguridadAleatorioopc	string	Default: últimos 9 dígitos del timestamp
totalesauto	object	Calculado automáticamente. No enviar.

Códigos de motivo (motivo.motivo)

Código	Descripción
1	Devolución y ajuste de precios
2	Devolución
3	Descuento
4	Bonificación
5	Crédito incobrable
6	Recupero de costo
7	Recupero de gasto
8	Ajuste de precio

El campo descripcionMotivo es truncado automáticamente a 20 caracteres si excede ese límite (restricción de SIFEN).

Respuesta exitosa

{
  "success": true,
  "credit_note_id": 2,
  "fecha": "2026-05-09 14:09:07",
  "cdc": "05046029001001001000000112026050819876543216",
  "cdc_referencia": "01046029001001001000000412026050816313211444",
  "numero": "0000001",
  "dCarQR": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=0504...",
  "codigo": "0300",
  "mensaje": "Lote recibido con éxito",
  "batch_number": "4974854722242998972",
  "respuesta_xml": "<ns2:rResEnviLoteDe>...</ns2:rResEnviLoteDe>"
}

El CDC de una nota de crédito comienza con 05. El código 0300 indica que el lote fue recibido — consultá el CDC para obtener el estado final.

Ejemplo cURL

curl --location 'https://factura-facil.com.py/api/signCreditNote' \
--header 'Content-Type: application/json' \
--data '{
  "tenant": "HASH_40_CHARS_DEL_CLIENTE",
  "token": "TOKEN_DEL_CONTRIBUYENTE",
  "cdc_referencia": "01046029001001001000000412026050816313211444",
  "datosDocumento": {
    "establecimiento": "001",
    "punto": "001",
    "numero": "0000001",
    "codigoSeguridadAleatorio": "987654321",
    "fecha": "2026-05-09T10:30:00",
    "moneda": "PYG",
    "cambio": 0,
    "cliente": {
      "contribuyente": true,
      "ruc": "80012345-6",
      "razonSocial": "Comercial Demo S.A.",
      "tipoOperacion": 1,
      "direccion": "Avda. Mariscal López",
      "numeroCasa": 1200,
      "departamento": 11, "departamentoDescripcion": "CENTRAL",
      "distrito": 145, "distritoDescripcion": "SAN LORENZO",
      "ciudad": 145, "ciudadDescripcion": "SAN LORENZO",
      "pais": "PRY", "paisDescripcion": "Paraguay",
      "tipoContribuyente": 1,
      "documentoTipo": 1, "documentoNumero": "1234567"
    },
    "items": [{
      "codigo": "PRD-001",
      "descripcion": "Servicio de implementación",
      "unidadMedida": 77,
      "cantidad": 1,
      "precioUnitario": 350000,
      "descuento": 0, "descuentoGlobal": 0,
      "anticipo": 0, "anticipoGlobal": 0,
      "ivaTipo": 1, "ivaBase": 100, "iva": 10
    }],
    "motivo": { "motivo": 2, "descripcionMotivo": "Devolucion" }
  }
}'

Nota de crédito

Consultar nota de crédito

Usa el mismo endpoint de consulta por CDC. El CDC de una nota de crédito comienza con 05.

Endpoint

POST https://factura-facil.com.py/api/consultarCDC

Request body

{
  "tenant": "HASH_40_CHARS_DEL_CLIENTE",
  "token": "TOKEN_DEL_CONTRIBUYENTE",
  "cdc": "05046029001001001000000112026050819876543216"
}

La respuesta es idéntica al endpoint de Consultar estado por CDC.

Nota de crédito

Anular nota de crédito

Usa el mismo endpoint de anulación. El sistema detecta automáticamente el tipo de documento desde el CDC y actualiza tanto cancellations como credit_notes.

Endpoint

POST https://factura-facil.com.py/api/cancellationElectronicDocument

Request body

{
  "tenant": "HASH_40_CHARS_DEL_CLIENTE",
  "token": "TOKEN_DEL_CONTRIBUYENTE",
  "cdc": "05046029001001001000000112026050819876543216",
  "motivo": "Error en datos de la nota de crédito."
}

La respuesta es idéntica al endpoint de Anular documento electrónico, con "document_type": "nota_credito".

Códigos de error

HTTP

400

Parámetros faltantes o inválidos. Revisá el body del request (tenant, token y campos del endpoint son obligatorios).

401

Tenant inválido o no reconocido — la base de datos no fue identificada. También aplica si el token del contribuyente no existe en esa base.

405

Método no permitido. Todos los endpoints requieren POST.

500

Error interno: certificado no encontrado, error de firma o error de conexión con SIFEN.

SIFEN — Envío de lote

Código	Descripción
0300	Lote recibido con éxito. El documento está en proceso.
0160	XML mal formado o datos inválidos.

SIFEN — Consulta por CDC

Código	Descripción
0422	Documento aprobado. Se retorna el XML completo del DE.
0420	Documento no existe en SIFEN o fue rechazado.

SIFEN — Anulación

Código	Descripción
0260	Evento de anulación aprobado por SIFEN.
0500	CDC inexistente en SIFEN.
0501	El documento no está aprobado, no se puede anular.
0502	Plazo de anulación vencido (más de 48 horas desde la emisión).

Flujo de integración

1. Construir JSON

2. POST a signDocument

3. Guardar CDC

4. Consultar CDC

5. Estado = APROBADO