Facturalo API

API v3

API REST para emisión de comprobantes electrónicos ante SUNAT (Perú). Soporta Facturas, Boletas, Notas de Crédito/Débito y Guías de Remisión. Los cálculos de IGV, subtotales y totales son automáticos — solo envía el precioUnitario y el tipoIgv.

• Emitir factura — POST /documentos/enviar
• Emitir boleta — POST /documentos/enviar
• Emitir guía — POST /guias/enviar
• SIRE — Ventas — Registro de Ventas e Ingresos (RVIE)
• SIRE — Compras — Registro de Compras Electrónico (RCE)

Idempotencia y webhooks

• Idempotencia — Idempotency-Key y clave natural para no emitir dos veces
• Webhooks — Firma HMAC-SHA256 y hasta 5 reintentos automáticos
• Estado del servicio — API, docs, web, webhooks y SUNAT

Autenticación

Hay dos tipos de token, ambos se envían en el header Authorization. El entorno (demo / producción) se detecta automáticamente del prefijo del token.

• user_sk_... — Token de usuario — Crear y gestionar empresas y establecimientos.
• sk_test_... — Token de empresa — Demo — Facturas/boletas en SUNAT Beta; guías en el simulador GRE de Facturalo (validación XSD/XSL real).
• sk_live_... — Token de empresa — Producción — Documentos y guías en producción SUNAT.

// Token de empresa — documentos y guías
Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

// Token de usuario — gestión de empresas y establecimientos
Authorization: user_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ejemplo rápido

-primary-dark)">curl -X POST https://api.facturalo.pe/api/v3/documentos/enviar \
  -H "Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": false,
    "documento": {
      "sunatTransaccion": "0101",
      "tipoComprobante": "01",
      "serie": "F001",
      "correlativo": "1",
      "fechaEmision": "2026-06-13",
      "moneda": "PEN",
      "formaPago": "CONTADO",
      "otrosCampos": [
        { "label": "Cajero", "value": "Guillermo" },
        { "label": "Método de pago", "value": "Yape" },
        { "label": "Mesa", "value": "12" }
      ],
      "cliente": {
        "tipoDocumento": "6",
        "numeroDocumento": "20000000001",
        "denominacion": "EMPRESA S.A.C.",
        "direccion": "AV. LIMA 123 - LIMA - LIMA - LIMA"
      },
      "items": [{
        "unidadMedida": "NIU",
        "descripcion": "SERVICIO DE CONSULTORÍA",
        "cantidad": 1,
        "precioUnitario": 590,
        "tipoIgv": "10"
      }]
    }
  }'

{
  "success": true,
  "message": "La Factura numero F001-00000001 ha sido aceptada",
  "data": {
    "estado": "ACEPTADA",
    "entorno": "demo",
    "documento": {
      "id": "83ad82a0-680e-11f1-8e35-2d93ac0f2c84",
      "estado": "ACEPTADA",
      "serie": "F001",
      "correlativo": "00000001",
      "tipo": "FACTURA"
    },
    "sunat": {
      "estado": "ACEPTADA",
      "codigo": "0",
      "mensaje": "La Factura numero F001-00000001 ha sido aceptada",
      "notas": []
    },
    "enlaces": {
      "pdf": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.pdf",
      "pdfTicket": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.ticket.pdf",
      "xml": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.xml",
      "cdr": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.cdr"
    },
    "hash": "xvQpVbLssRc8FlD8/0LuSYeIPo8=",
    "cadenaQr": "20601476551 | 01 | F001 | 00000001 | 720.00 | 4720.00 | 13/06/2026 | 6 | 20000000001 | xvQpVbLssRc8FlD8/0LuSYeIPo8= |"
  }
}

Características clave

• Cálculos automáticos — Solo envía precioUnitario y tipoIgv por ítem. La API calcula IGV, subtotales y totales automáticamente.
• Entorno por token — El entorno (demo / producción) se detecta del token. sk_test_ = demo, sk_live_ = producción. No existe parámetro de entorno. En demo, facturas → SUNAT Beta; guías → simulador GRE de Facturalo (SUNAT no tiene beta GRE pública).
• Síncrono o asíncrono — Con "webhook": false (default) la respuesta incluye el resultado SUNAT. Con "webhook": true retorna EN_PROCESO y el resultado llega al webhook.
• Si SUNAT no responde — El comprobante o guía queda en proceso: reintentos en cola (~30 min, hasta ~5 h) y, en producción, recuperación horaria de pendientes entre 07:00 y 00:00 (hora Lima).
• Archivos públicos — Los endpoints /{id}.pdf, /{id}.xml y /{id}.cdr no requieren autenticación — son links compartibles directamente con el cliente.
• Respuesta estructurada — Todas las respuestas exitosas siguen el mismo esquema: success, message, data. Dentro de data: estado, entorno, documento, sunat.notas, enlaces.

Códigos de respuesta HTTP

• 200 — OK — Petición exitosa
• 201 — Created — Recurso creado (empresa, establecimiento)
• 400 — Bad Request — Cuerpo de la petición mal formado o JSON inválido
• 401 — Unauthorized — Token inválido o ausente
• 403 — Forbidden — El token no tiene permisos para este recurso
• 404 — Not Found — Recurso no encontrado
• 422 — Unprocessable Entity — Errores de validación — revisa el campo errors
• 429 — Too Many Requests — Límite de peticiones alcanzado — reintenta más tarde
• 500 — Internal Server Error — Error interno del servidor