API REST de FEPY

URL base y tenant

Cada empresa emisora es un tenant: un identificador propio que va en la ruta de todos los endpoints. El equipo de FEPY te entrega el tenant junto con el token cuando da de alta la empresa.

https://www.fepy.nicosdev.com/api/<tenant>

Para verificar que un tenant existe hay un ping sin autenticación. Devuelve OK con 200 si el tenant está registrado, y Not Found con 404 si no. Es texto plano, no JSON.

Autenticación

Todos los endpoints salvo el ping requieren un token fijo por tenant en la cabecera Authorization. No hay refresh ni expiración corta: el token vive hasta que se rote.

Authorization: Bearer api_key_<tu-token>

El prefijo api_key_ es opcional: el servidor lo quita si está presente. Ambas formas funcionan, pero conviene usar siempre la misma para que los logs sean uniformes.

Códigos HTTP y errores

Códigos que sí devuelve la autenticación

Forma del error de negocio

{
  "success": false,
  "error": "Algunos DEs presentan errores de validación previa",
  "errors": [
    { "index": 0, "error": "Faltan datos obligatorios." }
  ]
}

El campo errors aparece solo cuando el fallo es por documento: cada entrada trae el index dentro del array que enviaste, para que puedas mapear el error al documento exacto.

Tu primera llamada

/test confirma tres cosas de una: que el token es válido, en qué ambiente está la empresa, y si está conectada a SIFEN.

curl -H "Authorization: Bearer api_key_<tu-token>" \
  https://www.fepy.nicosdev.com/api/<tenant>/test

{
  "success": true,
  "message": "Conectado con FEPY, hora del Servidor: 2026-09-07 17:25:48",
  "data": {
    "empresa": "80012345-0 | EMPRESA EMISORA S.A.",
    "conectado_sifen": false,
    "idCdc": "0001",
    "ambiente": "test"
  }
}

La versión ?text=t agrega la última factura aprobada de la empresa, útil cuando migrás de servidor y necesitás saber en qué numeración quedaste.

Numeración de documentos

Cada documento se identifica por la terna establecimiento · punto de expedición · número, con ceros a la izquierda. FEPY no lleva el correlativo por vos: el número lo asigna tu sistema y debe ser único e irrepetible por terna.

El resultado visible es 001-001-0000001. Podés mandar los campos sin padding (por ejemplo 1): FEPY completa los ceros. Lo que no puede hacer es adivinar cuál sigue.

Clientes y tipoOperacion

El bloque cliente cambia de forma según quién sea el receptor. Las dos decisiones que gobiernan todo lo demás son contribuyente (si tiene RUC o no) y tipoOperacion.

Con contribuyente: true mandás ruc y tipoContribuyente (1 persona física, 2 persona jurídica). Con contribuyente: false mandás documentoTipo y documentoNumero.

Catálogos a mapear

SIFEN trabaja con códigos, no con descripciones. Estos son los catálogos que típicamente hay que agregar a un sistema que nunca facturó electrónicamente:

Los tres primeros están encadenados: la ciudad pertenece a un distrito y el distrito a un departamento. Si mandás una combinación inconsistente, el generador la rechaza. El apéndice tiene el catálogo completo, y un ZIP con todo.

Qué persistir de la respuesta

La respuesta de emisión trae datos que tu sistema necesita guardar. Si no los guardás, después no podés consultar el estado ni reimprimir el KUDE.

POST /lote/create

Tipos de documento

Ejemplo mínimo: una factura

curl -X POST https://www.fepy.nicosdev.com/api/<tenant>/lote/create \
  -H "Authorization: Bearer api_key_<tu-token>" \
  -H "Content-Type: application/json" \
  -d @factura.json

[
  {
    "tipoDocumento": 1,
    "establecimiento": "001",
    "punto": "001",
    "numero": "0000001",
    "fecha": "2026-09-07T10:00:00",
    "tipoTransaccion": 2,
    "tipoImpuesto": 1,
    "moneda": "PYG",
    "cliente": {
      "contribuyente": true,
      "ruc": "4303489-6",
      "razonSocial": "CLIENTE DE PRUEBA S.A.",
      "tipoOperacion": 1,
      "pais": "PRY",
      "tipoContribuyente": 2,
      "codigo": "001"
    },
    "factura": { "presencia": 1 },
    "items": [
      {
        "codigo": "SRV001",
        "descripcion": "Servicio de prueba",
        "unidadMedida": 77,
        "cantidad": 1,
        "precioUnitario": 550000,
        "ivaTipo": 1,
        "ivaBase": 100,
        "iva": 10
      }
    ],
    "condicion": {
      "tipo": 1,
      "entregas": [
        { "tipo": 1, "monto": 550000, "moneda": "PYG" }
      ]
    }
  }
]

Estructura del documento

Cabecera

Bloque cliente

Bloque items

Bloque condicion

tipo: 1 es contado y lleva entregas. tipo: 2 es crédito y lleva el bloque credito con plazo o cuotas.

"condicion": {
  "tipo": 2,
  "credito": {
    "tipo": 1,
    "plazo": "30 días"
  }
}

Bloques por tipo de documento

Respuesta y situaciones

{
  "success": true,
  "result": {
    "loteId": 42,
    "deList": [
      {
        "numeroFactura": "001-001-0000001",
        "cdc": "01800123450001001000000112026090711234567890",
        "serie": "",
        "respuesta_codigo": "0260",
        "respuesta_mensaje": "Aprobado",
        "situacion": 1,
        "estado": "Aprobado",
        "fechaFirma": "2026-09-07T11:47:58",
        "fechaEmision": "2026-09-07T10:00:00",
        "loteId": 42,
        "isEncontrado": false,
        "qr": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=...",
        "xml": "<?xml version=\"1.0\"?>..."
      }
    ]
  }
}

Situaciones

Borradores y confirmación

Con ?draft=true el lote se genera, se firma y se guarda, pero no se transmite. Sirve para previsualizar el KUDE antes de emitir en firme — el caso típico es el mostrador, donde el cliente todavía puede cambiar algo.

POST /lote/qr

Es el endpoint ideal para probar un payload nuevo: si pasa acá, pasa en /lote/create, y no te deja documentos basura en la base.

{
  "success": true,
  "result": {
    "deList": [
      {
        "cdc": "01800123450001001000000112026090711234567890",
        "qr": "https://ekuatia.set.gov.py/consultas/qr?nVersion=150&Id=..."
      }
    ]
  }
}

POST /de/create (síncrono)

La respuesta es el envelope de SIFEN parseado, no el deList del lote. El estado resuelto queda persistido con situacion 2, 3 o 4 según lo que devuelva SIFEN.

Estado de un lote

curl -H "Authorization: Bearer api_key_<tu-token>" \
  "https://www.fepy.nicosdev.com/api/<tenant>/lote/42?xml=f"

El lote debe pertenecer a la empresa del token. Si no, la respuesta es Lote no encontrado — no se filtra información de otros tenants.

Estado por CDC

{
  "success": true,
  "data": {
    "numeroFactura": "001-001-0000001",
    "cdc": "0180012345000100100000001...",
    "is_conectado": true,
    "ambiente": "t",
    "respuesta_codigo": "0260",
    "respuesta_mensaje": "Aprobado",
    "situacion": 2,
    "estado": "Aprobado",
    "fechaFirma": "2026-09-07T11:47:58",
    "fechaEmision": "2026-09-07T10:00:00",
    "qr": "https://ekuatia.set.gov.py/consultas/qr?...",
    "json": { },
    "xml": "<?xml ...",
    "eventos": [],
    "loteId": 42
  }
}

Estados en bloque

{
  "cdcList": [
    { "cdc": "0180012345000100100000001..." },
    { "cdc": "0180012345000100100000002..." }
  ]
}

La respuesta es {"success": true, "deList": [...]} con un elemento por CDC encontrado. Los CDC inexistentes se omiten en silencio: compará contra la lista que enviaste para detectar faltantes.

CDC de terceros

Si el documento no existe o fue cancelado, la respuesta es {"success": false, "error": "CDC no encontrado o cancelado"}.

Consulta de RUC

En la respuesta, el campo dRUCCons vuelve con el DV calculado por FEPY (módulo 11). Sirve para normalizar la base de clientes sin implementar el cálculo por tu cuenta.

curl -H "Authorization: Bearer api_key_<tu-token>" \
  https://www.fepy.nicosdev.com/api/<tenant>/ruc/4303489

Descarga del XML

Solo entrega documentos en situación aprobado (2), aprobado con observación (3) o cancelado (99), y solo de tu propia empresa. Cualquier otro caso responde 404 sin cuerpo.

Descarga del KUDE

{
  "cdcList": [
    { "cdc": "0180012345000100100000001..." }
  ]
}

Con un solo CDC el archivo se llama <Tipo>_<numeroFactura>.pdf. Con varios, los documentos van en un único PDF llamado <Tipo>_cant_<N>.pdf. El formato de hoja sale de la configuración de la empresa o del establecimiento.

Parámetros de la empresa

Útil para que tu sistema lea de acá los establecimientos y puntos habilitados en vez de tenerlos duplicados en tu configuración.

Cancelación

Anula un documento aprobado. Al aprobarse, FEPY marca el documento local en situacion: 99 (Cancelado).

{
  "cdc": "01800123450001001000000112026090711234567890",
  "motivo": "Error en los datos del receptor"
}

Inutilización

Declara ante SIFEN un rango de numeración que nunca se va a usar. Es para saltos de correlativo: se cortó la luz, se perdió una numeración, se anuló un preimpreso.

{
  "tipoDocumento": 1,
  "establecimiento": "001",
  "punto": "001",
  "desde": 15,
  "hasta": 18,
  "motivo": "Salto de numeracion por corte de energia",
  "timbrado": "12345678"
}

No lleva cdc: no anula documentos, reserva números. Si el rango incluye un número ya emitido, SIFEN rechaza el evento.

Una vez aprobado, las consultas de estado (cdc, de/estado, lote/{id}) informan con situacion: 90 (Inutilizado), inutilizado: true y fechaInutilizacion todo documento local de ese tipo, establecimiento y punto cuyo número caiga en el rango y que no esté en cola (0/1), aprobado (2/3) ni cancelado (99). El 90 se calcula al responder: no se guarda en el documento y esos números no se consultan en SIFEN.

Si algún documento del rango todavía está en cola (0/1), el evento se rechaza sin registrarse ni enviarse a SIFEN: "Hay documentos en cola dentro del rango a inutilizar. Espere el resultado del lote antes de enviar el evento." Lo mismo vale para cancelación y nominación de un documento en cola: "El documento todavía está en cola en SIFEN. Espere el resultado del lote antes de enviar el evento."

Un lote nuevo que use un número del rango se rechaza en la validación previa con [4066] Existe número inutilizado en el rango solicitado, sin guardar nada.

Nominación

Asigna o corrige los datos del receptor de un documento ya aprobado — el caso clásico es la factura emitida a consumidor final que el cliente después pide a su RUC.

{
  "cdc": "01800123450001001000000112026090711234567890",
  "cliente": {
    "contribuyente": true,
    "ruc": "4303489-6",
    "razonSocial": "CLIENTE DE PRUEBA S.A.",
    "tipoOperacion": 1,
    "pais": "PRY",
    "tipoContribuyente": 2
  }
}

Anulación por nota de crédito

{
  "cdcFactura": "01800123450001001000000112026090711234567890",
  "comprobante": "001-001-0000045"
}

FEPY toma los ítems, el cliente y la moneda de la factura original, arma la nota de crédito con tipoDocumento: 5, motivo 2 y el documento asociado apuntando al CDC, y la emite. La respuesta es la de /lote/create más un bloque info_anulacion.

Qué hace el modo desconectado

Es decir: todo el trabajo de integración se puede hacer y probar. El armado del payload, el mapeo de catálogos, el manejo de errores de validación y la numeración se ejercitan igual que en producción.

{
  "success": true,
  "message": "Lote creado con éxito - Sin conexión a SIFEN",
  "result": {
    "loteId": 0,
    "deList": [
      {
        "numeroFactura": "001-001-0000001",
        "cdc": "01800123450001001000000112026090711234567890",
        "xml": "<?xml version=\"1.0\"?>..."
      }
    ]
  }
}

Los documentos quedan guardados con respuesta_codigo: "0260", estado: "Aprobado" y situacion: 1. Son aprobaciones simuladas: te sirven para desarrollar el flujo completo de tu lado.

Límites y trampas

Qué probar igual antes de conectar

Cuando el certificado esté cargado y la empresa se conecte, tu integración no cambia: los mismos endpoints empiezan a devolver qr, XML firmado y situaciones reales de SIFEN.

Descargar las tablas

Cada tabla está en CSV —para abrir en Excel o importar a tu base— y en JSON, para sembrarla desde un script. El CSV lleva BOM, así que Excel en Windows respeta los acentos sin que tengas que tocar nada.

Ninguna tabla coincide con ese filtro.

Consumo por HTTP

Las mismas tablas se sirven sin autenticación, para que puedas actualizarlas desde un script en vez de bajarlas a mano.

curl https://www.fepy.nicosdev.com/manual/codigos
curl -O https://www.fepy.nicosdev.com/manual/codigos/unidades-medida.csv
curl -O https://www.fepy.nicosdev.com/manual/codigos/todo.zip

{
  "success": true,
  "tablas": [
    { "tabla": "departamentos", "etiqueta": "Departamentos", "filas": 18 },
    { "tabla": "distritos",     "etiqueta": "Distritos",     "filas": 252 }
  ]
}

Un slug fuera del catálogo devuelve 404 con {"success": false, "error": "Tabla inexistente"}.