Tienda

Tus propios sistemas pueden trabajar con los pedidos, los productos, las existencias y los descuentos de tu Tienda a través de la API de Magpie.

La API de la Tienda permite que un programa que gestionas, como un sistema de almacén o de contabilidad, trabaje con tu Tienda. Puede leer pedidos, añadir envíos y reembolsos, y cambiar precios y existencias. Los webhooks envían un POST firmado a tu dirección cuando cambian pedidos, productos o existencias, o un cliente pide una devolución.

Crear cuenta
Greenpoint Studio’s Store webhook to its warehouse system: the HTTPS address, on, the signing secret’s last characters, and the events it receives, such as store.order.paid.

Claves de API y permisos de la Tienda

Cada solicitud lleva una clave de API. Las claves de API requieren Pro en la cuenta de quien las crea, y el secreto de una clave se muestra una sola vez. La cabecera X-Magpie-Team-Id elige el equipo.

Una clave puede hacer en la Tienda lo que puede hacer quien la creó. Un miembro que no es administrador necesita el permiso de Tienda de cada tipo de solicitud.

See orders
Listar y leer pedidos y devoluciones.
Ship and edit orders
Añadir envíos, notas y etiquetas.
Refund and cancel orders
Reembolsar pedidos.
Manage products y Manage stock
Leer Productos y cambiar precios y SKU; fijar existencias y registrar cambios de existencias.
Manage customers y Manage discounts
Leer clientes; listar, crear, cambiar y desactivar descuentos.
Webhooks
Solo los administradores del equipo pueden añadir y cambiar webhooks.

Pedidos

Listar y leer
Los pedidos se listan del más reciente al más antiguo, filtrados por texto de búsqueda, pago, envío, canal de venta, etiqueta y fechas. Un pedido llega con sus artículos, cuántos de cada uno se han enviado, los envíos, los reembolsos, las devoluciones, las direcciones y el historial.
Añadir un envío
Un envío lleva el transportista, el número y el enlace de seguimiento, y los artículos que contiene. Sin artículos, se envía todo lo que queda. Magpie enviará un correo al cliente, igual que desde la página del pedido.
Reembolsar
Un reembolso es un importe, o todo lo que aún se puede reembolsar, con los artículos que vuelven a las existencias. Un pedido pagado con Stripe se reembolsará en tu cuenta de Stripe.
Una sola vez
Con una cabecera Idempotency-Key en un reembolso o un envío, una solicitud repetida devuelve la primera respuesta y no se ejecuta dos veces.

Productos, existencias, devoluciones y clientes

Productos y precios
Tu programa puede leer cada producto con el precio, el SKU y las existencias de cada variante. Puede cambiar el precio, el precio de comparación o el SKU de una variante.
Cambios de existencias
Tu programa puede fijar las unidades en almacén de una variante, registradas como una corrección por recuento. Puede añadir o quitar existencias con un motivo, como recibidas o dañadas. Un cambio puede indicar una ubicación de stock y un coste por artículo.
Existencias bajas
La lista de inventario da las unidades en almacén, reservadas en pagos y disponibles de cada variante que sigue existencias. Puede listar solo las que están en su punto de pedido o por debajo.
Devoluciones y clientes
Tu programa puede leer las solicitudes de devolución, y los clientes con su número de pedidos, su gasto, sus etiquetas y su consentimiento de marketing.

Descuentos

Crea y cambia descuentos con los mismos ajustes que la página de un descuento en la Tienda.

Un código o automático
Un descuento es un código que escriben los compradores, o un descuento automático con un título.
Tipos y límites
Un descuento es un porcentaje, un importe fijo, envío gratis o compra X y llévate Y. Se aplica a todo o a productos o colecciones elegidos. Puede tener un mínimo, límites de uso, un segmento de clientes y fechas.
Borrador hasta activarlo
Un descuento nuevo es un borrador hasta que se envía con el estado activo. Si se rechaza un valor de un cambio, la respuesta lo nombra y no se cambia nada.
Desactivar
Desactivar archiva un descuento: deja de aplicarse en el pago y conserva su historial.

Eventos de webhook

Un webhook envía un POST a una dirección HTTPS cuando pasa algo en la Tienda. Añades webhooks en los ajustes de la Tienda, sin necesidad de clave de API, o con la API. Una Tienda puede tener hasta 20, cada uno con los eventos que elijas.

store.order.paid
Se paga un pedido, en línea o registrado a mano.
store.order.fulfilled
Se añade un envío, una vez por envío.
store.order.ready_for_pickup
Un pedido de recogida se marca como listo para recoger.
store.order.refunded y store.order.canceled
Un reembolso se completa, o se cancela un pedido sin pagar.
store.product.updated
Cambia un Producto o sus precios.
store.stock.low
Las existencias de una variante llegan a su punto de pedido.
store.return.requested
Un cliente pide devolver artículos.

Firmas, reintentos y el registro de entregas

Cada POST lleva las cabeceras X-Magpie-Event, X-Magpie-Id, X-Magpie-Timestamp y X-Magpie-Signature. La firma es un HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo sin procesar, hecho con el secreto de firma del webhook. El secreto se muestra una sola vez y se puede sustituir por uno nuevo. X-Magpie-Id no cambia cuando una entrega se reenvía, así que tu programa puede ignorar una repetición.

Tu programa responde con cualquier código 2xx. Cualquier otra respuesta, o ninguna, se reintentará durante unos dos días, hasta 8 intentos. La página del webhook lista las entregas recientes con sus resultados, y Enviar de nuevo reenvía una que falló.

Importes, páginas y la referencia de la API

Los precios y los totales son números enteros en la unidad más pequeña de la moneda de la Tienda: 1999 es 19,99 en dólares. Las listas devuelven hasta 100 registros por página. Los pedidos y los clientes incluyen nombres, direcciones de correo, teléfonos y direcciones, así que lo que guarde tu programa son datos de clientes.

La referencia de la API, en /docs/api, enlaza al archivo OpenAPI, que lista todos los campos.

Conecta tu Tienda a tus propios sistemas.

Crea una cuenta de Magpie y ponle nombre a tu Tienda.

Crear cuenta