Folyo API

API de facturación electrónica para Chile

Emite facturas, boletas y los 9 tipos de DTE ante el SII desde tu propio sistema. API REST con JSON, webhooks firmados, SDK oficiales y un plan gratis para integrar y probar.

Crear cuenta gratisLeer la documentación

Actualizado el

Qué resuelve una API de facturación electrónica en Chile

Emitir un documento tributario electrónico en Chile no es enviar un JSON y esperar un OK. El SII exige que cada DTE siga su formato oficial, se timbre con un folio autorizado (CAF), se firme con el certificado digital del contribuyente, se envíe por los servicios del SII y se consulte después hasta tener un veredicto firme. Cada paso tiene reglas propias y largos máximos por campo, y un error en cualquiera hace que el SII rechace el documento.

Una API de facturación electrónica se encarga de esa cadena completa para que tu sistema solo describa el documento: tipo, receptor y líneas de detalle. Folyo API es una API REST con JSON, autenticada con API key, que valida el cuerpo contra las reglas del SII antes de aceptarlo, asigna el folio, firma el XML, lo envía al SII y te informa el resultado. Tú mantienes tu sistema de ventas, tu ERP o tu plataforma; la parte tributaria corre del lado de Folyo.

Está pensada para equipos que facturan desde su propio código: tiendas en línea, puntos de venta, software de gestión, plataformas que facturan por cuenta de sus usuarios y empresas con varias razones sociales. La referencia completa, con el contrato OpenAPI de la versión vigente (v1.26.0), está en el portal de documentación.

Cómo integrar facturación electrónica en 5 pasos

Desde el registro hasta el primer DTE en producción. Los tres primeros pasos se hacen en el plan gratuito, sin tarjeta de crédito.

  1. 01

    Crea tu cuenta y una API key

    Regístrate y confirma tu correo. Toda cuenta nueva parte en el plan Free, con 25 DTE al mes. Desde el panel crea una API key y envíala en el header X-API-Key en cada petición. Cada key queda ligada a una empresa: si administras varias, crea una por empresa.

  2. 02

    Carga el certificado digital y los folios

    Sube el certificado digital de tu empresa (.pfx o .p12) con su clave; se guarda cifrado y firma todo lo que emitas. Luego solicita folios al SII desde la sección Folios o carga un archivo CAF. Sin folios no se puede emitir, y los de certificación y producción son independientes.

  3. 03

    Emite en el ambiente de certificación

    Tu empresa parte en el ambiente de certificación del SII, donde los documentos no tienen validez tributaria. Envía un POST /v1/dte/emitir con el JSON del documento: la API valida los datos, responde 202 con un job_id y procesa el envío en segundo plano. Consulta el resultado con GET /v1/dte/emision/:jobId hasta un estado terminal.

  4. 04

    Configura webhooks

    Registra una URL https en el panel y suscríbete a dte.emitido, dte.rechazado y dte.fallido. Cada entrega va firmada con HMAC-SHA256 en el header X-Webhook-Signature y se reintenta hasta 5 veces con backoff exponencial. Con webhooks activos, tu sistema no necesita consultar el estado del job. Están incluidos en los planes de pago.

  5. 05

    Pasa a producción

    Cuando el flujo completo funcione en certificación, cambia la empresa a producción desde Configuración. Requiere que tu empresa esté autorizada por el SII como emisor electrónico, con certificado digital y folios de producción. Si aún no lo está, el equipo de Folyo puede hacer ese trámite contigo.

Ejemplo: emitir una factura electrónica (DTE 33) con curl

Tomado de la guía de emisión de facturas. La respuesta es un 202 con job_id, folio referencial y estado pending; el folio definitivo llega con el job completado y en el webhook.

bash
curl -X POST "https://api.folyo.cl/v1/dte/emitir" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tipo_dte": 33,
  "fecha_vencimiento": "2026-10-15",
  "rut_solicita": "77.888.999-6",
  "receptor": {
    "rut": "76.543.210-K",
    "razon_social": "Cliente SpA",
    "giro": "Comercio",
    "direccion": "Av. Siempre Viva 123",
    "comuna": "Santiago"
  },
  "detalle": [
    {
      "nombre": "Notebook 14 pulgadas",
      "cantidad": 2,
      "precio": 650000,
      "monto": 1300000,
      "codigos": [
        { "tipo_codigo": "INT1", "valor": "NB-14-2026" },
        { "tipo_codigo": "EAN", "valor": "7801234567890" }
      ]
    }
  ]
}'

El mismo flujo con el SDK de TypeScript

Los SDK oficiales traen tipos derivados del OpenAPI, reintentos con backoff, idempotencia y la emisión asíncrona resuelta: emitirYEsperar envía el documento y espera el estado terminal del job. En Python, el equivalente es folyo.dte.emitir_y_esperar.

typescript
import { Folyo } from "@folyo/sdk";

const folyo = new Folyo({ apiKey: process.env.FOLYO_API_KEY! });

// Emisión asíncrona con polling del resultado.
const job = await folyo.dte.emitirYEsperar(
  {
    tipo_dte: 33,
    receptor: {
      rut: "12.345.678-9",
      razon_social: "Cliente SpA",
      giro: "Comercio",
      direccion: "Av. Siempre Viva 123",
      comuna: "Santiago",
    },
    detalle: [
      { nombre: "Servicio de consultoría", cantidad: 1, precio: 100000, monto: 100000 },
    ],
  },
  { idempotencyKey: crypto.randomUUID() },
);

console.log(job.estado, job.folio, job.result?.track_id);

Capacidades técnicas de la API de facturación electrónica

Lo que ya está disponible en la versión vigente de la API, sin módulos aparte.

9 tipos de DTE y exportación

Facturas afectas y exentas (33, 34), boletas (39, 41), liquidación-factura (43), factura de compra (46), guía de despacho (52) y notas de débito y crédito (56, 61), firmados del lado del servidor. Los documentos de exportación (110, 111, 112) se emiten solo por API con el bloque exportacion.

Emisión asíncrona con estados claros

POST /v1/dte/emitir responde 202 de inmediato con un job_id y el job avanza por estados documentados hasta completed, failed, dlq o discarded. Para dashboards en el navegador hay un stream de Server-Sent Events con los mismos eventos.

Webhooks firmados con HMAC-SHA256

Eventos dte.emitido, dte.rechazado, dte.fallido y los de acuse de recibo, firmados en el header X-Webhook-Signature con el secret del webhook, con hasta 5 reintentos y backoff exponencial. La URL debe ser https y apuntar a un host público.

Idempotencia con Idempotency-Key

Una clave por emisión lógica. Si reintentas por un error de red con la misma clave y el mismo cuerpo, recibes el mismo job y no se consume otro folio. La misma clave con otro cuerpo responde 409 IDEMPOTENCY_KEY_CONFLICT.

SDK para TypeScript y Python

@folyo/sdk en npm (Node 18+, ESM y CJS, sin dependencias de runtime) y folyo en PyPI (Python 3.9+). Tipos derivados del OpenAPI, errores tipados por caso y redacción automática de credenciales en logs y errores.

OpenAPI y referencia completa

Contrato OpenAPI publicado y API Reference con ejemplos listos para copiar en cURL, JavaScript, Python, Go y PHP. Respuestas con envoltorio uniforme: ok, data y un code estable para programar contra los errores.

Multi-empresa desde una cuenta

Cada API key queda ligada a una empresa; crea una por razón social y usa la que corresponda. En los planes multi-RUT, la cuota mensual de DTE se comparte entre todas las empresas de la cuenta.

Certificación ante el SII como servicio

Si tu empresa todavía no está autorizada como emisor electrónico, el equipo de Folyo hace el trámite ante el SII contigo. Es distinto del ambiente de certificación, que es solo para pruebas y no certifica a tu empresa.

Ambientes del SII, límites y manejo de errores

El SII tiene dos ambientes con numeración de folios separada: certificación, para pruebas sin validez tributaria, y producción, donde los documentos son legalmente válidos. El mismo certificado digital sirve para ambos y toda cuenta nueva parte en certificación. El header X-SII-Ambiente permite validar una solicitud de folios o una consulta contra el otro ambiente sin tocar la configuración de la empresa; la emisión no lo admite, para que los folios nunca se mezclen.

Todos los errores comparten el mismo formato: ok en false, un mensaje legible en error y un code estable pensado para programar contra él. Conviene distinguir dos casos que se parecen y no lo son. Un 429 RATE_LIMITED es una ráfaga de peticiones y se resuelve esperando el tiempo indicado en Retry-After. Un 403 PLAN_LIMIT es la cuota mensual del plan agotada o una capacidad que el plan no incluye; no se resuelve esperando, sino al inicio del próximo mes o subiendo de plan. Cada respuesta sujeta a cuota trae los headers X-Quota-Limit, X-Quota-Remaining y X-Quota-Period.

Cuando el job termina en failed, el campo error indica la causa: SII_REJECTED con el código del SII, NO_FOLIOS, CERT_ERROR o XML_SIGN_ERROR. Un failed o dlq no demuestra que el SII no haya recibido el documento, así que no reemitas en automático: primero confirma que no existe Track ID. Folyo reintenta el envío al SII por su cuenta antes de marcar un job como fallido y no asigna otro folio por una falla de persistencia posterior al envío.

En el plan gratuito, la descarga del XML firmado y del PDF expira: 4 horas después de la emisión en producción y 30 minutos en certificación. Pasada la ventana, los endpoints de descarga responden 410 XML_EXPIRADO; el documento sigue emitido y vigente ante el SII, solo expira la descarga, así que guarda los archivos apenas termina el job. En los planes de pago no expiran. Las descargas tienen además un límite de 20 peticiones por ventana de 4 segundos por cuenta.

Preguntas frecuentes sobre la API de facturación electrónica

¿Puedo probar la API sin pagar?
Sí. El plan gratuito incluye 25 DTE al mes, en certificación o en producción, sin tarjeta de crédito. Si tu empresa ya está autorizada por el SII, esos documentos son reales y tienen validez tributaria. Los planes del carril API (API Free, API Start, API Pro y API Scale) escalan en volumen de DTE, API keys, webhooks, multi-RUT y consultas al SII.
¿Necesito un certificado digital propio?
Sí. Lo emite un prestador autorizado a nombre de tu empresa o de su representante y firma cada DTE. Lo subes una vez (.pfx o .p12) y Folyo lo guarda cifrado con AES-256-GCM. Queda a tu nombre ante el SII, no a nombre del proveedor: si cambias de sistema, te lo llevas. Sirve para certificación y producción.
¿Cómo sé si el SII aceptó el documento?
En dos tiempos. El job llega a completed cuando el SII recibe el envío y devuelve un Track ID; eso dispara el webhook dte.emitido. El veredicto tributario llega después: Folyo consulta al SII en automático hasta obtener respuesta firme y el documento pasa a aceptado_sii o rechazado_sii. La aceptación se consulta con GET /v1/dte/consulta/:tipo/:folio y un rechazo dispara dte.rechazado. En horas de alta carga el SII puede tardar más de una hora; no es un error y no hay que reemitir.
¿Hay SDK oficial?
Sí, para TypeScript/JavaScript (@folyo/sdk en npm) y Python (folyo en PyPI), ambos en la versión 0.3.0, con tipos derivados del OpenAPI, reintentos con backoff, idempotencia, emisión asíncrona con espera del resultado y errores tipados por caso. Desde cualquier otro lenguaje consumes la API REST con un cliente HTTP; la referencia trae ejemplos en cURL, JavaScript, Python, Go y PHP.
¿Qué tipos de DTE soporta la API?
Los 9 tipos de uso general en Chile: factura (33), factura exenta (34), boleta (39), boleta exenta (41), liquidación-factura (43), factura de compra (46), guía de despacho (52), nota de débito (56) y nota de crédito (61), más los documentos de exportación (110, 111 y 112) solo por API, con el bloque exportacion. Admite descuentos globales, referencias a órdenes de compra y HES, impuestos adicionales y retenciones por línea, y envío del XML a la casilla de intercambio del receptor.
¿Sirve para boleta electrónica?
Sí. La boleta (39) y la boleta exenta (41) se emiten por el mismo endpoint, con precios con IVA incluido y receptor anónimo (RUT 66666666-6) si no tienes el dato. Los folios de boleta requieren un plan que incluya boletas: en los planes gratuitos la API responde PLAN_LIMIT al solicitar o cargar folios de boleta, antes de contactar al SII. En el carril API, API Start incluye un volumen mensual de boletas y desde API Pro no tienen límite.
¿Qué pasa si mi sistema cae mientras emite?
Nada se duplica si usas Idempotency-Key. Genera una clave por emisión lógica (un UUID v4 sirve) y guárdala junto a la venta antes de llamar a la API: si tu proceso reintenta con la misma clave y el mismo cuerpo, Folyo devuelve el job existente con su folio. Del lado de Folyo, el job sigue su curso aunque tu conexión se corte: recuperas el resultado con GET /v1/dte/emision/:jobId o por webhook, que se reintenta hasta 5 veces si tu endpoint no responde.

Enlaces relacionados

Tu primer documento está a una decisión de distancia.

Parte gratis, valida tu operación y escala cuando el volumen lo pida.

Crear cuenta gratisLeer la documentación