Contabilidad por API

La contabilidad de la tienda —comprobantes fiscales, dinero, compras e impuestos— se lee con los mismos feeds de cambios que el catálogo: cargá todo una vez y después mantené la copia al día con eventos y el cursor.

Cargando el índice de búsqueda…

Contabilidad por API

Acceso

La contabilidad se divide en scopes según el tipo de dato, y la aplicación recibe solo lo que necesita:

ScopeQué abre
fiscal:readRazones sociales, comprobantes fiscales con su PDF, períodos fiscales, retenciones y percepciones con sus certificados.
finance:readCuentas, categorías y movimientos de dinero, transferencias, el tipo de cambio del día contable, turnos de caja, gift cards, cuentas corrientes de clientes.
procurement:readProveedores con sus comprobantes y pagos, compensaciones, órdenes de compra, recepciones, devoluciones al proveedor, liquidaciones de consignación.
orders:read, payments:read, refunds:readVentas: pedidos con el impuesto de cada ítem, pagos y devoluciones.

Dos scopes agregan campos a otros recursos: costs:read suma el costo de los ítems del pedido, customers:read suma el receptor del comprobante fiscal (son datos personales).

Escribir requiere scopes aparte: finance:write para movimientos y transferencias, procurement:write para proveedores, órdenes de compra y comprobantes de proveedor, fiscal:write para emitir facturas. Aprobar un comprobante para pago (procurement:approve), pagarlo fuera del sistema (procurement:pay) y anular una factura (fiscal:annul) son permisos aparte: el scope de escritura no los incluye, y el dueño de la tienda activa cada uno en el acceso de la aplicación.

Carga inicial

Cada listado es un feed de cambios: leelo hasta el final y guardá el sync_cursor — mirá paginación y sincronización. Los feeds son independientes, pero los comprobantes apuntan a los datos de referencia por id, así que conviene cargar primero esos datos:

  1. Datos de referencia: razones sociales, cuentas y categorías de dinero, proveedores, períodos fiscales.
  2. Ventas: comprobantes fiscales, pedidos, pagos, devoluciones.
  3. Dinero y compras: movimientos de dinero, comprobantes de proveedor, sus pagos, retenciones.

updated_since arranca la carga desde un momento y no desde el principio del historial; por ejemplo, desde el inicio del ejercicio. Es un momento con zona horaria, así que la medianoche de la tienda en Buenos Aires es T03:00:00Z:

Solicitud
curl "https://api.saleya.app/v1/fiscal-documents?updated_since=2026-01-01T03:00:00Z&limit=250" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"

Los períodos fiscales los llevan las tiendas con contabilidad impositiva argentina; para una tienda de otro país su listado responde 403 capability_disabled.

Después: eventos y cursor

Suscribí una URL a los eventos contables — mirá webhooks. El evento avisa que un registro cambió, y la fuente de verdad sigue siendo el listado: con cada evento, sincronizá ese listado con el cursor guardado.

Qué pasóEvento
ARCA emitió un comprobante, la emisión falló, se anuló una facturafiscal_document.issued, fiscal_document.failed, fiscal_document.annulled
Se cerró o se reabrió un período fiscaltax_period.status_changed
Se registró, cambió o borró un movimiento de dineromoney_transaction.created, money_transaction.updated, money_transaction.deleted
Se contabilizó o anuló un comprobante de proveedorsupplier_bill.posted, supplier_bill.voided
Se registró o anuló un pago a proveedorsupplier_bill_payment.created, supplier_bill_payment.deleted
Se registró o anuló una retencióntax_withholding.created, tax_withholding.annulled

Sincronizá los feeds también de forma programada: un evento puede no llegar, y un listado con cursor no se saltea nada.

Qué impuesto usar

El impuesto de una venta aparece en dos lugares, y son dos verdades distintas:

  • el impuesto del pedido: tax_lines de los ítems, el envío y el total de un pedido y de una devolución. Lo calcula la tienda con la clasificación impositiva de los productos al momento de la venta;
  • el impuesto del comprobante: tax_lines de un comprobante fiscal. Lo autorizó ARCA y lo determina el régimen de la razón social emisora. Este impuesto es el que vale legalmente.

Pueden diferir con razón: un monotributista emite factura C sin impuesto aunque el producto esté gravado, y una tienda con varias razones sociales reparte las ventas entre ellas; al emisor lo indica el legal_entity_id del comprobante.

TareaDe dónde tomarlo
Asientos, libros de IVA, declaraciones juradasComprobantes fiscales con estado issued: facturas, notas de crédito y de débito.
Contabilidad de gestión: margen, ventas por alícuota, tienda sin facturación electrónicaEl impuesto del pedido y de la devolución.
El archivo Libro IVA Digital para el portal de ARCALa operación masiva libro_iva.export: mirá «Libros de IVA» más abajo.
Una venta facturada por una caja externaEl comprobante de la caja: mirá «Ventas de una caja externa» más abajo.

La línea de impuesto es la misma en los dos lugares: {regime, kind, rate_bps, base, amount, jurisdiction}. rate_bps es la alícuota en puntos básicos (2100 es 21 %), jurisdiction es la provincia en los impuestos que la necesitan. Tomá amount tal cual en vez de recalcularlo con la base y la alícuota: el impuesto está redondeado igual que en el comprobante.

Ventas de una caja externa

Una venta que pasó a una caja FuDo o Poster, o que vino de ella, la factura esa caja: no hay comprobante fiscal de Saleya. El pedido trae el campo external_fiscal_document (solo con el scope fiscal:read):

CampoQué es
issuerLa caja que emite el comprobante: fudo, poster.
statuspending: la cuenta está abierta en la caja; issued: la caja emitió el comprobante.
numberNúmero del comprobante en la caja; null hasta que se emite o si la caja no lo informa.

external_fiscal_document: null significa que no hay comprobante de la caja. El impuesto que vale legalmente en esa venta está en el comprobante de la caja: no lo busques entre los comprobantes fiscales de Saleya ni registres el impuesto del pedido por segunda vez. Emitir la factura más tarde para ese pedido se rechaza: un segundo comprobante de la misma venta duplicaría el impuesto.

Importes, fechas y tipos de cambio

  • Los importes son enteros en unidades menores de la moneda del campo currency de al lado: 150000 en ARS son 1.500,00.
  • La fecha contable es YYYY-MM-DD en la zona horaria de la tienda (occurred_on, issued_on), y el período fiscal, YYYY-MM. Un momento es ISO 8601 en UTC (occurred_at). Un comprobante con fecha contable del 31 queda en su mes aunque en UTC ya sea el siguiente.
  • Los tipos de cambio y las cantidades son strings decimales, no números de punto flotante.
  • Un movimiento de dinero en una cuenta en otra moneda trae amount en la moneda de la tienda, account_amount en la moneda de la cuenta y exchange_rate, el tipo de cambio con el que se convirtió.
  • source {type, id} es el registro que generó el movimiento (un pago, una devolución, un pago a proveedor) y document {type, id}, su comprobante de origen (un pedido, un comprobante de proveedor, un turno de caja): conciliá por ellos y no por importe y fecha.

El tipo de cambio del día contable, con el que los libros convierten los movimientos en otra moneda de esa fecha, lo da el tipo de cambio de la moneda:

Solicitud
curl "https://api.saleya.app/v1/exchange-rates/USD?date=2026-11-03" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Respuesta
HTTP/1.1 200 OK

{
  "currency": "USD",
  "store_currency": "ARS",
  "date": "2026-11-03",
  "rate": "1452.5",
  "rate_date": "2026-11-03",
  "source": "ar_oficial"
}

rate: null significa que el tipo de cambio de ese día todavía no se fijó: lo fija la primera operación en otra moneda del día.

Retenciones al pagar a proveedores

Una tienda agente de retención retiene impuesto del pago al proveedor. En un pago del comprobante fuera del sistema, las líneas de withholdings llevan el importe en la moneda del comprobante del proveedor, y ese importe reduce lo que cobra el proveedor.

  • La retención entra en el registro de retenciones en la moneda de la tienda, al tipo de cambio del día contable del pago, porque en esa moneda se deposita y se declara. Un comprobante en dólares con una retención de 10 dólares da un registro en pesos al tipo de cambio de ese día.
  • Si no hay tipo de cambio para el día del pago, el pago se rechaza con 422 en withholdings y no se registra nada.
  • En Ingresos Brutos (turnover) y en la tasa municipal (municipal) la provincia en jurisdiction es obligatoria: sin ella la retención no entraría en ninguna declaración.
  • El certificado que la tienda le da al proveedor es el PDF de la retención.

En el registro están tanto el impuesto que retuvo la tienda (direction: practiced, hay que depositarlo) como el que le retuvieron a la tienda un banco, un procesador de pagos o un cliente agente (direction: suffered, va a cuenta).

Períodos cerrados

La tienda cierra un período fiscal una vez presentado, y sus comprobantes ya no cambian: ni en el panel de la tienda ni por la API. Una escritura que cambiaría un período cerrado recibe 422 validation_error en su campo, tax_period en un comprobante de proveedor, con el mismo texto que ve una persona en el panel.

La corrección se hace con un comprobante del siguiente período abierto (una nota), o se reabre el período en la tienda. El estado del período está en el listado de períodos y en el evento tax_period.status_changed.

Libros de IVA y paquete para el contador

Los archivos reglamentarios los arma una operación masiva, no un feed: libro_iva.export arma los libros Libro IVA Digital de una razón social para un mes en el formato del portal de ARCA, y accountant_package.export, el paquete para el contador (libros, saldo de IVA, registro de retenciones e Ingresos Brutos) en un solo ZIP.

Si un libro no se puede armar por comprobantes del período, la operación termina en failed y error.documents nombra cada comprobante con su motivo: corregilos en la tienda y volvé a lanzar la operación.

Siguiente guíaErrores