# Inicio rápido

Tu primera respuesta en cinco minutos, sin registrarte.

## 1. La primera consulta, ya

Con el token público del [sandbox](https://nexoid.victorllerena.com/docs/sandbox.md), que responde con un conjunto fijo de empresas de prueba:

```bash
curl https://nexoid.victorllerena.com/id/v1/ruc/20999999906 \
  -H "Authorization: Bearer nxid_test_sandboxpublicodenexoidpruebas001"
```

Responde la ficha de **SANDBOX ACTIVA Y COMPLETA S.A.C.**, con `meta.origen: sandbox`. `data` trae la ficha; `meta` dice de dónde sale: `origen`, `fecha_dato`, la `atribucion` de la fuente y el `request_id`, que es lo que hay que darnos si algo falla.

## 2. Desde tu lenguaje

Con los [SDKs](https://nexoid.victorllerena.com/docs/sdks.md) de PHP y JavaScript, o con lo que ya usas.

### PHP

```php
$nexoid = new Nexo\Id\Cliente(token: 'nxid_test_sandboxpublicodenexoidpruebas001');

$empresa = $nexoid->ruc('20999999906');
echo $empresa?->nombre;          // SANDBOX ACTIVA Y COMPLETA S.A.C.
echo $empresa?->meta->origen;    // sandbox
```

### JavaScript y TypeScript

```ts
import { NexoId } from '@nexo-lat/id';

const nexoid = new NexoId({ token: 'nxid_test_sandboxpublicodenexoidpruebas001' });
const empresa = await nexoid.ruc('20999999906');
console.log(empresa?.datos.nombre);   // SANDBOX ACTIVA Y COMPLETA S.A.C.
```

### Python

```python
import requests

r = requests.get(
    'https://nexoid.victorllerena.com/id/v1/ruc/20999999906',
    headers={'Authorization': 'Bearer nxid_test_sandboxpublicodenexoidpruebas001'},
    timeout=5,
)
print(r.json()['data']['nombre'])  # SANDBOX ACTIVA Y COMPLETA S.A.C.
```

## 3. Pasa a datos reales

Pide tu token por WhatsApp: https://wa.me/51925786403?text=Hola%2C%20quiero%20acceso%20a%20la%20API%20de%20NexoID. `nxid_live_…` consulta el padrón real, con las consultas gratis de cada mes: cambias el token y nada más. 🔒 Guárdalo en tu servidor: nunca en el navegador ni en una variable `VITE_…`.

## Los errores que verás primero

| Estado | Código | Qué hacer |
|---|---|---|
| 401 | `token_invalido` | Revisa la cabecera `Authorization: Bearer`. El token pudo expirar o ser revocado. |
| 403 | `scope_insuficiente` | El scope efectivo es la intersección del token con el plan: mira `scopes_efectivos` en `/me` para saber cuál de los dos falta. |
| 403 | `finalidad_no_declarada` | Faltan finalidad, base legal o el anexo de tratamiento firmado. Es requisito para servir identidad y se resuelve con nosotros, no en el código. |
| 422 | `documento_invalido` | El RUC o el DNI no pasan la validación de formato o de dígito verificador. Valídalo en tu lado y ahorras la llamada. |
| 429 | `cuota_agotada` | La cuota del periodo se acabó y el plan no permite excedente. Se arregla subiendo de plan. |

## La sorpresa del RUC 10

🔒 Un RUC que empieza en `10`, `15` o `17` es una persona natural, y su nombre es identidad: la consulta exige `dni.read` y finalidad declarada aunque la ruta sea `/ruc`. Con solo `ruc.read` recibes un 403, y es la regla.

Sigue con la [referencia](https://nexoid.victorllerena.com/docs/referencia.md) y las [guías](https://nexoid.victorllerena.com/docs/guias.md).