GSG Corp · Integraciones para e-commerce, CRM y ERP

Documentación pública de integración

Portal v1.4 · Actualizado el 2026-09-29 · API de integrador 1.4

GSG es un courier de última milla en Lima (Perú) que se integra con plataformas de e-commerce, CRMs y ERPs. Aquí vive la documentación técnica vigente para integradores. Guarda el enlace: cada documento se versiona en el mismo lugar, con su historial de cambios.

1.¿Cuál es tu caso? Elige en 30 segundos

La API es la misma para todos; lo único que cambia es cómo obtienes las credenciales. Ubícate en una de estas tres situaciones:

A · Tengo tienda online o sistema propio Tu web, tu ERP, tu app o un software hecho para tu negocio, y envías con GSG.

→ Integración directa: la solicitas desde tu panel GSG, GSG la aprueba y tú generas tu API key. Una sola credencial; sin store_token.
B · Soy un SaaS, CRM o sistema de ventas (varios clientes) Plataforma de e-commerce, CRM de ventas por WhatsApp, ERP en la nube… y varios de tus clientes envían con GSG.

→ Plataforma multi-tienda: GSG te entrega una API key; cada cliente tuyo se conecta desde su panel GSG y te da su store_token. Integras una vez, sirve para todos.
C · Vendo por WhatsApp y no tengo sistema No necesitas esta API. Registra tus envíos en el panel GSG (formulario o carga masiva) o usa un CRM / sistema de ventas que ya esté conectado a GSG (pídele a tu proveedor que se integre como plataforma, caso B).

2.Tu primera integración en 4 llamadas

Con tus credenciales en mano (ver cómo obtenerlas) esto es todo lo que necesitas para registrar un envío y saber cuánto cuesta. Sustituye {BASE_URL} por la URL que te indique GSG. Si eres plataforma, agrega -H "X-Store-Token: st_…" con el token de la tienda en cada llamada; en integración directa puedes omitirlo.

  1. 1 · Comprueba tus credenciales 
    curl "{BASE_URL}/api/v1/integration/me" -H "X-API-Key: gsg_PREFIJO_SECRETO"
    Responde 90200 con tu cliente de integración y la tienda resuelta. Si ves 90401, revisa la key o el store_token.
  2. 2 · Cotiza (cuánto le costará el envío a tu negocio) 
    curl -X POST "{BASE_URL}/api/v1/integration/quote" \
  -H "X-API-Key: gsg_PREFIJO_SECRETO" -H "Content-Type: application/json" \
  -d '{ "route_type": 1, "district": "MIRAFLORES", "size": "M" }'
    Devuelve total_service_cost con la tarifa real de tu negocio (descuentos y convenios incluidos). Úsalo para mostrar el costo del envío antes de confirmar la venta. Los nombres de distrito salen de GET /api/v1/integration/catalogs.
  3. 3 · Registra el pedido (mínimo necesario para una entrega a domicilio) 
    curl -X POST "{BASE_URL}/api/v1/integration/orders" \
  -H "X-API-Key: gsg_PREFIJO_SECRETO" -H "Content-Type: application/json" \
  -d '{
    "order_external_id": "PED-1001",
    "route_type": 1,
    "full_name": "Ana Torres",
    "telephone": "987654321",
    "address": "Av. Larco 345, Dpto. 502",
    "district": "MIRAFLORES",
    "date_route": "16-09-2026 10:00",
    "product": "Zapatillas talla 38",
    "size": "M",
    "code_pay_method": "PAGADO"
  }'
    order_external_id es el id del pedido en tu sistema: repetir la llamada con el mismo id no duplica el envío. La respuesta trae code_tracking (p. ej. GSG-E-231472), el estado inicial y service_cost. Si el destinatario paga contra entrega, usa "code_pay_method": "EFECTIVO" y "pay_amount_simple": "150". Todos los campos y tipos de envío (agencia, cambio, recojo en sede, Flex, XL) en API de pedidos.
  4. 4 · Sigue el envío 
    curl "{BASE_URL}/api/v1/integration/orders/PED-1001" -H "X-API-Key: gsg_PREFIJO_SECRETO"
    Estado actual, línea de tiempo con fotos y cobros. Para no consultar en bucle, configura un webhook: GSG avisa a tu URL en cada cambio de estado.
Prueba sin escribir código: descarga la colección Postman, completa base_url, api_key y (si aplica) store_token, y ejecuta las mismas cuatro llamadas.

3.Qué puedes hacer con la API

Con la API de integración tu sistema registra pedidos en GSG sin digitarlos en el panel, cotiza antes de confirmar, consulta el estado de cada envío y recibe notificaciones cuando el estado logístico cambia.

Registrar pedidos Entrega a domicilio, agencia (Shalom, Olva, Marvisur u otra), cambio, recojo en sede GSG y entrega Flex. Tamaños courier (S/M, en moto) y GSG XL (Grande / Plus / Max en van, o XL con peso y medidas para que GSG clasifique).
Cotizar y consultar catálogos Distritos con tarifa, tamaños, agencias y sucursales, sedes, métodos de pago y estados, con la tarifa real de tu negocio.
Seguir y cancelar Estado, línea de tiempo con fotos, cobros e incidencias por pedido; listado paginado; cancelación mientras el paquete no haya ingresado a GSG.
Webhooks Evento route.status_changed firmado con HMAC-SHA256, con reintentos y reenvío de eventos retenidos.

4.Los dos escenarios de integración (paso a paso)

Detalle de cada escenario de la sección 1. En ambos casos la API es la misma; cambia únicamente cómo se obtienen las credenciales.

A) Plataforma multi-tienda

Para SaaS de ventas, CRM o ERP que atienden a varios negocios que envían con GSG.
  1. GSG Da de alta la plataforma como cliente de integración y entrega la API key (se muestra una sola vez) por canal seguro.
  2. Cada negocio (tienda) Desde su panel GSG (Integraciones → Plataformas) se vincula a la plataforma y obtiene su store_token. Si la plataforma exige aprobación manual, GSG aprueba el vínculo antes de habilitar el token.
  3. Plataforma Guarda el store_token de cada tienda: el negocio lo pega en tu panel, o tu backend lo recupera con POST /api/integration/bindings/lookup a partir del external_store_id que el negocio declaró al vincularse.
  4. Plataforma Llama a la API con API key + store_token de la tienda correspondiente en cada petición.
Credenciales: X-API-Key (o Authorization: Bearer) + X-Store-Token por tienda. Webhook: una URL por plataforma, configurada por GSG.

B) Integración directa

Para un negocio con sistema propio (tienda online, ERP a medida) que envía con GSG.
  1. Negocio Desde su panel GSG (Integraciones → Integración directa) solicita la integración: nombre del sistema, descripción, contacto técnico y, opcionalmente, URL de webhook.
  2. GSG Revisa y aprueba la solicitud (o la rechaza con un motivo visible en el panel).
  3. Negocio Genera su API key desde el mismo panel (se muestra una sola vez; puede rotarla cuando quiera). El store_token también se muestra, pero no es obligatorio: la API key ya identifica al negocio.
  4. Negocio Llama a la API solo con la API key y configura su propio webhook desde el panel.
Credenciales: X-API-Key (o Authorization: Bearer). X-Store-Token opcional. Webhook: lo gestiona el propio negocio desde su panel.
Misma API para ambos: el registro de pedidos es POST /api/v1/orders/integration y el resto de operaciones viven bajo /api/v1/integration/*. La única diferencia es que una integración directa puede omitir X-Store-Token.

5.Requisitos

6.Documentos

v1.2 · 2026-09-29 Guía de inicio
Credenciales por escenario, URL base, cabeceras de autenticación, formato de respuesta y códigos, prueba de conexión con GET /api/v1/integration/me, rate limit y seguridad.
v1.4 · 2026-09-29 API de registro de pedidos
Contrato completo de POST /api/v1/orders/integration: campos, matriz por tipo de ruta (1, 2, 3, 4, 7), tamaños courier y XL, modo de cobro, apertura del paquete, hora límite del día, idempotencia, respuesta, errores y ejemplos.
v1.3 · 2026-09-29 Catálogos y tarifas
GET /api/v1/integration/catalogs sección por sección, cómo leer la tarifa courier vs XL y el descuento del negocio, y POST /api/v1/integration/quote para cotizar antes de registrar.
v1.2 · 2026-09-29 Seguimiento y cancelación de pedidos
Consulta por order_external_id o por código de tracking, listado paginado, cancelación, significado de los 18 estados y de los estados logísticos.
v1.2 · 2026-09-03 Manual de webhooks de estado de pedidos
Recibir notificaciones route.status_changed: verificación de firma HMAC, payload, orden de eventos offline, reintentos y buenas prácticas.
v1.2 · 2026-09-25 Referencia de errores
Tabla consolidada por endpoint: HTTP, message.code, mensaje típico, causa y qué hacer.
v1.3 · 2026-09-25 Colección Postman
Colección v2.1 con variables base_url, api_key, store_token y todos los requests (me, catálogos, cotización, registro por tipo, consulta, listado, cancelación, lookup).

7.Historial de cambios del portal

VersiónFechaCambios
1.42026-09-29 API de integrador 1.4, cambios aditivos, sin acción obligatoria. Hora límite de registro del día: GSG publica en GET /catalogs el bloque order_cutoff (cutoff_time HH:mm y timezone America/Lima). Un pedido con date_route de hoy registrado después de esa hora se acepta igual (no hay error nuevo), pero queda fuera de hora y GSG puede despacharlo el siguiente día hábil; la respuesta 200 del registro, el detalle y el listado agregan after_cutoff (booleano). Recomendado: pasada la hora, registrar con la fecha del día siguiente. Páginas: API de pedidos 1.4, catálogos 1.3, seguimiento 1.2, guía de inicio 1.2 (ejemplo de /me con api_version 1.4). El webhook, los errores y la colección Postman no cambian.
1.32026-09-25 API de integrador 1.3, cambios aditivos. El registro de pedidos acepta tres campos opcionales que antes se descartaban sin error: open_policy (apertura del paquete: SEALED no se puede abrir, INSPECT puede abrir y revisar, TRY_ON puede abrir y probar; sin enviar se aplica el predeterminado del negocio y, si no hay, SEALED; null en Agencia), pos_fee_included (0/1, solo con TARJETA: si el monto ya incluye el 5% del POS; no cambia montos) y url_maps (enlace http(s) de la ubicación del destinatario). Con latitude/longitude, address puede ir vacío. La respuesta 200 devuelve open_policy; GET /catalogs publica el bloque open_policy y business.default_open_policy; el detalle del pedido agrega open_policy, recipient.url_maps, recipient.location y payment.pos_fee_included. Tres 400 nuevos para valores inválidos. Páginas: API de pedidos 1.3, catálogos 1.2, seguimiento 1.1, errores 1.2; colección Postman 1.3. El webhook no cambia.
1.22026-09-15 Portada con guía de decisión (tienda con sistema propio / SaaS-CRM / venta por WhatsApp sin sistema) y quickstart en 4 llamadas. Nueva ruta POST /api/v1/integration/orders (alias idéntico de POST /api/v1/orders/integration, que se mantiene). GSG XL sobre el modelo de zonas: la tarifa XL sale de la zona del distrito (districts[].zone) y la categoría (XL_GRANDE, XL_PLUS, XL_MAX) por bulto; XL_STD deja de ofrecerse; size: "XL" + weight_kg, width_cm, height_cm, depth_cm deja que GSG elija la categoría; L queda marcado legacy_only. Regla XL_ZONE_TARIFF_V1 reemplaza a XL_DISTRICT_TARIFF_V1. Convenios por empresa (BUSINESS_AGREEMENT_V1) se reflejan en /quote y en service_cost.
1.12026-09-03 Portal completo. Nuevo escenario de integración directa (el negocio solicita, GSG aprueba, el negocio genera su API key; store_token opcional). Nuevos documentos: guía de inicio, catálogos y tarifas, seguimiento, errores y colección Postman. API de pedidos ampliada de forma aditiva: tamaños GSG XL (XL_STD, XL_PLUS, XL_GRANDE, XL_MAX), agencias por agency_code / agency_id con sucursales, flags package_registered / package_labeled, validación completa antes de reservar el order_external_id, campos nuevos en la respuesta (route_type_code, size_code, service, date_route, status, service_cost, tracking_url). Nuevos endpoints /api/v1/integration/me, /catalogs, /quote, /orders, /orders/:id, /orders/tracking/:code, /orders/:id/cancel. Manual de webhooks v1.2 con campos aditivos state_id, route_type_code, size_code, service. Rate limit de 300 peticiones/min por cliente de integración (más 900/min por IP).
1.12026-09-03 Revisión del mismo día (sin cambio de versión de páginas): 401 de vínculo no activo con el prefijo histórico Vínculo de tienda inactivo o bloqueado (…) en cuatro variantes; 401 API key expirada; genere una nueva; rate limit en dos niveles (300/min por cliente de integración + 900/min por IP) con cabeceras RateLimit; 400 El cuerpo JSON no es válido para JSON malformado; 500 con textos fijos; 409 de cancelación documentados con sus textos vigentes; Idempotency-Key de intentos fallidos liberada; order_external_id/store_token sin distinción de mayúsculas (regla "misma caja"); alias PEQUENIO; /quote no exige number_packages_in; GET /me → webhook null para plataformas; webhooks: 3xx retenido de inmediato, eventos de vínculos no activos recuperables, DRIVER_ASIGNADO/DRIVER_DESASIGNADO notificados, previous_status null; integración directa: el webhook_secret se muestra al solicitar y la solicitud pendiente puede retirarse. Colección Postman: X-Store-Token deshabilitado por defecto en /me y /catalogs.
1.02026-08-05 Portada inicial con el manual de webhooks v1.1.

8.Contacto y soporte

Las credenciales (API key, store_token, webhook_secret) se generan desde el panel de negocios GSG o se entregan por canal seguro; nunca por esta página.