Formatos
JSON, XML, fechas, enums y nulos en las respuestas de la API.
Esta guía cubre los formatos de la API: JSON como formato principal y XML como legado, las cabeceras propias de las respuestas, las fechas en hora de Chile, los enums numéricos, las claves en PascalCase y los valores null.
JSON, y XML como legado
La API trabaja en JSON. Mande siempre estas dos cabeceras:
Accept: application/json, en todo request;Content-Type: application/json, en todo request con cuerpo. Sin ese header el cuerpo no se lee como JSON, y qué hace la API en ese caso no está verificado.
La API también negocia XML (application/xml, text/xml) como legado. Si pide XML, puede recibir XML, también en los errores del framework. Este portal y el contrato documentan solo JSON: no use XML en una integración nueva.
Los errores de negocio y el rechazo por rate limit no son JSON, sino texto plano. Cómo leerlos está en Errores y reintentos.
Varias lecturas son POST y no GET, como las consultas de CAF y de empresa, porque el certificado viaja en el cuerpo.
Cabeceras de respuesta
Además de las estándar de HTTP, la API manda estas cabeceras propias:
| Cabecera | Cuándo viene | Formato |
|---|---|---|
RateLimit-Limit | En toda respuesta | Número entero de requests: hoy, 120 |
RateLimit-Remaining | En toda respuesta | Número entero de requests; 0 en un 409 |
X-Codigo-Error | Desde la versión 1.1, en los errores de negocio con código | Texto: el código, igual al que abre el cuerpo |
X-Reintentable | Desde la versión 1.1, en los errores de negocio con código | Texto, uno de tres valores en minúsculas y sin tilde: si, no o desconocido |
Retry-After | En el 429 de CAF_REQUEST_IN_PROGRESS y, desde la versión 1.1, en los errores con código cuando X-Reintentable es si | Número entero de segundos (hoy, 30), no una fecha |
Compare los nombres de cabecera sin distinguir mayúsculas, como manda HTTP. Qué significa cada una y cómo usarlas para decidir un reintento está en Errores y reintentos y en Rate limits.
Claves en PascalCase
Las claves de los objetos JSON van en PascalCase, tal como aparecen en la referencia: Estado, FechaEstado, RazonSocial. También las de los errores del framework: Message, MessageDetail. Use cada nombre exactamente como figura en la referencia, aunque parezca tener una errata.
Fechas: sin offset, en hora de Chile
Los campos de fecha y hora, como Fecha y FechaEstado de una certificación, llegan sin zona horaria: ni offset ni Z. Tienen esta forma, con fracción de segundo opcional (hasta 7 dígitos):
2026-10-08T10:15:00
2026-10-08T10:15:00.1234567Son hora de Chile. Interprételas en la zona America/Santiago, que tiene horario de verano, y no como UTC ni en la zona de su servidor.
Como no traen offset, una hora del día en que termina el horario de verano es ambigua: la hora que se repite al atrasar el reloj puede corresponder a dos instantes, y la fecha sola no dice cuál. No dependa de esas fechas para ordenar eventos que caen en esa hora.
// Mal: JavaScript interpreta una fecha sin offset en la zona de quien la ejecuta.
new Date('2026-10-08T10:15:00');Use una biblioteca de fechas que maneje zonas horarias IANA y asígnele la zona America/Santiago antes de convertirla.
No todas las fechas tienen esa forma. Algunos campos llegan como texto con otro formato, que la referencia indica en cada campo: por ejemplo, dd-mm-aaaa.
Enums numéricos
Los enums viajan como números, no como nombres: en una certificación, Estado es 0, 1, 2 o 3. La referencia de cada enum da el nombre y el significado de cada valor. Por ejemplo, Ambiente:
| Valor | Nombre | Significado |
|---|---|---|
0 | Homologacion | Homologación |
1 | Produccion | Producción |
Mande también números en los parámetros y en los cuerpos. Con ambiente importa en especial: un valor que la API no reconoce no da error, y la operación corre en producción. Pase siempre ambiente=0 mientras prueba; el detalle está en Ambientes.
Valores null
Los textos, las listas y los objetos pueden venir en null. Los números, los enums y los booleanos vienen siempre con valor, salvo que la referencia del campo diga lo contrario: HorasEnEstado, por ejemplo, admite null, y la referencia explica qué significa.
Un campo que la referencia marca como obligatorio no viene en null. Para el resto, trate igual un null y un campo ausente.
Base64
Los datos binarios viajan como texto en base64:
- Certificados digitales: el PFX que se manda en
Datao enCertData, y el certificado que devuelvecertificados_v1_descargar_e_cert. - CAF:
caf_v1_descargarycaf_v1_reobtenerresponden un string JSON con los bytes del CAF en base64. Decodifíquelo para obtener el archivo. - Documentos adjuntos: por ejemplo, la copia de la cédula en PDF (
CopiaCedula), de hasta 2 MB.
Una respuesta de CAF tiene esta forma (el contenido de este ejemplo no es un CAF real):
"RWplbXBsbzogbm8gZXMgdW4gQ0FGIHJlYWwu"El PFX y su contraseña son datos sensibles. No los registre en sus logs.
RUT
Mande los RUT sin puntos, con guion y con el dígito verificador, y la K en mayúscula:
12345678-5La API normaliza el RUT en algunas respuestas: por ejemplo, el RUT de la consulta de datos de empresa y el Rut de los folios anulados. Pero no en todas partes. El filtro RUT de certificaciones_v1_buscar compara el texto tal cual, sin normalizar: un RUT con puntos o con la k en minúscula no encuentra la certificación. Normalice los RUT de su lado antes de mandarlos y antes de compararlos.
Un certificado digital cuyo RUT termina en k minúscula no se puede usar (CERT_NO_VALIDO).