> ## Documentation Index
> Fetch the complete documentation index at: https://ayuda.gudink.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conectar tu web a Gudink con un agente de IA

> Instrucciones listas para pegarle a tu agente de IA (Claude, ChatGPT, Cursor) para que conecte tu web con la API de Gudink de punta a punta, y qué tenés que darle.

Un agente de IA puede hacer toda la conexión entre tu web y Gudink. Esta página tiene lo que le tenés que dar, las instrucciones para pegarle y cómo comprobar que quedó bien.

## Antes de empezar

Necesitás cuatro cosas, todas en el [entorno de pruebas](/api/entorno-de-pruebas), que es una cuenta aparte de la de producción:

1. **Una cuenta en el panel de pruebas** (`https://staging.gudink.com`), con el email verificado y los datos de facturación completos.
2. **La API habilitada en esa cuenta.** Ver [cómo pedir acceso](/api/introduccion#como-pedir-acceso).
3. **Al menos un producto diseñado** en esa cuenta, que es lo que tu web va a vender en las pruebas.
4. **Una clave de pruebas.** La creás en el panel de pruebas, en **Integraciones > API**. Empieza con `gk_stg_` y se muestra una sola vez.

En pruebas no se produce, no se envía y no se cobra nada.

## Cómo darle la clave al agente

La clave es una contraseña de tu cuenta: crea pedidos que se te cobran.

* **No la pegues en el chat.** Guardala como variable de entorno en tu servidor o en el archivo de secretos de tu proyecto, y decile al agente el nombre de la variable (`GUDINK_API_KEY`).
* Lo mismo con el secreto de los avisos (`GUDINK_WEBHOOK_SECRET`).
* La URL base va en otra variable (`GUDINK_API_BASE`), para que pasar a producción sea cambiar variables y no código.
* Si la pegaste en algún lado sin querer, revocala desde el panel y creá otra. Revocar es inmediato.

## Instrucciones para pegarle al agente

Copiá este bloque tal cual. Completá las dos líneas del final.

```text theme={null}
Quiero conectar mi tienda con la API de Gudink para que los pedidos se creen solos.

Antes de escribir código, leé la documentación completa, en este orden:
- Guía canónica: https://staging.gudink.com/api/v1/llms.txt (texto plano, sin clave).
  Si otra página dice algo distinto, vale esta guía.
- Contrato exacto (OpenAPI): https://staging.gudink.com/api/v1/openapi.json (sin clave).
  Ante una diferencia entre un ejemplo y la especificación, vale la especificación.
- Entorno de pruebas: https://ayuda.gudink.com/api/entorno-de-pruebas.md
- Errores, reintentos y límites: https://ayuda.gudink.com/api/errores-y-limites.md
- Si mi tienda es una plataforma (WooCommerce, Shopify, un ERP): lo que todo conector
  resuelve, en la sección "Conectar una plataforma de e-commerce" de la guía y en
  https://ayuda.gudink.com/api/conectar-una-plataforma.md

Entorno: trabajá SOLO contra el entorno de pruebas hasta que yo te diga lo contrario.
- GUDINK_API_BASE=https://staging.gudink.com/api/v1
- GUDINK_API_KEY=clave que empieza con gk_stg_ (ya está en mis variables de entorno)
- Nunca escribas https://app.gudink.com en el código: la URL base sale siempre de
  GUDINK_API_BASE. Producción es cambiar esas dos variables, nada más.
- La cuenta, los productos, la clave y el destino de avisos de pruebas son otros que
  los de producción. No guardes en el código ningún product_id ni variant_id.

Reglas que no se negocian:
1. La clave de Gudink se usa SOLO en el servidor, leída de la variable de entorno
   GUDINK_API_KEY. Nunca en el navegador, nunca en el repositorio, nunca en una URL,
   nunca en la descarga de una imagen.
2. Todo pedido se crea con un external_id único para siempre en mi cuenta de Gudink:
   un prefijo propio de esta instalación (un código que generás una vez y guardás en
   la configuración) más el número de pedido de mi tienda, por ejemplo woo-k7p2-10432.
   Nunca el número de pedido solo. Ante un error de red, un timeout o un 5xx, reintentá con el MISMO external_id y el MISMO
   cuerpo (guardá el cuerpo exacto que mandaste). Nunca generes un external_id nuevo
   para reintentar. Si se acaban los intentos, consultá GET /orders?external_id=...
   antes de volver a mandar. Después de cada 200 o 201 mirá status: si es
   "cancelled", ese pedido no va (para volver a pedirlo, external_id nuevo).
3. Decidí por error.code y por el status HTTP, nunca por el texto del mensaje.
4. Los importes son enteros en pesos argentinos con IVA incluido. No dividas ni
   multipliques por impuestos.
5. Las imágenes de los productos se descargan SIN la cabecera Authorization y se
   alojan en mi sitio. No se enlazan directo.
6. Validá el formato del destinatario y la dirección en mi checkout ANTES de cobrar
   (tabla "Qué va en cada campo").
7. En un pedido a domicilio, mandá en shipping_address.province la province que
   devolvió la cotización. Si la cotización responde province_required, pedile la provincia a mi
   comprador con un selector de las 24 provincias exactas de la documentación.
8. Ignorá los campos que no conozcas, tratá un status desconocido como "en curso" y
   respondé 2xx a un tipo de aviso que no conozcas.
9. Gudink no le escribe a mi comprador: el seguimiento se lo paso yo.
10. Una línea es siempre el par product_id + variant_id: el mismo variant_id aparece
   en varios productos, con precios distintos. Guardá las variantes con esa clave.
11. Un 409 out_of_stock no se reintenta en bucle. En pruebas, cancelá cada pedido
   que no vayas a simular hasta el final: los pedidos sin pagar reservan stock.
12. Cada llamada a la API lleva una cabecera User-Agent propia (por ejemplo
   MiTienda/1.0 (+https://mitienda.com)). Un 403 que no es JSON es un bloqueo de la
   red, no un problema de la clave: los error.code sólo cuentan si la respuesta trae
   el sobre { "error": { ... } }.
13. Las tareas programadas (sincronizar, alarmas) van con el cron del servidor, no con
   uno que dependa de las visitas al sitio.

Lo que tenés que construir:
A. Sincronizar el catálogo: GET /products paginando hasta next_cursor null. Guardar
   cada variante por el par (product_id, variant_id), con price y available, y el
   updated_at del producto. Cada 60 minutos, y además
   GET /products/:id de cada producto del carrito justo antes de cobrar.
B. En el checkout: POST /shipping/quotes con el carrito y el código postal, y mostrar
   las opciones con su price. Cada opción tiene un type: home (a domicilio) o pickup
   (retiro en sucursal). Si mi comprador elige pickup, mostrarle las sucursales de
   pickup_points (nombre, dirección, horario, operador) y que elija una antes de pagar.
   Una opción con un type que no conozcas, no la muestres.
C. Cuando la plata de mi comprador está acreditada (no cuando el pedido se registra):
   POST /orders con el quote_id y el service_code elegidos. En un retiro, también el
   pickup_point_id de la sucursal elegida y SIN shipping_address (sección "Retiro en
   sucursal" de la guía). Si el carrito tiene
   productos que no son de Gudink, cotizá y pedí sólo las líneas de Gudink.
D. Un endpoint HTTPS que reciba los avisos de Gudink, verifique la firma con
   GUDINK_WEBHOOK_SECRET, deduplique por webhook-id, responda 2xx enseguida y
   actualice el pedido en mi sistema. Tiene que aceptar el aviso de prueba
   (type "webhook.test", sin order). Con order.shipped u order.tracking_updated,
   pasarle el seguimiento a mi comprador.
E. Manejo de errores según la tabla de la documentación: hasta 4 intentos, nunca
   antes de Retry-After (si no viene, esperas de 1, 2 y 4 segundos). Adentro del
   checkout, nunca más de 30 segundos por espera: si Retry-After pide más, guardar
   el pedido como pendiente y seguir en segundo plano. En segundo plano, esperar lo
   que pida Retry-After. Un 5xx que no es JSON se trata como un error de red.
F. Una forma de ponerse al día después de una caída: GET /orders?created_after=...
   para los pedidos nuevos y GET /orders?updated_after=... para los que ya tenía.
G. Una alarma para mí, por ejemplo cada hora: GET /orders?status=pending_payment y
   avisarme de los que tienen expires_at en las próximas 24 horas, con su pay_url.
   Si un pedido llega cancelado, mirá cancel_reason y avisame para que decida.

Para verificar, corré el "Recorrido de prueba de punta a punta" de la página del
entorno de pruebas: creá un pedido de prueba y hacelo avanzar con
POST /sandbox/orders/{id}/simulate (pay, start_production, ship, deliver), comprobando
que mi sistema recibe cada aviso y guarda el número de seguimiento. NO pagues el pedido
desde pay_url. Mostrame el resultado de cada uno de los diez pasos.

Si algo de la documentación no alcanza para decidir, no adivines: decime qué falta.

Mi web está hecha con: [completar: WooCommerce, Next.js, Shopify, etc.]
Dónde querés que quede el endpoint de avisos: [completar: por ejemplo /api/gudink/webhook]
```

## Qué tenés que hacer vos, no el agente

Hay pasos que se hacen desde tu panel de Gudink y que el agente no puede hacer por vos:

1. **Crear la cuenta de pruebas, diseñar los productos y crear la clave** en Integraciones > API.
2. **Dar de alta el destino de avisos** en Integraciones > API > Avisos, con la URL del endpoint que armó el agente. Ahí te muestran el secreto de firma, una sola vez. Si el agente trabaja en tu máquina, la URL tiene que ser la de un túnel `https` con nombre de host público: Gudink no puede mandar avisos a `localhost`.
3. **Apretar "Mandar prueba"** para comprobar el endpoint.
4. **Pasar a producción**, cuando todo ande en pruebas: repetir en `https://app.gudink.com` la habilitación, los productos, la clave (`gk_live_`) y el destino de avisos, y cambiar `GUDINK_API_BASE`, `GUDINK_API_KEY` y `GUDINK_WEBHOOK_SECRET`.
5. **Pagar los pedidos**, ya en producción. Cada pedido que entra por la API lo pagás desde tu panel. Tenés 72 horas: si no, se cancela aunque tu comprador ya te haya pagado. Es una tarea de todos los días; ver [Pagar es una tarea de todos los días](/api/pedidos#pagar-es-una-tarea-de-todos-los-dias).

## Cómo saber que quedó bien

Pedile al agente que te muestre cada uno de estos puntos funcionando, en el entorno de pruebas:

1. `GET /me` responde con tu cuenta y `billing_complete` es `true`.
2. El catálogo de tu web muestra tus productos de Gudink, con las imágenes alojadas en tu sitio.
3. El checkout muestra las opciones de envío con su precio para un código postal real. Si ofrecés retiro en sucursal, también la lista de sucursales, y un pedido de prueba con retiro llega a tu panel con la sucursal elegida (ver [Retiro en sucursal](/api/pedidos#retiro-en-sucursal)).
4. Un pedido de prueba aparece en tu panel de pruebas como "pendiente de pago", con el nombre y la dirección de tu comprador.
5. Repetir el mismo pedido (mismo `external_id`, mismo cuerpo) no crea otro.
6. "Mandar prueba" en el panel llega a tu endpoint y la firma verifica.
7. Al simular `pay`, `start_production`, `ship` y `deliver`, tu sistema se entera solo de cada cambio de estado y guarda el número de seguimiento `TEST-…`.
8. Cancelar un pedido de prueba sin pagar llega a tu sistema como `order.cancelled` con `cancel_reason: "cancelled_by_seller"`, y repetir ese mismo pedido devuelve el pedido cancelado, que tu sistema no confirma.

El detalle de cada paso está en el [recorrido de prueba de punta a punta](/api/entorno-de-pruebas#recorrido-de-prueba-de-punta-a-punta).

Si alguno falla, pasale al agente el `error.code` que recibió y la página [Errores y límites](/api/errores-y-limites).

## Para el agente: cómo leer esta documentación

Hay una sola guía canónica y un solo contrato. Los dos los sirve la propia API, sin clave:

| Qué | Dónde | Cuándo vale |
| - | - | - |
| Guía canónica, en texto plano | `GET /api/v1/llms.txt` (en pruebas: `https://staging.gudink.com/api/v1/llms.txt`) | Si una página de este centro de ayuda dice algo distinto, vale la guía |
| Contrato exacto (OpenAPI): campos, tipos, límites de cada campo, forma de cada error | `GET /api/v1/openapi.json` (en pruebas: `https://staging.gudink.com/api/v1/openapi.json`) | Ante una diferencia entre un ejemplo y la especificación, vale la especificación |

* La ruta de simulación (`POST /sandbox/orders/{id}/simulate`) figura sólo en la especificación del entorno de pruebas.
* Estas páginas explican lo mismo, ordenado por tema. Cada una tiene su versión en texto plano agregando `.md` a la URL (por ejemplo `https://ayuda.gudink.com/api/pedidos.md`).
* Orden de lectura sugerido: [Inicio rápido](/api/inicio-rapido), [Entorno de pruebas](/api/entorno-de-pruebas), [Claves y autenticación](/api/claves-y-autenticacion), [Productos y envío](/api/productos-y-envio), [Pedidos](/api/pedidos), [Avisos](/api/avisos), [Errores y límites](/api/errores-y-limites).
* Si estás conectando una plataforma de e-commerce, leé también [Conectar una plataforma de e-commerce](/api/conectar-una-plataforma): las decisiones que todo conector termina resolviendo, con enlace a cada sección.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.