API: entorno de pruebas

El entorno de pruebas es un Gudink aparte para integrar sin riesgo. Toda la API funciona igual que en producción, y además tiene una ruta para hacer avanzar un pedido de prueba sin plata. Integrá y probá siempre acá primero. En producción no hay modo de prueba: un pedido creado en producción es real y se te cobra.

Las dos direcciones

	Pruebas	Producción
API	`https://staging.gudink.com/api/v1`	`https://app.gudink.com/api/v1`
Panel	`https://staging.gudink.com`	`https://app.gudink.com`
Prefijo de la clave	`gk_stg_`	`gk_live_`

Una clave de pruebas no sirve en producción, ni al revés: responde 401 invalid_api_key. Todos los ejemplos de esta documentación usan dos variables de entorno, para que ningún comando le pegue a producción por accidente:

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

Al pasar a producción cambian las dos variables (GUDINK_API_BASE="https://app.gudink.com/api/v1" y una clave gk_live_), nada más.

Es otra cuenta

La cuenta, los productos, las claves y los destinos de avisos de pruebas no son los de producción y no se copian. En pruebas hay que crear todo de nuevo:

Registrate en staging.gudink.com y verificá el email.
Pedile a Gudink que habilite la API en esa cuenta. Ver cómo pedir acceso.
Completá los datos de facturación de esa cuenta.
Diseñá ahí los productos que vas a usar para probar. Tienen otros product_id y variant_id que los de producción.
Creá la clave en Integraciones > API. Empieza con gk_stg_.
Da de alta el destino de avisos en Integraciones > API > Avisos.

Al pasar a producción, todo eso se crea de nuevo en https://app.gudink.com: cuenta habilitada, productos, clave gk_live_ y destino de avisos con su secreto nuevo. No guardes en tu código ningún product_id ni variant_id de pruebas.

Qué no pasa en pruebas

En pruebas
Producción	No se produce nada
Envío	No se envía nada. No hay transportista ni etiqueta
Cobro	No se cobra plata real
Factura	No se emite
Mails a tu comprador	No hay. Gudink tampoco le escribe a tu comprador en producción
Mails a vos	Te llegan igual (el link de pago, el pago acreditado, el despacho), al email de tu cuenta de pruebas. Cada pedido creado manda al menos uno, así que una corrida completa de pruebas manda varios. No se pueden apagar: usá en la cuenta de pruebas un email que puedas filtrar

No pagues desde payment.pay_url en pruebas. Para hacer avanzar un pedido está la simulación.

El stock de pruebas es chico

Los pedidos de prueba reservan stock igual que en producción (ver Stock y reservas).

Cancelá cada pedido de prueba que no vayas a simular hasta el final, con POST /orders/{id}/cancel. Si los dejás vencer, retienen unidades hasta 72 horas y tus próximas pruebas pueden responder 409 out_of_stock aunque la variante diga available: true.
No hay una forma garantizada de provocar un out_of_stock en pruebas. Tu código tiene que manejarlo igual: probalo, por ejemplo, con un doble de la API en tus tests.

Probar product_archived

No se puede archivar un producto por la API. Para probar el rechazo:

En el panel de pruebas, archivá un diseño de prueba.
Mandá un pedido con su product_id. Responde 409 product_archived. Ese chequeo va antes que el de la cotización, así que sirve cualquier quote_id.

Desde ese momento ese producto ya no sale en GET /products, GET /products/{id} responde 404 y cotizarlo también responde 404 not_found.

Simular el recorrido de un pedido

POST /sandbox/orders/{id}/simulate hace avanzar un paso un pedido tuyo creado por API. Los avisos (webhooks) salen igual que en producción: es la forma de probar tu destino de avisos y el seguimiento de punta a punta. Cuerpo: { "event": "<paso>" }. Los pasos van en este orden, y cada uno exige el anterior:

`event`	El pedido tiene que estar en	Queda en	Aviso que sale
`pay`	`pending_payment`	`paid`	`order.paid`
`start_production`	`paid`	`in_production`	`order.in_production`
`ship`	`in_production` o `ready_to_ship`	`shipped`	`order.shipped`, con `tracking` completo (número, url y operador de prueba)
`deliver`	`shipped`	`delivered`	`order.delivered`

Pagar:

curl -sS -X POST "$GUDINK_API_BASE/sandbox/orders/1043/simulate" \
  -H "Authorization: Bearer $GUDINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "pay"}'

Entrar a producción:

curl -sS -X POST "$GUDINK_API_BASE/sandbox/orders/1043/simulate" \
  -H "Authorization: Bearer $GUDINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "start_production"}'

Despachar:

curl -sS -X POST "$GUDINK_API_BASE/sandbox/orders/1043/simulate" \
  -H "Authorization: Bearer $GUDINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "ship"}'

Entregar:

curl -sS -X POST "$GUDINK_API_BASE/sandbox/orders/1043/simulate" \
  -H "Authorization: Bearer $GUDINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "deliver"}'

Qué responde

Status	`error.code`	Cuándo
200	(el pedido, ya en el estado nuevo)	El paso corresponde al estado del pedido
400	`validation_error`	`event` no es uno de los cuatro
404	`not_found`	El pedido no existe, no es tuyo o no lo creaste por API
409	`invalid_transition`	El paso está fuera de orden (por ejemplo `ship` sobre un pedido sin pagar). No cambia nada
429	`rate_limited`	Pasaste las 30 simulaciones por minuto

El 409 invalid_transition trae el estado actual del pedido y el paso que pediste:

{
  "error": {
    "code": "invalid_transition",
    "message": "(texto para una persona)",
    "details": { "status": "pending_payment", "event": "ship" }
  }
}

Lo que conviene saber

Sólo existe en el entorno de pruebas. En producción la ruta responde 404 not_found y la especificación de producción no la muestra. La de pruebas (https://staging.gudink.com/api/v1/openapi.json) sí.
Si en pruebas también responde 404 not_found con un pedido tuyo creado por API, pedile a Gudink que te habilite la simulación.
ship carga un número de seguimiento de mentira: TEST- más el número del pedido (por ejemplo TEST-GU-1000501), con tracking.url de ejemplo (https://example.com/envio-de-prueba/TEST-GU-1000501) y tracking.carrier Envío de prueba, así probás tu pantalla de seguimiento entera. Nunca se lo muestres a un comprador real.
La simulación mueve sólo los estados del pedido y del envío.
Un pedido sin simular se cancela solo a las 72 horas, igual que en producción, pero mientras tanto retiene stock. Para probar order.cancelled, cancelalo a mano con POST /orders/{id}/cancel.
Límite: 30 simulaciones por minuto por cuenta.
No se simulan reembolsos, cancelaciones de pedidos pagos ni entregas fallidas.
Un retiro en sucursal se simula igual, con los mismos cuatro pasos: deliver es el retiro hecho. Los avisos traen delivery_type: "pickup" y la sucursal en pickup_point.

Probar los avisos

“Mandar prueba”, en Integraciones > API > Avisos, te envía un aviso webhook.test firmado. Ver el aviso de prueba.
Cada paso de la simulación manda el aviso real que corresponde, firmado con el secreto de tu destino de pruebas.
Si tu servidor corre en tu máquina, necesitás cualquier túnel https con un nombre de host público: Gudink no puede mandar avisos a localhost, a una IP ni a un puerto que no sea 443. Cuando termines, borrá ese destino. Y la firma la podés probar sin red, firmando vos los avisos: ver Probar tu destino sin publicarlo.

Recorrido de prueba de punta a punta

Corré estos diez pasos, en orden. Si los diez salen bien, tu integración está lista para producción.

Paso	Qué hacés	Qué tiene que pasar
1	En el panel de pruebas: cuenta, datos de facturación completos, productos diseñados, clave `gk_stg_` y destino de avisos	Tenés la clave y el secreto `whsec_…` en variables de entorno de tu servidor
2	`GET /me`	Responde 200 y `billing_complete` es `true`
3	`GET /products`	Guardás un par `product_id` + `variant_id` con `available: true`
4	`POST /shipping/quotes` y después `POST /orders` con un `external_id` de prueba	Responde 201 con `status: "pending_payment"`. Llega el aviso `order.created`
5	Simulación con `pay`	Llega `order.paid`
6	Simulación con `start_production`	Llega `order.in_production`
7	Simulación con `ship`	Llega `order.shipped` con el número `TEST-…`, y `GET /orders/{id}` lo trae en `tracking.number`. Tu sistema se lo pasaría al comprador
8	Simulación con `deliver`	Llega `order.delivered`
9	Repetís el mismo `POST /orders` (mismo `external_id`, mismo cuerpo)	Responde 200 con el mismo pedido, sin duplicarlo
10	Creás otro pedido y lo cancelás con `POST /orders/{id}/cancel`. Después repetís ese mismo `POST /orders`	El cancel responde 200 con `status: "cancelled"` y `cancel_reason: "cancelled_by_seller"`, llega `order.cancelled` con ese mismo `cancel_reason` y sus unidades vuelven a estar disponibles. El `POST /orders` repetido responde 200 con el pedido `cancelled`: tu tienda tiene que mirar `status`, no sólo el 2xx

Si tu tienda ofrece retiro en sucursal, hacé también un recorrido con la opción pickup: el pedido del paso 4 va con pickup_point_id y sin shipping_address (ver Retiro en sucursal). Los pasos 4 a 8, con curl:

# 4a. Cotizar
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": 1 }]
  }'

# 4b. Crear el pedido con el quote_id, un service_code y la province de la cotización
curl -sS "$GUDINK_API_BASE/orders" \
  -H "Authorization: Bearer $GUDINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "prueba-k7p2-0001",
    "items": [{ "product_id": 812, "variant_id": 4410, "quantity": 1 }],
    "recipient": { "name": "Ana Pérez", "phone": "+54 9 11 5555 5555" },
    "shipping_address": {
      "street": "Av. Corrientes",
      "number": "1234",
      "city": "CABA",
      "province": "Capital Federal",
      "postal_code": "C1043AAZ"
    },
    "shipping": { "quote_id": "<quote_id de 4a>", "service_code": "<service_code de la opción elegida>" }
  }'

# 5 a 8. Un paso por vez, con el id del pedido que devolvió 4b
for EVENT in pay start_production ship deliver; do
  curl -sS -X POST "$GUDINK_API_BASE/sandbox/orders/1043/simulate" \
    -H "Authorization: Bearer $GUDINK_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"event\": \"$EVENT\"}"
done

# Ver el pedido al final
curl -sS "$GUDINK_API_BASE/orders/1043" \
  -H "Authorization: Bearer $GUDINK_API_KEY"

Pasar a producción

Repetí en https://app.gudink.com lo que hiciste en el panel de pruebas: API habilitada, datos de facturación, productos, clave y destino de avisos.
Cargá en tu servidor GUDINK_API_BASE="https://app.gudink.com/api/v1", la clave gk_live_ y el secreto nuevo del destino de avisos.
Volvé a sincronizar el catálogo: los product_id y variant_id de producción son otros.
Repasá el checklist antes de pasar a producción.

Empezar

Cuenta

Integración con Tiendanube

API para tu web

Catálogo

Editor / Diseños

Productos

Pedidos

Producción

Envíos

Pagos

API: entorno de pruebas

Las dos direcciones

Es otra cuenta

Qué no pasa en pruebas

El stock de pruebas es chico

Probar product_archived

Simular el recorrido de un pedido

Qué responde

Lo que conviene saber

Probar los avisos

Recorrido de prueba de punta a punta

Pasar a producción

​Las dos direcciones

​Es otra cuenta

​Qué no pasa en pruebas

​El stock de pruebas es chico

​Probar product_archived

​Simular el recorrido de un pedido

​Qué responde

​Lo que conviene saber

​Probar los avisos

​Recorrido de prueba de punta a punta

​Pasar a producción

Las dos direcciones

Es otra cuenta

Qué no pasa en pruebas

El stock de pruebas es chico

Probar product_archived

Simular el recorrido de un pedido

Qué responde

Lo que conviene saber

Probar los avisos

Recorrido de prueba de punta a punta

Pasar a producción