API: listar productos y cotizar el envío

export GUDINK_API_BASE="https://staging.gudink.com/api/v1"
export GUDINK_API_KEY="gk_stg_..."   # nunca la escribas en el código

​

Listar tus productos

curl -sS "$GUDINK_API_BASE/products?limit=25" \
  -H "Authorization: Bearer $GUDINK_API_KEY"

{
  "data": [
    {
      "id": 812,
      "name": "Remera Logo Sur",
      "product_type": "tshirt",
      "thumbnail_url": "https://staging.gudink.com/...",
      "mockups": [
        { "url": "https://staging.gudink.com/...", "color": "Negro", "view": "front" }
      ],
      "orderable": true,
      "variants": [
        { "id": 4410, "size": "M", "color": "Negro", "available": true, "price": 15990 },
        { "id": 4411, "size": "L", "color": "Negro", "available": false, "price": 15990 }
      ],
      "updated_at": "2026-10-01T18:30:00.000Z"
    }
  ],
  "next_cursor": "eyJ1Ijo0MTIsImkiOjgxMn0"
}

​

Qué es cada campo

​

Una línea es un par

• Guardá tus variantes con la clave (product_id, variant_id), nunca sólo por variant_id.
• Mandá siempre el par, al cotizar y al crear el pedido.
• Una variante con el product_id de otro producto responde 409 variant_not_orderable.

​

Paginado

• limit va de 1 a 25. Por defecto 20.
• Si next_cursor no es null, pedí la página siguiente con cursor=<next_cursor>. Cuando es null, terminaste.
• El cursor es opaco y sólo sirve para tu cuenta. No lo armes ni lo interpretes.

​

Un producto solo

curl -sS "$GUDINK_API_BASE/products/812" \
  -H "Authorization: Bearer $GUDINK_API_KEY"

​

Imágenes

​

Cada cuánto sincronizar

• No vendas una variante con available: false. available puede cambiar en cualquier momento.
• Igual el alta del pedido puede responder 409 out_of_stock: available: true dice que hay al menos una unidad, no cuántas, y los pedidos sin pagar reservan unidades. Prepará tu checkout para eso. Ver Stock y reservas.
• Un producto que desaparece de GET /products (o que responde 404 en GET /products/:id) se archivó o dejó de ser tuyo: dejá de venderlo. Si igual llega a un pedido, el alta responde 409 product_archived.
• No hay aviso (webhook) de cambios de producto: un evento product.updated todavía no existe. Los avisos son sólo de pedidos.
• Programá la sincronización con un reloj de verdad (el cron del servidor). Si tu plataforma corre sus tareas programadas sólo cuando alguien visita el sitio (WP-Cron de WordPress, por ejemplo), en una tienda con poco tráfico pueden pasar horas sin sincronizar.

​

Cuando cambia un precio

• El pedido toma el precio del momento en que lo creás. items[].unit_price del pedido es lo que se te cobra, aunque el producto cambie de precio después.
• Gudink te avisa por mail los cambios de precio antes de que entren en vigor, con la fecha.
• Desde ese día, tu próxima sincronización ya trae el precio nuevo en variants[].price.

​

Cotizar el envío

curl -sS "$GUDINK_API_BASE/shipping/quotes" \
  -H "Authorization: Bearer $GUDINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postal_code": "C1043AAZ",
    "items": [{ "product_id": 812, "variant_id": 4410, "quantity": 2 }]
  }'

{
  "quote_id": "sq_9f3kQ2v7c1ZxLwP0aB8mT4yR6eHn5uJd",
  "postal_code": "1043",
  "province": "Capital Federal",
  "expires_at": "2026-10-03T15:04:05.000Z",
  "options": [
    {
      "service_code": "opt_1",
      "label": "Envío a domicilio",
      "price": 6890,
      "min_business_days": 3,
      "max_business_days": 5
    },
    {
      "service_code": "opt_2",
      "label": "Envío express a domicilio",
      "price": 9450,
      "min_business_days": 1,
      "max_business_days": 2
    }
  ]
}

​

Qué mandar

​

Qué devuelve

​

Reglas de la cotización

• service_code identifica una opción dentro de esa cotización y sólo vale junto con su quote_id. Copialo tal cual en el pedido.
• No se garantiza que sea el mismo en dos cotizaciones del mismo carrito: el opt_1 de una cotización nueva puede ser otro envío. Si recotizás, elegí de nuevo entre las opciones nuevas, por label y price.
• Las líneas tienen que ser exactamente las del pedido: mismo producto, misma variante, misma cantidad. El orden no importa. Si cambia el carrito, cotizá de nuevo.
• Una cotización vigente sirve para más de un pedido con las mismas líneas y el mismo código postal.
• Cotizar no mira el stock. El stock se reserva recién al crear el pedido.
• Mandá cada par product_id + variant_id una sola vez, con la cantidad sumada. Si repetís el par en dos líneas, la cotización y el pedido lo aceptan y quedan como dos líneas separadas (cada una con su tope de unidades), pero no lo necesitás para nada: evitalo.
• Carritos mixtos. Si el carrito tiene productos que no son de Gudink, cotizá sólo las líneas de Gudink: lo de Gudink sale en su propio paquete, desde Gudink, y el envío del resto lo calculás vos como siempre. Mostrale a tu comprador la suma, o los dos envíos por separado.
• Sólo hay envío a domicilio.
• Límite: 30 cotizaciones por minuto por cuenta.

​

Errores de la cotización

{
  "error": {
    "code": "province_required",
    "message": "(texto para una persona)",
    "details": {
      "fields": { "province": "El código postal no está en nuestra tabla: mandá también la provincia." }
    }
  }
}

curl -sS "$GUDINK_API_BASE/shipping/quotes" \
  -H "Authorization: Bearer $GUDINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postal_code": "9999",
    "province": "Santa Cruz",
    "items": [{ "product_id": 812, "variant_id": 4410, "quantity": 2 }]
  }'

​

Provincias

1. Si la API reconoce el código postal, la provincia sale del código postal y no hace falta mandarla al cotizar. En el pedido, la que mandes se ignora, no se rechaza: el pedido sale con la del código postal.
2. Si no lo reconoce, responde 400 province_required: pedísela a tu comprador con un selector de estos 24 valores.
3. En el pedido, mandá en shipping_address.province la province que devolvió la cotización. Así nunca difiere. Qué compara la API entre la cotización y el pedido: ver Qué compara la cotización con el pedido.