Ruka / Desarrolladores

Tus datos operativos. En lo que quieras construir.

Lleva tus compras a un dashboard, conecta tu ERP o recibe cambios en tus propios sistemas.

Explorar la API Referencia completa

Facturas, líneas de compra, clasificaciones y documentos. Datos para tu código, no otra planilla que mantener.

HTTP / v1Bearer authOpenAPI 3.1

Tu primera conexión

HTTP / v1

Comprueba la clave

Ejecuta esta petición desde tu servidor. HTTP 200 valida la clave; no concede permisos de reportes.

Comprobar la clave · cURL

curl --fail-with-body --max-time 15 \
  'https://api.rukafactura.cl/api/v1/ping' \
  --header "Authorization: Bearer $RUKA_API_KEY"

Ejemplos locales. Sin peticiones, credenciales ni datos de clientes.

Empieza por lo que quieres construir.

Elige tu caso. Te mostramos qué entrega Ruka, qué construyes tú y por dónde partir.

Del total de la factura al costo de cada insumo.

Cruza el detalle de compras con tu modelo de negocio. Ruka entrega cantidades, importes, clasificaciones y centros de costo; tú eliges cómo analizarlos.

01Compras en Ruka
02Líneas y repartos
03Tu modelo de costos

Recibes las líneas que coinciden con tus filtros, sin multiplicarlas por centro de costo.

De tu lado. Tu integración normaliza unidades, guarda los datos y construye las métricas.

Ver esta operación Guía paso a paso

Conserva la precisión decimal y las unidades. Una caja y un kilo no se suman como si fueran lo mismo.

Del contrato al código.

Diez operaciones. Sus permisos, parámetros y respuestas en un solo lugar. Explora sin conectar una cuenta.

OpenAPI 3.1

Buscar operaciónFamilia

10 de 10 operaciones

Operación

Compras · Líneas de compra
Operación abierta; los filtros no la modifican.

GETSolo lectura

Líneas de compra

/api/v1/reports/purchase_lines

Pagina líneas con invoice y cost_center_allocations; no multiplica filas por centro. Decimales como strings.

Permiso: Clave activa y Ver módulo de reportes.

Ajustar parámetros del ejemplo · solo local

Usa datos de ejemplo. No introduzcas claves ni información de clientes. El código se actualiza aquí; ninguna petición se envía.

issued_from · obligatorio

Inicio inclusivo, YYYY-MM-DD.

issued_to · obligatorio

Fin inclusivo, YYYY-MM-DD. Diferencia máxima: 31 días.

page · opcional

Entero positivo. Página solicitada.

per_page · opcional

Entero positivo; valores mayores a 100 se reducen a 100.

Petición de ejemplo

GET /api/v1/reports/purchase_lines · cURL

curl --fail-with-body --max-time 15 \
  --get \
  'https://api.rukafactura.cl/api/v1/reports/purchase_lines' \
  --header "Authorization: Bearer $RUKA_API_KEY" \
  --data-urlencode 'issued_from=2026-08-01' \
  --data-urlencode 'issued_to=2026-08-31' \
  --data-urlencode 'page=1' \
  --data-urlencode 'per_page=50'

No se ejecuta desde esta página. RUKA_API_KEY es una variable de tu servidor, nunca del navegador.

Buscar un parámetro

Parámetros obligatorios

issued_fromdatequery · obligatorio: Inicio inclusivo, YYYY-MM-DD.
Ejemplo: "2026-08-01"
issued_todatequery · obligatorio: Fin inclusivo, YYYY-MM-DD. Diferencia máxima: 31 días.
Ejemplo: "2026-08-31"

Ver 15 parámetros opcionales

pageintegerquery · opcional

Entero positivo. Página solicitada.

Por defecto: 1

Ejemplo: 1

per_pageintegerquery · opcional

Entero positivo; valores mayores a 100 se reducen a 100.

Por defecto: 50

Ejemplo: 50

vendor_tax_idstringquery · opcional

RUT exacto del proveedor; sin coincidencia devuelve datos vacíos.

Ejemplo: "76123456-0"

foliostringquery · opcional

Folio exacto.

Ejemplo: "1001"

dte_typeintegerquery · opcional

Tipo DTE positivo; restringe 33/34 o 33/34/61/56 al incluir notas.

Ejemplo: 33

include_credit_notesbooleanquery · opcional

Agrega NC 61 y ND 56; usa montos originales cuando existen, sin cambiar su signo.

Por defecto: false

Admite: true · false · 1 · 0

Ejemplo: true

include_excludedbooleanquery · opcional

Incluye excluidos, nunca reclamados.

Por defecto: false

Admite: true · false · 1 · 0

Ejemplo: true

company_idsinteger[]query · opcional

IDs positivos por comas o array (company_ids[]). Intersecta empresas autorizadas.

Ejemplo: [1,2]

cost_center_idsinteger[]query · opcional

IDs positivos por comas o array. División → línea → factura; expone solo centros coincidentes.

Ejemplo: [1,2]

due_fromdatequery · opcional

Vencimiento desde, YYYY-MM-DD; opcional e inclusivo.

Ejemplo: "2026-09-01"

due_todatequery · opcional

Vencimiento hasta, YYYY-MM-DD; no anterior al inicio.

Ejemplo: "2026-09-30"

reviewedstringquery · opcional

Estado de revisión.

Por defecto: "all"

Admite: all · yes · no

Ejemplo: "yes"

acknowledgedstringquery · opcional

Presencia de acuse SII.

Por defecto: "all"

Admite: all · yes · no

Ejemplo: "yes"

style_modestringquery · opcional

Materia prima (incluye sin estilo), ambos o solo administrativos. Prevalece sobre include_g_adm.

Por defecto: "raw_material_and_gadm"

Admite: raw_material_only · raw_material_and_gadm · gadm_only

Ejemplo: "raw_material_and_gadm"

date_basisstringquery · opcional

Emisión o mes de reporte completo; sin mes, acuse y luego emisión.

Por defecto: "issued"

Admite: issued · reporting

Ejemplo: "reporting"

Respuesta de ejemplo

Respuesta de éxito del ejemplo. No acredita una conexión real.

Respuesta sintética · HTTP 200

{
  "data": [
    {
      "id": 900001,
      "line_number": 1,
      "name": "Harina de ejemplo",
      "description": "Saco de ejemplo",
      "quantity": "2.0",
      "unit_price": "500.0",
      "amount": "1000.0",
      "vat_amount": "190.0",
      "additional_tax_amount": "0.0",
      "discount": "0.0",
      "surcharge": "0.0",
      "product_id": 900001,
      "unit": null,
      "classification": {
        "supply": {
          "id": 900001,
          "name": "Harina"
        },
        "style": {
          "id": 900001,
          "name": "Harinas"
        },
        "product_type": {
          "id": 900001,
          "name": "Abarrotes"
        },
        "general_category": {
          "id": 900001,
          "name": "Alimentos"
        },
        "included_in_report": true
      },
      "cost_center_allocations": [
        {
          "cost_center": {
            "id": 900001,
            "name": "Cocina"
          },
          "quantity": "2.0",
          "amount": "1000.0",
          "percentage": "100.0",
          "vat_amount": "190.0",
          "additional_tax_amount": "0.0",
          "discount": "0.0",
          "surcharge": "0.0"
        }
      ],
      "accounting": {
        "mode": "single",
        "effective": {
          "id": 900001,
          "name": "Materia prima",
          "path": [
            {
              "id": 900001,
              "level": 0,
              "name": "Materia prima"
            }
          ]
        },
        "resolved_from": "line_item",
        "dimensions": {
          "line_item": {
            "id": 900001,
            "name": "Materia prima",
            "path": [
              {
                "id": 900001,
                "level": 0,
                "name": "Materia prima"
              }
            ]
          },
          "supply": {
            "id": 900001,
            "name": "Materia prima",
            "path": [
              {
                "id": 900001,
                "level": 0,
                "name": "Materia prima"
              }
            ]
          },
          "product": null,
          "invoice": null
        },
        "splits": []
      },
      "invoice": {
        "id": 900001,
        "folio": "1001",
        "dte_type": 33,
        "issued_on": "2026-08-12",
        "due_on": "2026-09-12",
        "reporting_month": null,
        "status": "registered",
        "company": {
          "id": 900001,
          "name": "Empresa de ejemplo SpA",
          "tax_id": "76123456-0"
        },
        "vendor": {
          "id": 900001,
          "name": "Proveedor de ejemplo SpA",
          "tax_id": "76234567-4"
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 1,
    "total_pages": 1
  }
}

Leer los campos de este ejemplo

Primer registro de data. Tipos observados en esta respuesta sintética; no reemplazan el esquema del contrato.

id: number
line_number: number
name: string · texto
description: string · texto
quantity: string · texto
unit_price: string · texto
amount: string · texto
vat_amount: string · texto
additional_tax_amount: string · texto
discount: string · texto
surcharge: string · texto
product_id: number
unit: null · sin valor
classification: objeto
cost_center_allocations: array · 1 elementos
accounting: objeto
invoice: objeto

Variantes del contrato, no respuestas en vivo ni un esquema exhaustivo. Elegir una respuesta aquí no cambia los parámetros de la petición.

Lo importante de esta operación

Rango obligatorio: issued_from e issued_to en YYYY-MM-DD, ambos inclusivos; la diferencia entre ellos no puede superar 31 días. Los filtros se aplican antes de contar y paginar.
Filtra por emisión e incluye todos los estilos por defecto. date_basis=reporting usa mes de reporte completo; si falta, acuse y luego emisión.
Los filtros de estilo y centro devuelven sólo las líneas coincidentes; cost_center_allocations no multiplica filas. Orden: emisión, ID de factura e ID de línea.
Paginación con page y per_page (default 50, máximo 100). La respuesta trae data y meta con page, per_page, total y total_pages.
Incluye DTE 33 y 34. include_credit_notes agrega 61 y 56 con sus montos originales cuando existen, sin cambiar el signo.
Centro de costo por división, luego línea y luego factura. Los montos divididos ya son absolutos; IVA, impuestos, descuento y recargo se prorratean. DTE 34 y líneas exentas no generan IVA.
accounting trae mode, effective, resolved_from, dimensions y splits. Precedencia: línea, insumo, producto y factura. Una división usa mode: split. Porcentajes en escala humana: 75.0 es 75 %.
Montos y cantidades llegan como strings decimales. Los valores desconocidos pueden ser null.

Contrato completo de esta operación

Índice completo de endpoints

GET /api/v1/ping

Valida la clave y devuelve su API ID.

GET /api/v1/reports/purchase_invoices

Pagina facturas con line_items anidados y meta. Montos y cantidades decimales como strings.

GET /api/v1/reports/purchase_lines

Pagina líneas con invoice y cost_center_allocations; no multiplica filas por centro. Decimales como strings.

GET /api/v1/products/:id/classification

Insumo, estilo, tipo y categoría general del producto autorizado. Los niveles sin asignar son null.

GET /api/v1/reports/purchase_book

Detalle del libro de compras con aprobación interna en Ruka. Incluye líneas, impuestos, referencias, clasificaciones y datos originales del libro; no incluye el XML.

GET /api/v1/purchase_documents

Busca por folio, tipo DTE y RUT emisor. Devuelve el XML almacenado, su contenido convertido a JSON o el PDF generado por Ruka. Solo documentos aprobados internamente en Ruka.

GET /api/v1/webhooks

Consulta las URLs registradas, sus eventos y su configuración de entrega. Los secretos nunca se incluyen en la respuesta.

POST /api/v1/webhooks

Registra una URL para recibir los eventos seleccionados mediante POST application/json. Puedes enviar un mismo evento a varios destinos.

PATCH /api/v1/webhooks/:id

Cambia los eventos, el formato o la autenticación de un webhook. Los campos omitidos conservan su valor.

DELETE /api/v1/webhooks/:id

Da de baja un webhook y cancela sus entregas pendientes. Una petición que ya comenzó puede finalizar.

Una integración confiable empieza por leer bien los datos.

No todos los reportes se recorren igual. Elige la ruta según la tarea y conserva sus filtros durante toda la extracción.

Facturas y líneas

Por número de página.

page=1page=2hasta meta.total_pages

Usa issued_from y issued_to. Ambos extremos se incluyen y su diferencia no puede superar 31 días. Continúa hasta meta.total_pages, con un máximo de 100 registros por página.

En facturas, los filtros de líneas seleccionan documentos, pero mantienen el total completo de la factura. En líneas, recibes solo las que coinciden.

Implementar una carga paginada

Libro de compras

Por cursor de continuación.

next_after_idafter_id

Usa start_date y end_date. El final debe ser anterior al mismo día del mes siguiente al inicio. Envía meta.next_after_id como after_id hasta que el cursor sea null.

Con date_basis=updated puedes buscar cambios. El libro expone estado actual, no un historial de eliminaciones: solapa ventanas y reconcilia lo que ya guardaste.

Implementar cursor y reconciliación

Precisión, unidades y valores que faltan

Los importes y cantidades pueden llegar como strings decimales. Conserva su precisión y trata null como información desconocida, no como cero. cost_center_allocations no multiplica la línea original: no sumes su importe y sus repartos dos veces.

Notas de crédito y débito

include_credit_notes=true incorpora DTE 61 y 56 con sus montos originales, sin invertir el signo automáticamente. Define el tratamiento por tipo de documento antes de sumar; no restes una nota dos veces.

El documento correcto para cada uso

purchase_documents usa folio, dte_type y vendor_tax_id. Conserva ceros iniciales del folio y agrega company_id si hay ambigüedad. JSON representa el XML almacenado; XML entrega ese archivo; PDF es una representación generada por Ruka, no el original del proveedor.

Claves, identidades y migraciones

Una clave solo permite consultar el alcance de su cuenta. No asumas que los IDs de una integración anterior coinciden con V3. Comprueba equivalencias, permisos y empresas antes de migrar. No expongas la clave en un frontend.

Recibe el cambio.
No pierdas el contexto.

Los webhooks evitan consultar todo el día. Tu receptor debe estar preparado para una entrega repetida, un retraso o una caída.

Construir el receptor Descargar verificador de firma

Ejemplo Node.js. No incluye almacenamiento ni un worker.

01Verificar firma
02Guardar evento
03Responder 2xx
04Procesar en cola

Primero guarda. Después confirma.

Si la firma es válida, persiste el evento y el trabajo pendiente antes del 2xx. Una respuesta rápida no sirve si el proceso se cae y el evento se pierde.

Cómo verificar la firma

Usa HMAC-SHA256 sobre timestamp + punto + cuerpo crudo, sin volver a serializar el JSON. Compara en tiempo constante y controla la antigüedad del timestamp. El verificador descargable muestra este paso; no incluye la cola ni la base de datos.

Guía de diseño del receptor, no una entrega en vivo. Considera eventos fuera de orden y reconcilia el histórico.

Llevarlo a mi pauta de integración

Antes de registrar una suscripción

Necesitas una clave permanente de la persona dueña de la cuenta con administración y reportes, y un receptor HTTPS en el puerto 443 que responda al HEAD de comprobación con 2xx o 405. Guarda el signing_secret al crear: solo se muestra una vez. PATCH reemplaza la lista de eventos; agregar uno no recupera el pasado.

Eventos, intentos y contrato de entrega

Un error. Un siguiente paso claro.

El estado HTTP es el comienzo, no el diagnóstico completo. Consulta también el código del cuerpo y la operación que llamaste.

Revisa la clave

Puede estar inválida, revocada o fuera del acceso habilitado. En administración de webhooks también importa que sea permanente. No repitas la misma petición indefinidamente.

Códigos del contrato · ejemplos

invalid_tokenComprobar acceso

No todos estos códigos corresponden a todas las operaciones. El enlace lleva al contrato de un endpoint que lo documenta.

Antes de ponerlo a trabajar.

Una pauta para llevar a tu equipo. Marca lo que ya revisaste y descarga los pendientes.

0 / 8 revisados

Se conserva solo mientras estás en esta página. Marcar todo no verifica tu implementación ni habilita la API.

Acceso y empresas confirmadosProbé la clave y los permisos de la operación sobre una cuenta autorizada.

Clave fuera del frontendLa credencial está en el servidor; no aparece en código público ni logs.

Identidades y unidades resueltasDefiní equivalencias de IDs, precisión decimal y tratamiento de valores null.

Todas las páginas recorridasUso el mecanismo correcto de continuación y guardo el avance después de persistir.

Errores con una salida definidaDistingo permisos, parámetros, conflictos y fallos transitorios; limito los reintentos.

Webhooks protegidos, si los usoVerifico firma, persisto antes del 2xx y proceso sin duplicar efectos. Si no uso webhooks, lo marco como revisado sin aplicación.

Reconciliación y recuperación probadasComprobé qué ocurre con datos atrasados, repetidos y una ejecución interrumpida.

Resultado contrastado con RukaRevisé el resultado en destino contra los documentos de la cuenta autorizada.

Llévate el contrato a tus herramientas.

OpenAPI 3.1 con las diez operaciones, autenticación, parámetros y respuestas de referencia. Impórtalo en tu entorno: no es un SDK ni una sandbox.

Descargar OpenAPI · JSON

Antes de conectar
una cuenta real.

¿Qué puedo consultar con la API de Ruka?

El contrato público incluye facturas y líneas de compra, clasificaciones de productos, un libro de compras con revisión interna, documentos en JSON, XML o PDF y administración de webhooks. El acceso depende de la cuenta, sus permisos y las empresas autorizadas.

¿Dónde obtengo la clave y dónde debo guardarla?

Accede a la documentación con tu cuenta para revisar la habilitación y las credenciales disponibles. Usa Authorization: Bearer y guarda la clave en el servidor, fuera del código público y del navegador. Comprobar /api/v1/ping valida la clave, no concede permisos de reportes.

¿Puedo probar aquí con una clave real?

No. Este explorador muestra ejemplos del contrato y no envía peticiones. No solicita credenciales ni es una sandbox. Los ejemplos de respuesta son sintéticos; la validación con datos autorizados se hace desde tu entorno.

¿La API registra automáticamente compras en mi ERP?

La API permite consultar datos. Tu integración debe mapear identidades, decidir cómo persistir cada documento y reconciliar el resultado. No escribe automáticamente en un ERP externo. Si necesitas implementar el proceso, puedes evaluar su alcance con Ruka One.

¿Los webhooks reemplazan una carga histórica?

No. Los eventos pueden repetirse o llegar fuera de orden y agregar una suscripción no recupera el pasado. Combina un receptor con firma verificada, persistencia y deduplicación con consultas de reconciliación del histórico.

¿Esta documentación incluye emisión de DTE?

Esta referencia pública documenta compras y webhooks, no una API de emisión. RukaFactura es otra capacidad de Ruka; no asumas que compartir el dominio de la API habilita emisión de documentos en estos endpoints.

Referencia revisada el 26 de octubre de 2026. Consulta el contrato enlazado para los campos y permisos vigentes. Los ejemplos de esta página no consultan datos de clientes.

Tus datos operativos. En lo que quieras construir.

Tu primera conexión

Comprueba la clave

Empieza por lo que quieres construir.

Del total de la factura al costo de cada insumo.

Las compras revisadas, listas para tu integración.

Que un cambio en Ruka ponga tu flujo en marcha.

Del contrato al código.

Líneas de compra

Petición de ejemplo

Parámetros obligatorios

Una integración confiable empieza por leer bien los datos.

Por número de página.

Por cursor de continuación.

Recibe el cambio.
No pierdas el contexto.

Primero guarda. Después confirma.

Mismo evento, un solo efecto.

Sin autenticidad, no hay trabajo que ejecutar.

Un error. Un siguiente paso claro.

Revisa la clave

Códigos del contrato · ejemplos

Revisa los permisos

Códigos del contrato · ejemplos

Revisa identidad y disponibilidad

Códigos del contrato · ejemplos

Resuelve el conflicto

Códigos del contrato · ejemplos

Corrige los parámetros

Códigos del contrato · ejemplos

Espacia las solicitudes

Códigos del contrato · ejemplos

Conserva el trabajo pendiente

Códigos del contrato · ejemplos

Antes de ponerlo a trabajar.

Llévate el contrato a tus herramientas.

Antes de conectar
una cuenta real.

Empieza por lo que quieres construir.

Del total de la factura al costo de cada insumo.

Las compras revisadas, listas para tu integración.

Que un cambio en Ruka ponga tu flujo en marcha.

Del contrato al código.

Líneas de compra

Petición de ejemplo

Parámetros obligatorios

Una integración confiable empieza por leer bien los datos.

Por número de página.

Por cursor de continuación.

Recibe el cambio.No pierdas el contexto.

Primero guarda. Después confirma.

Mismo evento, un solo efecto.

Sin autenticidad, no hay trabajo que ejecutar.

Un error. Un siguiente paso claro.

Revisa la clave

Códigos del contrato · ejemplos

Revisa los permisos

Códigos del contrato · ejemplos

Revisa identidad y disponibilidad

Códigos del contrato · ejemplos

Resuelve el conflicto

Códigos del contrato · ejemplos

Corrige los parámetros

Códigos del contrato · ejemplos

Espacia las solicitudes

Códigos del contrato · ejemplos

Conserva el trabajo pendiente

Códigos del contrato · ejemplos

Antes de ponerlo a trabajar.

Llévate el contrato a tus herramientas.

Antes de conectaruna cuenta real.

Recibe el cambio.
No pierdas el contexto.

Antes de conectar
una cuenta real.