Credenciales de guías (GRE)

Registra el acceso OAuth2 propio de la empresa para emitir guías de remisión con su identidad.

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

Consideraciones

Las guías (09, 31) salen por el servicio REST de SUNAT, que usa OAuth2 con credenciales emitidas en SOL a nombre del contribuyente.
Si la empresa las registra, sus guías salen con su acceso. Si no, se usan las del proveedor.
Tiene sentido sobre todo junto al certificado propio: si la empresa firma con su identidad, sus guías deberían salir también con ella.
El client_secret se guarda cifrado y no se devuelve nunca; la respuesta solo confirma si está configurado.
Se envían los dos juntos: un client_id sin secreto no autentica nada y haría fallar las guías con un error de OAuth poco claro.
Enviar ambos vacíos desactiva las credenciales propias y vuelve a las del proveedor.
En demo no hacen falta ni se usan. El entorno de pruebas de guías solo acepta unas credenciales fijas, y son las que aplicamos automáticamente. Regístralas cuando pases a producción.

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

Cuándo hacen falta

Solo si emites guías de remisión, y solo en producción. Las facturas, boletas y notas van por otro servicio y no las usan.

SUNAT emite estas credenciales en SOL, a nombre del contribuyente. Sin ellas, tus guías salen con el acceso del proveedor — funciona, pero la petición a SUNAT va a nombre de otro.

En demo no se usan

En pruebas no configures nada: el entorno de demo solo admite unas credenciales fijas y son las que aplicamos solos. Las que registres aquí se ignoran hasta que la empresa pase a producción.

Junto al certificado propio

Si registraste tu certificado propio, lo coherente es registrar también estas credenciales: estarías firmando con tu identidad pero enviando guías con la del proveedor.

curl -X PATCH https://api.xmlperu.dev/v1/companies/$RUC/gre-credentials \
  -H "Authorization: Bearer $TOKEN_CUENTA" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "a1b2c3d4-…", "client_secret": "…"}'

Para ver si están puestas, consulta GET /v1/companies/{ruc}/certificate — devuelve credenciales_gre junto con el estado del certificado.

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 la empresa (11 dígitos).

Body

Name	Type	Description
client_id	string	Client ID de OAuth2 emitido en SOL.
client_secret	string	Client secret de OAuth2. Se guarda cifrado.

Ejemplo de solicitud

Copiar

curl -X PATCH https://api.xmlperu.dev/v1/companies/20123456789/gre-credentials \
  -H "Authorization: Bearer $TOKEN_CUENTA" \
  -H "Accept: application/json"

Copiar

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.xmlperu.dev/v1/companies/20123456789/gre-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',
]);

$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/gre-credentials', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${TOKEN_CUENTA}`,
    Accept: 'application/json',
  },
});

const data = await res.json();

Copiar

import requests

TOKEN_CUENTA = "pega-aqui-tu-token"

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

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

Respuesta

200 Registradasapplication/json

{
  "success": true,
  "message": "Credenciales de guías registradas.",
  "data": {
    "gre_credentials": {
      "client_id": "a1b2c3d4-…",
      "client_secret_set": true,
      "uses_own": true
    }
  }
}

200 Desactivadasapplication/json

Enviando ambos campos vacíos. Las guías vuelven a salir con las credenciales del proveedor.

{
  "success": true,
  "message": "Credenciales de guías desactivadas.",
  "data": {
    "gre_credentials": {
      "client_secret_set": false,
      "uses_own": false
    }
  }
}

422 Incompletasapplication/json

{
  "success": false,
  "message": "Envía client_id y client_secret juntos, o ambos vacíos para desactivarlas."
}