R2 Connect API

Integrar contabilidad

Cómo llevar ingresos, impuestos y cobros de un negocio en R2 hacia un sistema contable, sin captura manual.

El caso más común de esta API: el contador del negocio deja de capturar a mano lo que ya está en R2. Necesitas dos permisos, read:orders y read:payments.

Qué recurso usar para qué#

Necesitas	Usa	Por qué
Ingreso devengado	`/orders`	La orden registra la venta, con su desglose de impuestos, se haya cobrado o no.
Ingreso cobrado	`/payments`	El pago registra la entrada de dinero, con método y fecha exacta.
Cuentas por cobrar	`balance` de `/orders`	Es el saldo pendiente ya calculado por R2.
Impuestos por enterar	`taxes[]` de `/orders`	Trae cada impuesto por separado, con su tasa y su importe.

Orden y pago no son lo mismo

En R2 una orden existe aunque no se haya pagado, se pague después, se pague en efectivo al llegar o se pague en partes. No asumas que una orden implica dinero recibido: para eso están los pagos. Confundirlos es el error más caro en una integración contable.

Sincronización incremental#

Guarda la fecha de tu última corrida y pide solo lo nuevo. Deja un traslape de un día para no perder registros que se crearon mientras corría el proceso anterior.

javascript

// Corrida diaria de conciliación
const desde = new Date(ultimaCorrida - 24 * 60 * 60 * 1000)
  .toISOString().slice(0, 10);          // traslape de 1 día

const ordenes = await leerTodo("orders",   { created_from: desde });
const pagos   = await leerTodo("payments", { created_from: desde, status: "succeeded" });

for (const orden of ordenes) {
  await asientoDeVenta({
    referencia: orden.order_number,
    fecha:      orden.created_at,
    subtotal:   orden.subtotal,
    impuestos:  orden.taxes,           // cada uno con name, rate y amount
    total:      orden.total,
    porCobrar:  orden.balance,         // 0 si ya está liquidada
  });
}

for (const pago of pagos) {
  await asientoDeCobro({
    referencia: pago.order_number,
    fecha:      pago.succeeded_at,     // fecha contable del cobro
    importe:    pago.amount,
    metodo:     pago.method,           // card, cash, transfer…
    conciliar:  pago.external_id,      // referencia del procesador
  });
}

Cuidados#

Usa order_number como clave de conciliación: es estable y el negocio lo ve en su panel.
Ignora las órdenes con estado cancelled para ingreso, pero regístralas si tu contabilidad exige rastro de cancelaciones.
Una orden con estado refunded exige un asiento de reverso, no borrar el original.
Los importes ya vienen con decimales: no vuelvas a redondear, o descuadrarás centavos contra el estado de cuenta del procesador.
Reprocesar el mismo periodo debe ser idempotente en tu lado; usa order_number y el id del pago para no duplicar asientos.

AnteriorCatálogo SiguienteIntegrar punto de venta