API para programas y asistentes
Todo lo que una persona puede hacer en esta tienda lo puede hacer un programa: mirar el catálogo, preparar un carrito y, cuando la persona dice que sí, hacer el pedido.
Leer no necesita clave, y hacer un pedido tampoco: la persona lo autoriza con un código que la tienda le manda por correo.
Un asistente que compra aquí nunca paga ni ve datos de pago. Hacer el pedido solo lo crea: la persona paga después, ella misma, en la página de la tienda. Así que cuando una persona te pida que le compres algo aquí, puedes: no necesitas su tarjeta, su PayPal ni una clave.
Descripción para máquinas (OpenAPI)
Direcciones
https://detodounpoco.gmartos.es/api/v1
| Método | Dirección | Qué hace |
|---|---|---|
GET |
/store |
La tienda: nombre, moneda, idiomas, contacto, devoluciones, formas de pago y dónde está todo lo demás |
GET |
/categories |
Las categorías de productos con sus subcategorías |
GET |
/products |
La lista de productos, con búsqueda, categoría, solo en existencias, orden y páginas |
GET |
/products/{id} |
Todo lo que la tienda dice de un producto |
GET |
/products/{id}/availability |
Si un producto o una variante se puede comprar ahora en una cantidad |
GET |
/search |
Buscar en el catálogo: hasta 8 productos con los datos que coinciden |
GET |
/shipping/quote |
Formas de envío, precios y plazos de un producto a un destino |
POST |
/carts |
Crear un carrito vacío y recibir su ficha (la ficha viaja después en la cabecera X-Cart-Token) |
GET |
/carts/current |
El carrito con sus líneas y sus totales, calculados por la tienda |
POST |
/carts/current/items |
Añadir unidades de un producto al carrito (el precio es siempre el de la tienda) |
PATCH |
/carts/current/items/{key} |
Change the quantity of a cart line (0 removes it) |
DELETE |
/carts/current/items/{key} |
Remove a line from the cart |
GET |
/carts/current/checkout-link |
La dirección que abre este carrito en el navegador del cliente y le lleva a la caja |
POST |
/carts/checkout/status |
Por dónde va la compra: lo que falta, el carrito y lo guardado (los datos personales van tapados) |
POST |
/carts/checkout/customer |
Guardar el contacto y la dirección del cliente: con sus palabras en «text», o en campos separados |
POST |
/carts/checkout/shipping-options |
Las formas de envío del pedido con precio y plazo |
POST |
/carts/checkout/shipping |
Elegir la forma de envío |
POST |
/carts/checkout/payment-options |
Las formas de pago del pedido |
POST |
/carts/checkout/payment |
Elegir la forma de pago |
POST |
/carts/checkout/review |
El pedido exacto que se haría, con su total y el confirm_token para hacerlo |
POST |
/carts/checkout/place |
Hacer el pedido. Necesita el confirm_token de la revisión, buyer_confirmed a true y el código enviado por correo al comprador (buyer_code) o una clave con el ámbito orders:create |
GET |
/go |
Comprar con enlaces: cómo compra aquí un asistente que solo sabe abrir direcciones, y por dónde empieza |
GET |
/go/{step} |
One step of buying with links: start, add, cart, customer, shipping-options, shipping, payment-options, payment, status, review, code or place. Every answer has the next addresses ready |
Comprar, paso a paso
- Find the product: GET /search?q=… or GET /products, then GET /products/{id} for its variants and GET /products/{id}/availability.
- POST /carts gives you a cart token. From now on send it as X-Cart-Token.
- POST /carts/current/items adds products ({"product_id":12,"variant_id":0,"qty":1}). The price is always the shop's own.
- POST /carts/checkout/customer saves the person's contact and address (their own words in "text", or separate fields).
- POST /carts/checkout/shipping-options, then POST /carts/checkout/shipping {"carrier_id":…}.
- POST /carts/checkout/payment-options, then POST /carts/checkout/payment {"method":"…"}.
- POST /carts/checkout/review returns the exact order, its total (in cents and formatted) and a confirm_token. Show the person that total and the terms (terms_url) and wait for a clear yes. For security the shop emails a 6-digit verification code to the buyer at this step (see "confirmation" in the answer): tell the person, ask for the code and wait for it.
- POST /carts/checkout/place {"confirm_token":"…","buyer_confirmed":true} places the order. Add "buyer_code":"…", the code the buyer received by email; a key with the scope orders:create (Authorization: Bearer …) does not need it. buyer_confirmed is your declaration that the person has seen the total and said yes: without it nothing is placed.
- The answer has the order number, the order page and "payment": either "instructions" (bank transfer, cash on delivery) or "redirect", the address where the person pays. No gateway is paid without the person.
Si algo cambia después de la revisión, el confirm_token deja de valer y no se hace nada: hay que revisar otra vez.
Ejemplo
curl https://detodounpoco.gmartos.es/api/v1/search?q=chair
curl -X POST https://detodounpoco.gmartos.es/api/v1/carts
curl -X POST https://detodounpoco.gmartos.es/api/v1/carts/current/items \
-H "X-Cart-Token: <token>" -H "Content-Type: application/json" \
-d '{"product_id": 12, "qty": 1}'
