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