> ## 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.

# API: entorno de pruebas

> Dónde y cómo probar tu integración con la API de Gudink sin producir, enviar ni cobrar nada: URLs, clave de pruebas, cómo simular el pago, la producción, el despacho y la entrega, y un recorrido de punta a punta.

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:

```bash theme={null}
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:

1. Registrate en [staging.gudink.com](https://staging.gudink.com?utm_source=ayuda\&utm_medium=help_center\&utm_campaign=entorno_de_pruebas) y verificá el email.
2. Pedile a Gudink que habilite la API en esa cuenta. Ver [cómo pedir acceso](/api/introduccion#como-pedir-acceso).
3. Completá los datos de facturación de esa cuenta.
4. Diseñá ahí los productos que vas a usar para probar. Tienen otros `product_id` y `variant_id` que los de producción.
5. Creá la clave en **Integraciones > API**. Empieza con `gk_stg_`.
6. 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](/api/pedidos#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:

1. En el panel de pruebas, archivá un diseño de prueba.
2. 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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](/api/avisos#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](/api/avisos#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](/api/pedidos#retiro-en-sucursal)).

Los pasos 4 a 8, con `curl`:

```bash theme={null}
# 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

1. 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.
2. 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.
3. Volvé a sincronizar el catálogo: los `product_id` y `variant_id` de producción son otros.
4. Repasá el [checklist antes de pasar a producción](/api/errores-y-limites#checklist-antes-de-pasar-a-produccion).


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