Clave SOL del principal

Carga el usuario y la clave SOL del usuario principal para que los trámites ante SUNAT se hagan solos.

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

Consideraciones

Opcional. Sin ella la empresa funciona igual: los trámites los hace el contribuyente a mano en el portal de SUNAT, y el botón «Verificar altas SUNAT» del panel los comprueba.
Tiene que ser el usuario principal: los menús 11.9.6.1.1 (autorizar el PSE) y 11.14.1.1.1 (vincular el OSE) no existen para un usuario secundario.
Los trámites corren en segundo plano: la respuesta los muestra en pending y GET /v1/companies/{ruc} los ve pasar a done — o a error, con el motivo de SUNAT en el panel.
Solo se hacen los que apliquen a la empresa: el PSE si firmamos nosotros, el OSE si sale por nuestro OSE. Los que no aplican vienen null.
La clave se guarda cifrada y nunca se devuelve: la respuesta solo dice sol_credentials: true.
También se puede mandar al crear la empresa, con sol_username y sol_password en POST /v1/companies.

PATCHhttps://api.xmlperu.dev/v1/companies/{ruc}/sol-credentialsCopiar

Para qué sirve

Antes de emitir, el contribuyente tiene que hacer uno o dos trámites en el portal de SUNAT con su clave SOL:

Trámite	Menú SOL	Cuándo hace falta
Autorizar el PSE	11.9.6.1.1	Si firmamos nosotros (`signing: provider`)
Vincular el OSE	11.14.1.1.1	Si sale por nuestro OSE (`destination: provider_ose`)

Sin ellos SUNAT rechaza los comprobantes, y el mensaje no dice cuál falta. Con la clave del principal cargada, los hacemos nosotros: se abre una sesión en el portal, se consulta si el trámite ya existe y, si no, se registra.

Cómo se sigue

Los trámites tardan segundos contra el portal de SUNAT, así que la respuesta no espera: vuelve con sunat_procedures en pending y se consultan después:

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

Estado	Qué significa
`null`	No aplica a esta empresa (no hay nada que tramitar)
`not_started`	Aplica y nadie lo ha hecho todavía
`pending`	En curso, o falló por algo temporal y se reintentará
`done`	Consultado en SUNAT y confirmado
`error`	Credenciales o permisos: hay que revisar. El motivo exacto se ve en el panel

Si el cliente ya lo hizo a mano

No pasa nada por cargar la clave igual: antes de registrar nada se consulta, y si el trámite ya figura en SUNAT se marca done sin repetirlo.

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`.

Parámetros de URL

Name	Type	Description
ruc*	string	RUC de 11 dígitos de la empresa.

Body

Name	Type	Description
sol_username*	string	Usuario SOL del principal (no el RUC: el usuario).
sol_password*	string	Clave SOL del principal.

Ejemplo de solicitud

Copiar

curl -X PATCH https://api.xmlperu.dev/v1/companies/20123456789/sol-credentials \
  -H "Authorization: Bearer $TOKEN_CUENTA" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "sol_username": "MIUSUARIO",
  "sol_password": "********"
}'

Copiar

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.xmlperu.dev/v1/companies/20123456789/sol-credentials');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token_cuenta,
    'Accept: application/json',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "sol_username": "MIUSUARIO",
  "sol_password": "********"
}
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/20123456789/sol-credentials', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${TOKEN_CUENTA}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "sol_username": "MIUSUARIO",
      "sol_password": "********"
  }),
});

const data = await res.json();

Copiar

import requests

TOKEN_CUENTA = "pega-aqui-tu-token"

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

payload = {
    "sol_username": "MIUSUARIO",
    "sol_password": "********"
}

res = requests.patch("https://api.xmlperu.dev/v1/companies/20123456789/sol-credentials", json=payload, headers=headers)
data = res.json()

Respuesta

200 Guardadaapplication/json

{
  "success": true,
  "message": "Clave SOL guardada. Los trámites ante SUNAT se están gestionando.",
  "data": {
    "company": {
      "ruc": "20123456789",
      "business_name": "MI EMPRESA SAC",
      "plan_type": "01",
      "environment": "02",
      "environment_name": "production",
      "destination": "provider_ose",
      "signing": "provider",
      "sol_credentials": true,
      "sunat_procedures": { "pse": "pending", "ose": "pending" },
      "is_active": true
    }
  }
}

422 Datos inválidosapplication/json

{
  "success": false,
  "message": "The sol password field is required.",
  "errors": { "sol_password": ["The sol password field is required."] }
}