Acceso
La contabilidad se divide en scopes según el tipo de dato, y la aplicación recibe solo lo que necesita:
| Scope | Qué abre |
|---|---|
fiscal:read | Razones sociales, comprobantes fiscales con su PDF, períodos fiscales, retenciones y percepciones con sus certificados. |
finance:read | Cuentas, 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:read | Proveedores con sus comprobantes y pagos, compensaciones, órdenes de compra, recepciones, devoluciones al proveedor, liquidaciones de consignación. |
orders:read, payments:read, refunds:read | Ventas: 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:
- Datos de referencia: razones sociales, cuentas y categorías de dinero, proveedores, períodos fiscales.
- Ventas: comprobantes fiscales, pedidos, pagos, devoluciones.
- 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:
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 factura | fiscal_document.issued, fiscal_document.failed, fiscal_document.annulled |
| Se cerró o se reabrió un período fiscal | tax_period.status_changed |
| Se registró, cambió o borró un movimiento de dinero | money_transaction.created, money_transaction.updated, money_transaction.deleted |
| Se contabilizó o anuló un comprobante de proveedor | supplier_bill.posted, supplier_bill.voided |
| Se registró o anuló un pago a proveedor | supplier_bill_payment.created, supplier_bill_payment.deleted |
| Se registró o anuló una retención | tax_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_linesde 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_linesde 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.
| Tarea | De dónde tomarlo |
|---|---|
| Asientos, libros de IVA, declaraciones juradas | Comprobantes 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ónica | El impuesto del pedido y de la devolución. |
| El archivo Libro IVA Digital para el portal de ARCA | La operación masiva libro_iva.export: mirá «Libros de IVA» más abajo. |
| Una venta facturada por una caja externa | El 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):
| Campo | Qué es |
|---|---|
issuer | La caja que emite el comprobante: fudo, poster. |
status | pending: la cuenta está abierta en la caja; issued: la caja emitió el comprobante. |
number | Nú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
currencyde al lado:150000en ARS son 1.500,00. - La fecha contable es
YYYY-MM-DDen 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
amounten la moneda de la tienda,account_amounten la moneda de la cuenta yexchange_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) ydocument {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:
curl "https://api.saleya.app/v1/exchange-rates/USD?date=2026-11-03" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"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
withholdingsy no se registra nada. - En Ingresos Brutos (
turnover) y en la tasa municipal (municipal) la provincia enjurisdictiones 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.