API Folyo

Emisión asíncrona

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:

Flujo con webhook

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

{ "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)

# 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.13.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. Las API keys no expiran y se envian via header X-API-Key.

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.