Gestión de empresas

Estas operaciones usan un token de cuenta (empresas:manage), no el de firma. Ver Autenticación.

Listar empresas

curl https://api.xmlperu.dev/v1/companies \
  -H "Authorization: Bearer $TOKEN_CUENTA"

Crear una empresa

curl -X POST https://api.xmlperu.dev/v1/companies \
  -H "Authorization: Bearer $TOKEN_CUENTA" -H "Content-Type: application/json" \
  -d '{
    "ruc": "20123456789",
    "business_name": "MI EMPRESA SAC",
    "plan_type": "01",
    "environment": "01"
  }'

Campo	Valores
plan_type	01 por comprobante · 02 por certificado
environment	01 demo · 02 producción

Nota · Si el RUC existe en otra cuenta, la respuesta es 409. Reenvía con "confirm": true para registrarlo de todas formas.

La respuesta incluye el token de firma (cpe:sign) de la empresa, ya generado y listo para emitir en /v1/cpe — así no tienes que pasar por el panel. Se muestra una sola vez: guárdalo.

Nota · No pasa nada — el RUC es único, así que reenviar no duplica la empresa (te avisa que ya existe). Y puedes generar otro token cuando quieras:

curl -X POST https://api.xmlperu.dev/v1/companies/{ruc}/token \
  -H "Authorization: Bearer $TOKEN_CUENTA"

Cambiar el plan

curl -X PATCH https://api.xmlperu.dev/v1/companies/{ruc}/plan \
  -H "Authorization: Bearer $TOKEN_CUENTA" -H "Content-Type: application/json" \
  -d '{ "plan_type": "02" }'

Importante · Al pasar a plan por certificado (02), la empresa necesita un certificado asignado para poder emitir. La vigencia arranca en el primer uso en producción.

Cambiar el entorno

curl -X PATCH https://api.xmlperu.dev/v1/companies/{ruc}/environment \
  -H "Authorization: Bearer $TOKEN_CUENTA" -H "Content-Type: application/json" \
  -d '{ "environment": "02" }'

No se permite volver de producción a demo (respuesta 422).

Cómo trabaja cada empresa

Estos ajustes cambian el comportamiento de sus emisiones. Se configuran una vez y no hace falta repetirlos en cada comprobante.

# Quién manda a SUNAT: nosotros al firmar (por defecto) o tú cuando decidas
curl -X PATCH https://api.xmlperu.dev/v1/companies/{ruc}/sending \
  -H "Authorization: Bearer $TOKEN_CUENTA" -H "Content-Type: application/json" \
  -d '{ "mode": "manual" }'

# Boletas sueltas (por defecto) o esperando el resumen del día
curl -X PATCH https://api.xmlperu.dev/v1/companies/{ruc}/receipts \
  -H "Authorization: Bearer $TOKEN_CUENTA" -H "Content-Type: application/json" \
  -d '{ "mode": "summary" }'

# Si el envío espera el CDR (solo para quien migra de otro proveedor)
curl -X PATCH https://api.xmlperu.dev/v1/companies/{ruc}/response \
  -H "Authorization: Bearer $TOKEN_CUENTA" -H "Content-Type: application/json" \
  -d '{ "mode": "wait" }'

# Dónde avisamos cuando un comprobante queda resuelto
curl -X PATCH https://api.xmlperu.dev/v1/companies/{ruc}/webhook \
  -H "Authorization: Bearer $TOKEN_CUENTA" -H "Content-Type: application/json" \
  -d '{ "url": "https://tu-sistema.com/webhooks/cpe" }'

El detalle de cada uno —qué implica, qué pasa si no lo tocas— está en Quién envía a SUNAT, Cómo se informan las boletas, Cuándo responde el envío y Configurar el webhook.

El webhook es el que más ahorra: sin él hay que consultar en bucle para saber cómo terminó cada comprobante.

Quién firma y por dónde sale

Son dos decisiones distintas y se combinan: quién pone la firma digital, y por dónde sale el comprobante hacia SUNAT. Determinan lo que consume cada emisión y qué trámites hay que hacer en el portal de SUNAT.

Una empresa creada por API nace firmando con nuestro certificado y enviando directo a SUNAT. Es lo que funciona sin configurar nada más. Las otras combinaciones se eligen al crearla (destination, signing) o después:

# Por dónde sale: sunat (por defecto) · own_ose · provider_ose
curl -X PATCH https://api.xmlperu.dev/v1/companies/{ruc}/destination \
  -H "Authorization: Bearer $TOKEN_CUENTA" \
  -d '{"destination": "provider_ose"}'

# Quién firma: provider (por defecto) · external — external exige provider_ose
curl -X PATCH https://api.xmlperu.dev/v1/companies/{ruc}/signing \
  -H "Authorization: Bearer $TOKEN_CUENTA" \
  -d '{"signing": "external"}'

Ver Por dónde sale y Quién firma.

Quién firma

	Qué es	Qué consume
Nuestro certificado	Por defecto. Firmamos nosotros como PSE.	Una firma del plan
Certificado propio	La empresa sube el suyo y firma con su identidad.	Menos que una firma completa — sigue usando la plataforma
Firmado en su sistema	El XML llega ya firmado; solo lo transportamos.	Solo el paquete de envíos por nuestro OSE

El certificado propio se carga por API (Certificado propio) y las otras dos se eligen con signing. En /v1 se leen como provider, own_certificate y external.

Por dónde sale

	Qué necesita
SUNAT directo	Por defecto. Con certificado propio, además el usuario secundario SOL de la empresa
El OSE de la empresa	Sus credenciales de OSE
Nuestro OSE	Consume el paquete de envíos. Ver abajo los dos trámites

Firmado en su sistema va siempre por nuestro OSE. Es lo único que la empresa consume de la plataforma; con otro destino no habría servicio que prestar.

Los trámites ante SUNAT

Antes de emitir, el contribuyente tiene que autorizarnos en el portal de SUNAT con su clave SOL — y no basta un usuario secundario, hace falta el principal:

Trámite	Menú SOL	Cuándo hace falta
Autorizar el PSE	11.9.6.1.1	Solo si firmamos nosotros
Vincular el OSE	11.14.1.1.1	Solo si sale por nuestro OSE

Sin ellos SUNAT rechaza los comprobantes, y el mensaje no dice cuál falta. En el listado del panel se ve el estado de cada uno.

Si se carga el usuario y la clave SOL del principal —en el panel, o por API con PATCH /{ruc}/sol-credentials o al crear la empresa—, los trámites que apliquen se hacen solos. Por API se siguen en sunat_procedures de GET /v1/companies/{ruc}. Si no, se hacen a mano en el portal y el botón «Verificar altas SUNAT» del listado lo comprueba después.

Ojo · Salir por nuestro OSE necesita dos cosas: vincularlo ante SUNAT (automatizable) y tener cuenta en el OSE, que se solicita por su web y tarda unas 24 h. Con una sola de las dos, los envíos rebotan.

Emitir con el certificado de la empresa

Si la empresa tiene su propio certificado digital, puede firmar con él en vez de con el nuestro — y entonces consume menos de su plan.

curl -X POST https://api.xmlperu.dev/v1/companies/{ruc}/certificate \
  -H "Authorization: Bearer $TOKEN_CUENTA" \
  -F "certificate=@mi-certificado.pfx" -F "password=…"

La contraseña se usa para convertirlo y se descarta: no queda guardada. Ver Certificado propio.

Si además emite guías de remisión, lo coherente es registrar también sus credenciales GRE: estaría firmando con su identidad y enviando guías con la nuestra.

Eliminar una empresa

curl -X DELETE https://api.xmlperu.dev/v1/companies/{ruc} \
  -H "Authorization: Bearer $TOKEN_CUENTA"

Solo se puede eliminar una empresa sin movimiento en producción. Al eliminarla se libera su certificado (sin estrenar), se limpian sus datos demo y se revocan sus tokens de firma.

Importante · Si la empresa ya emitió o envió en producción, la respuesta es 422 y no se elimina. Es una acción irreversible.