Skip to main content
Esta página te lleva de la clave al primer pedido en cinco llamadas. Los detalles de cada una están en las páginas siguientes.

Lo básico

La API se usa de servidor a servidor. No funciona desde un navegador, a propósito: la clave nunca tiene que llegar al dispositivo de tu comprador. Mandá siempre una cabecera User-Agent propia, por ejemplo MiTienda/1.0 (+https://mitienda.com). La red que está delante de la API puede rechazar el que algunas librerías mandan por defecto (pasa con urllib de Python) con un 403 que no es JSON (un texto como error code: 1010), incluso en GET /llms.txt. Ese 403 no tiene que ver con tu clave: ver Respuestas que no son de la API. curl ya manda uno propio, así que los ejemplos de esta página andan tal cual.

Antes de la primera llamada

Los ejemplos usan dos variables de entorno, para que ningún comando le pegue a producción por accidente. Definilas una vez:
Así apuntan al entorno de pruebas, donde nada se produce, se envía ni se cobra. En producción no hay modo de prueba. Para pasar a producción cambian las dos variables, nada más: GUDINK_API_BASE="https://app.gudink.com/api/v1" y una clave gk_live_.

1. Probá la clave

Si billing_complete es false, completá tus datos de facturación en el panel antes de seguir: sin ellos POST /orders responde 403 billing_data_required.

2. Listá tus productos

De la respuesta guardá, por cada variante, el id del producto (product_id) y el id de la variante (variant_id), siempre como par: el mismo variant_id aparece en varios productos, con precios distintos. Ese par es lo que vas a mandar al cotizar y al crear el pedido.

3. Cotizá el envío

Te devuelve un quote_id, la province de ese código postal y una lista de options, cada una con su service_code (opt_1, opt_2, …), su type y su price. type es home (envío a domicilio) o pickup (retiro en sucursal, con la lista de sucursales en pickup_points). Mostrale las opciones a tu comprador. Guardá el quote_id, el service_code elegido y la province. Los dos primeros van juntos dentro de shipping al crear el pedido. Si responde 400 province_required, la API no reconoce ese código postal: pedile la provincia a tu comprador y repetí la llamada sumando "province". Ver Provincias.

4. Creá el pedido

Cuando la plata de tu comprador está acreditada (no cuando el pedido se registra):
Este ejemplo es un envío a domicilio. Si tu comprador elige retirar en una sucursal, el pedido no lleva shipping_address: en shipping va también el pickup_point_id de la sucursal elegida. Ver Retiro en sucursal.
  • external_id identifica el pedido en toda tu cuenta de Gudink, para siempre. No uses sólo el número de pedido de tu tienda, que se repite si reinstalás, si tenés una copia de pruebas de tu sitio o si conectás más de una tienda: armalo con un prefijo propio de tu instalación más tu número de pedido (woo-k7p2-10432, donde k7p2 es un código que generás una sola vez al instalar). Ver No duplicar pedidos.
  • Si la conexión se corta y no sabés si se creó, repetí la misma llamada con el mismo external_id y el mismo cuerpo: no se duplica.
  • En shipping_address.province mandá la province que devolvió la cotización.
  • Después de cada 200 o 201, mirá status: un reintento de un pedido que ya se canceló devuelve 200 con status: "cancelled". Ver Qué mirar después de cada 200 o 201.
La respuesta 201 trae el pedido con status: "pending_payment", los importes y payment.pay_url, que es donde lo pagás vos desde tu panel. En el entorno de pruebas no lo pagues: usá la simulación.

5. Consultá el pedido

O, mejor, dejá de consultar y recibí un aviso cada vez que cambia: ver Avisos (webhooks).

Qué sigue

  • Entorno de pruebas: cómo hacer avanzar el pedido hasta entregado sin plata y el recorrido de prueba completo.
  • Claves y autenticación: cómo cuidar la clave y qué responde la API cuando algo falla al entrar.
  • Productos y envío: el catálogo en detalle, las imágenes, cada cuánto sincronizar y las reglas de la cotización.
  • Pedidos: idempotencia, formato de cada campo, pago, vencimiento, estados y cancelación.
  • Errores y límites: la tabla completa de códigos, qué trae cada error y cómo reintentar.