# Convenciones

Reglas comunes que aplican a todos los endpoints del API de Chapi.

## Formato del RUT

El API valida el RUT con la siguiente expresión regular:

```
\d{1,2}\.?\d{3}\.?\d{3}-[\dkK]$
```

Esto admite ambas formas de escritura habituales en Chile:

| Forma | Ejemplo | ¿Acepta? |
|---|---|---|
| Sin puntos, con guión, dígito verificador numérico | `22222222-2` | sí |
| Con puntos, con guión, dígito verificador numérico | `12.345.678-9` | sí |
| Sin puntos, con guión, dígito verificador `K` | `9876543-K` | sí |
| Sin puntos, con guión, dígito verificador `k` minúscula | `9876543-k` | sí |
| Sin guión | `222222222` | **no** |
| Sin dígito verificador | `22222222` | **no** |

Si el RUT viene en formato inválido, el API responde **`400 Invalid RUT`** (ver [Errores](/docs/api/errors)).

> **Recomendación.** Normaliza siempre del lado cliente a `<sin-puntos>-<dv>` (por ejemplo `12345678-9`) antes de enviar. Es la forma más estable y la que se documenta en los ejemplos.

## Codificación

- **Encoding:** UTF-8 en request y response.
- **Content-Type:** `application/json` para los `POST` con body.
- **Accept:** `application/json` (es el default).

## Paginación

Sólo el endpoint [`POST /api/name-to-rut`](/docs/api/endpoints/name-to-rut) está paginado. Los parámetros van en query string:

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

La respuesta envuelve los resultados:

```json
{
  "count": 137,
  "page": 1,
  "page_size": 25,
  "total_pages": 6,
  "results": [{ "rut": "...", "full_name": "..." }]
}
```

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

## Reutilización mensual de Checks

`POST /api/check` no genera un Check nuevo cada vez que lo llamas para el mismo RUT dentro del **mismo mes calendario**: devuelve el Check existente (200 con el mismo `id`). `GET /api/check/{rut}` recupera ese Check vigente.

Esto significa que los Checks tienen vigencia natural por mes calendario (entre el día 1 y el último día del mes, hora local de Chile).

## Pendiente de aclaración

> **Timezone.** El campo `created_at` se devuelve en `ISO 8601` (`YYYY-MM-DDTHH:MM:SSZ`). El "mes calendario" para reutilización está documentado en el OpenAPI pero no especifica explícitamente la zona horaria; lo más probable es `America/Santiago` (UTC-3 o UTC-4 según horario de verano). Confirmar con Chapi.

> **Idempotencia.** No hay header `Idempotency-Key` documentado. La reutilización mensual del Check funciona como una idempotencia natural por `(rut, mes_calendario)`.

> **Versionado.** El OpenAPI declara `version: 0.0.1`. No hay header `Api-Version` ni prefijo `/v1/` en los paths actuales. Asume que `/api/...` es estable hasta nuevo aviso (ver [Changelog](/docs/api/changelog)).

---

Última actualización: 2026-05-01