# POST /api/rut-to-name

Devuelve los datos asociados a un RUT (nombre completo y RUT canónico).

- **URL completa:** `https://app.chapi.cl/api/rut-to-name`
- **Método:** `POST`
- **Auth:** `Authorization: Token <token>` o cookie `sessionid` ([más](/docs/api/authentication)).
- **Tag OpenAPI:** `Rutificador`

## Headers requeridos

| Header | Valor |
|---|---|
| `Authorization` | `Token <token>` (si no usas cookie auth) |
| `Content-Type` | `application/json` |

## Request body

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `rut` | string | sí | RUT a consultar. Patrón: `\d{1,2}\.?\d{3}\.?\d{3}-[\dkK]$`. Ver [Convenciones](/docs/api/conventions). |

### Ejemplo válido

```json
{ "rut": "12345678-5" }
```

## Respuestas

### `200 OK`

Devuelve un **array** de coincidencias. Schema: `RUT[]`.

```json
[
  { "rut": "12345678-5", "full_name": "Juan Pérez González" }
]
```

#### `RUT`

| Campo | Tipo | Descripción |
|---|---|---|
| `rut` | string (read-only) | RUT en formato canónico. |
| `full_name` | string nullable (≤ 255) | Nombre completo asociado. Puede ser `null`. |

> **Nota.** La respuesta es una lista. Aunque un RUT identifica a una única persona o empresa, el shape `array` permite contemplar casos en que existan registros con el mismo RUT en diferentes fuentes. En la práctica esperarás 0 o 1 elementos.

### Errores

| Código | `message` | Causa |
|---|---|---|
| `400` | `Invalid RUT` | RUT inválido o ausente. |
| `402` | `Insufficient balance` | Saldo insuficiente. |
| `404` | `No data found` | Sin coincidencias para ese RUT. |

## Ejemplos

### curl

```bash
curl -X POST https://app.chapi.cl/api/rut-to-name \
  -H "Authorization: Token TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rut": "12345678-5"}'
```

### Python (`requests`)

```python
import requests

def rut_to_name(rut: str, token: str) -> str | None:
    r = requests.post(
        "https://app.chapi.cl/api/rut-to-name",
        headers={"Authorization": f"Token {token}"},
        json={"rut": rut},
        timeout=30,
    )
    if r.status_code == 404:
        return None
    r.raise_for_status()
    matches = r.json()
    return matches[0]["full_name"] if matches else None

print(rut_to_name("12345678-5", "TU_TOKEN"))
```

### JavaScript (`fetch`)

```javascript
const resp = await fetch("https://app.chapi.cl/api/rut-to-name", {
  method: "POST",
  headers: {
    "Authorization": "Token TU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ rut: "12345678-5" }),
});
if (resp.status === 404) {
  console.log("Sin coincidencias.");
} else if (!resp.ok) {
  throw new Error(`HTTP ${resp.status}`);
} else {
  const matches = await resp.json();
  console.log(matches[0]?.full_name ?? "—");
}
```

---

Última actualización: 2026-05-01