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

# Claves de la API y autenticación

> Cómo crear y cuidar tu clave de la API de Gudink, cómo se manda en cada llamada y qué responde la API cuando la clave no sirve.

Cada llamada a la API se identifica con una clave que creás en tu panel. La clave actúa en nombre de tu cuenta: crea pedidos que se te cobran. Tratala como una contraseña.

## Crear una clave

1. Entrá a tu panel de Gudink, sección **Integraciones > API** (`/integraciones/api`). Necesitás el email verificado y la API habilitada en tu cuenta. El panel de pruebas y el de producción son dos cuentas distintas: ver [Entorno de pruebas](/api/entorno-de-pruebas).
2. Creá una clave con un nombre que te diga dónde la usás, por ejemplo "mi web producción".
3. **Copiala en ese momento.** Se muestra una sola vez. Si la perdés, revocala y creá otra.

| Entorno | Prefijo de la clave | URL base |
| - | - | - |
| Pruebas | `gk_stg_` | `https://staging.gudink.com/api/v1` |
| Producción | `gk_live_` | `https://app.gudink.com/api/v1` |

Después del prefijo vienen 40 caracteres entre `a-z` y `0-9`. Una clave de pruebas no sirve en producción, ni al revés: responde 401 `invalid_api_key`. Podés tener hasta 5 claves activas por cuenta. Cada clave nueva te manda un mail de seguridad.

## Cómo cuidarla

* **Sólo en tu servidor.** Nunca en un navegador, en una app móvil ni en código que corra en el dispositivo de tu comprador. La API no tiene CORS, a propósito: se usa de servidor a servidor.
* **Nunca en un repositorio**, aunque sea privado. Usá una variable de entorno o un gestor de secretos.
* **Nunca en la URL.** Sólo en la cabecera `Authorization`.
* **Nunca en una descarga de imagen.** Las imágenes de los productos son públicas y se bajan sin clave.
* **Nunca en el chat con un agente de IA.** Pasale el nombre de la variable de entorno, no el valor.
* Si creés que se filtró, revocala desde el panel. Es inmediato.

## Cuándo se revocan solas

Para protegerte, Gudink revoca todas tus claves y desactiva tus destinos de avisos cuando cambia quién controla la cuenta: si se resetea o cambia la contraseña, si se confirma un cambio de email, si la cuenta se desactiva o si se apaga el acceso a la API. Después de cualquiera de esos casos, creá claves nuevas.

## Cómo se manda

Toda ruta lleva esta cabecera, salvo `GET /openapi.json` y `GET /llms.txt`, que se leen sin clave:

```
Authorization: Bearer <clave>
```

Los ejemplos usan dos variables de entorno. Así como están apuntan al entorno de pruebas; para producción cambiá las dos (`https://app.gudink.com/api/v1` y tu clave `gk_live_`):

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

Para comprobar que anda:

```bash theme={null}
curl -sS "$GUDINK_API_BASE/me" \
  -H "Authorization: Bearer $GUDINK_API_KEY"
```

```json theme={null}
{
  "id": 412,
  "name": "Remeras del Sur",
  "billing_complete": true,
  "missing_billing_fields": []
}
```

`billing_complete` dice si tu cuenta tiene los datos de facturación que hacen falta para crear pedidos. Si es `false`, `POST /orders` responde 403 `billing_data_required` hasta que los completes en tu panel.

`missing_billing_fields` dice cuáles faltan, con los mismos nombres que usa ese error en `details.missing_fields`:

| Valor | Qué falta |
| - | - |
| `cuit` | El CUIT |
| `razon_social` | La razón social |
| `condicion_fiscal` | La condición fiscal |
| `phone` | El teléfono |

## Qué responde cuando la clave no sirve

| Status | `error.code` | Qué pasó | Qué hacer |
| - | - | - | - |
| 401 | `invalid_api_key` | Falta la cabecera, la clave está mal escrita, fue revocada, es de otro entorno o la cuenta está inactiva | Revisá la cabecera, la clave y que `GUDINK_API_BASE` sea del mismo entorno que la clave |
| 403 | `api_access_disabled` | Tu cuenta no tiene la API habilitada | [Pedí acceso](/api/introduccion#como-pedir-acceso) |
| 403 | `account_under_review` | Tu cuenta está en revisión | Escribinos a [soporte@gudink.com](mailto:soporte@gudink.com) |
| 429 | `rate_limited` | Demasiados intentos fallidos seguidos, o pasaste un límite de uso | Esperá los segundos que dice la cabecera `Retry-After` |

No reintentes un 401 en bucle: la clave no va a empezar a funcionar sola, y demasiados intentos fallidos seguidos terminan en 429 por unos minutos. Una clave válida sigue entrando igual.

Estos códigos sólo cuentan cuando la respuesta es JSON y trae el sobre `{ "error": { ... } }`.

## Un 403 que no es JSON no es tu clave

Si recibís un 403 con un texto o una página en vez de JSON (por ejemplo `error code: 1010`), es un bloqueo de la red que está delante de la API, no de la API: tu clave no tiene nada que ver, y no es `api_access_disabled`. Pasa incluso en `GET /llms.txt`, que no lleva clave.

* Casi siempre es el `User-Agent` que tu librería manda por defecto (pasa con `urllib` de Python).
* Mandá una cabecera `User-Agent` propia en cada llamada, por ejemplo `MiTienda/1.0 (+https://mitienda.com)`, y repetí.
* Si sigue, escribinos a [soporte@gudink.com](mailto:soporte@gudink.com) con la hora y tu IP.

Ver [Respuestas que no son de la API](/api/errores-y-limites#respuestas-que-no-son-de-la-api).

La tabla completa de errores, con qué trae cada uno, está en [Errores y límites](/api/errores-y-limites).


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