Formato de respuesta

Toda respuesta de la API de Folyo usa un envoltorio uniforme. En vez de retornar el payload pelado, la API lo envuelve junto a un indicador ok. Esto te permite programar contra una forma estable, sin importar el endpoint.

Envoltorio de éxito

Toda respuesta 2xx tiene la forma { "ok": true, "data": <payload> }. El payload real vive siempre dentro de data.

json

{
  "ok": true,
  "data": {
    "job_id": "a1b2c3d4-...",
    "estado": "en_proceso"
  }
}

{
  "ok": true,
  "data": {
    "job_id": "a1b2c3d4-...",
    "estado": "en_proceso"
  }
}

En los endpoints de lista, data es directamente el array de resultados:

json

{
  "ok": true,
  "data": [
    { "id": "...", "folio": 1024, "tipo": 33 },
    { "id": "...", "folio": 1025, "tipo": 33 }
  ]
}

{
  "ok": true,
  "data": [
    { "id": "...", "folio": 1024, "tipo": 33 },
    { "id": "...", "folio": 1025, "tipo": 33 }
  ]
}

Para leer el resultado, siempre accede a .data:

javascript

const res = await fetch("https://api.folyo.cl/v1/documentos", {
  headers: { "X-API-Key": "<api_key>" },
});
const body = await res.json();

if (body.ok) {
  const documentos = body.data; // el payload real
}

const res = await fetch("https://api.folyo.cl/v1/documentos", {
  headers: { "X-API-Key": "<api_key>" },
});
const body = await res.json();

if (body.ok) {
  const documentos = body.data; // el payload real
}

Envoltorio de error

Las respuestas de error tienen la forma { "ok": false, "error": "<mensaje legible>", "code": "<CODIGO>" }. El status HTTP acompaña e indica la categoría del problema.

json

{
  "ok": false,
  "error": "El período indicado no es válido",
  "code": "INVALID_PERIODO"
}

{
  "ok": false,
  "error": "El período indicado no es válido",
  "code": "INVALID_PERIODO"
}

code es un identificador estable, pensado para programar contra él. No cambia entre versiones.
error es texto legible por humanos. Puede cambiar y no debes usarlo para tomar decisiones en código.

Códigos comunes

`code`	Descripción
`INVALID_PERIODO`	El período tributario indicado no es válido
`PLAN_LIMIT`	Alcanzaste el límite de tu plan actual
`ACCOUNT_LOCKED`	La cuenta está bloqueada temporalmente

Programa contra code, no contra el status HTTP ni contra error:

javascript

if (!body.ok) {
  if (body.code === "PLAN_LIMIT") {
    // sugerir upgrade de plan
  }
}

if (!body.ok) {
  if (body.code === "PLAN_LIMIT") {
    // sugerir upgrade de plan
  }
}

Los ejemplos de la referencia muestran el envoltorio completo

Todos los ejemplos de Response en la API Reference muestran el envoltorio completo, no el payload pelado. Esto es intencional: puedes copiar el ejemplo tal cual y coincidirá byte a byte con lo que retorna la API, incluyendo el campo ok y la ubicación del payload en data.