Kuat-ia API

Facturación electrónica SIFEN (Paraguay) — documentación para integraciones. Compatible con FacturaSend.

URL base:  https://api.kuat-ia.com.py/api/tu-empresa
API key:   Bearer api_key_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

• Autenticación
• Emitir (lote/create)
• Consultar estado
• Cancelar
• Descargar KUDE (PDF)
• Descargar XML
• Enviar por correo
• Consultas (CDC / RUC)
• Tabla de situación
• Todos los endpoints
• Errores
• API nativa /v1

Autenticación

Todas las rutas cuelgan de https://api.kuat-ia.com.py/api/{slug}, donde {slug} es el identificador de tu empresa. Autenticá con la API key de la empresa (te la da tu administrador) en el header Authorization:

Si tu sistema anterior apuntaba a una URL sin el /api/ —es decir https://api.kuat-ia.com.py/{slug}/…— también funciona: este servidor acepta las dos formas. Migrar es cambiar el host y la key, nada más.

Authorization: Bearer api_key_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Content-Type: application/json

Los errores de negocio se devuelven con HTTP 400 y el cuerpo { "success": false, "error": "…" } (nunca 5xx), para que tu cliente siempre pueda leer el mensaje.

Antes que nada, probá la conexión — si esto responde, el host, la clave y el slug están bien:

curl https://api.kuat-ia.com.py/api/tu-empresa/test -H "Authorization: Bearer api_key_..."
Kuat-ia Funciona. - 04/08/2026 16:20 (hora de Asunción) - TU EMPRESA S.A.

Emitir un documento — POST/api/{slug}/lote/create

El cuerpo es un array de documentos. Agregá ?draft=true para generar un borrador. No espera la aprobación de SIFEN: devuelve el CDC, el número y las fechas al instante; el estado lo consultás después con /de/estado.

curl -X POST https://api.kuat-ia.com.py/api/tu-empresa/lote/create \
  -H "Authorization: Bearer api_key_..." \
  -H "Content-Type: application/json" \
  -d '[{
    "tipoDocumento": 1,
    "establecimiento": "001", "punto": "001", "numero": 1,
    "fecha": "2026-07-26T10:00:00",
    "moneda": "PYG",
    "cliente": {
      "contribuyente": true, "ruc": "80012345-0",
      "razonSocial": "CLIENTE EJEMPLO S.A.",
      "tipoOperacion": "1", "tipoContribuyente": 2
    },
    "items": [
      { "descripcion": "Servicio mensual", "cantidad": 1,
        "precioUnitario": 550000, "ivaTipo": 1, "iva": 10, "unidadMedida": 77 }
    ]
  }]'

Respuesta

{
  "success": true,
  "result": {
    "deList": [
      { "cdc": "0105234…266", "numero": "001-001-0000001",
        "fechaEmision": "2026-07-26T10:00:00", "fechaFirma": "2026-07-26T10:00:00" }
    ],
    "loteId": 1
  }
}

tipoDocumento: 1 Factura · 2 Fact. Exportación · 3 Fact. Importación · 4 Autofactura · 5 Nota de Crédito · 6 Nota de Débito · 7 Nota de Remisión. IVA por ítem: gravado 10 % → ivaTipo 1/iva 10; gravado 5 % → iva 5; exenta → ivaTipo 3/iva 0. El numero lo administra tu sistema (se respeta); si mandás 0, Kuat-ia asigna el correlativo. Para NC/ND agregá "documentoAsociado": { "cdc": "…" }.

Consultar estado — POST/api/{slug}/de/estado

curl -X POST https://api.kuat-ia.com.py/api/tu-empresa/de/estado \
  -H "Authorization: Bearer api_key_..." \
  -d '{ "cdcList": [ { "cdc": "0105234…266" } ] }'

{
  "success": true,
  "deList": [
    { "cdc": "0105234…266", "numero": "001-001-0000001",
      "situacion": 2, "fecha": "2026-07-26T10:00:00",
      "respuesta_codigo": "", "respuesta_mensaje": "" }
  ]
}

Un CDC que no existe devuelve situacion: 98. Ver la tabla de situación.

Cancelar — POST/api/{slug}/evento/cancelacion

curl -X POST https://api.kuat-ia.com.py/api/tu-empresa/evento/cancelacion \
  -H "Authorization: Bearer api_key_..." \
  -d '{ "cdc": "0105234…266", "motivo": "Error en el monto facturado" }'

{
  "success": true,
  "result": {
    "ns2:rRetEnviEventoDe": {
      "ns2:dFecProc": "2026-07-26T10:05:00",
      "ns2:gResProcEVe": {
        "ns2:dEstRes": "Aprobado", "ns2:dProtAut": "…",
        "ns2:gResProc": { "ns2:dCodRes": "0600", "ns2:dMsgRes": "Evento registrado correctamente" }
      }
    }
  },
  "cdc": "0105234…266"
}

dCodRes = 0600 ⇒ cancelado. success:false ⇒ no llegó a SIFEN. El motivo debe tener entre 5 y 500 caracteres; la cancelación de una FE aprobada debe hacerse dentro de las 48 h.

Descargar KUDE en PDF — POST/api/{slug}/de/pdf

curl -X POST https://api.kuat-ia.com.py/api/tu-empresa/de/pdf \
  -H "Authorization: Bearer api_key_..." \
  -d '{ "cdcList": [ { "cdc": "0105234…266" } ], "type": "base64", "format": "custom" }'

Devuelve el PDF codificado en base64 como cuerpo de la respuesta. format: ticket (80 mm) o custom (A4).

Descargar XML — GET/api/{slug}/de/xml/{cdc}

curl https://api.kuat-ia.com.py/api/tu-empresa/de/xml/0105234…266 -H "Authorization: Bearer api_key_..."

Devuelve el XML del documento (firmado si ya fue enviado a SIFEN).

Enviar por correo — POST/api/{slug}/de/email

curl -X POST https://api.kuat-ia.com.py/api/tu-empresa/de/email \
  -H "Authorization: Bearer api_key_..." \
  -d '{ "email": "cliente@correo.com", "cdcList": [ { "cdc": "0105234…266" } ] }'

{ "success": true, "message": "Correo enviado a cliente@correo.com con 1 documento(s)" }

Consultas — CDC y RUC

GET/api/{slug}/de/cdc/{cdc} — un documento en Kuat-ia

{ "success": true, "result": {
    "cdc": "0105234…266", "numero": "001-001-0000001",
    "situacion": 2, "info_codigo": "", "info_descripcion": "",
    "fecha": "2026-07-26T10:00:00", "lote_estado": 2 } }

POST/api/{slug}/dte/cdc/{cdc} — consulta el DTE en SIFEN (requiere certificado)

{ "success": true, "fecha": "…", "respuesta_codigo": "0422",
  "respuesta_mensaje": "CDC encontrado", "protocolo": "…" }

POST/api/{slug}/ruc/{ruc} — consulta un RUC en SIFEN (requiere certificado)

{ "success": true, "result": {
    "respuesta_codigo": "0502", "respuesta_mensaje": "…",
    "razon_social": "…", "estado_codigo": "ACT", "estado_mensaje": "…" } }

Tabla de situación

Todos los endpoints (capa compatible)

Las marcadas como no disponibles devuelven un error 400 que lo explica, no un éxito vacío: preferimos decirlo antes que hacerte creer que el archivo se generó.

Errores

Los errores de negocio se devuelven con HTTP 400 y el cuerpo:

{ "success": false, "error": "descripción del problema",
  "errores": [ { "error": "descripción del problema" } ] }

HTTP 200 respuesta correcta · 400 error de negocio / autenticación / validación · 404 ruta inexistente.

API nativa /v1 (para integraciones nuevas)

Kuat-ia también expone una API propia bajo /v1/tenants/:id/… con claves que empiezan con kuat_live_. Es opcional: si venís de FacturaSend, usá la capa compatible de arriba. La API nativa cubre emisión, envío de lotes, KUDE, XML, export CSV/ZIP, webhooks y consultas SIFEN.