Crear empresa

Registra un nuevo RUC emisor en la cuenta. El plan y el entorno se pueden cambiar luego.

Autenticación: token Bearer de cuenta (empresas:manage).

Consideraciones

Si el RUC ya está registrado en otra cuenta, responde 409: reenvía con "confirm": true para reclamarlo.
Crea la empresa en el entorno que indiques; recomendado empezar en demo (01) y pasar a producción cuando esté probada.
La respuesta incluye el token de firma de la empresa (ability cpe:sign) ya generado, listo para emitir en /v1/cpe. Se muestra una sola vez: guárdalo.
También devuelve las credenciales de login (usuario/password), por si tu integración obtiene el token con POST /api/auth/cpe/token en vez de usar el token directo. Elige el estilo que ya uses.
Por defecto nace enviando directo a SUNAT y firmando con nuestro certificado: funciona sin configurar nada más.
Con destination y signing eliges desde el alta por dónde sale y quién firma. Firmar fuera (external) exige provider_ose. El certificado propio se carga después, con POST /{ruc}/certificate.
Si mandas la clave SOL del principal, los trámites ante SUNAT (autorizar el PSE, vincular el OSE) arrancan solos en segundo plano; la respuesta los muestra en sunat_procedures. Es opcional.

POSThttps://api.xmlperu.dev/v1/companiesCopiar

Headers

Name	Type	Description
Accept	string	application/json
Content-Type	string	application/json
Authorization	string	Bearer <token>. Genéralo desde tu panel, en `Tokens de API`.

Body

Name	Type	Description
ruc*	string	RUC de 11 dígitos.
business_name*	string	Razón social del emisor.
plan_type*	string	`01` por firma · `02` por certificado.
environment*	string	`01` demo · `02` producción.
destination	string	`sunat` (por defecto) · `own_ose` · `provider_ose`. Ver Por dónde sale.
signing	string	`provider` (por defecto) · `external`. Ver Quién firma.
ose_username	string	Usuario del OSE de la empresa. Obligatorio con `destination: own_ose`.
ose_password	string	Clave del OSE de la empresa. Obligatoria con `destination: own_ose`.
ose_url_production	string	Endpoint de producción del OSE de la empresa. Obligatorio con `destination: own_ose`.
ose_url_demo	string	Endpoint de demo del OSE de la empresa. Obligatorio con `destination: own_ose`.
sol_username	string	Usuario SOL del principal. Con él (y la clave) los trámites ante SUNAT se hacen solos.
sol_password	string	Clave SOL del principal. Van los dos o ninguno.
confirm	boolean	Envíalo en `true` para reclamar un RUC registrado en otra cuenta (tras un `409`).

Ejemplo de solicitud

Copiar

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

Copiar

<?php
$token_cuenta = 'pega-aqui-tu-token';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.xmlperu.dev/v1/companies');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token_cuenta,
    'Accept: application/json',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "ruc": "20123456789",
  "business_name": "MI EMPRESA SAC",
  "plan_type": "01",
  "environment": "01",
  "destination": "sunat",
  "signing": "provider",
  "confirm": false
}
JSON);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

Copiar

const TOKEN_CUENTA = 'pega-aqui-tu-token';

const res = await fetch('https://api.xmlperu.dev/v1/companies', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${TOKEN_CUENTA}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "ruc": "20123456789",
      "business_name": "MI EMPRESA SAC",
      "plan_type": "01",
      "environment": "01",
      "destination": "sunat",
      "signing": "provider",
      "confirm": false
  }),
});

const data = await res.json();

Copiar

import requests

TOKEN_CUENTA = "pega-aqui-tu-token"

headers = {
    "Authorization": f"Bearer {TOKEN_CUENTA}",
    "Accept": "application/json",
}

payload = {
    "ruc": "20123456789",
    "business_name": "MI EMPRESA SAC",
    "plan_type": "01",
    "environment": "01",
    "destination": "sunat",
    "signing": "provider",
    "confirm": false
}

res = requests.post("https://api.xmlperu.dev/v1/companies", json=payload, headers=headers)
data = res.json()

Respuesta

201 Creadaapplication/json

{
  "success": true,
  "message": "Empresa registrada.",
  "data": {
    "company": {
      "ruc": "20123456789",
      "business_name": "MI EMPRESA SAC",
      "plan_type": "01",
      "environment": "01",
      "environment_name": "demo",
      "sending": "automatic",
      "receipts": "individual",
      "response": "wait",
      "destination": "sunat",
      "signing": "provider",
      "sol_credentials": false,
      "sunat_procedures": { "pse": "not_started", "ose": null },
      "bonus": {
          "signatures": 100,
          "signatures_used": 12.4,
          "signatures_left": 87.6
      },
      "is_active": true,
      "created_at": "2026-07-27T10:00:00-05:00"
    },
    "token": {
      "ability": "cpe:sign",
      "plain_text_token": "3|9pW51RgVhQ7LUR0yyHNOo6GCfgBL4kAsEHPxb1QW…",
      "note": "Guárdalo ahora: no se vuelve a mostrar. Úsalo como Bearer (token de empresa) para emitir en /v1/cpe."
    },
    "credentials": {
      "username": "a1b2c3d4",
      "password": "e5f6g7h8"
    }
  }
}

409 RUC en otra cuentaapplication/json

Reenvía la misma petición con "confirm": true para reclamarlo.

{
  "success": false,
  "message": "El RUC ya está registrado en otra cuenta. Confirme para reasignarlo."
}

422 Datos inválidosapplication/json

{
  "success": false,
  "message": "The ruc field must be 11 characters.",
  "errors": {
    "ruc": ["The ruc field must be 11 characters."]
  }
}