API Folyo

La API REST de facturación electrónica chilena. Emite DTEs, consulta estados en el SII, gestiona folios y más — todo desde tu código.

Base URL

url
https://api.folyo.cl

Autenticación

La API soporta dos métodos de autenticación:

JWT Bearer Token

Login con email/password. Retorna un access_token (1h) y un refresh_token (7d).

header
Authorization: Bearer <access_token>

API Key

Creada desde el dashboard. No expira. Ideal para integraciones server-to-server.

header
X-API-Key: <api_key>

Multi-empresa

Una cuenta puede tener varias empresas, pero la emisora no se elige por request: sale de la credencial. Cada API key queda ligada a una empresa cuando la creas, así que para operar con varias necesitas una key por empresa. Con sesión de usuario, la empresa activa se cambia con:

http
POST /v1/empresa/seleccionar

{ "empresa_id": "<empresa_id>" }

Rate limits y cuotas

Folyo aplica dos límites distintos, con respuestas distintas. No los confundas: uno protege la infraestructura y se recupera en segundos; el otro es tu cupo mensual del plan.

Rate limit (throughput)

Ráfaga de requests por tenant y por API key. Si lo excedes, la API responde 429 Too Many Requests con el header Retry-After. Reintenta pasados esos segundos.

Cuota mensual de consultas al SII

Un contador por cuenta que se reinicia cada mes (hora de Chile). El tope depende de tu plan. Si lo agotas, la API responde 403 con el código PLAN_LIMIT, no un 429: se resuelve subiendo de plan, no esperando.

Qué consume una consulta

Cada llamada que Folyo hace por ti a un servicio externo de pago por uso descuenta una unidad de la cuota. Emitir DTEs y boletas no cuenta aquí (tiene su propia cuota de emisión), y leer datos que ya viven en Folyo tampoco. Cuentan, entre otras:

  • Consulta de contribuyente y situación tributaria (/v1/contribuyente/:rut, /v1/sii/situacion/:rut).
  • Sincronización del RCV con el SII (POST /v1/rcv/:periodo/sync). Leer un período ya sincronizado no cuenta.
  • Estado de un DTE o de un envío (/v1/dte/consulta/:tipo/:folio, /v1/dte/estado/:trackId) y la consulta de emitidos/recibidos por período.
  • Solicitud de folios (CAF), envío y consulta de RCOF, y acuse de recibo.
  • Autocompletado de datos de empresa y extracción de documentos con IA (compras internacionales, cartola de tarjeta).

Sigue tu consumo por header

Toda respuesta sujeta a cuota trae estos headers, así no tienes que adivinar cuánto te queda:

http
X-Quota-Period: 202608     # período consumido (AAAAMM, hora de Chile)
X-Quota-Limit: 100         # tope del plan (o "unlimited")
X-Quota-Remaining: 24      # consultas restantes en el período

Al agotar la cuota, la respuesta es:

json
{
  "ok": false,
  "error": "Límite de consultas mensuales alcanzado. Actualice su plan.",
  "code": "PLAN_LIMIT"
}

Emisión asíncrona

Breaking change — v1.4.0

El header X-Sync: true fue eliminado. POST /v1/dte/emitir responde siempre 202 Accepted con un job_id. Si tu integracion leia track_id o xml_firmado del response del POST, debes migrar a webhook o polling (ver abajo).

Tras el 202, el backend firma el XML y lo envía al SII en segundo plano. El resultado llega por uno de tres canales, según tu caso:

Webhook

Recomendado para backends. Firmado con HMAC-SHA256. Reintento automático. Evento dte.emitido.

Polling

GET /v1/dte/emision/:jobId. Útil para debugging o como fallback si perdiste el webhook.

SSE

Solo para dashboards en browser. GET /v1/events/stream. No recomendado server-side (sin retry).

Flujo con webhook

http
# 1. Emitir el DTE
POST /v1/dte/emitir
Content-Type: application/json
X-API-Key: <tu_api_key>

{ "tipo_dte": 33, "receptor": { ... }, "detalle": [ ... ] }

# 2. Respuesta inmediata
HTTP/1.1 202 Accepted
{
  "ok": true,
  "data": {
    "job_id": "0a9c4f3b-...",
    "folio": 1234,
    "tipo_dte": 33,
    "estado": "pending",
    "mensaje": "Emision encolada..."
  }
}

# 3. Tu endpoint de webhook recibe el resultado (segundos despues)
POST https://tu-backend/webhooks/folyo
X-Folyo-Signature: sha256=<hmac>
X-Folyo-Event: dte.emitido
Content-Type: application/json

{
  "evento": "dte.emitido",
  "data": {
    "job_id": "0a9c4f3b-...",
    "tipo_dte": 33,
    "folio": 1234,
    "track_id": "123456789",
    "rut_emisor": "76.123.456-0",
    "rut_receptor": "77.924.588-8",
    "monto_total": 119000,
    "fecha_emision": "2026-04-22"
  }
}

Flujo con polling (fallback)

http
# Tras el 202, consulta cada 2-3s hasta que estado != "pending"/"processing"
GET /v1/dte/emision/0a9c4f3b-...
X-API-Key: <tu_api_key>

# Cuando el job termina:
{
  "ok": true,
  "data": {
    "id": "0a9c4f3b-...",
    "estado": "completed",
    "tipo_dte": 33,
    "folio": 1234,
    "completed_at": "2026-04-22T10:00:04Z",
    "result": {
      "track_id": "123456789",
      "folio": 1234,
      "rut_receptor": "77.924.588-8",
      "monto_total": 119000,
      "xml_firmado": "<?xml ...>"
    }
  }
}

Estados posibles: pending (en cola), processing (enviando al SII), completed (OK), failed (rechazo SII o error interno, ver campo error).

Autenticacion

Registro, login y manejo de sesiones con JWT.

Cuenta

Informacion de la cuenta, uso de cuota y gestion de plan.

Empresa

Gestion de empresas (contribuyentes) del tenant.

DTE | Emision

Emision de documentos tributarios electronicos, consulta de estado y descarga de XML/PDF. Tipos soportados: 33 (factura afecta), 34 (factura exenta), 39 (boleta), 41 (boleta exenta), 43 (liquidacion-factura), 46 (factura de compra), 52 (guia de despacho), 56 (nota de debito), 61 (nota de credito), 110 (factura de exportacion), 111 (nota de debito de exportacion) y 112 (nota de credito de exportacion). Los documentos de exportacion son exentos de IVA, se expresan en moneda extranjera con conversion obligatoria a CLP y requieren el bloque exportacion (moneda, tipo_cambio, tot_bultos, cod_pais_recep). (v1.14.0)

DTE | Folios (CAF)

Gestion de folios (CAF) para la emision de DTEs. Los folios son rangos de numeros autorizados por el SII.

DTE | Consultas

Consultas de estado de DTEs en el SII, documentos emitidos/recibidos por periodo y datos de contribuyentes.

DTE | Acuse de Recibo

Registro de aceptacion o reclamo de DTE (Ley 19.983 / 20.956). Cubre las dos partes del flujo: como emisor consultar si el receptor acepto o reclamo tu DTE, y como receptor registrar acuse, aceptacion o reclamo sobre los DTE que te emitieron.

DTE | RCOF

Reporte de Consumo de Folios. Resumen diario obligatorio de boletas emitidas.

RCV

Registro de Compras y Ventas. Sincronizacion con SII, vinculaciones de notas de credito y consultas por periodo.

Compras internacionales

Factura de compra internacional: sube el invoice de un proveedor extranjero (PDF o imagen), Folyo extrae los datos, convierte el monto a CLP con el dolar observado de la fecha del documento y arma un borrador de DTE 46 (receptor generico 55.555.555-5) para recuperar el IVA como credito fiscal. Solo disponible desde el plan Profesional. La conversion y los montos son siempre editables antes de emitir.

Clientes

Libreta de clientes de la empresa: CRUD, busqueda por RUT o razon social, ordenamiento y paginacion, importacion desde el Registro de Ventas del SII y metricas de facturacion por cliente. Las metricas (total_facturado, num_documentos, ultimo_dte) son una funcion premium disponible desde el plan Profesional.

Plantilla PDF

Gestion de plantillas para la generacion de PDFs de DTEs. Soporte para versionado y logo personalizado.

API Keys

Gestion de API keys para autenticacion sin sesion. Se envian via header X-API-Key. Pueden crearse con fecha de expiracion opcional; sin expires_at la key no expira.

Usuarios

Gestion de usuarios del tenant. Invitaciones, roles y permisos.

Webhooks

Configuracion de webhooks para recibir notificaciones de eventos en tiempo real.

Eventos (tiempo real)

Stream de eventos en tiempo real via Server-Sent Events (SSE). Pensado para dashboards y clientes de navegador que quieren refrescar la UI al instante. Para integraciones server-side use webhooks: son mas fiables (retry, firma HMAC) y no requieren mantener una conexion abierta.

Billing

Estado de suscripcion, historial de cobros y gestion de checkout.

BTE | Boleta de Terceros

Boleta de Prestacion de Servicios de Terceros Electronica. A diferencia de la BHE — que emite la persona natural que presta el servicio — la BTE la emite el PAGADOR (normalmente una empresa) por servicios recibidos de un tercero persona natural, aplicando la retencion correspondiente.