DOCUMENTACIÓN · API v1 · SIFEN
Emití documentos electrónicos desde tu propio sistema.
Una API REST sobre HTTPS, con JSON de ida y de vuelta. Vos mandás la venta; nosotros generamos el CDC, armamos el XML, lo firmamos con tu certificado y lo transmitimos a SIFEN. En la misma llamada te devolvemos el CDC, el número y el QR del documento.
Toda cuenta nueva arranca en el ambiente de pruebas de SIFEN: integrás, probás y recién cuando funciona pasás a producción. La URL no cambia — el ambiente lo define tu emisor.
LO PRIMERO
Cuatro cosas y ya podés leer el resto.
URL base
Todas las rutas cuelgan de acá. Solo HTTPS.
https://api.gcompy.com/api/v1
Autenticación
Una clave por cuenta, en el header. La generás desde el portal y se muestra una sola vez: guardala en tu servidor, nunca en el navegador ni en un repositorio.
X-API-Key: tu_clave
Los endpoints del portal (listados, eventos del receptor, cancelación) usan el token JWT que devuelve POST /auth/login.
Forma de la respuesta
La mayoría de los endpoints devuelve el mismo sobre. El payload real siempre está en data.
{ "success": true, "message": "OK", "data": { … } }
La regla que más cuesta
HTTP 200 no significa "aprobado por SIFEN". Significa que la llamada salió bien. Si SIFEN rechazó el documento, vas a recibir un 200 con data.estado = "rechazado" y el motivo en mensaje_set. Miralo siempre.
En producción, el veredicto llega después
SIFEN habilita dos canales de transmisión y en producción el canal síncrono no está habilitado: los documentos se transmiten por lote. En la práctica, para vos:
- La llamada de emisión te devuelve 200 con estado: "preparado" — el documento ya está firmado, numerado y con su CDC y su QR definitivos
- El veredicto de SIFEN (aprobado o rechazado) lo resolvemos nosotros contra el lote, y vos lo leés con GET /de/{cdc}
- En el ambiente de pruebas el canal síncrono sí funciona: ahí la misma llamada suele volver ya aprobado
Programá siempre contra el caso de producción: emitís, guardás el CDC, entregás el comprobante y consultás el estado después. Si tu código asume "aprobado" en la respuesta, anda en pruebas y se rompe el día que pasás a producción.
Los montos son guaraníes enteros, sin decimales, y el precio_unitario ya incluye el IVA — como se factura en Paraguay. Las cantidades sí aceptan decimales (litros, kilos).
UNA FACTURA, DE PUNTA A PUNTA
Esta es la llamada que vas a hacer mil veces.
POST /de/factura/simple es la forma corta: le pasás el receptor y los ítems, y la plataforma completa todo lo que exige el Manual Técnico de SIFEN — timbrado, CDC, subtotales por tasa de IVA, firma y envío.
- Si no mandás receptor, sale a consumidor final
- referencia_externa es tu número de venta: repetirlo no duplica la factura
- La respuesta trae el CDC, el número y el QR ya definitivos
- El estado arranca en preparado y lo consultás después
¿Necesitás controlar cada grupo del XML (descuentos, cuotas, transporte, moneda extranjera)? Está POST /de/factura, la forma completa.
curl -X POST https://api.gcompy.com/api/v1/de/factura/simple \
-H "X-API-Key: $GCOMPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"receptor": {
"ruc": "80012345",
"nombre": "Cliente S.A.",
"email": "compras@cliente.com.py"
},
"items": [
{ "codigo": "PROD-001",
"descripcion": "Teclado mecanico USB",
"cantidad": 2,
"precio_unitario": 150000,
"tasa_iva": 10 }
],
"condicion_venta": 1,
"referencia_externa": "venta-12345"
}'
# 200 OK — el documento ya existe, con su CDC y su QR
{
"success": true,
"message": "OK",
"data": {
"cdc": "01801234500010010000522…",
"estado": "preparado",
"display_estado": "Pendiente de envío",
"numero_factura": "001-001-0000522",
"qr_url": "https://ekuatia.set.gov.py/consultas/qr?…",
"monto_total": 300000,
"mensaje_set": null
}
}
# Después, el veredicto de SIFEN:
curl https://api.gcompy.com/api/v1/de/01801234500010010000522… \
-H "X-API-Key: $GCOMPY_API_KEY"
{ "data": { "estado": "aprobado",
"display_estado": "Aprobado por SIFEN",
"mensaje_set": null } }REFERENCIA
Todo lo que expone la API.
Los cinco tipos de documento electrónico que reconoce SIFEN, sus eventos y las consultas. Cada ruta va prefijada con /api/v1.
Emisión
| Método | Ruta | Qué hace | Auth |
|---|---|---|---|
| POST | /de/factura/simple | Factura electrónica en su forma corta. El endpoint de los puntos de venta. | API Key |
| POST | /de/factura | Factura electrónica completa: control sobre cada grupo del XML. | API Key |
| POST | /de/nota-credito | Nota de crédito asociada a un documento ya emitido. | API Key |
| POST | /de/nota-debito | Nota de débito asociada a un documento ya emitido. | API Key |
| POST | /de/autofactura | Autofactura: compras a quien no emite comprobante. | API Key |
| POST | /de/nota-remision | Nota de remisión electrónica para el traslado de mercadería. | API Key |
En producción los seis se transmiten por el canal de lote, porque es el único que SIFEN habilita: la llamada te devuelve el documento en preparado —ya firmado, numerado y con su CDC— y el veredicto lo leés después. De eso nos ocupamos nosotros; vos no tenés que armar el lote. Si preferís manejarlo por tu cuenta, ahí abajo está el canal de lote directo.
Lotes
El canal asíncrono de SIFEN, expuesto tal cual. Es lo que usan los integradores que facturan por volumen o que calculan el CDC en su propio sistema.
| Método | Ruta | Qué hace | Auth |
|---|---|---|---|
| POST | /lotes/precalculado | Recibe hasta 50 documentos con el CDC ya calculado por tu sistema: los validamos uno por uno, los firmamos y los transmitimos. | API Key |
| POST | /lotes/precalculado/reintentar | Reintenta los rechazados del batch conservando su CDC, y devuelve el veredicto de cada uno. | API Key |
| POST | /lotes | Junta los documentos tuyos que están pendientes de envío, arma el lote y lo transmite. | API Key |
| GET | /lotes/{id} | Estado del lote. | API Key |
| GET | /lotes/{id}/detalle | El lote con el veredicto documento por documento. | API Key |
| POST | /lotes/{id}/consultar | Le pide a SIFEN el resultado del lote ahora, sin esperar el ciclo automático. | API Key |
Reglas de SIFEN que la plataforma hace cumplir: hasta 50 documentos por lote, todos del mismo tipo y del mismo RUC emisor. El lote es idempotente por referencia_externa: reenviarlo devuelve el lote que ya existe en vez de re-transmitir — retransmitir CDCs hace que SIFEN bloquee el RUC por un rato.
Consulta y comprobantes
| Método | Ruta | Qué hace | Auth |
|---|---|---|---|
| GET | /de/{cdc} | Estado del documento y su línea de tiempo (creado, firmado, enviado, respuesta). | API Key o JWT |
| GET | /de/{cdc}/kude | KuDE en PDF: el comprobante que se le entrega al cliente. | API Key o JWT |
| GET | /de/{cdc}/xml | XML firmado tal como se envió a SIFEN. | API Key o JWT |
| POST | /de/{cdc}/consultar-sifen | Le pregunta a SIFEN, en vivo, por el estado de ese CDC. | API Key o JWT |
| GET | /de | Listado paginado con filtros por estado, fecha y búsqueda. | JWT |
| GET | /de/{cdc}/logs | Historial de las llamadas a SIFEN de ese documento. | JWT |
Correcciones y eventos
| Método | Ruta | Qué hace | Auth |
|---|---|---|---|
| POST | /de/{cdc}/reintentar | Reenvía un documento rechazado, con o sin corrección. | API Key o JWT |
| POST | /de/{cdc}/cancelar | Evento de cancelación en SIFEN (dentro de las 48 horas). | JWT |
| POST | /de/inutilizar | Inutiliza un rango de números que no se van a usar. | API Key o JWT |
| POST | /eventos/conformidad | Conformidad del receptor con un documento recibido. | JWT |
| POST | /eventos/disconformidad | Disconformidad del receptor. | JWT |
| POST | /eventos/desconocimiento | Desconocimiento de una operación que no reconocés. | JWT |
| POST | /eventos/notificacion-recepcion | Notificación de recepción del documento. | JWT |
Cuenta y configuración
| Método | Ruta | Qué hace | Auth |
|---|---|---|---|
| POST | /auth/login | Devuelve el token JWT y su refresh. | — |
| POST | /apikeys | Genera una clave de API. Se muestra una sola vez. | JWT |
| POST | /emisor/certificado | Sube tu certificado .p12. Se guarda cifrado y no se descarga. | JWT |
| PATCH | /emisor/ambiente | Cambia entre pruebas y producción. | JWT |
| POST | /timbrados | Carga un timbrado con su establecimiento y punto de expedición. | JWT |
El detalle campo por campo, con los códigos de error de cada endpoint y una colección Postman lista para importar, se entrega al integrarse. Pedila por WhatsApp o escribinos a info@gcompy.com.
QUÉ HACER CON CADA RESPUESTA
Seis estados, y qué hacer con cada uno.
| estado | Significa | Qué hacés |
|---|---|---|
| aprobado | Válido fiscalmente. | Entregás el KuDE y seguís. |
| aprobado_obs | Aprobado, con observaciones de SIFEN. | Es válido igual. Conviene leer la observación. |
| rechazado | SIFEN no lo aceptó. El motivo viene en mensaje_set. | Corregís el dato y reintentás con la misma referencia. |
| preparado | Firmado y transmitido, sin veredicto todavía. Es el estado normal al emitir en producción. | Consultás GET /de/{cdc} cada 30 segundos. |
| error_sifen | SIFEN no respondió: caída o timeout. | Nada: se reintenta solo. Vos consultás el estado. |
| contingencia | Emitido en modo contingencia. | Se regulariza automáticamente cuando SIFEN vuelve. |
Un documento nunca se borra: cambia de estado. Es un registro fiscal y la DNIT puede auditarlo años después.
LO QUE PASA CUANDO ALGO SALE MAL
Reintentar no te va a duplicar una factura.
Idempotencia por referencia
Mandás tu número de venta en referencia_externa. Si la red se cortó y no sabés si llegó, repetís la llamada: te devolvemos el documento que ya existe, con el mismo CDC.
Rechazado se re-emite
Si el anterior fue rechazado, la misma referencia genera un documento nuevo con CDC nuevo. El rechazado queda guardado como historial de auditoría.
Si SIFEN se cae
El documento queda encolado y se reenvía solo, con reintentos espaciados. Antes de reenviar consultamos el CDC en SIFEN, así no se manda dos veces lo que ya entró.
CÓMO EMPEZAR
De la cuenta a la primera factura.
Creás tu cuenta
Con tu correo y los datos fiscales de la empresa. Nace en el ambiente de pruebas de SIFEN, donde nada tiene valor fiscal.
Cargás certificado y timbrado
El certificado lo emite un prestador habilitado y el timbrado sale de Marangatu. Cómo se consigue el certificado
Generás tu clave y emitís
Desde el portal, en Configuración. La clave se muestra una sola vez. Con eso ya podés llamar a /de/factura/simple.
¿Sos integrador y necesitás un sandbox para tus clientes? Trabajamos así con varias casas de software. Escribinos y lo armamos.
PREGUNTAS FRECUENTES
Lo que se pregunta antes de integrar.
- ¿En qué lenguaje puedo integrarme?
- En el que uses. Es HTTP con JSON: si tu sistema puede hacer un POST, puede facturar. Hay integraciones andando en PHP, Python y JavaScript.
- ¿Tengo que armar el XML de SIFEN?
- No. Vos mandás la venta en JSON. El XML del Manual Técnico, el CDC de 44 dígitos, la firma XMLDSig y el código QR los generamos nosotros.
- ¿Cómo pruebo sin emitir documentos con valor fiscal?
- Toda cuenta arranca en el ambiente de pruebas de SIFEN. Emitís todo lo que quieras, sin efecto fiscal. Cuando tu integración funciona, se pasa la cuenta a producción — la URL de la API no cambia.
- ¿La respuesta me dice si SIFEN lo aprobó?
- En producción no, y es lo primero que hay que entender: ahí los documentos se transmiten por lote, así que la emisión te devuelve el CDC y el QR con estado preparado, y el veredicto lo leés después con GET /de/{cdc}. En el ambiente de pruebas la respuesta suele volver ya resuelta — no programes contra ese caso.
- ¿Qué pasa si mando dos veces la misma venta?
- Si usás referencia_externa con tu número de venta, la segunda llamada te devuelve el documento que ya existe en vez de emitir otro. Es lo que evita duplicados cuando se corta la red.
- ¿Hay límite de llamadas?
- Hay un límite por clave para proteger el servicio; el volumen normal de un comercio no lo toca. Lo que se cobra es el documento emitido, según el plan.
- ¿El certificado digital lo dan ustedes?
- No: lo emite un prestador de certificación habilitado por el MIC. Te decimos con quiénes hablar y qué pedir, y lo subís al portal cuando lo tengas.
¿Lo probamos?
Creás la cuenta, generás tu clave y emitís la primera factura de prueba hoy mismo.
Hablemos de tu empresa.
Contanos qué necesitás y te respondemos con una propuesta concreta.