Documentación API

Introducción

URL base

https://mblapirest.com/pse-api/v1

Cómo empezar

1. Pídenos que activemos tu cuenta de revendedor. Te entregamos un token de cuenta una sola vez — guárdalo, no se vuelve a mostrar.
2. Con ese token, registra cada RUC de tu cliente: POST /companies. La respuesta trae las credenciales_cpe de esa empresa (también una sola vez).
3. Con esas credenciales, pide un token corto de firma: POST /auth/cpe/token.
4. Con el token corto, firma (POST /cpe/generar) o firma y envía a SUNAT (POST /cpe/procesar) cada comprobante.
5. Para anular, recuperar un CDR perdido o consultar un envío que quedó en proceso, ver Gestión de lo ya emitido.

Ambientes

Cada empresa (RUC) tiene un environment propio: demo o produccion. Además, /cpe/generar y /cpe/procesar tienen variantes explícitas -demo para pruebas sin tocar el ambiente de producción de SUNAT.

Qué tipos de comprobante cubre cada endpoint

Certificado con el que se firma

Por defecto (modo: "pse_directo") firmamos con nuestro certificado compartido — no necesitas subir nada. Si prefieres usar el certificado propio de tu cliente para un RUC puntual, súbelo con POST /companies/{id}/certificado (ver Empresas).

Autenticación CPE

El token que usas contra /cpe/* para firmar/enviar comprobantes de una empresa puntual — distinto del token de cuenta que administra tus empresas (ver Autenticación de cuenta, en Gestión de empresas).

Obtener el token corto

POST/auth/cpe/token — pide un token de 10 minutos para firmar/enviar en nombre de una empresa puntual. Mismos nombres de campo que Smart PSE, si vienes de ahí.

curl -X POST https://mblapirest.com/pse-api/v1/auth/cpe/token \
  -H "Content-Type: application/json" \
  -d '{"usuario":"a1b2c3d4e5f6...","password":"9f8e7d6c..."}'

{ "token_acceso": "eyJlbXByZXNhX2lkIjoxMiwiZXhwIjoxNzM4NTAwMDAwfQ.3f9a1c..." }

Úsalo igual que el token de cuenta, en la cabecera Authorization: Bearer, contra /cpe/generar o /cpe/procesar. Vencido a los 10 minutos: si te da 401, vuelve a pedir uno.

Errores de autenticación

Solo firmar — cpe/generar

POST/cpe/generar (o /cpe/generar-demo para pruebas) — SOLO firma el XML que le mandes, no lo transmite a SUNAT. Sirve para cualquier tipo de comprobante, incluidas boletas y guías. Usa tu token corto de empresa.

Parámetros

curl -X POST https://mblapirest.com/pse-api/v1/cpe/generar \
  -H "Authorization: Bearer TU_TOKEN_CORTO" -H "Content-Type: application/json" \
  -d '{
    "nombre_archivo": "20123456789-01-F001-123",
    "contenido_archivo": "PD94bWwgdmVyc2lvbj0i..."
  }'

Respuesta

{
  "estado": 200,
  "mensaje": "XML firmado correctamente.",
  "xml": "PD94bWwgdmVyc2lvbj0i...",
  "codigo_hash": "abc123..."
}

Errores comunes

Firmar + Enviar — cpe/procesar

POST/cpe/procesar (o /cpe/procesar-demo para pruebas) — firma el XML y lo transmite a SUNAT en la misma llamada. Usa tu token corto de empresa.

Parámetros comunes

Factura, Nota de Crédito, Nota de Débito (01/07/08)

Envío directo por SOAP sendBill — la respuesta trae el CDR de SUNAT en la misma llamada.

curl -X POST https://mblapirest.com/pse-api/v1/cpe/procesar \
  -H "Authorization: Bearer TU_TOKEN_CORTO" -H "Content-Type: application/json" \
  -d '{
    "nombre_archivo": "20123456789-01-F001-123",
    "contenido_archivo": "PD94bWwgdmVyc2lvbj0i...",
    "tipo_documento": "01",
    "sol_user": "MIUSUARIO",
    "sol_password": "miclavesol"
  }'

{
  "estado": 200,
  "mensaje": "La Factura numero F001-123, ha sido aceptada",
  "xml_firmado": "PD94bWwgdmVyc2lvbj0i...",
  "cdr": "UEsDBBQA...",
  "rechazado": false
}

rechazado: true cuando SUNAT devuelve un CDR de rechazo — sigue viniendo en cdr, con el motivo en mensaje.

Boleta (03)

SUNAT no acepta boletas por sendBill: se informan vía Resumen Diario (RC), que es asíncrono (SUNAT devuelve un ticket, el CDR se consulta después). Aquí se arma un RC de una sola boleta por llamada — no hace falta acumular varias del día en el mismo resumen. Los datos de la línea (moneda, cliente, desglose de impuestos) se leen directamente del XML que mandas: no hay campos adicionales que llenar.

Mismos parámetros que arriba, con tipo_documento: "03". La respuesta espera hasta ~8 segundos por el resultado del ticket:

{
  "estado": 200,
  "mensaje": "...",
  "xml_firmado": "PD94bWwgdmVyc2lvbj0i...",
  "ticket": "2026090200001234",
  "cdr": "UEsDBBQA...",
  "rechazado": false
}

Guía de Remisión (09/31)

SUNAT tampoco acepta guías por SOAP: usan su API REST GRE ("GRE 2.0"), autenticada con OAuth2 del propio RUC emisor — mismo criterio que la Clave SOL: nunca credenciales nuestras. Por eso el cuerpo exige dos campos más:

curl -X POST https://mblapirest.com/pse-api/v1/cpe/procesar \
  -H "Authorization: Bearer TU_TOKEN_CORTO" -H "Content-Type: application/json" \
  -d '{
    "nombre_archivo": "20123456789-09-T001-45",
    "contenido_archivo": "PD94bWwgdmVyc2lvbj0i...",
    "tipo_documento": "09",
    "sol_user": "MIUSUARIO",
    "sol_password": "miclavesol",
    "client_id_sunat": "...",
    "client_secret_sunat": "..."
  }'

También asíncrono (ticket + espera acotada), misma forma de respuesta que boletas — consulta el ticket con /cpe/consultar-ticket.

Errores comunes

Gestión de lo ya emitido

Tres endpoints para lo que pasa después de emitir: anular, recuperar un CDR perdido, o consultar un envío asíncrono que quedó "en proceso". Usa tu token corto de empresa.

Anular un comprobante (Comunicación de Baja)

POST/cpe/anular (o /cpe/anular-demo)

Igual que factura/NC/ND: tú armas el XML UBL completo (VoidedDocuments) declarando qué comprobante anulas y por qué — nosotros solo lo firmamos y enviamos. Es asíncrono (ticket + espera acotada), mismo mecanismo que el Resumen Diario de boletas.

curl -X POST https://mblapirest.com/pse-api/v1/cpe/anular \
  -H "Authorization: Bearer TU_TOKEN_CORTO" -H "Content-Type: application/json" \
  -d '{"nombre_archivo":"20123456789-RA-20260902-1","contenido_archivo":"PD94bWwg...","sol_user":"...","sol_password":"..."}'

{
  "estado": 200,
  "mensaje": "...",
  "xml_firmado": "PD94bWwg...",
  "ticket": "2026090200005678",
  "cdr": "UEsDBBQA...",
  "rechazado": false
}

Consultar un ticket pendiente

POST/cpe/consultar-ticket

Cuando una boleta, anulación o guía quedó "en proceso" (sin cdr en la respuesta original), vuelve a consultar el mismo ticket aquí.

curl -X POST https://mblapirest.com/pse-api/v1/cpe/consultar-ticket \
  -H "Authorization: Bearer TU_TOKEN_CORTO" -H "Content-Type: application/json" \
  -d '{"ticket":"2026090200001234","tipo_documento":"03","sol_user":"...","sol_password":"..."}'

Misma forma de respuesta que el envío original: si sigue en proceso, estado: 0 sin cdr; si ya resolvió, trae cdr y rechazado.

Recuperar el CDR de una factura, NC o ND

POST/cpe/recuperar-cdr

Solo para 01/07/08 (envío inmediato por sendBill) — si perdiste la respuesta de /cpe/procesar, la vuelves a pedir por serie y número. Boletas, guías y anulaciones son asíncronas: para esas usa /cpe/consultar-ticket con el ticket.

curl -X POST https://mblapirest.com/pse-api/v1/cpe/recuperar-cdr \
  -H "Authorization: Bearer TU_TOKEN_CORTO" -H "Content-Type: application/json" \
  -d '{"tipo_documento":"01","serie":"F001","numero":123,"sol_user":"...","sol_password":"..."}'

{
  "estado": "aceptado",
  "mensaje": "El comprobante existe y esta aceptado.",
  "cdr": "UEsDBBQA...",
  "rechazado": false
}

estado puede ser aceptado, rechazado, anulado, no_existe o error.

Autenticación de cuenta

Dos niveles de credenciales, uno arriba del otro:

Cómo se usa

Se envía en la cabecera Authorization:

curl https://mblapirest.com/pse-api/v1/companies \
  -H "Authorization: Bearer TU_TOKEN_DE_CUENTA"

Errores de autenticación

Empresas

Cada RUC de tu cliente es una "empresa" en tu cuenta. Todos estos endpoints usan tu token de cuenta.

Registrar un RUC

POST/companies

Idempotente por RUC: si ese RUC ya está registrado en tu cuenta, actualiza en vez de duplicar (para cambiar de ambiente, ver también el PUT más abajo).

curl -X POST https://mblapirest.com/pse-api/v1/companies \
  -H "Authorization: Bearer TU_TOKEN_DE_CUENTA" -H "Content-Type: application/json" \
  -d '{"ruc":"20123456789","razon_social":"Mi Cliente S.A.C.","environment":"demo"}'

{
  "data": {
    "id": 12,
    "ruc": "20123456789",
    "razon_social": "Mi Cliente S.A.C.",
    "modo": "pse_directo",
    "environment": "demo",
    "credenciales_cpe": {
      "usuario_secundaria": "a1b2c3d4e5f6...",
      "token_acceso": "9f8e7d6c..."
    }
  }
}

Listar tus empresas

GET/companies

curl https://mblapirest.com/pse-api/v1/companies \
  -H "Authorization: Bearer TU_TOKEN_DE_CUENTA"

{ "data": [ { "id": 12, "ruc": "20123456789", "razon_social": "Mi Cliente S.A.C.", "modo": "pse_directo", "environment": "demo" } ] }

Ver una empresa

GET/companies/{id}

curl https://mblapirest.com/pse-api/v1/companies/12 \
  -H "Authorization: Bearer TU_TOKEN_DE_CUENTA"

{ "data": { "id": 12, "ruc": "20123456789", "razon_social": "Mi Cliente S.A.C.", "modo": "pse_directo", "environment": "demo" } }

Cambiar ambiente o razón social

PUT/companies/{id}

Por ahora solo actualiza environment y/o razon_social — el ambiente es un atributo mutable de la empresa, no una empresa nueva.

curl -X PUT https://mblapirest.com/pse-api/v1/companies/12 \
  -H "Authorization: Bearer TU_TOKEN_DE_CUENTA" -H "Content-Type: application/json" \
  -d '{"environment":"produccion"}'

Activar / desactivar

PATCH/companies/{id}/activation — sin body.

Alterna el estado entre activo e inactivo. Una empresa inactiva no puede pedir token corto ni firmar — /auth/cpe/token y todo /cpe/* le responden 401.

curl -X PATCH https://mblapirest.com/pse-api/v1/companies/12/activation \
  -H "Authorization: Bearer TU_TOKEN_DE_CUENTA"

{ "mensaje": "Empresa INACTIVO", "data": { "id": 12, "ruc": "20123456789", ... } }

Eliminar una empresa

DELETE/companies/{id}

Borra la empresa y sus credenciales_cpe de forma definitiva — no se puede deshacer. Los documentos que ya firmaste con ella quedan intactos en tu historial (guardan su propio RUC/serie/número), pero ya no podrás firmar ni consultar tickets a nombre de esa empresa.

curl -X DELETE https://mblapirest.com/pse-api/v1/companies/12 \
  -H "Authorization: Bearer TU_TOKEN_DE_CUENTA"

{ "mensaje": "Empresa eliminada" }

Subir certificado propio

POST/companies/{id}/certificado — multipart/form-data.

Opcional. Sin esto, esta empresa firma con nuestro certificado compartido (modo: "pse_directo"). Si tu cliente tiene su propio certificado y prefieres usarlo solo para él, súbelo aquí — pasa a modo: "propio".

curl -X POST https://mblapirest.com/pse-api/v1/companies/12/certificado \
  -H "Authorization: Bearer TU_TOKEN_DE_CUENTA" \
  -F "certificado=@/ruta/certificado.pfx" \
  -F "password_certificado=mi_clave"

Referencia de endpoints y errores

Todos los endpoints en una sola tabla, más el significado de cada campo de respuesta y los códigos de error — para integrar sin tener que ir sección por página ni escribirnos.

Todos los endpoints

Campos de la respuesta

Facturas/NC/ND (01/07/08) vs. boletas/anulación/guías (03/RA/09/31)

Los primeros tres van por sendBill: la respuesta de /cpe/procesar ya trae cdr de una vez, aceptado o rechazado. Los otros cuatro son asíncronos — SUNAT los procesa aparte, así que /cpe/procesar (o /cpe/anular) solo confirma el envío y devuelve un ticket; nosotros esperamos hasta 8 segundos por si resuelve rápido, pero si sigue en proceso tu sistema debe volver a consultar ese ticket con /cpe/consultar-ticket más tarde. Si tu sistema no lo hace, el documento se queda "en proceso" indefinidamente aunque SUNAT ya lo haya resuelto — es la causa más común de comprobantes que parecen atascados.

Códigos HTTP de error

Errores más comunes al integrar

Consumo

Cada empresa activa consume contra el plan de tu cuenta. Revisa el consumo y el historial de documentos firmados/enviados en tu panel: Mi cuenta → Documentos / Reportes.