Documentación API — Smart PSE · PSE Autorizado SUNAT

Comprobantes Electrónicos (CPE)

Smart PSE expone dos flujos de integración. Elige el que mejor se adapte a tu arquitectura:

Flujo B Solo firma

Smart PSE firma el XML con el certificado PSE y te lo devuelve. Tú envías a SUNAT con tus propias credenciales.

1. POST /api/cpe/generar

→ recibes XML firmado

2. Tu sistema envía a SUNAT

Flujo A Firma + Envío recomendado

Smart PSE firma el XML y lo envía a SUNAT. Recibes el CDR directamente en una sola llamada.

1. POST /api/cpe/procesar

→ recibes XML firmado + CDR

Prerequisito: antes de usar los endpoints CPE, debes crear la empresa con la API de gestión y obtener sus credenciales_cpe (usuario_secundaria + token_acceso). Esas credenciales se usan en el token CPE de cada empresa.

POST

Obtener token CPE

/api/auth/cpe/token

Genera un JWT de corta duración (10 min) para una empresa específica. Usa las credenciales_cpe que obtienes al crear o consultar la empresa.

POST /api/auth/cpe/token
Content-Type: application/json

{
  "usuario":  "AB3KPQR9",   // usuario_secundaria de la empresa
  "password": "MX7TNVQG"   // token_acceso de la empresa
}

// Respuesta 200
{
  "token_acceso": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expira_en": 600
}

POST

Solo firmar — Flujo B

/api/cpe/generar

Firma el XML con el certificado PSE y devuelve el ZIP firmado listo para enviar a SUNAT. Tu sistema es responsable del envío y de recibir el CDR.

POST /api/cpe/generar
Authorization: Bearer {token_acceso}
Content-Type: application/json

{
  "nombre_archivo":    "20123456789-01-F001-00000001",
  "contenido_archivo": "base64(xml_sin_firmar)"
}

// Respuesta 200
{
  "estado":      200,
  "mensaje":     "XML firmado correctamente",
  "xml":         "base64(zip_firmado)",  ← envía este ZIP a SUNAT
  "codigo_hash": "Pz3R9mKjT..."
}

// Entorno demo (beta SUNAT)
POST /api/cpe/generar-demo

POST

Firmar + Enviar a SUNAT — Flujo A

/api/cpe/procesar

Firma el XML y lo envía a SUNAT en una sola llamada. Devuelve el XML firmado y el CDR. Para resúmenes (RC/RA/RR) devuelve un ticket que debes consultar después.

POST /api/cpe/procesar
Authorization: Bearer {token_acceso}
Content-Type: application/json

{
  "nombre_archivo":    "20123456789-01-F001-00000001",
  "contenido_archivo": "base64(xml_sin_firmar)"
}

// Respuesta 200 — aceptado
{
  "estado":        200,
  "mensaje":       "Aceptado por SUNAT",
  "xml_firmado":   "base64(zip_firmado)",
  "codigo_hash":   "Pz3R9mKjT...",
  "cdr":           "base64(xml_cdr)",
  "rechazado":     false,
  "observaciones": null,
  "errores":       null,
  "ticket":        null
}

// Respuesta — resumen asíncrono (RC/RA/RR)
{
  "estado":   200,
  "mensaje":  "Resumen enviado, consulte el ticket",
  "ticket":   "20123456789-RC-20260410-1-001",
  "rechazado": false
}

// Entorno demo (beta SUNAT)
POST /api/cpe/procesar-demo

GET

Consultar ticket (resúmenes)

/api/cpe/consultar/{nombre_archivo}

Consulta el estado de un resumen asíncrono (RC/RA/RR) usando el ticket devuelto por /procesar. Repite la consulta hasta obtener "estado": 200.

GET /api/cpe/consultar/20123456789-RC-20260410-1
Authorization: Bearer {token_acceso}

// Respuesta 200 — procesado
{
  "estado":    200,
  "mensaje":   "Procesado",
  "cdr":       "base64(xml_cdr)",
  "rechazado": false
}

// Respuesta 202 — aún en proceso (reintenta en unos segundos)
{
  "estado":  202,
  "mensaje": "En proceso"
}

POST

Guías de Remisión Electrónicas (GRE)

/api/cpe/procesar · /api/cpe/enviar

doc_type 09 Guía Remitente

Emitida por quien despacha la mercancía.

RUC-09-T001-00000001

doc_type 31 Guía Transportista

Emitida por la empresa de transporte.

RUC-31-V001-00000001

Ambos tipos usan el mismo endpoint y requieren exactamente los mismos 4 campos adicionales. A diferencia de facturas y boletas, las guías no van por SOAP — SUNAT exige el envío vía API REST con OAuth2 del propio RUC emisor, por lo que el PSE no puede enviarlas con su certificado propio.

Campo en el request	Descripción	Equivalente en panel
sol_user	RUC + usuario secundario SOL. Ej: `20611544791MIUSUARIO`	SOAP Usuario
sol_password	Contraseña del usuario secundario SOL	SOAP Password
client_id_sunat	Client ID generado en SUNAT API Hub	Client ID
client_secret_sunat	Clave del Client ID	Client Secret (Clave)

¿Cómo obtener Client ID y Client Secret?

Ingresa a sunat.gob.pe → Operaciones en Línea (SOL) con el RUC emisor → busca API SUNAT → Gestión Credenciales de API SUNAT

Completa el formulario "Registre su aplicación":

• Nombre de su aplicación: cualquier nombre (ej. MiSistema)
• URL de su aplicación: cualquier URL válida (ej. https://misistemafacturacion.com)
• Marcar: GRE Emision de Comprobantes /v1/contribuyente/gem
• Alcance: Desktop

Haz clic en Guardar. SUNAT genera el ID (client_id_sunat) y la CLAVE (client_secret_sunat). Guárdalos en un lugar seguro.

El usuario secundario SOL (sol_user) debe tener habilitado el perfil "Envío de Guías de Remisión Electrónicas". Si no existe, créalo en SOL → Mis operaciones en línea → Usuarios secundarios.

⏱ Espera ~2 horas después de registrar la aplicación antes de hacer el primer envío. SUNAT tarda en activar las credenciales.

// ── Guía Remitente (doc_type 09) ────────────────────────────
POST /api/cpe/procesar
Authorization: Bearer {token_acceso}
Content-Type: application/json

{
  "nombre_archivo":       "20611544791-09-T001-00000001",
  "contenido_archivo":    "base64(xml_sin_firmar)",
  "environment":          "produccion",
  "sol_user":             "20611544791MIUSUARIO",
  "sol_password":         "MiClaveSOL",
  "client_id_sunat":      "abc123xyz...",
  "client_secret_sunat":  "secret456..."
}

// ── Guía Transportista (doc_type 31) ─────────────────────────
// Exactamente el mismo request, solo cambia el nombre_archivo:

{
  "nombre_archivo":       "20611544791-31-V001-00000001",
  "contenido_archivo":    "base64(xml_sin_firmar)",
  "environment":          "produccion",
  "sol_user":             "20611544791MIUSUARIO",
  "sol_password":         "MiClaveSOL",
  "client_id_sunat":      "abc123xyz...",
  "client_secret_sunat":  "secret456..."
}

// ── Respuesta 200 — aceptado (igual para ambos tipos) ─────────
{
  "estado":    200,
  "mensaje":   "Aceptado por SUNAT",
  "cdr":       "base64(xml_cdr)",
  "rechazado": false,
  "ticket":    null
}

// ── Si ya tienes el XML firmado, usa /enviar ──────────────────
POST /api/cpe/enviar
{
  "nombre_xml_firmado":    "20611544791-31-V001-00000001",
  "contenido_xml_firmado": "base64(xml_firmado)",
  "environment":           "produccion",
  "sol_user":             "20611544791MIUSUARIO",
  "sol_password":         "MiClaveSOL",
  "client_id_sunat":      "abc123xyz...",
  "client_secret_sunat":  "secret456..."
}

// En modo demo los 4 campos son opcionales → /api/cpe/procesar-demo

Importante: sin los 4 campos, Smart PSE responde HTTP 422 "Las guías de remisión requieren client_id_sunat, client_secret_sunat, sol_user y sol_password del tenant". Esto aplica tanto al flujo A (/procesar) como al flujo B (/enviar).

URL base

https://panel.smartpse.pe

Rutas canónicas bajo /api/v1/. Las rutas legacy /api/empresas/ siguen funcionando por compatibilidad.

Autenticación

Todas las peticiones deben incluir tu API Token en el header Authorization. Encuéntralo en tu panel en Configuraciones → API Token.

Authorization: Bearer {TU_API_TOKEN}

Nota: este es el API Token de gestión de empresas (tu cuenta Smart PSE). No confundir con las credenciales CPE de cada empresa (usuario + token para firmar documentos).

GET

Listar empresas

/api/v1/companies

Query params opcionales: search (RUC o razón social), environment (demo / produccion), per_page (máx 100, default 15), page

GET /api/v1/companies?search=20611544791&per_page=1
Authorization: Bearer {TU_API_TOKEN}

// Respuesta 200
{
  "success": true,
  "data": {
    "data": [
      {
        "id": 3,
        "ruc": "20611544791",
        "razon_social": "FACTUSMART E.I.R.L.",
        "environment": "produccion",
        "servidor": "PRODUCCIÓN",
        "active": true,
        "estado": "ACTIVO",
        "start_date": "2025-01-01",
        "end_date": null,
        "fecha_inicio": "2025-01-01",
        "fecha_fin": null,
        "sin_limite_fecha": true,
        "firmas_usadas": 45,
        "credenciales_cpe": {
          "usuario_secundaria": "FURZQQ7F",
          "token_acceso": "379VMR6U"
        }
      }
    ],
    "total": 1,
    "current_page": 1,
    "last_page": 1
  }
}

GET

Ver empresa

/api/v1/companies/{id}

GET /api/v1/companies/3
Authorization: Bearer {TU_API_TOKEN}

// Respuesta 200
{
  "success": true,
  "data": {
    "id": 3,
    "ruc": "20611544791",
    "razon_social": "FACTUSMART E.I.R.L.",
    "environment": "produccion",
    "servidor": "PRODUCCIÓN",
    "active": true,
    "estado": "ACTIVO",
    "credenciales_cpe": {
      "usuario_secundaria": "FURZQQ7F",
      "token_acceso": "379VMR6U"
    }
  }
}

POST

Crear empresa

/api/v1/companies

Al crear, se generan automáticamente las credenciales CPE (usuario_secundaria y token_acceso). Si razon_social no se envía, se busca automáticamente por RUC. Si ya existe la empresa para tu cuenta, devuelve 200 con los datos actuales (idempotente).

POST /api/v1/companies
Content-Type: application/json
Authorization: Bearer {TU_API_TOKEN}

{
  "ruc": "20123456789",              // requerido, 11 dígitos
  "razon_social": "MI EMPRESA SAC",  // opcional — se auto-busca por RUC si se omite
  "environment": "produccion",       // opcional: "demo" (default) o "produccion"
  "servidor": "PRODUCCIÓN",          // alias legacy: "PRODUCCIÓN" o "DEMO"
  "start_date": "2025-01-01",        // opcional — default: hoy
  "end_date": "2025-12-31"           // opcional — omitir = sin límite
}

// Respuesta 201 (empresa nueva)
{
  "success": true,
  "message": "Empresa creada",
  "data": {
    "id": 7,
    "ruc": "20123456789",
    "razon_social": "MI EMPRESA SAC",
    "environment": "demo",
    "servidor": "DEMO",
    "active": true,
    "estado": "ACTIVO",
    "credenciales_cpe": {
      "usuario_secundaria": "AB3KPQR9",
      "token_acceso": "MX7TNVQG"
    }
  }
}

// Respuesta 200 (empresa ya existente — mismas credenciales)
{
  "success": true,
  "message": "Empresa ya existente",
  "data": { ... }
}

PUT

Actualizar empresa

/api/v1/companies/{id}

Solo envía los campos que deseas modificar.

PUT /api/v1/companies/7
Content-Type: application/json
Authorization: Bearer {TU_API_TOKEN}

{
  "razon_social": "NUEVO NOMBRE SAC",
  "environment": "produccion",
  "end_date": "2026-12-31"
}

// Respuesta 200
{
  "success": true,
  "message": "Empresa actualizada",
  "data": { ... }
}

PATCH

Activar / Desactivar

/api/v1/companies/{id}/activation

Alterna el estado entre ACTIVO e INACTIVO. No requiere body.

PATCH /api/v1/companies/7/activation
Authorization: Bearer {TU_API_TOKEN}

// Respuesta 200
{
  "success": true,
  "message": "Empresa INACTIVO",
  "data": { "id": 7, "active": false, "estado": "INACTIVO" }
}

DELETE

Eliminar empresa

/api/v1/companies/{id}

DELETE /api/v1/companies/7
Authorization: Bearer {TU_API_TOKEN}

// Respuesta 200
{
  "success": true,
  "message": "Empresa eliminada"
}

Códigos de error

HTTP	Causa
401	Token inválido o faltante
422	Datos inválidos (RUC mal formado, campo requerido faltante)
404	Empresa no encontrada o no pertenece a tu cuenta
500	Error interno — contacta soporte

¿Listo para integrar?

Crea tu cuenta gratis y obtén tu API Token en segundos. Sin tarjeta de crédito.

Crear cuenta gratis