XmlPeruDevDocs

Migración desde otro proveedor

Cómo migrar desde otro proveedor con un cambio mínimo, y qué ganas al pasar a la API v1.

Si ya integraste con otro proveedor, no necesitas reescribir tu integración. Ofrecemos una capa de compatibilidad que replica los endpoints más habituales del mercado: los mismos paths y los mismos nombres de campo.

El flujo es el que ya conoces —firmar y enviar— y el resultado de SUNAT llega en la respuesta del envío, como en tu plataforma actual.

En paralelo, exponemos una API v1 más completa (nombres en inglés, external_id, entrada por JSON además de XML, y validaciones más estrictas). Puedes migrar primero por compatibilidad y adoptar v1 cuando quieras.

Dos caminos

Compatibilidad (migración) API v1 (recomendada)
Entrada XML UBL ya armado JSON — el UBL lo generamos nosotros
Firmar POST /api/cpe/generar POST /v1/cpe — firma y encola
Enviar POST /api/cpe/enviar — devuelve el CDR — (va solo)
Identificador nombre_archivo (RUC-TIPO-SERIE-NUMERO) external_id (UUID estable)
Validaciones Estructura básica XSD + reglas SUNAT antes de enviar
Autenticación Login usuario/contraseña o token Token de empresa (cpe:sign)

El flujo: firmar, enviar

Es el mismo que ya usas, y el que comparten todas las plataformas del mercado:

  1. POST /api/cpe/generar — firma tu XML. El comprobante queda válido y lo puedes imprimir.
  2. POST /api/cpe/enviar — lo manda a SUNAT y te devuelve el CDR en la respuesta.

No hay un tercer paso obligatorio. La consulta existe para dos casos concretos:

  • Resúmenes y guías. SUNAT los resuelve por ticket y no devuelve CDR al enviarlos. Eso pasa en cualquier plataforma, así que ahí ya consultabas.
  • Si SUNAT no contesta a tiempo. Entonces enviar responde 202 y te dice justo eso. Tu comprobante está firmado y el envío sigue su curso: consultas más tarde, o dejas que te avise el webhook. No lo reenvíes — podrías duplicarlo.

:::note[Si tu plataforma tenía «firmar y enviar» en una sola llamada] Solo dos de las cuatro plataformas del mercado lo ofrecían, con nombres distintos (procesar, generarenviar). Nosotros seguimos el camino que comparten las cuatro, así que esa llamada se convierte en dos: primero generar, luego enviar con el external_id que te devolvió.

Es el único cambio de código de toda la migración. El paquete PHP lo hace por ti en un solo método. :::

1. Autenticación

Tienes dos formas, elige la que menos toque tu código actual:

a) Login con usuario y contraseña

Si tu proveedor actual trabaja así, aquí es igual: intercambias credenciales por un token.

b) Token directo (API-first)

Si prefieres saltarte el login, usa el token de empresa con ámbito cpe:sign como Authorization: Bearer. Es lo que recomendamos para integraciones nuevas.

2. Endpoints equivalentes

Los paths son los más extendidos del mercado, así que lo más probable es que ya reconozcas el tuyo por su nombre:

Acción Nuestro endpoint compat Si el tuyo se llama
Firmar POST /api/cpe/generar generar
Enviar y recibir el CDR POST /api/cpe/enviar enviar
Consultar estado (ticket) GET /api/cpe/consultar/{filename} consultar
Firmar y mandar de una vez — (son generar + enviar) procesar · generarenviar

Prefijo de entorno en la ruta

Si tu integración actual mete el entorno en la ruta (/pro/demo/..., /pro/produccion/...), también funciona:

POST /api/pro/demo/cpe/enviar
POST /api/pro/produccion/cpe/enviar

Y lo tomamos en serio. Ese segmento no se ignora: es lo que tú afirmas, y lo comprobamos contra el entorno de tu empresa. Si no coinciden respondemos 409 y no se emite nada, con los dos entornos en la respuesta para que sepas cuál corregir.

Es a propósito. Sin esa comprobación, un desacuerdo entre tu sistema y el nuestro no se nota hasta que el daño está hecho: emitir comprobantes reales creyendo que pruebas, o creer que facturaste sin haberlo hecho.

Sufijo -demo

Como en esos servicios, cada endpoint tiene su variante -demo (/api/cpe/generar-demo, /api/cpe/enviar-demo, …). No es obligatoria — pero si la usas, también es una afirmación: si tu empresa está en producción, responde 409.

Con el sufijo solo puedes decir «demo». Para afirmar producción usa el prefijo /pro/produccion/..., que es el único que sabe decirlo.

Comprueba antes de emitir

La forma más barata de no llevarte una sorpresa:

  • GET /v1/me te dice en qué entorno está tu empresa, con tu token de firma.
  • El login devuelve entorno en cada respuesta.
  • En demo, el texto de las respuestas llega con marca [DEMO].

3. Formato del nombre_archivo

Igual que el estándar del sector: RUC-TIPO-SERIE-NUMERO, sin extensión.

20123456789-03-B001-777
│           │  │    └ correlativo
│           │  └───── serie
│           └──────── tipo (01 factura, 03 boleta, 07 NC, 08 ND, 09/31 GRE, RC/RA/RR)
└──────────────────── RUC del emisor (debe coincidir con la empresa del token)

4. Respuesta con doble juego de campos

Para no romper integraciones existentes, la respuesta trae los campos en español (estado, mensaje, observaciones, errores) y su equivalente en inglés (state_label, message, notes, errors). El cdr viene en base64. Usa los que ya lees hoy y migra a los nuevos cuando quieras.

Ver el detalle de estados y rechazos en Errores y respuestas.

El segundo paso: dejar de armar el XML

Migrar no tiene por qué ser una sola decisión. Son dos, y conviene separarlas.

Primero, cambias de proveedor. Apuntas a nuestra URL base y tu código sigue igual: mismos paths, mismos nombres de campo, mismo XML que ya sabes armar. Eso es todo lo que cubre esta guía.

Después, si quieres, dejas de armar el XML. Con POST /v1/cpe envías JSON y el UBL lo generamos nosotros: la estructura, los totales, los tributos, las leyendas. Lo validamos contra el XSD y las reglas de SUNAT antes de firmar, así que los errores de estructura los ves en la respuesta y no en un rechazo.

Lo que dejas de mantener no es poco: plantillas UBL 2.1, catálogos de SUNAT, y las actualizaciones cada vez que cambia una regla.

El segundo paso es opcional y no tiene fecha. Puedes quedarte en la superficie de compatibilidad indefinidamente — no la vamos a retirar.