Guía de inicio

Esta guía te lleva desde cero hasta tu primera llamada exitosa: cómo obtener credenciales según tu escenario, cómo autenticarte, qué forma tienen las respuestas y cómo comprobar la conexión.

1.Obtener credenciales

Escenario A · Plataforma multi-tienda

La plataforma obtiene el store_token de dos formas: el negocio lo copia de su panel GSG y lo pega en la configuración de tu producto, o tu backend lo recupera automáticamente con POST /api/integration/bindings/lookup usando el external_store_id que el negocio declaró al vincularse.

Escenario B · Integración directa

1. El negocio entra a su panel GSG → Integraciones → Integración directa y envía la solicitud (nombre del sistema, descripción, contacto técnico, URL de webhook opcional).
2. GSG revisa la solicitud. Mientras está pendiente, el panel muestra "en revisión"; si se rechaza, muestra el motivo y permite volver a solicitar.
3. Aprobada la solicitud, el negocio pulsa Generar API key (pide re-autenticación). El panel muestra una sola vez la api_key y el store_token. El webhook_secret se mostró una sola vez al enviar la solicitud (si indicó URL de webhook); si no lo guardó, rótelo desde Integraciones → Integración directa → Webhook (rotate_secret: true) o marque "rotar el secret" al regenerar la API key.

Mientras la solicitud está pendiente, el negocio puede retirarla desde el mismo panel (queda inactiva y puede volver a solicitarse más adelante).

2.URL base y entornos

En toda la documentación las rutas se muestran relativas a {BASE_URL}. Sustitúyela por la URL base que te indique GSG. La URL base de producción es la que se muestra en el panel de negocios GSG (sección Integraciones); GSG puede facilitarte además un ambiente de pruebas.

• Solo HTTPS en producción; valida el certificado.
• Content-Type: application/json en todas las peticiones con cuerpo.

3.Cabeceras de autenticación

* Debes enviar una de las dos formas de API key.

Qué endpoint exige qué

4.Formato de respuesta y códigos

Todas las respuestas de la API de integrador usan el mismo envelope. En éxito hay message y data; en error solo message. El campo message.code es "90" + código HTTP.

{
  "message": { "description": "Ok", "title": "OK OK", "code": "90200" },
  "data": { ... }
}

{
  "message": {
    "description": "texto explicativo del error",
    "title": "Error",
    "code": "90400"
  }
}

5.Prueba de conexión: GET /api/v1/integration/me

Devuelve quién eres para GSG: tu cliente de integración, el prefijo de la API key en uso, la tienda (si enviaste store_token o eres integración directa), el estado de tu webhook (solo integración directa) y el rate limit. No tiene efectos secundarios: úsalo como health check de credenciales.

curl "https://{BASE_URL}/api/v1/integration/me" \
  -H "X-API-Key: gsg_PREFIJO_SECRETO" \
  -H "X-Store-Token: st_TOKEN_DE_TIENDA"

{
  "message": { "description": "Ok", "title": "OK OK", "code": "90200" },
  "data": {
    "api_version": "1.4",
    "server_time": "2026-09-03T15:00:00.000Z",
    "integration_client": {
      "id": 1,
      "code": "stocky_360",
      "name": "Stocky360",
      "type": "PLATFORM",
      "status": "active"
    },
    "api_key": {
      "prefix": "2d35df56256315f7",
      "created_at": "2026-08-01T14:02:11.000Z",
      "last_used_at": "2026-09-03T14:59:40.000Z"
    },
    "store": {
      "binding_id": 12,
      "business_id": 2120,
      "business_name": "Ctrl go",
      "external_store_id": "flujos_ctrlgo",
      "status": "active"
    },
    "webhook": null,
    "rate_limit": { "per_minute": 300 },
    "docs_url": "https://business.gsgcorp.pe/documentacion_publica/"
  }
}

Respuesta con Cache-Control: no-store.

6.Recuperar el store_token de una tienda (plataformas)

Servidor a servidor. Devuelve el store_token de una tienda ya vinculada a tu plataforma a partir del external_store_id que el negocio declaró al vincularse en su panel GSG. No es para polling: consúltalo al conectar una tienda o al recibir 401 por token inválido, y cachea el resultado.

POST {BASE_URL}/api/integration/bindings/lookup
X-API-Key: gsg_PREFIJO_SECRETO
Content-Type: application/json

{ "external_store_id": "flujos_ctrlgo" }

{
  "message": { "description": "Ok", "title": "OK OK", "code": "90200" },
  "data": {
    "exists": true,
    "binding": {
      "id": 12,
      "business_id": 2120,
      "user_id": 3310,
      "store_token": "st_a1b2c3…",
      "external_store_id": "flujos_ctrlgo",
      "status": "active",
      "created_at": "2026-08-20T16:45:00.000Z"
    }
  }
}

{
  "message": { "description": "Ok", "title": "OK OK", "code": "90200" },
  "data": {
    "exists": true,
    "binding": { "id": 12, "business_id": 2120, "user_id": 3310, "store_token": null,
                 "external_store_id": "flujos_ctrlgo", "status": "pending", "created_at": "…" },
    "reason": "El vínculo existe pero está pendiente de aprobación por GSG."
  }
}

{ "message": { "description": "Ok", "title": "OK OK", "code": "90200" }, "data": { "exists": false } }

7.Rate limit

Todos los endpoints de integrador (/api/v1/integration/* y POST /api/v1/orders/integration) aplican dos límites independientes:

Al superar cualquiera de los dos, la respuesta es 429 con el envelope estándar:

{
  "message": {
    "description": "Demasiadas peticiones: máximo 300 por minuto por cliente de integración. Espere y reintente con backoff.",
    "title": "Too Many Requests",
    "code": "90429"
  }
}

Cada respuesta incluye las cabeceras estándar RateLimit-* (borrador IETF draft-7): RateLimit-Policy: 300;w=60 y RateLimit: limit=300, remaining=<n>, reset=<segundos> (las del límite que esté más cerca de agotarse). Úsalas para regular tus ráfagas. Recomendaciones:

• Registra pedidos a medida que se generan (no en lotes masivos al final del día). Si debes migrar un histórico, coordina con GSG.
• Ante 429 aplica backoff exponencial respetando reset; no reintentes en bucle.
• Cachea GET /catalogs (TTL 5 min) y usa webhooks para estados; deja el polling como respaldo.

8.Seguridad de las credenciales

1. Guarda la API key en un vault o gestor de secretos (o variables de entorno cifradas). Nunca en el repositorio, en logs ni en tickets.
2. Nunca la uses desde un frontend (navegador, app móvil, plugin cliente). Todas las llamadas deben salir de tu backend.
3. Rota la key periódicamente y ante cualquier sospecha de filtración. Integraciones directas: botón "Rotar API key" en el panel (la anterior queda revocada al instante). Plataformas: solicítalo a GSG. Planifica el despliegue de la key nueva antes de rotar: no hay periodo de convivencia.
4. Trata cada store_token como credencial: quien lo tenga junto con tu API key puede registrar pedidos a nombre de esa tienda. Guárdalo y envíalo exactamente como lo recibiste (la comparación no distingue mayúsculas, pero usa siempre la misma caja).
5. Guarda el webhook_secret igual que la key y verifica siempre la firma de los eventos.
6. Registra en tu sistema el api_key.prefix que devuelve /me: te permite saber qué key está desplegada en cada ambiente sin exponer el secreto.

9.Siguientes pasos

1. Descarga la colección Postman y configura base_url, api_key y store_token.
2. Llama a GET /catalogs y guarda distritos, tamaños, agencias y sedes (Catálogos y tarifas).
3. Cotiza con POST /quote y registra tu primer pedido con POST /api/v1/integration/orders (API de pedidos). El ejemplo mínimo está en la portada.
4. Consulta el pedido con GET /orders/:orderExternalId y configura tu webhook (Seguimiento, Webhooks).

10.Historial de cambios