Cómo integrar facturación electrónica en tu sistema vía API REST

Si tienes un sistema propio (ERP, e-commerce, punto de venta, app móvil) y quieres que genere facturas y boletas electrónicas sin que tus usuarios tengan que cambiar de pantalla, la solución es integrar una API de facturación electrónica.

En este artículo te explicamos cómo funciona el proceso de integración con QENTI, desde la autenticación hasta la emisión de tu primera factura vía API.

¿Por qué integrar en lugar de usar el portal?

Usar el portal web de QENTI directamente funciona bien para equipos pequeños que facturan manualmente. Pero si tu negocio tiene:

• Un e-commerce que necesita generar boleta automáticamente con cada compra
• Un ERP o sistema de gestión que ya registra las ventas
• Un punto de venta (POS) que opera en caja
• Una app móvil para vendedores de campo

…entonces la integración vía API es la solución correcta. El flujo queda 100% automatizado sin intervención humana.

Arquitectura de la integración

Tu sistema → API QENTI → PSE certificado → SUNAT → CDR de vuelta

Tu sistema envía los datos de la factura (cliente, productos, montos) en formato JSON. QENTI los valida, genera el XML firmado, lo envía al PSE, recibe el CDR de SUNAT y te devuelve la respuesta con el estado del comprobante y los archivos PDF/XML.

Autenticación

La API de QENTI usa autenticación JWT (JSON Web Token). Para obtener tu token:

POST https://api.qenti.pe/v1/auth/token
Content-Type: application/json

{
  "api_key": "tu_api_key_aqui",
  "api_secret": "tu_api_secret_aqui"
}

Respuesta:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

El token tiene vigencia de 1 hora. Implementa un sistema de refresh automático en tu integración.

Emitir una factura electrónica

POST https://api.qenti.pe/v1/comprobantes/factura
Authorization: Bearer {tu_token}
Content-Type: application/json

{
  "serie": "F001",
  "moneda": "PEN",
  "fecha_emision": "2025-06-01",
  "receptor": {
    "tipo_documento": "6",
    "numero_documento": "20123456789",
    "razon_social": "EMPRESA CLIENTE S.A.C.",
    "direccion": "Av. Los Pinos 123, Lima"
  },
  "items": [
    {
      "descripcion": "Servicio de consultoría",
      "cantidad": 1,
      "precio_unitario": 1000.00,
      "igv_porcentaje": 18,
      "codigo_unidad": "ZZ"
    }
  ],
  "leyendas": [
    {
      "codigo": "1000",
      "valor": "MIL Y 00/100 SOLES"
    }
  ]
}

Respuesta exitosa:

{
  "success": true,
  "comprobante": {
    "id": "FAC-2025-F001-00000123",
    "serie": "F001",
    "numero": "00000123",
    "estado_sunat": "aceptado",
    "cdr_code": "0",
    "cdr_description": "La Factura numero F001-00000123...",
    "pdf_url": "https://cdn.qenti.pe/pdf/FAC-2025-F001-123.pdf",
    "xml_url": "https://cdn.qenti.pe/xml/FAC-2025-F001-123.xml",
    "cdr_url": "https://cdn.qenti.pe/cdr/FAC-2025-F001-123.zip"
  }
}

Emitir una boleta de venta

El proceso es idéntico al de la factura, con dos diferencias:

1. El endpoint es /v1/comprobantes/boleta
2. La serie empieza con “B” (ej: B001)
3. El receptor puede no tener RUC (usa tipo_documento: "1" para DNI o "0" para no identificado)

{
  "serie": "B001",
  "receptor": {
    "tipo_documento": "1",
    "numero_documento": "12345678",
    "nombres": "Juan",
    "apellidos": "Pérez García"
  }
}

Manejo de errores

SUNAT puede rechazar comprobantes por varias razones. La API de QENTI devuelve el código de error original de SUNAT con una descripción en español:

{
  "success": false,
  "error": {
    "code": "2329",
    "sunat_code": "2329",
    "message": "El RUC del receptor no está activo en SUNAT",
    "suggestion": "Verifica que el RUC 20999999999 esté activo en el portal de SUNAT"
  }
}

Los errores más frecuentes:

Webhooks para notificaciones

En lugar de consultar el estado de cada comprobante manualmente, configura webhooks para recibir notificaciones automáticas:

POST https://api.qenti.pe/v1/webhooks
Authorization: Bearer {tu_token}

{
  "url": "https://tuapp.com/webhook/qenti",
  "events": ["comprobante.aceptado", "comprobante.rechazado"],
  "secret": "tu_webhook_secret"
}

QENTI enviará un POST a tu URL con los datos del comprobante cada vez que cambie de estado.

Entorno sandbox para pruebas

Antes de pasar a producción, usa el entorno sandbox:

Base URL sandbox: https://sandbox.api.qenti.pe/v1/

En sandbox puedes emitir comprobantes de prueba sin que lleguen a SUNAT real. Los RUCs y números de serie en sandbox son simulados.

SDK disponibles

Para acelerar la integración, QENTI ofrece SDKs oficiales:

• PHP: composer require qenti/sdk-php
• Python: pip install qenti-sdk
• Node.js: npm install @qenti/sdk

Cada SDK incluye manejo automático de tokens, retry en errores temporales y tipado completo.

Checklist antes de ir a producción

• ✓ Integración probada en sandbox con todos los tipos de comprobante
• ✓ Manejo de errores implementado (reintentos, logs, alertas)
• ✓ Webhook configurado y probado
• ✓ Series registradas en SUNAT (F001, B001, etc.)
• ✓ Certificado digital configurado en cuenta QENTI
• ✓ Datos de empresa verificados (RUC, nombre, dirección)

¿Tienes preguntas técnicas sobre la integración? Escríbenos a soporte@qenti.pe o revisa la documentación completa de la API.