Desarrolladores

Referencia de la API

REST sobre HTTPS con JSON. Cada solicitud lleva un token de aplicación, y el token determina la tienda.

Cargando el índice de búsqueda…

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.

ScopeEn el panel de la tiendaQué habilitaEndpoints
catalog:readCatálogo — LecturaLeer 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:writeCatálogo — EscrituraCrear, 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:readStock — LecturaLeer 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:writeStock — EscrituraFijar el stock físico después de un conteo, ingresar mercadería y darla de baja. Incluye inventory:read
orders:readPedidos — LecturaLeer 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:writePedidos — EscrituraCrear 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:wholesalePedidos — Listas de precios mayoristasCondiciones 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:readClientes — LecturaLeer 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:writeClientes — EscrituraCrear y cambiar clientes, su libreta de direcciones y sus datos fiscales; gestionar los grupos de clientes y sus miembros. Incluye customers:read
locations:readSucursales — LecturaLeer los locales de la tienda a los que la aplicación tiene acceso.
payments:readPagos — LecturaLeer los pagos de los pedidos.
payments:writePagos — EscrituraConfirmar un pago manual como cobrado y confirmar un borrador como pagado. Incluye payments:read
refunds:readReembolsos — LecturaLeer los reembolsos de los pedidos.
refunds:writeReembolsos — EscrituraCalcular y crear reembolsos, confirmar devoluciones manuales de dinero y cancelar pedidos con dinero cobrado. Incluye refunds:read
costs:readCostos — LecturaAgregar 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:readContabilidad — LecturaLeer 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:writeContabilidad — EscrituraEmitir 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:annulContabilidad — Anulación de facturasAnular 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:readDinero — LecturaLeer 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:writeDinero — EscrituraRegistrar 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:readCompras — LecturaLectura 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:writeCompras — EscrituraCrear 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:approveCompras — Aprobación de pagos de comprobantesAprobar 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:payCompras — Pago de comprobantes de proveedoresPago 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:readWebhooks y eventos — LecturaLeer el feed de eventos, los endpoints de webhooks y sus entregas.
webhooks:writeWebhooks y eventos — EscrituraCrear, cambiar y eliminar endpoints de webhooks, obtener y rotar sus secretos, enviar eventos de prueba y reintentar entregas. Incluye webhooks:read
bulk:readOperaciones masivas — LecturaLeer las operaciones masivas, descargar sus resultados y consultar las cargas.
bulk:writeOperaciones masivas — EscrituraSubir 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ímiteValor
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

Catálogo

Stock

Pedidos y pagos

Clientes

Contabilidad

Compras

Parámetros de toda solicitud

  • Accept-Languagestring

    Idioma de los textos de error: es, en o ru. Inglés por defecto.

    Ejemplo:
    es

Encabezados de toda respuesta exitosa

  • RateLimitstringobligatorio

    Solicitudes 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-Policystringobligatorio

    Políticas de límite: cupo por ventana en segundos.

    Ejemplo:
    "app";q=300;w=60, "store";q=1200;w=60
  • X-Request-Idstringobligatorio

    ID 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

EstadoTipoQué pasó
401api_token_expiredEl token de la API venció
401api_token_invalidEl token de la API no es válido
401api_token_missingFalta el token de la API
401api_token_revokedEl token de la API fue revocado
403capability_disabledRecurso no disponible para esta tienda
403forbiddenProhibido
403insufficient_scopeFalta un permiso
403integration_api_not_in_planLa API para integraciones no está en el plan
403ip_not_allowedDirección no permitida
404not_foundNo encontrado
405method_not_allowedMétodo no permitido
409address_book_fullLa libreta de direcciones del cliente está llena
409bulk_operation_finishedLa operación ya terminó
409bulk_operation_queue_fullLa cola de operaciones de la app está llena
409bulk_operation_result_unavailableNo hay archivo de resultado
409consent_requiredHace falta consentir las consecuencias
409customer_contact_in_useEl contacto ya pertenece a un cliente de la tienda
409draft_order_closedEl borrador de pedido está cerrado
409external_id_archivedEl registro con este ID externo está archivado
409external_id_in_useEl ID externo está en uso
409fiscal_document_annul_refusedNo se puede anular la factura
409fiscal_document_dismiss_refusedNo se puede sacar el comprobante de control
409fiscal_document_pdf_unavailableEl comprobante no tiene archivo
409fiscal_document_reissue_refusedNo se puede reemitir el comprobante
409idempotency_key_in_useHay una solicitud en curso con esta clave
409in_use_conflictRegistro en uso
409invoice_issue_refusedNo se puede emitir la factura del pedido ahora
409money_transaction_lockedEl movimiento no se cambia a mano
409order_cancel_refusedEl pedido no se puede cancelar
409order_transition_refusedEl pedido no puede pasar a este estado
409payment_not_confirmableEl pago no se puede confirmar
409plan_limit_reachedSe alcanzó el límite del plan
409purchase_order_refusedLa orden de compra no acepta este comando
409record_limit_reachedSe alcanzó el tope de registros
409refund_not_confirmableLa devolución no espera confirmar un reintegro
409refund_refusedEl pedido no se puede devolver
409shipment_in_progressYa hay una emisión de envío en curso
409shipment_label_unavailableEl envío no tiene etiqueta
409shipment_outcome_unknownEl resultado de la emisión anterior es desconocido
409shipment_refusedNo se puede emitir el envío ahora
409shipment_tracking_refusedNo se puede cargar el número de seguimiento a mano
409stock_held_by_write_offsEl stock está retenido por bajas pendientes de aprobación
409stock_on_hand_changedCambió el stock físico
409supplier_bill_payment_lockedEl pago del comprobante no se anula directamente
409supplier_bill_refusedEl comprobante de proveedor no acepta este comando
409tax_withholding_certificate_unavailableEl registro no tiene certificado
409unique_conflictValor repetido
409upload_offset_mismatchLa parte no empieza donde corresponde
409webhook_endpoint_limit_reachedLa app tiene el máximo de endpoints de webhook
410cursor_expiredEl cursor de sincronización venció
412precondition_failedEl registro cambió
416range_not_satisfiableEl rango empieza después del resultado
422idempotency_key_requiredFalta la clave de idempotencia
422idempotency_key_reusedLa clave de idempotencia ya se usó
422invalid_idempotency_keyLa clave de idempotencia no es válida
422last_variant_of_productÚltima variante del producto
422money_out_of_rangeImporte fuera de rango
422validation_errorSolicitud inválida
428precondition_requiredFalta If-Match
429too_many_requestsDemasiadas solicitudes
500server_errorError del servidor
503carrier_unavailableEl transportista no responde
503store_frozenTienda congelada
503transient_conflictConflicto temporal
según la solicitudhttp_errorError HTTP

Cuerpos de error

Problem

  • typestringobligatorio

    Tipo 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.

  • titlestringobligatorio

    Resumen breve del problema en el idioma de la solicitud.

  • statusintegerobligatorio

    Estado HTTP de la respuesta.

  • detailstring

    Explicación de este caso en el idioma de la solicitud.

ForbiddenProblem

  • typestringobligatorio

    Tipo 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.

  • titlestringobligatorio

    Resumen breve del problema en el idioma de la solicitud.

  • statusintegerobligatorio

    Estado HTTP de la respuesta.

  • detailstring

    Explicación de este caso en el idioma de la solicitud.

  • required_scopestring

    En insufficient_scope — el scope que necesita el endpoint.

  • accepted_scopesarray de string

    En insufficient_scope — los scopes que acepta el endpoint: alcanza con cualquiera. En un endpoint con un solo scope, solo ese.

ValidationProblem

  • typestringobligatorio

    Tipo 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.

  • titlestringobligatorio

    Resumen breve del problema en el idioma de la solicitud.

  • statusintegerobligatorio

    Estado HTTP de la respuesta.

  • detailstring

    Explicación de este caso en el idioma de la solicitud.

  • errorsmapa de array de stringobligatorio

    Campos con errores: nombre del campo (los anidados con puntos, como variants.0.price) → mensajes.

RateLimitProblem

  • typestringobligatorio

    Tipo 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.

  • titlestringobligatorio

    Resumen breve del problema en el idioma de la solicitud.

  • statusintegerobligatorio

    Estado HTTP de la respuesta.

  • detailstring

    Explicación de este caso en el idioma de la solicitud.

  • policystringobligatorio

    Qué 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

  • typestringobligatorio

    Tipo 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.

  • titlestringobligatorio

    Resumen breve del problema en el idioma de la solicitud.

  • statusintegerobligatorio

    Estado HTTP de la respuesta.

  • detailstring

    Explicación de este caso en el idioma de la solicitud.

  • currentobject

    El 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_idstring

    En external_id_in_use y external_id_archived — el ID externo ocupado.

  • consent_kindstring

    En consent_required — el tipo de consecuencia que hay que aceptar.

  • consequencesmapa de integer

    En consent_required — qué cambiará: tipo de datos → cantidad de registros.

    Mínimo:
    0
  • consent_tokenstring

    En consent_required — huella de las consecuencias mostradas. Repetí la solicitud con consent[<consent_kind>]=<consent_token>.

  • variant_idinteger

    En 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}).

  • limitinteger

    En plan_limit_reached, address_book_full, bulk_operation_queue_full y webhook_endpoint_limit_reached — el límite.

    Mínimo:
    0
  • fieldstring

    En customer_contact_in_use — el contacto que pertenece a otro cliente: phone o email.

    Valores:
    phoneemail
  • existing_customer_idinteger

    En customer_contact_in_use — el cliente al que pertenece el contacto.

  • receivedinteger

    En upload_offset_mismatch — bytes que ya recibió la carga: el desplazamiento desde el que continuar.

    Mínimo:
    0
  • operation_statusstring

    En bulk_operation_finished — el estado con el que terminó la operación.