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).

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 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:

{
  "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).