Explorando Formatos de Respuesta

La API no siempre devuelve solo JSON. Según el endpoint, puedes pedir otros formatos en el parámetro de consulta formato (cuando esté documentado): por ejemplo HTML para mostrar en pantalla, CSV para bajar tablas a Excel o XML para integraciones que lo esperan.

No todos los endpoints soportan todos los formatos. La lista permitida sale en la documentación interactiva de cada operación.

Formatos disponibles (orientación general)

Tabla principal

Formato	Parámetro típico	Descripción	Ideal para
JSON	`formato=json` o valor por defecto	Estructurado, fácil de parsear	Aplicaciones, automatización
HTML	`formato=html`	Página similar a la del SII	Mostrar al usuario en navegador o iframe
CSV	`formato=csv`	Texto separado por columnas	Excel, reportes
XML	`formato=xml`	Estructura tipo SII	Integraciones que consumen XML

Modificar el formato en la documentación interactiva

Paso 1: Localizar el parámetro

Abre www.apigateway.cl/docs/api.
Elige un endpoint que liste el query parameter formato (u otro nombre indicado).
Lee qué valores admite (enum o descripción).

Paso 2: Probar con “Try it out”

Try it out
Completa ruta, body (si hay) y el campo formato
Execute
Observa si el cuerpo cambia de JSON a HTML, texto CSV, etc.

Ejemplo de URLs (patrón)

Sustituye ... por la ruta real del endpoint (aparece en la documentación):

# JSON (habitual por defecto)
https://app.apigateway.cl/api/v2/sii/.../datos

# HTML
https://app.apigateway.cl/api/v2/sii/.../datos?formato=html

# CSV
https://app.apigateway.cl/api/v2/sii/.../datos?formato=csv

Recuerda incluir siempre Authorization: Token … al probar fuera del navegador.

Trabajar con cada formato

JSON — procesamiento automático

Cuándo usar: backends, scripts, APIs entre sistemas.

Ejemplo ilustrativo:

{
  "rut": "11111111-1",
  "razon_social": "EMPRESA DEMO",
  "actividades": [
    {
      "codigo": 620100,
      "descripcion": "ACTIVIDADES DE PROGRAMACION INFORMATICA"
    }
  ]
}

HTML — mostrar en pantalla

Cuándo usar: quieres una vista “tipo sitio SII” sin maquetar tú todo.

Características: suele traer estilos; se puede incrustar en iframe (valora implicancias de seguridad y cookies según tu caso).

CSV — Excel y análisis

Cuándo usar: exportar a hoja de cálculo.

La coma suele ser el valor por defecto; el punto y coma es cómodo para Excel en español.

Ejemplo ilustrativo:

rut;razon_social;actividad_codigo;actividad_descripcion
11111111-1;EMPRESA DEMO;620100;ACTIVIDADES DE PROGRAMACION INFORMATICA

XML — interoperabilidad

Cuándo usar: el sistema destino exige XML o validación con esquemas.

Casos de uso prácticos

Caso 1: Panel para un usuario final

Necesidad: mostrar una pantalla con datos del SII. Opción: formato=html en un iframe (ajusta URL y token según tu arquitectura; muchas veces el HTML se obtiene vía llamada servidor a servidor, no exponiendo el token en el navegador).

<iframe
  title="Consulta SII"
  src="https://app.apigateway.cl/api/v2/sii/.../datos?formato=html"
  width="100%"
  height="600"
></iframe>

En integraciones reales, valorar autenticación y no incrustar el token en URLs visibles al usuario sin analizar riesgos.

Caso 2: Reporte mensual en Excel

Necesidad: analizar en hoja de cálculo. Opción: formato=csv.

Caso 3: ERP u otro backend

Necesidad: procesar en servidor. Opción: JSON por defecto.

Caso 4: Consumo en XML

Necesidad: otro sistema solo acepta XML. Opción: formato=xml si el endpoint lo documenta.

Consideraciones importantes

Disponibilidad

Si no ves formato en los parámetros, ese endpoint probablemente solo devuelve un tipo de respuesta. Respeta el Content-Type de la respuesta (application/json, text/html, etc.).

Buena práctica

En integraciones críticas, fija explícitamente formato si quieres evitar sorpresas si cambia el valor por defecto en el futuro.

Primeros pasos