# POST /api/name-to-rut

Busca RUTs a partir de un nombre completo. Devuelve resultados paginados.

- **URL completa:** `https://app.chapi.cl/api/name-to-rut`
- **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` |

## Query parameters

| Parámetro | Tipo | Default | Máximo | Descripción |
|---|---|---|---|---|
| `page` | integer | `1` | — | Página solicitada (1-indexed). |
| `page_size` | integer | `25` | `25` | Cantidad de resultados por página. |

Si `page` queda fuera de rango, el API responde `404 No data found`.

## Request body

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `name` | string | sí | Nombre completo a buscar. |

### Ejemplo válido

```json
{ "name": "Juan Pérez" }
```

## Respuestas

### `200 OK`

Schema: `PaginatedRUTResponse`.

```json
{
  "count": 137,
  "page": 1,
  "page_size": 25,
  "total_pages": 6,
  "results": [
    { "rut": "12345678-9", "full_name": "Juan Pérez González" },
    { "rut": "9876543-K", "full_name": "Juan Pérez Soto" }
  ]
}
```

#### Campos

| Campo | Tipo | Descripción |
|---|---|---|
| `count` | integer | Total de coincidencias en todas las páginas. |
| `page` | integer | Página devuelta. |
| `page_size` | integer | Tamaño de la página devuelta. |
| `total_pages` | integer | Cantidad total de páginas. |
| `results` | array de `RUT` | Coincidencias en esta página. |

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

### Errores

| Código | Causa |
|---|---|
| `400` | Nombre ausente o con formato inválido. |
| `402` | `Insufficient balance` — saldo insuficiente. |
| `404` | `No data found` — sin coincidencias o página fuera de rango. |

## Ejemplos

### curl

```bash
curl -X POST 'https://app.chapi.cl/api/name-to-rut?page=1&page_size=25' \
  -H "Authorization: Token TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Juan Pérez"}'
```

### Python (`requests`)

```python
import requests

def search_by_name(name: str, token: str, page: int = 1, page_size: int = 25):
    r = requests.post(
        "https://app.chapi.cl/api/name-to-rut",
        params={"page": page, "page_size": page_size},
        headers={"Authorization": f"Token {token}"},
        json={"name": name},
        timeout=30,
    )
    if r.status_code == 404:
        return {"count": 0, "results": []}
    r.raise_for_status()
    return r.json()

result = search_by_name("Juan Pérez", "TU_TOKEN")
print(f"{result['count']} matches; page 1 of {result.get('total_pages', 0)}")
```

### JavaScript (`fetch`)

```javascript
const params = new URLSearchParams({ page: "1", page_size: "25" });
const resp = await fetch(`https://app.chapi.cl/api/name-to-rut?${params}`, {
  method: "POST",
  headers: {
    "Authorization": "Token TU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Juan Pérez" }),
});
if (resp.status === 404) {
  console.log("Sin coincidencias.");
} else if (!resp.ok) {
  throw new Error(`HTTP ${resp.status}`);
} else {
  const data = await resp.json();
  console.log(`${data.count} matches`);
}
```

## Iterar todas las páginas

```python
def iter_all(name, token):
    page = 1
    while True:
        result = search_by_name(name, token, page=page, page_size=25)
        for r in result.get("results", []):
            yield r
        if page >= result.get("total_pages", 0):
            return
        page += 1
```

---

Última actualización: 2026-05-01