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:GUDINK_API_BASE="https://app.gudink.com/api/v1" y una clave gk_live_.
1. Probá la clave
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
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
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):shipping_address: en shipping va también el pickup_point_id de la sucursal elegida. Ver Retiro en sucursal.
external_ididentifica 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, dondek7p2es 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_idy el mismo cuerpo: no se duplica. - En
shipping_address.provincemandá laprovinceque devolvió la cotización. - Después de cada
200o201, mirástatus: un reintento de un pedido que ya se canceló devuelve200constatus: "cancelled". Ver Qué mirar después de cada 200 o 201.
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
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.

