Desarrolladores
Referencia de la API
REST sobre HTTPS con JSON. Cada solicitud lleva un token de aplicación, y el token determina la tienda.
Referencia de la API
- URL base
https://api.saleya.app/v1- Versión
- 1
- Autenticación
- Token de la aplicación de la configuración de la tienda, en Authorization: Bearer <token>.
- Especificación
La propia API da estas direcciones: un GET a la URL base o a la raíz de su host no pide token y devuelve las direcciones de esta referencia, del archivo OpenAPI y de la colección de Postman; las dos primeras vienen también en su encabezado Link (RFC 8631).
Scopes
Una aplicación recibe solo los scopes que eligió la tienda. Un scope de escritura incluye el de lectura de su recurso, y una solicitud sin el scope de su endpoint recibe 403 insufficient_scope.
| Scope | En el panel de la tienda | Qué habilita | Endpoints |
|---|---|---|---|
catalog:read | Catálogo — Lectura | Leer el catálogo: categorías, productos con sus variantes y fotos, reglas de recomendaciones, listas de precios de local con precios y recargos fijos. | |
catalog:write | Catálogo — Escritura | Crear, cambiar y archivar categorías, productos, variantes, opciones y fotos de productos y reglas de recomendaciones; fijar la regla, los precios y los recargos de las listas de precios de local; seguir las descargas de fotos. Incluye catalog:read | |
inventory:read | Stock — Lectura | Leer el stock por local, el registro de movimientos de stock, los lotes, los traslados, los inventarios y los motivos de baja de la tienda. | |
inventory:write | Stock — Escritura | Fijar el stock físico después de un conteo, ingresar mercadería y darla de baja. Incluye inventory:read | |
orders:read | Pedidos — Lectura | Leer pedidos, borradores, estados de pedido, métodos de envío y medios de pago manuales. Los contactos del cliente en los pedidos necesitan además customers:read. | |
orders:write | Pedidos — Escritura | Crear y confirmar borradores, mover pedidos entre estados, cancelarlos y emitir sus envíos con el transportista y cargar el número de seguimiento de un servicio de envíos sin integración. Confirmar un borrador como pagado necesita además payments:write; cancelar un pedido con dinero cobrado, refunds:write. Incluye orders:read | |
orders:wholesale | Pedidos — Listas de precios mayoristas | Condiciones mayoristas — el permiso del panel para llevar la venta mayorista: crear, cambiar y borrar listas de precios mayoristas, sus precios y recargos fijos, y asignar una lista mayorista a un cliente (con customers:write). Incluye orders:read, catalog:read y costs:read: una lista mayorista calcula el precio desde el costo. La venta mayorista no está disponible por la API. Incluye orders:read, catalog:read, costs:read | |
customers:read | Clientes — Lectura | Leer clientes con su libreta de direcciones, datos fiscales y grupos, y ver los contactos, la dirección y el comentario del cliente en los pedidos y el receptor de los comprobantes fiscales. Campos extra en orders:read, fiscal:read | |
customers:write | Clientes — Escritura | Crear y cambiar clientes, su libreta de direcciones y sus datos fiscales; gestionar los grupos de clientes y sus miembros. Incluye customers:read | |
locations:read | Sucursales — Lectura | Leer los locales de la tienda a los que la aplicación tiene acceso. | |
payments:read | Pagos — Lectura | Leer los pagos de los pedidos. | |
payments:write | Pagos — Escritura | Confirmar un pago manual como cobrado y confirmar un borrador como pagado. Incluye payments:read | |
refunds:read | Reembolsos — Lectura | Leer los reembolsos de los pedidos. | |
refunds:write | Reembolsos — Escritura | Calcular y crear reembolsos, confirmar devoluciones manuales de dinero y cancelar pedidos con dinero cobrado. Incluye refunds:read | |
costs:read | Costos — Lectura | Agregar el costo a las variantes del catálogo y a los ítems de los pedidos, y mostrar las listas de precios mayoristas, que calculan el precio desde el costo. No abre endpoints propios y funciona solo junto con catalog:read u orders:read. Campos extra en catalog:read, orders:read | |
fiscal:read | Contabilidad — Lectura | Leer las razones sociales de la tienda, los comprobantes fiscales con su PDF, los períodos fiscales y las retenciones y percepciones con los certificados de la tienda. El receptor del comprobante requiere además customers:read. Junto con orders:read agrega a los pedidos el comprobante de la caja externa. Campos extra en orders:read | |
fiscal:write | Contabilidad — Escritura | Emitir la factura de una venta cerrada, reemitir un comprobante tras una falla o un rechazo del fisco y sacar de control un comprobante rechazado. La emisión va al fisco: la clave de idempotencia es obligatoria. Incluye fiscal:read | |
fiscal:annul | Contabilidad — Anulación de facturas | Anular facturas emitidas con una nota de crédito. Es irreversible: la nota queda en el fisco. No da escritura: emitir comprobantes y anularlos son permisos distintos. Incluye fiscal:read | |
finance:read | Dinero — Lectura | Leer las cuentas de dinero con su saldo, las categorías, el libro de movimientos de dinero con su origen y comprobante principal, la cotización contable del día, los turnos de caja con su arqueo y el diario del cajón, las tarjetas de regalo con la deuda de la tienda y sus movimientos, y las cuentas corrientes de clientes con sus movimientos y su resumen. | |
finance:write | Dinero — Escritura | Registrar ingresos y egresos manuales, editarlos y borrarlos, transferir entre cuentas, categorizar el libro en lote y registrar cobros de cuentas corrientes con dinero ya recibido. Las cuentas y las categorías se manejan en el panel de la tienda. Incluye finance:read | |
procurement:read | Compras — Lectura | Lectura de proveedores con datos fiscales y condiciones de pago, comprobantes de proveedores con impuestos, líneas y saldo pendiente, pagos de comprobantes, saldos, conciliaciones, compensaciones, órdenes de compra, recepciones, devoluciones a proveedores y liquidaciones de consignación. | |
procurement:write | Compras — Escritura | Crear y cambiar proveedores: datos fiscales, condiciones de pago e ID externo. Órdenes de compra: borrador, cambios, colocación, cancelación y cierre. Comprobantes de proveedores: borrador, cambios, eliminación del borrador, registro y anulación. Incluye procurement:read | |
procurement:approve | Compras — Aprobación de pagos de comprobantes | Aprobar el pago de comprobantes de proveedores registrados y revocar la aprobación: sin ella el comprobante no se paga. No otorga escritura: cargar comprobantes y autorizar su pago son facultades distintas. Incluye procurement:read | |
procurement:pay | Compras — Pago de comprobantes de proveedores | Pago de comprobantes de proveedores aprobados fuera del sistema —cuando el dinero salió por fuera de las cuentas de la tienda, por ejemplo desde el banco del ERP— y anulación del pago. No otorga escritura ni aprobación: cargar comprobantes, autorizar su pago y pagarlos son facultades distintas. Incluye procurement:read | |
webhooks:read | Webhooks y eventos — Lectura | Leer el feed de eventos, los endpoints de webhooks y sus entregas. | |
webhooks:write | Webhooks y eventos — Escritura | Crear, cambiar y eliminar endpoints de webhooks, obtener y rotar sus secretos, enviar eventos de prueba y reintentar entregas. Incluye webhooks:read | |
bulk:read | Operaciones masivas — Lectura | Leer las operaciones masivas, descargar sus resultados y consultar las cargas. | |
bulk:write | Operaciones masivas — Escritura | Subir archivos, iniciar y cancelar operaciones masivas. Cada tipo de operación necesita además el scope de su recurso. Incluye bulk:read |
Límites
Topes y plazos de conservación de la API. Los límites de solicitudes del plan llegan en el encabezado RateLimit-Policy de cada respuesta.
| Límite | Valor |
|---|---|
| Registros en una página de un listado (limit). | 250 registros |
| Tokens vigentes de una aplicación: uno en uso y otro en reemplazo. | 2 |
| Cuánto se guarda la respuesta a una solicitud con Idempotency-Key. | 24 horas |
| Cuánto vale un cursor de sincronización; uno más viejo recibe 410 cursor_expired. | 30 días |
| Cuánto se guardan los eventos en GET /v1/events. | 30 días |
| Cuánto quedan las solicitudes en el registro de la aplicación. | 30 días |
| Endpoints de webhooks de una aplicación. | 10 |
| Cuánto espera una entrega de webhook la respuesta del endpoint. | 10 segundos |
| Cuánto sigue firmando el secreto anterior después de una rotación. | 24 horas |
| Reintentos automáticos de una entrega de webhook fallida. | 10 |
| Cuánto duran, aproximadamente, los reintentos automáticos de una entrega. | 72 horas |
| Cuánto puede fallar un endpoint sin un solo éxito antes de que se desactive. | 72 horas |
| Operaciones masivas de una aplicación en espera o en curso a la vez. | 5 |
| Tamaño del archivo de entrada de una operación masiva. | 256 MB |
| Tamaño de una línea de la entrada. | 1 MB |
| Tamaño de una parte de una carga. | 1 MB |
| Cuánto se guardan una operación masiva terminada y sus archivos. | 7 días |
| Cuántas solicitudes por minuto de una misma dirección pueden rechazarse en la entrada (401, 403) antes de que la dirección reciba 429. | 60 |
Recursos
Conceptos básicos
Aplicación y token
En nombre de quién habla el token: la aplicación, sus scopes, locales y límites. La primera llamada: muestra si el token funciona y qué scopes faltan.
Tienda
Con qué se leen todas las demás respuestas: la moneda de los importes, la zona horaria de las fechas y los idiomas del contenido.
Locales
Locales de la tienda: tiendas, depósitos, cocinas y puntos de retiro. El stock, los pedidos y los retiros los nombran.
Catálogo
Categorías
Categorías del catálogo como lista plana: el árbol se arma con parent_id. Se crean, cambian, archivan y vinculan por el ID externo.
- getListar las categorías del catálogo cambiadas desde un momento dado
- postCrear una categoría del catálogo
- getObtener una categoría del catálogo
- patchCambiar una categoría del catálogo
- deleteArchivar una categoría del catálogo
- getObtener una categoría del catálogo por su ID externo
- patchCrear o cambiar una categoría del catálogo por su ID externo
Productos
Fichas de producto: nombres, descripciones, categorías, opciones y fotos. Las variantes tienen sus endpoints; el producto se escribe junto con ellas.
- getListar los productos: categorías, opciones y fotos, sin variantes
- postCrear un producto con sus variantes
- getObtener un producto
- patchModificar la ficha de un producto: campos, categorías, ID externo
- deleteArchivar un producto con sus variantes
- getObtener un producto por su ID externo
- patchCrear o modificar un producto con sus variantes por su ID en la app
- putReemplazar las opciones del producto y distribuir sus variantes
Variantes
Lo que se vende y se guarda en stock: SKU, códigos de barras, precios, unidad y forma de venta. Cambian bajo la versión de la ficha del producto.
- getListar las variantes: SKU, códigos de barras, precios y unidades
- postAgregar una variante a un producto
- getObtener una variante
- patchModificar una variante de producto
- deleteArchivar una variante de producto
- getObtener una variante por su ID externo
- patchCrear o modificar una variante por su ID en la app
- getObtener la receta de una variante: componentes y rendimiento del preelaborado
- putReemplazar la receta de una variante: componentes y rendimiento del preelaborado
Fotos del producto
La galería de un producto: agregar una foto por URL, reordenar, elegir la principal, quitar.
Descargas de fotos
Las fotos agregadas por URL se descargan en segundo plano; la descarga muestra su estado y el motivo de una falla.
Grupos de modificadores
Elecciones para un ítem: salsas, extras, tamaño de porción. El grupo fija los límites de la elección; las opciones, el recargo y la composición.
- getListar los grupos de modificadores con opciones cambiados desde el momento indicado
- postCrear un grupo de modificadores con opciones
- getObtener un grupo de modificadores con sus opciones
- patchModificar un grupo de modificadores y su conjunto de opciones
- deleteArchivar un grupo de modificadores
- getObtener un grupo de modificadores por ID externo
- patchCrear o modificar un grupo de modificadores por ID externo
Modificadores del producto
Qué grupos de modificadores tiene un producto, en orden, con su regla de elección y los recargos de opciones por variante.
Reglas de recomendaciones
Qué ofrecer junto a los productos de una categoría o colección, por prioridad: la lista propia del producto, las reglas en orden y la selección automática.
Clases de impuesto
Clases de impuesto de la tienda a las que remiten los productos con tax_class_id: el tipo de impuesto y su alícuota.
Listas de precios
Listas de precios de local y mayoristas: un porcentaje sobre el precio base o sobre el costo, con redondeo. Precios y recargos fijos en feeds propios.
- getListar las listas de precios de la tienda: de local y mayoristas, con su regla y redondeo
- postCrear una lista de precios mayorista
- getObtener una lista de precios
- patchCambiar una lista de precios: ajuste y redondeo, y el nombre de una mayorista; la regla de una lista de local cambia los precios en todos sus locales
- deleteBorrar una lista de precios mayorista; su asignación a clientes se quita con consentimiento
Precios fijos de listas
Precios fijos de variantes en listas de precios, por encima de la regla: el precio en la moneda de la lista y en la moneda de la tienda.
Recargos fijos de listas
Recargos fijos de opciones de modificadores en listas de precios: para una variante o para todas, en la moneda de la lista y en la de la tienda.
- getListar los recargos fijos de opciones de modificadores en listas de precios modificados desde un momento dado
- getObtener un recargo fijo de opción en una lista de precios
- postFijar recargos de opciones de modificadores en una lista de precios, en lote
- postQuitar recargos fijos de opciones de una lista de precios, en lote
Stock
Stock
Stock de una variante en un local: leer los niveles, fijar el stock físico después de un conteo, ingresar o dar de baja mercadería.
Movimientos de stock
Diario del stock físico del local: ventas, recepciones, bajas, inventarios, traslados y sus reversiones. Solo se agrega.
Lotes
Lotes de producto: número del envase, vencimiento y disponibilidad. Los movimientos de stock y las líneas de documentos apuntan al lote.
Traslados
Traslados de mercadería entre locales de la tienda: un documento registrado con líneas. Un error se corrige con un traslado inverso.
Inventarios
Inventarios de un local: alcance, conteo ciego y estado desde el borrador hasta el registro. Las líneas tienen su propio feed.
Líneas de inventario
Lo que encontró el conteo: stock esperado y contado por artículo y lote, la diferencia, el ajuste aplicado y el stock del local después del registro.
Motivos de baja
Motivos de la tienda que nombra una baja: el motivo define el tipo contable y si hace falta un comentario.
Pedidos y pagos
Pedidos
Pedidos de todos los canales: ítems, totales, estado y pago. El listado devuelve los cambios en orden de confirmación; el estado sigue las reglas de la tienda.
- getListar los pedidos cambiados desde un momento dado: ítems, totales, estado del pedido y estado del pago
- getObtener un pedido
- getDescargar en PDF la etiqueta del envío actual del pedido; lleva los datos del destinatario, por eso también requiere customers:read
- postPasar un pedido a otro estado de la tienda
- postCancelar un pedido
- postEmitir el envío del pedido con su transportista: la solicitud se procesa en segundo plano y el resultado aparece en el pedido y llega con order.updated
- postCargar el número de seguimiento de un servicio de envíos sin integración: número, enlace y nombre del servicio
- postQuitar un número de seguimiento cargado a mano
Estados de pedido
Lista de estados de la tienda con los propios, el significado permanente de cada uno y las transiciones permitidas.
Borradores de pedido
Un pedido que prepara la aplicación: se calcula en vivo según catálogo, descuentos y envío, muestra qué impide confirmarlo y al confirmarse es un pedido.
- getObtener un borrador de pedido: ítems, totales y lo que impide confirmarlo
- patchCambiar un borrador de pedido: cliente, entrega, medio de pago e ítems
- deleteEliminar un borrador de pedido
- postCrear un borrador de pedido para un cliente
- postConfirmar el pedido desde un borrador: cobrarle al cliente o registrar el pago como recibido
Pagos
Intentos de pago de los pedidos y su resultado. Aquí se confirman los pagos manuales que esperan el dinero.
Reembolsos
Reembolsos de pedidos: primero el cálculo, después el reembolso de ítems y envío; el dinero vuelve por los medios de pago, la mercadería vuelve al stock.
- getListar las devoluciones de pedidos cambiadas desde un momento dado: ítems y movimientos por pago
- getObtener una devolución de un pedido
- postCalcular la devolución de un pedido y lo que queda por devolver, sin escribir nada
- postDevolver ítems y envío de un pedido: el dinero vuelve por los medios de pago, la mercadería al stock
- postConfirmar que el dinero de la devolución se reintegró fuera del sistema
Métodos de envío
Métodos de envío de la tienda que nombran los pedidos y los borradores.
Medios de pago manuales
Medios de pago manuales de la tienda, como una transferencia bancaria, que nombran los pedidos y los pagos.
Clientes
Clientes
Clientes de la tienda con sus contactos, consentimiento de marketing y libreta de direcciones. Todo esto son datos personales bajo el scope customers:read.
- getListar los clientes cambiados desde un momento dado: contactos, consentimiento de marketing, direcciones y grupos; búsqueda por teléfono, email y grupo
- postCrear un cliente: un nombre y al menos un contacto
- getObtener un cliente
- patchActualizar el nombre, el idioma y el ID externo de un cliente
- getObtener un cliente por su ID externo
- patchCrear o actualizar un cliente por su ID externo
- postAsignar a un cliente una lista de precios mayorista o quitársela
Direcciones de clientes
La libreta de direcciones de un cliente: agregar, cambiar, marcar como principal, eliminar.
Datos fiscales de clientes
Datos fiscales con los que se emiten los comprobantes de los pedidos nuevos del cliente.
Grupos de clientes
Grupos manuales de clientes a los que apuntan descuentos y envíos: VIP, mayoristas, personal. La membresía es el campo group_ids del cliente.
- getListar los grupos de clientes de la tienda: nombre, descripción y si están activos
- postCrear un grupo de clientes
- getObtener un grupo de clientes
- patchCambiar el nombre, la descripción o la actividad de un grupo
- deleteEliminar un grupo: sus membresías se van con él, y las reglas de descuento y los envíos dejan de apuntarle
- postAgregar clientes a un grupo
- postQuitar clientes de un grupo
Contabilidad
Razones sociales
Las razones sociales de la tienda: identificación y condición fiscal, emisoras de comprobantes. Los comprobantes y los períodos fiscales las referencian.
Comprobantes fiscales
Facturas, notas de crédito y de débito de las ventas tal como las emitió el fisco: número, fecha, impuestos, anulación y PDF.
- getListar los comprobantes fiscales cambiados desde un momento: facturas, notas de crédito y de débito en todos los estados
- getObtener un comprobante fiscal
- getDescargar el PDF de un comprobante fiscal, el mismo archivo que recibe el cliente
- postEmitir la factura de una venta cerrada: la emisión corre en segundo plano y el resultado llega como evento
- postReemitir un comprobante tras una falla o un rechazo del fisco
- postSacar de control un comprobante rechazado: no se va a emitir
- postAnular una factura emitida con una nota de crédito
Períodos fiscales
Meses de la contabilidad fiscal de cada razón social: un período cerrado ya se declaró y sus datos no cambian más. Solo tiendas de Argentina.
Retenciones y percepciones
Impuesto que le retuvieron a la tienda, a computar, y el que retuvo la tienda a proveedores, a ingresar; certificados de la tienda en PDF.
Cuentas de dinero
Cuentas donde entra y de donde sale el dinero de la tienda: caja, banco, adquirente, billetera. El saldo está en la moneda de la cuenta.
Categorías de dinero
Árbol de categorías de ingresos y egresos. Una categoría del sistema se reconoce por system_code, no por su nombre.
Movimientos de dinero
Libro de ingresos y egresos por cuenta: importe del asiento, registro que lo asentó y comprobante principal.
- getListar los movimientos de dinero cambiados desde un momento: ingresos y egresos por cuenta con su origen y comprobante principal
- postRegistrar un ingreso o egreso manual en una cuenta de dinero
- getObtener un movimiento de dinero
- patchEditar un movimiento de dinero: en uno con documento de origen, solo la categoría, la contraparte y la descripción
- deleteBorrar un movimiento manual y devolver el saldo de la cuenta
Transferencias entre cuentas
Transferencia de dinero de una cuenta a otra con comisión: alta, edición y baja. Sus partes son movimientos de dinero con transfer_id.
Cotizaciones contables
Cotización de una moneda respecto de la moneda de la tienda en una fecha, la del libro de dinero; para revaluar cuentas y conciliar.
Turnos de caja
Turnos de caja con el arqueo del cajón en cada moneda: fondo inicial, esperado, contado, diferencia y fondo que queda en el cajón.
Movimientos del cajón
Diario del cajón del turno: ventas y devoluciones en efectivo, ingresos, retiros, depósitos, cambio y anulaciones. Solo se agrega.
Motivos de ingreso y retiro
Motivos que nombran un ingreso o retiro de efectivo del cajón, con la categoría en la que el libro de movimientos de dinero lo asienta.
Tarjetas de regalo
Las tarjetas de regalo de la tienda: valor nominal, saldo y deuda de la tienda por cada una. El código no se guarda ni se devuelve.
Movimientos de tarjetas de regalo
Movimientos de las tarjetas: emisión, canje, devolución a la tarjeta, ajuste, anulación y bloqueo. Solo se agregan.
Cuentas corrientes de clientes
La cuenta corriente de cada cliente: saldo, límite de crédito, plazo de pago y resumen de un período con los vencimientos.
- getCuentas corrientes de clientes: saldo, límite de crédito y plazo de pago
- getCuenta corriente de un cliente
- getResumen de la cuenta corriente de un cliente en un período: saldo inicial y final, movimientos con saldo acumulado y deudas abiertas con vencimiento
- postRegistrar un cobro de cuenta corriente con dinero ya recibido: entrada en la cuenta corriente con certificados de retención
Movimientos de cuentas corrientes
Movimientos de las cuentas corrientes: venta a cuenta, cobro, devolución, baja por incobrable, compensación, retención y anulación. Solo se agregan.
Compras
Proveedores
Directorio de proveedores: datos fiscales, moneda de compra, plazo de pago y modo de liquidación, con saldo y conciliación. Sin persona de contacto ni notas.
- getProveedores de la tienda: datos fiscales y condiciones de pago
- postCrear un proveedor: datos fiscales y condiciones de pago
- getProveedor
- patchActualizar los datos fiscales, las condiciones de pago y el ID externo de un proveedor
- getProveedor por su ID externo
- patchCrear o actualizar un proveedor por su ID externo
- getSaldo del proveedor: cuánto le debe la tienda ahora, por componente y vencimiento
- getConciliación de saldos con el proveedor en un período: saldo inicial y final, líneas con saldo acumulado
Comprobantes de proveedores
Cuentas a pagar: facturas, notas de débito y crédito, deudas por entregas sin factura, con IVA por alícuota, percepciones y líneas.
- getComprobantes de proveedores: facturas, notas y deudas por entregas sin factura, con impuestos y líneas
- postCrear un borrador de comprobante de proveedor
- getComprobante de proveedor
- patchCambiar un borrador de comprobante de proveedor
- deleteEliminar un borrador de comprobante de proveedor
- postRegistrar un comprobante de proveedor: entra en las cuentas a pagar y el libro de compras
- postAnular un comprobante de proveedor junto con sus pagos y compensaciones
- postAprobar el pago de un comprobante de proveedor registrado
- postRevocar la aprobación de pago de un comprobante de proveedor
Pagos de comprobantes de proveedores
Con qué y por cuánto se canceló un comprobante: dinero, compensación, nota de crédito, anticipo, gasto del libro o fuera del sistema.
Acuerdos de compensación
La base de una compensación: partes, compensación bilateral o tripartita, número y fecha del contrato, vigencia y calendario de la compensación periódica.
Compensaciones
Documento de compensación: lo que un cliente le debe a la tienda contra lo que la tienda le debe a un proveedor. Si se anula, queda con estado voided.
Líneas de compensaciones
Qué se compensó: un pedido o la deuda de la cuenta corriente del cliente y un comprobante del proveedor, con las cancelaciones que creó la compensación.
Órdenes de compra
Lo que la tienda pidió al proveedor: líneas con cantidad pedida, confirmada y recibida, precio y fecha de entrega prometida.
- getÓrdenes de compra: lo pedido, lo confirmado por el proveedor y lo recibido por línea
- postCrear un borrador de orden de compra
- getOrden de compra
- patchCambiar una orden de compra: el borrador entero; de la colocada, las líneas, la fecha y la nota con revisión
- deleteBorrar un borrador de orden de compra
- postMarcar el borrador como colocado con el proveedor
- postCancelar una orden de compra colocada
- postCerrar una orden de compra recibida
Recepciones
Mercadería recibida del proveedor: líneas con precio del remito y costo, correcciones de antes y después. La anulación marca voided_at.
Devoluciones a proveedores
Mercadería enviada de vuelta al proveedor: líneas y compensación esperada y recibida, sea nota de crédito, reposición o dinero.
Liquidaciones de consignación
Rendición al proveedor de la mercadería en consignación vendida en un período, base de su factura: secciones, líneas y totales.
Operaciones masivas
Cargas
Un archivo grande enviado por partes: la entrada de una operación masiva.
Operaciones masivas
Miles de registros en una solicitud: fijar stock, escribir productos, exportar pedidos. El resultado es NDJSON, una línea por entrada, descargable por rangos.
- getListar las operaciones masivas de la app cambiadas desde un momento dado: avance y resultados
- postIniciar una operación masiva desde una carga o una dirección de entrada, una exportación del listado o la generación de un archivo
- getObtener una operación masiva
- getObtener el resultado de una operación masiva: NDJSON, una línea por línea de entrada o por elemento exportado, o el ZIP de una operación de archivo; se reanuda con Range
- postCancelar una operación masiva en el límite de una línea
Eventos y webhooks
Eventos
Lo que cambió en la tienda en los últimos 30 días, con el registro tal como está ahora. Los mismos eventos van a los endpoints de webhooks.
Endpoints de webhooks
Direcciones a las que la tienda envía eventos firmados según Standard Webhooks; el secreto de firma, su rotación y un evento de prueba.
- getListar los endpoints de webhook de la app
- postAgregar un endpoint de webhook y suscribirlo a tipos de evento
- getObtener un endpoint de webhook
- patchModificar un endpoint de webhook: URL, descripción, tipos de evento, estado
- deleteEliminar un endpoint de webhook
- postEmitir un nuevo secreto de firma: el anterior sigue firmando las entregas junto con él durante 24 horas
- getObtener el secreto de firma de las entregas de un endpoint de webhook
Entregas de webhooks
Qué salió hacia un endpoint, qué espera un reintento y qué falló, con las respuestas del receptor; una entrega se puede reintentar.
- getEntregas de un endpoint de webhook: lo enviado, lo que espera un reintento y lo que falló
- getUna entrega de webhook con todos sus intentos y respuestas del receptor
- postEnviar al endpoint el evento de prueba ping — un intento firmado con el secreto actual
- postReintentar la entrega ahora, con el mismo cuerpo y el mismo webhook-id
Parámetros de toda solicitud
Accept-LanguagestringIdioma de los textos de error: es, en o ru. Inglés por defecto.
- Ejemplo:
es
Encabezados de toda respuesta exitosa
RateLimitstringobligatorioSolicitudes que pasan seguidas y segundos hasta que el cupo vuelve a estar lleno, por política.
- Ejemplo:
"app";r=87;t=3, "store";r=390;t=1
RateLimit-PolicystringobligatorioPolíticas de límite: cupo por ventana en segundos.
- Ejemplo:
"app";q=300;w=60, "store";q=1200;w=60
X-Request-IdstringobligatorioID de la solicitud. Indicalo cuando escribas a soporte.
Errores
Los errores llegan como application/problem+json (RFC 9457). type es un código estable para decidir qué hacer; title y detail son texto para personas, en el idioma de Accept-Language.
Tipos de error
| Estado | Tipo | Qué pasó |
|---|---|---|
| 401 | api_token_expired | El token de la API venció |
| 401 | api_token_invalid | El token de la API no es válido |
| 401 | api_token_missing | Falta el token de la API |
| 401 | api_token_revoked | El token de la API fue revocado |
| 403 | capability_disabled | Recurso no disponible para esta tienda |
| 403 | forbidden | Prohibido |
| 403 | insufficient_scope | Falta un permiso |
| 403 | integration_api_not_in_plan | La API para integraciones no está en el plan |
| 403 | ip_not_allowed | Dirección no permitida |
| 404 | not_found | No encontrado |
| 405 | method_not_allowed | Método no permitido |
| 409 | address_book_full | La libreta de direcciones del cliente está llena |
| 409 | bulk_operation_finished | La operación ya terminó |
| 409 | bulk_operation_queue_full | La cola de operaciones de la app está llena |
| 409 | bulk_operation_result_unavailable | No hay archivo de resultado |
| 409 | consent_required | Hace falta consentir las consecuencias |
| 409 | customer_contact_in_use | El contacto ya pertenece a un cliente de la tienda |
| 409 | draft_order_closed | El borrador de pedido está cerrado |
| 409 | external_id_archived | El registro con este ID externo está archivado |
| 409 | external_id_in_use | El ID externo está en uso |
| 409 | fiscal_document_annul_refused | No se puede anular la factura |
| 409 | fiscal_document_dismiss_refused | No se puede sacar el comprobante de control |
| 409 | fiscal_document_pdf_unavailable | El comprobante no tiene archivo |
| 409 | fiscal_document_reissue_refused | No se puede reemitir el comprobante |
| 409 | idempotency_key_in_use | Hay una solicitud en curso con esta clave |
| 409 | in_use_conflict | Registro en uso |
| 409 | invoice_issue_refused | No se puede emitir la factura del pedido ahora |
| 409 | money_transaction_locked | El movimiento no se cambia a mano |
| 409 | order_cancel_refused | El pedido no se puede cancelar |
| 409 | order_transition_refused | El pedido no puede pasar a este estado |
| 409 | payment_not_confirmable | El pago no se puede confirmar |
| 409 | plan_limit_reached | Se alcanzó el límite del plan |
| 409 | purchase_order_refused | La orden de compra no acepta este comando |
| 409 | record_limit_reached | Se alcanzó el tope de registros |
| 409 | refund_not_confirmable | La devolución no espera confirmar un reintegro |
| 409 | refund_refused | El pedido no se puede devolver |
| 409 | shipment_in_progress | Ya hay una emisión de envío en curso |
| 409 | shipment_label_unavailable | El envío no tiene etiqueta |
| 409 | shipment_outcome_unknown | El resultado de la emisión anterior es desconocido |
| 409 | shipment_refused | No se puede emitir el envío ahora |
| 409 | shipment_tracking_refused | No se puede cargar el número de seguimiento a mano |
| 409 | stock_held_by_write_offs | El stock está retenido por bajas pendientes de aprobación |
| 409 | stock_on_hand_changed | Cambió el stock físico |
| 409 | supplier_bill_payment_locked | El pago del comprobante no se anula directamente |
| 409 | supplier_bill_refused | El comprobante de proveedor no acepta este comando |
| 409 | tax_withholding_certificate_unavailable | El registro no tiene certificado |
| 409 | unique_conflict | Valor repetido |
| 409 | upload_offset_mismatch | La parte no empieza donde corresponde |
| 409 | webhook_endpoint_limit_reached | La app tiene el máximo de endpoints de webhook |
| 410 | cursor_expired | El cursor de sincronización venció |
| 412 | precondition_failed | El registro cambió |
| 416 | range_not_satisfiable | El rango empieza después del resultado |
| 422 | idempotency_key_required | Falta la clave de idempotencia |
| 422 | idempotency_key_reused | La clave de idempotencia ya se usó |
| 422 | invalid_idempotency_key | La clave de idempotencia no es válida |
| 422 | last_variant_of_product | Última variante del producto |
| 422 | money_out_of_range | Importe fuera de rango |
| 422 | validation_error | Solicitud inválida |
| 428 | precondition_required | Falta If-Match |
| 429 | too_many_requests | Demasiadas solicitudes |
| 500 | server_error | Error del servidor |
| 503 | carrier_unavailable | El transportista no responde |
| 503 | store_frozen | Tienda congelada |
| 503 | transient_conflict | Conflicto temporal |
| según la solicitud | http_error | Error HTTP |
Cuerpos de error
Problem
typestringobligatorioTipo técnico del problema: un código estable para decidir qué hacer, como insufficient_scope. Cada tipo tiene una página en el catálogo de errores.
titlestringobligatorioResumen breve del problema en el idioma de la solicitud.
statusintegerobligatorioEstado HTTP de la respuesta.
detailstringExplicación de este caso en el idioma de la solicitud.
ForbiddenProblem
typestringobligatorioTipo técnico del problema: un código estable para decidir qué hacer, como insufficient_scope. Cada tipo tiene una página en el catálogo de errores.
titlestringobligatorioResumen breve del problema en el idioma de la solicitud.
statusintegerobligatorioEstado HTTP de la respuesta.
detailstringExplicación de este caso en el idioma de la solicitud.
required_scopestringEn insufficient_scope — el scope que necesita el endpoint.
accepted_scopesarray de stringEn insufficient_scope — los scopes que acepta el endpoint: alcanza con cualquiera. En un endpoint con un solo scope, solo ese.
ValidationProblem
typestringobligatorioTipo técnico del problema: un código estable para decidir qué hacer, como insufficient_scope. Cada tipo tiene una página en el catálogo de errores.
titlestringobligatorioResumen breve del problema en el idioma de la solicitud.
statusintegerobligatorioEstado HTTP de la respuesta.
detailstringExplicación de este caso en el idioma de la solicitud.
errorsmapa de array de stringobligatorioCampos con errores: nombre del campo (los anidados con puntos, como variants.0.price) → mensajes.
RateLimitProblem
typestringobligatorioTipo técnico del problema: un código estable para decidir qué hacer, como insufficient_scope. Cada tipo tiene una página en el catálogo de errores.
titlestringobligatorioResumen breve del problema en el idioma de la solicitud.
statusintegerobligatorioEstado HTTP de la respuesta.
detailstringExplicación de este caso en el idioma de la solicitud.
policystringobligatorioQué balde se agotó: app — el de la aplicación; store — el de la tienda, compartido por todas sus aplicaciones; rejected — el de solicitudes de una misma dirección rechazadas en la entrada.
- Valores:
appstorerejected
ConflictProblem
typestringobligatorioTipo técnico del problema: un código estable para decidir qué hacer, como insufficient_scope. Cada tipo tiene una página en el catálogo de errores.
titlestringobligatorioResumen breve del problema en el idioma de la solicitud.
statusintegerobligatorioEstado HTTP de la respuesta.
detailstringExplicación de este caso en el idioma de la solicitud.
currentobjectEl registro tal como está ahora, los campos del conflicto: on_hand en stock_on_hand_changed, status en un cambio de pedido rechazado, status y order_id en un borrador cerrado.
external_idstringEn external_id_in_use y external_id_archived — el ID externo ocupado.
consent_kindstringEn consent_required — el tipo de consecuencia que hay que aceptar.
consequencesmapa de integerEn consent_required — qué cambiará: tipo de datos → cantidad de registros.
- Mínimo:
- 0
consent_tokenstringEn consent_required — huella de las consecuencias mostradas. Repetí la solicitud con consent[<consent_kind>]=<consent_token>.
variant_idintegerEn consent_required de una línea de variante dentro de la escritura de un producto — la variante: el consentimiento se da al cambiar esa variante (PATCH /v1/variants/{variant}).
limitintegerEn plan_limit_reached, address_book_full, bulk_operation_queue_full y webhook_endpoint_limit_reached — el límite.
- Mínimo:
- 0
fieldstringEn customer_contact_in_use — el contacto que pertenece a otro cliente: phone o email.
- Valores:
phoneemail
existing_customer_idintegerEn customer_contact_in_use — el cliente al que pertenece el contacto.
receivedintegerEn upload_offset_mismatch — bytes que ya recibió la carga: el desplazamiento desde el que continuar.
- Mínimo:
- 0
operation_statusstringEn bulk_operation_finished — el estado con el que terminó la operación.