Saltar al contenido
API de Ruka

Guía de integración

Entrega las compras revisadas a tu ERP.

Usa el libro de compras aceptadas para consultar documentos con revisión interna y conservar sus códigos, líneas y referencias en tu integración contable.

Revisado el

Qué vas a construir

Un flujo de lectura con paginación y reconciliación. Tu integración decide cómo registrar cada documento en el ERP, sin confundir revisión interna con aceptación ante el SII.

Antes de empezar

  • Clave de la cuenta con permiso de reportes y empresas autorizadas.
  • Documentos revisados internamente en Ruka, no reclamados ni excluidos.
  • Un mapeo explícito de empresas, proveedores y cuentas contables entre Ruka y tu ERP. Los IDs de V3 no tienen por qué coincidir con una integración anterior.

1. Define la ventana y el alcance.

GET /api/v1/reports/purchase_book usa start_date y end_date, no los filtros de fecha de purchase_lines. Las fechas son inclusivas y el final debe ser anterior al mismo día del mes siguiente al inicio. Por ejemplo, del 1 al 31 de octubre cabe; del 1 de octubre al 1 de noviembre no.

date_basis=updated permite encontrar documentos emitidos antes que cambiaron durante la ventana. El corte usa America/Santiago. Por defecto se excluyen documentos sin XML; include_without_xml=true permite incluirlos, pero no fabrica el archivo que falta.

1. Define la ventana y el alcance.
curl --fail-with-body --get \
  'https://api.rukafactura.cl/api/v1/reports/purchase_book' \
  --header "Authorization: Bearer $RUKA_API_KEY" \
  --data-urlencode 'start_date=2026-10-01' \
  --data-urlencode 'end_date=2026-10-26' \
  --data-urlencode 'date_basis=updated' \
  --data-urlencode 'per_page=100'

2. Continúa por cursor, no por número de página.

Toma meta.next_after_id y envíalo como after_id, conservando todos los filtros. Termina cuando next_after_id sea null. El ejemplo descargable rechaza cursores que se repiten para no quedarse en un bucle.

Guarda documentos por su identidad y api_changed_at en tu destino; el nombre concreto de tu tabla depende de tu integración. Solo confirma el avance después de persistir el lote. Un fallo intermedio no debe transformarse en un período marcado como completo.

2. Continúa por cursor, no por número de página.
import { purchaseBookPages } from './ruka-purchases.mjs';

for await (const page of purchaseBookPages({
  start_date: '2026-10-01',
  end_date: '2026-10-26',
  date_basis: 'updated',
}, { token: process.env.RUKA_API_KEY })) {
  // Actualiza tu destino por identidad y versión.
  // Persiste page.data antes de guardar el checkpoint.
}

3. Recupera el documento que necesitas.

GET /api/v1/purchase_documents identifica el documento por folio, dte_type y vendor_tax_id. Conserva los ceros iniciales del folio. Si la misma identidad corresponde a varias empresas receptoras autorizadas, recibirás 409 ambiguous_document: agrega company_id.

response_format=json convierte el XML almacenado y conserva sus etiquetas, atributos y valores como texto. xml entrega el archivo almacenado. pdf genera una representación de Ruka; no es el PDF original del proveedor. Un XML ausente devuelve 404 xml_not_available; un fallo del generador PDF puede devolver 503 pdf_unavailable.

4. Reconciliar también es parte de integrar.

El libro expone el estado actual, no un historial de eliminaciones. Un documento que después se reclama, excluye o deja de estar revisado puede desaparecer del resultado. Solapa ventanas, deduplica por identidad y programa una reconciliación de los documentos que ya guardaste; no interpretes ausencia en una página como autorización para borrar datos contables.

Comprueba en tu muestra que revisión interna, recepción física y acuse del SII se mantienen separados. Esta consulta no declara IVA, no presenta el F29 ni registra automáticamente un asiento en tu ERP.

Antes de conectar producción

  • La carga termina al recibir next_after_id=null.
  • Repetir una ventana actualiza, no duplica.
  • Una falla no adelanta el checkpoint.
  • La ambigüedad de empresa se resuelve explícitamente.
  • Existe reconciliación para documentos que dejan de aparecer.

Ejemplo para tu servidor

Archivo JavaScript legible, para Node.js 22 o superior. No incluye claves, no se ejecuta al descargarlo y no reemplaza la persistencia ni los controles de tu integración.

Descargar ejemplo .mjs

Contrato y mantenimiento

La guía acompaña el contrato publicado en la fecha indicada. Antes de integrar, revisa permisos, filtros y respuestas vigentes en la referencia. Trabaja primero con datos de prueba autorizados.

Ver referencia de esta operación