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.

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.