API de registro de pedidos

Documentación para el equipo técnico del integrador (plataforma de e-commerce, CRM, ERP o sistema propio del negocio) que enviará pedidos a GSG. No utiliza sesión web (JWT): la autenticación es API key y, para plataformas multi-tienda, token de tienda (store_token).

1.Novedades de esta versión (1.4)

• Hora límite de registro del día: GSG cierra la recepción de pedidos para el mismo día a una hora configurable (hora de Lima; se publica en GET /catalogs → order_cutoff.cutoff_time). Un pedido con date_route de hoy registrado después de esa hora se acepta igual (no hay error nuevo), pero queda marcado fuera de hora: GSG puede despacharlo el siguiente día hábil. Ver § 5.4.1.
• La respuesta 200 agrega after_cutoff (true si entró fuera de hora). También aparece en el detalle y el listado del pedido.
• Nada cambia en el cuerpo que envías: si quieres evitar la marca, a partir de la hora límite registra con la fecha del día siguiente.

Novedades de la versión 1.3 (2026-09-25)

• Apertura del paquete (open_policy, opcional): indica si el destinatario puede abrir el paquete antes de recibirlo o pagarlo: SEALED (no se puede abrir), INSPECT (puede abrir y revisar) o TRY_ON (puede abrir y probar). Si lo omites se aplica el predeterminado de tu negocio. Ver § 5.5.
• Cobro con POS (pos_fee_included, opcional, solo con TARJETA): indica si el monto a cobrar ya incluye el 5% de comisión del POS. Es informativo para el motorizado: no cambia montos.
• Enlace de ubicación (url_maps, opcional): enlace http(s) de Google Maps, Apple Maps o WhatsApp con la ubicación del destinatario. GSG lo muestra al motorizado.
• La respuesta 200 agrega open_policy (valor efectivo guardado). El catálogo 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.
• Antes de esta versión estos tres campos se descartaban sin error. Ahora se validan: un valor inválido responde 400 (ver § 12).

Novedades de la versión 1.2 (2026-09-15)

• Ruta bajo el prefijo del API de integrador: POST /api/v1/integration/orders. Es un alias idéntico de POST /api/v1/orders/integration (mismas cabeceras, body, respuestas e idempotencia); la ruta histórica se mantiene.
• GSG XL por zonas: el precio XL sale de la zona del distrito (districts[].zone en el catálogo) y la categoría, por bulto. Categorías vigentes: XL_GRANDE, XL_PLUS, XL_MAX (XL_STD ya no se ofrece). Ver § 6.
• Clasificación automática: envía "size": "XL" con weight_kg, width_cm, height_cm y depth_cm por bulto y GSG elige la categoría (gana el criterio más exigente). Si envías una categoría explícita y medidas, se queda la mayor de las dos.
• L (GRANDE) queda como tamaño de compatibilidad (legacy_only en el catálogo): no lo ofrezcas en tu UI; usa S/M o una categoría XL.
• Convenios por empresa: si tu negocio tiene un precio pactado con GSG, /quote y service_cost lo aplican (pricing_rule = BUSINESS_AGREEMENT_V1).

Novedades de la versión 1.1 (2026-09-03)

• Tamaños GSG XL en size, válidos en los tipos 1, 2, 3, 4 y 7. Ver § 6.
• Agencias por catálogo: identifica la agencia con agency_code (recomendado) o agency_id; agency_name se mantiene. Agencias partner (Shalom, Olva, Marvisur) no exigen district, destination_address ni telephone. Sucursal opcional con agency_branch_id; flags package_registered / package_labeled.
• Validación completa antes de reservar el order_external_id: cualquier 400 (incluida la pre-cotización con base de datos: cobertura, agencia, tarifa XL) sale sin consumir el id. Además, un intento fallido nunca bloquea el reintento corregido.
• Campos nuevos en la respuesta 200: route_type_code, size_code, service, date_route, status, service_cost, tracking_url. Ver § 11.
• Límites de longitud con 400 claro (antes: error SQL). Ver § 8.
• Validación de number_packages, number_packages_in, montos y coordenadas opcionales latitude/longitude.
• Rate limit en dos niveles (HTTP 429, code 90429): 300 peticiones/min por cliente de integración (tras autenticar; el valor vigente se consulta en /me → rate_limit.per_minute) y 900/min por IP (antes de autenticar). Ver Errores.
• Nuevos endpoints complementarios: catálogos y cotización, consulta, listado y cancelación.

2.Flujo operativo (resumen)

Escenario A · Plataforma multi-tienda

1. GSG da de alta un cliente de integración (la plataforma) y genera una API key (se muestra una sola vez). Esa clave identifica a la plataforma tecnológica (por ejemplo, su sistema de ventas).
2. El negocio (tienda), en su panel GSG (Integraciones → Plataformas), se vincula a la plataforma y obtiene su store_token. Si la plataforma está configurada con aprobación manual, GSG aprueba el vínculo antes de habilitar el token.
3. La plataforma obtiene el store_token de cada tienda: o el negocio lo pega en el panel de la plataforma, o la plataforma lo recupera automáticamente con POST /api/integration/bindings/lookup (ver Guía de inicio § 6).
4. La plataforma configura en su sistema la API key (secreta, servidor a servidor) y el store_token de cada tienda conectada.
5. Cada pedido se envía con POST /api/v1/orders/integration usando esas credenciales y el identificador del pedido en el e-commerce (order_external_id).
6. Notificaciones de estado (webhook): GSG envía eventos a una URL única por plataforma (la configura un administrador GSG), firmados con HMAC. Deduplica por X-GSG-Event-Id: GSG puede reenviar eventos. Ver Manual de webhooks.

Escenario B · Integración directa

1. El negocio solicita la integración desde su panel GSG (Integraciones → Integración directa).
2. GSG aprueba la solicitud.
3. El negocio genera su API key desde el panel (se muestra una vez). El store_token se muestra también pero es opcional: la API key ya identifica al negocio.
4. Cada pedido se envía con POST /api/v1/orders/integration solo con la API key. El webhook lo configura el propio negocio en su panel.

3.Endpoint

Sustituye {BASE_URL} por la URL base que te indique GSG (la de producción se muestra en el panel de negocios GSG). La ruta histórica POST {BASE_URL}/api/v1/orders/integration sigue vigente y es idéntica (mismo handler): los ejemplos de este documento valen para ambas.

• Protocolo: solo HTTPS en producción.
• Content-Type: application/json.
• Rate limit: 300 peticiones/min por cliente de integración (compartido entre POST /api/v1/orders/integration y /api/v1/integration/*, evaluado tras autenticar) y 900 peticiones/min por IP (antes de autenticar). Mensajes exactos en Errores.

4.Cabeceras HTTP

* Debe enviarse una de las dos formas de API key (no hace falta ambas).
** Si no usas X-Store-Token, puedes enviar el mismo valor en el cuerpo JSON como store_token.

Formato de la API key

La clave tiene el formato gsg_<prefijo_hexadecimal>_<secreto> y debe enviarse completa, tal como se generó.

5.Cuerpo JSON

5.1 Campos propios de la integración

* Plataformas: al menos uno entre X-Store-Token y store_token en body.

Todo lo demás es el mismo modelo que el registro de pedidos del panel GSG. El servidor valida campos extra según route_type.

Campos ignorados: id_client, products, business_id, headquarter_id, provider_user_id, id_package_size y flk_manage_products se descartan (tampoco participan en el hash de idempotencia). Un integrador no puede adjuntar el pedido a un cliente ya existente en GSG ni descontar stock: el destinatario se crea siempre con los datos del body.

5.2 Tipos de ruta (route_type) — cuándo usar cada uno

Otros valores devuelven 400: route_type debe ser 1 (Entrega), 2 (Agencia), 3 (Cambio), 4 (Recojo en GSG) o 7 (Entrega Flex). Puede enviarse como número (1) o string ("1").

5.3 Modo de cobro recomendado: detallado (cost + advance)

El backend calcula el monto a cobrar en ruta como máximo(cost − advance, 0) (salvo PAGADO).

• Regla code_pay_method: "PAGADO": si el pedido ya está pagado, el sistema fuerza costo, adelanto y monto a cobrar a 0. Aun así debes enviar code_pay_method; cost/advance pueden ser 0.
• No envíes pay_amount_simple si trabajas en modo detallado: si llega con valor y no es PAGADO, el servidor prioriza pay_amount_simple e ignora el cálculo desde cost/advance.
• Campo pay_amount_detailed: no existe en la API; algunos ejemplos antiguos lo muestran, pero el backend no lo lee.
• Estos montos son lo que el destinatario paga por el producto. La tarifa del servicio GSG (lo que GSG cobra al negocio) la calcula GSG y se devuelve en service_cost; puedes anticiparla con POST /quote.

5.4 Catálogo de valores útiles

code_pay_method (obligatorio, texto): PAGADO, EFECTIVO, TARJETA, TRANSFERENCIA, YAPE, PLIN, OTRO. La lista vigente la devuelve GET /catalogs (payment_methods). El servidor normaliza a MAYÚSCULAS ("pagado" se procesa como PAGADO); aun así envía el código en mayúsculas.

size (o size_code): tamaño del bulto. Courier (moto): S, M (alias PEQUEÑO, MEDIANO; L/GRANDE solo compatibilidad). GSG XL (van): XL_GRANDE, XL_PLUS, XL_MAX, o XL + weight_kg, width_cm, height_cm, depth_cm por bulto para que GSG clasifique. Si lo omites se usa S. Detalle en § 6.

district (obligatorio en tipos 1, 3 y 7; en tipo 2 solo cuando la agencia se identifica por agency_name o no es partner): distrito de entrega, validado contra el catálogo de distritos GSG — el distrito determina la tarifa del servicio. Se normaliza a mayúsculas y la comparación no distingue tildes ("Miraflores", "MIRAFLORES" y "JESÚS MARÍA"/"JESUS MARIA" son equivalentes). Un distrito fuera de catálogo devuelve 400 con mensaje claro. En tipo 4 se ignora: el servidor lo fija según la sede. Lista vigente: GET /catalogs (districts).

client_pays_delivery: 0 = no paga delivery adicional; 1 = el cliente paga el delivery (informativo para el motorizado). Acepta número o string numérico (0, 1, "0", "1"); cualquier otro valor devuelve 400. En tipo 2 el servidor lo fuerza siempre a 0.

pay_at_destination (obligatorio en tipo 2): 0 o 1 — si el cobro del saldo es en destino (agencia). Acepta número o string numérico; cualquier otro valor devuelve 400.

package_registered, package_labeled (opcionales, tipo 2 partner): 0 o 1. Indican si el negocio ya registró el envío en la agencia y si ya rotuló el paquete. Si envías 0, GSG hace ese trabajo y lo cobra como recargo (registro S/ 2.00, rotulado S/ 0.50). Si los omites se asume trabajo hecho (no hay recargo). Solo tienen efecto con agencias partner. Se aceptan como número o string numérico; el valor entra al hash de idempotencia tal como lo envías (0 y "0" no son el mismo cuerpo), así que reintenta siempre con el mismo tipo JSON.

date_route (obligatorio): fecha y hora (con minutos) en que debe salir el pedido. Formatos aceptados (parsing estricto):

Cualquier otro formato (p. ej. ISO 2026-01-16T14:30) u omitirlo devuelve 400 con mensaje descriptivo — el pedido no se registra con la fecha actual. La respuesta devuelve la fecha normalizada como YYYY-MM-DD HH:mm:ss.

5.4.1 Hora límite de registro del díav1.4

GSG recibe pedidos para despachar el mismo día hasta una hora límite (hora de Lima, America/Lima). La hora vigente está en GET /api/v1/integration/catalogs → order_cutoff ({"cutoff_time": "15:00", "timezone": "America/Lima"}; cutoff_time es null si no hay hora límite). GSG la puede cambiar: léela del catálogo, no la fijes en tu código.

• Hasta la hora límite inclusive (con 15:00: hasta las 15:00) el pedido para hoy entra normal. Desde el minuto siguiente (15:01) un pedido con date_route de hoy se registra igual, con after_cutoff: true: queda fuera de hora y GSG puede despacharlo el siguiente día hábil.
• Pedidos con fecha de otro día nunca quedan fuera de hora.
• Recomendado: pasada la hora límite, envía date_route con el día siguiente (los domingos no hay reparto: usa el lunes).

order_number: opcional; máximo 120 caracteres. Si no lo envías, GSG copia order_external_id (truncado a 120). Se muestra en el panel y en el detalle del pedido.

sede (obligatorio en tipo 4): nombre de la sede GSG: ATE, LOS OLIVOS o LA VICTORIA (no distingue mayúsculas). Un valor fuera de esa lista devuelve 400. Direcciones en GET /catalogs (sedes).

Agencia (tipo 2): identifica la agencia con una de estas opciones:

5.5 Apertura del paquete, cobro con POS y enlace de ubicación

Tres campos opcionales. Si no los envías, el pedido se registra igual que en la versión 1.2.

• Con latitude/longitude (ya aceptados), address puede ir como cadena vacía (""). El district sigue siendo obligatorio porque define la tarifa.
• Opciones y textos vigentes de la apertura: GET /catalogs → open_policy. Muestra esos textos en tu sistema en lugar de copiarlos.

6.Tamaños: courier (S/M) y GSG XL

El campo size (alias size_code) define el vehículo y la tarifa: S y M viajan en moto y pagan la tarifa courier del distrito; las categorías XL viajan en van (GSG XL) y pagan la tarifa de la zona del distrito por categoría y por bulto. El tamaño no cambia el tipo de ruta: un XL puede ser entrega, agencia, cambio, recojo en sede o flex.

Los límites son los vigentes al publicar esta página; los actuales siempre están en package_sizes[] del catálogo (max_weight_kg, max_side_cm, max_volume_m3).

• Clasificación automática ("size": "XL" + peso y medidas por bulto): GSG toma la primera categoría, de menor a mayor, cuyos tres límites se cumplen. 5 kg pero 85 cm de lado ⇒ XL_MAX; supera XL Max ⇒ 400 (Especial / Cargo, cotización manual con GSG). Si envías una categoría explícita y medidas, se aplica la mayor entre la pedida y la calculada.
• Con S o M puedes enviar weight_kg opcionalmente: si supera el máximo de moto ⇒ 400 El tamaño M viaja en moto y admite hasta 3 kg por bulto….
• XL es válido en los tipos 1, 2, 3, 4 y 7: en 1, 3, 7 (y agencia no partner) el precio es la tarifa de la zona del distrito; en agencia partner (Shalom/Olva/Marvisur) la tarifa XL fija de esa agencia; en recojo en sede GSG, la mitad de la tarifa XL de la zona Base. Siempre × number_packages.
• El precio XL es cerrado: no aplica el descuento del negocio ni el recargo de tamaño courier. Un convenio por empresa (BUSINESS_AGREEMENT_V1) sí lo sustituye.
• Si el distrito no tiene tarifa XL para esa categoría (districts[].xl es null o no incluye la categoría) → 400 con el motivo.
• Si el servicio XL está deshabilitado temporalmente por GSG → 400 size: el servicio GSG XL no está disponible por integración en este momento; use S o M. El catálogo lo anuncia en features.xl_enabled.

7.Matriz: qué es obligatorio según el validador

Si falta cualquiera de estos campos (cuando aplican), la API responde 400 con un mensaje que indica exactamente qué corregir (varios errores se concatenan con ". "). Toda la validación, incluida la que necesita base de datos (cobertura, agencia, tarifa XL), ocurre antes de reservar el order_external_id.

Obligatorios en todos los tipos de ruta

Obligatorios según el tipo de ruta

* El validador no lo exige, pero sin address el motorizado no puede entregar: envíalo siempre en los tipos 1, 3 y 7 (y en "otra agencia" como dirección del destinatario final si aplica). Si envías latitude/longitude, address puede ir vacío (""); aun así ayuda al motorizado (número, Mz/Lt, dpto.).

• Recomendado en pedidos con dirección (1, 3, 7): address, address_reference, number_packages, size, más cost y advance.
• Tipo 2: el servidor fuerza client_pays_delivery = 0. Si envías partner por agency_name (p. ej. "Shalom"), district sigue siendo obligatorio por validador aunque GSG lo reemplace por su sede; por eso recomendamos agency_code.
• Tipo 4: no requiere address ni district; el servidor los fija según la sede.

8.Límites de longitud y formatos

Un valor más largo devuelve 400 <campo> supera el máximo de N caracteres (no se trunca). Estos límites también se publican en GET /catalogs → limits.

9.Ejemplos JSON por tipo

Cabeceras típicas en todos: X-API-Key (o Authorization), X-Store-Token (plataformas), Idempotency-Key. Si el token va en cabecera, omite store_token del body.

9.1 Tipo 1 — Entrega a domicilio (courier), modo detallado

Incluye los campos opcionales de la versión 1.3 (§ 5.5): el destinatario puede abrir y revisar el producto antes de pagar (open_policy: "INSPECT"), el saldo con tarjeta ya incluye el 5% del POS (pos_fee_included: 1) y la ubicación llega como enlace (url_maps). Si no los necesitas, omítelos.

{
  "order_external_id": "ORD-2026-778291",

  "route_type": 1,
  "full_name": "María López Sánchez",
  "telephone": "987654322",
  "other_telephone": "987654323",
  "address": "Jr. Los Olivos 456",
  "address_reference": "Cerca al parque central",
  "district": "MIRAFLORES",
  "number_document": "40123456",
  "observation": "Producto frágil, manejar con cuidado",

  "date_route": "16-01-2026 14:30",
  "code_pay_method": "TARJETA",
  "cost": "500.00",
  "advance": "200.00",

  "product": "Laptop HP",
  "product_detail": "Modelo HP Pavilion 15, color plateado",
  "number_packages": 1,
  "size": "M",
  "pay_comments": "Cliente pagó adelanto con tarjeta, saldo pendiente",
  "client_pays_delivery": 1,

  "open_policy": "INSPECT",
  "pos_fee_included": 1,
  "url_maps": "https://maps.app.goo.gl/Xk4bQ2mNcP8vRt7w9"
}

9.2 Tipo 1 — Entrega a domicilio con tamaño GSG XL

Solo cambia size. El precio sale de la zona del distrito (districts[].xl.XL_PLUS en el catálogo) × bultos. Si prefieres que GSG elija la categoría, reemplaza la última línea por "size": "XL", "weight_kg": 12, "width_cm": 58, "height_cm": 55, "depth_cm": 40 (medidas por bulto): la respuesta trae en size_code la categoría asignada.

{
  "order_external_id": "ORD-2026-778295",

  "route_type": 1,
  "full_name": "Carla Ruiz Paredes",
  "telephone": "987111222",
  "address": "Av. Benavides 1890, Dpto. 402",
  "address_reference": "Edificio con fachada blanca, frente a farmacia",
  "district": "MIRAFLORES",

  "date_route": "04-09-2026 10:30",
  "code_pay_method": "PAGADO",
  "cost": "0",
  "advance": "0",

  "product": "Silla de oficina ergonómica",
  "product_detail": "Caja 58 x 55 x 40 cm, 12 kg",
  "number_packages": 1,
  "size": "XL_PLUS"
}

9.3 Tipo 2 — Agencia partner por agency_code (recomendado)

Sin district, destination_address ni telephone: GSG traslada el paquete a la sucursal de Shalom. agency_branch_id es opcional (ver agencies[].branches en el catálogo). Con package_registered: 0 GSG registra el envío en la agencia y lo cobra como recargo.

{
  "order_external_id": "ORD-2026-778292",

  "route_type": 2,
  "agency_code": "SHALOM",
  "agency_branch_id": 3,
  "full_name": "Ana Martínez Quispe",
  "number_document": "87654321",
  "pay_at_destination": 1,
  "package_registered": 0,
  "package_labeled": 1,
  "destination_address": "Arequipa / Arequipa / Arequipa",

  "date_route": "18-01-2026 09:00",
  "code_pay_method": "TRANSFERENCIA",
  "cost": "300.00",
  "advance": "100.00",

  "product": "Ropa y accesorios",
  "product_detail": "3 polos, 2 pantalones, 1 par de zapatos",
  "number_packages": 2,
  "size": "L",
  "pay_comments": "Adelanto transferido, saldo se cobrará en destino",
  "observation": "Verificar estado de los productos antes de enviar"
}

9.4 Tipo 2 — Otra agencia por agency_name

El nombre no coincide con ningún alias del catálogo, así que se registra como "Otra agencia". GSG lleva el paquete a la dirección de la agencia en Lima (destination_address + district, ambos obligatorios). El mismo resultado se obtiene con "agency_code": "OTHER" más agency_name.

{
  "order_external_id": "ORD-2026-778296",

  "route_type": 2,
  "agency_name": "Transportes Cruz del Sur Cargo",
  "destination_address": "Av. Javier Prado Este 1155 (agencia Cruz del Sur Cargo)",
  "district": "LA VICTORIA",
  "full_name": "Luis Fernández Rojas",
  "number_document": "45678912",
  "pay_at_destination": 0,

  "date_route": "18-01-2026 09:00",
  "code_pay_method": "PAGADO",
  "cost": "0",
  "advance": "0",

  "product": "Repuestos automotrices",
  "number_packages": 1,
  "size": "M",
  "observation": "Entregar en ventanilla de encomiendas a nombre del destinatario"
}

9.5 Tipo 3 — Cambio

Debe incluir number_packages_in ≥ 1 (bultos que se recogen para el cambio).

{
  "order_external_id": "ORD-2026-778293",

  "route_type": 3,
  "full_name": "Pedro Gómez",
  "telephone": "987654328",
  "other_telephone": "987654329",
  "address": "Jr. Lima 147",
  "address_reference": "Segundo piso, departamento 201",
  "district": "BREÑA",

  "date_route": "20-01-2026 15:30",
  "code_pay_method": "YAPE",
  "cost": "180.00",
  "advance": "50.00",

  "product": "Camisa para cambio",
  "product_detail": "Camisa manga larga, color azul, talla M",
  "number_packages": 1,
  "number_packages_in": 2,
  "size": "S",
  "pay_comments": "Adelanto pagado por YAPE",
  "observation": "Recoger 2 camisas y entregar 1 camisa nueva"
}

9.6 Tipo 4 — Recojo en sede GSG

sede es el nombre de la sede: ATE, LOS OLIVOS o LA VICTORIA. Sin address/district: el servidor los completa con la dirección de la sede. Para PAGADO usa cost y advance en 0.

{
  "order_external_id": "ORD-2026-778294",

  "route_type": 4,
  "full_name": "Roberto Silva",
  "telephone": "987654331",
  "other_telephone": "987654332",
  "sede": "LOS OLIVOS",

  "date_route": "22-01-2026 14:00",
  "code_pay_method": "EFECTIVO",
  "cost": "450.00",
  "advance": "0.00",

  "product": "Paquete con productos electrónicos",
  "product_detail": "1 tablet, 2 auriculares, 1 cargador",
  "number_packages": 1,
  "size": "M",
  "pay_comments": "Cliente pagará al recoger",
  "observation": "Verificar identidad del cliente al recoger"
}

9.7 Tipo 7 — Entrega Flex

Mismo cuerpo que el tipo 1 (dirección, distrito, contacto, cost/advance). No hay campos extra por validador; mantén coherencia con tu operación de última milla.

{
  "order_external_id": "ML-2000012345678",

  "route_type": 7,
  "full_name": "Diana Torres Vega",
  "telephone": "987222333",
  "address": "Calle Los Cedros 250",
  "address_reference": "Casa de dos pisos, portón negro",
  "district": "SAN BORJA",
  "latitude": -12.0985,
  "longitude": -77.0012,

  "date_route": "05-09-2026 08:00",
  "code_pay_method": "PAGADO",
  "cost": "0",
  "advance": "0",

  "product": "Zapatillas running talla 40",
  "number_packages": 1,
  "size": "S",
  "order_number": "2000012345678"
}

9.8 Modo simple (opcional, no prioritario)

Alternativa al detallado: un solo campo pay_amount_simple (string o número) con el monto a cobrar, cuando code_pay_method no es PAGADO. No mezcles con cost/advance si quieres que prevalezca el detallado: vacía pay_amount_simple o no lo envíes.

9.9 Referencia rápida de campos comunes

10.Idempotencia y order_external_id

• Cada combinación tienda + order_external_id corresponde a un solo pedido en GSG. Si repites el mismo order_external_id con el mismo contenido (mismo hash interno), obtienes de nuevo la misma respuesta exitosa almacenada (replay, HTTP 200), incluidos los campos nuevos de la respuesta.
• El hash se calcula sobre el JSON después de normalizar (mayúsculas en code_pay_method/size/district/sede, trim de los obligatorios), pero es sensible al tipo JSON y a la caja de los campos no normalizados (agency_code, agency_name, package_registered, package_labeled, open_policy, pos_fee_included y url_maps entran tal como llegan): "cost": "500.00" y "cost": 500.00 producen hashes distintos → 409. Para reintentar, reenvía el mismo JSON byte a byte.
• order_external_id se compara sin distinguir mayúsculas: ORD-1 y ord-1 apuntan al mismo pedido (si el contenido difiere, 409). Usa siempre la misma caja.
• Si repites el mismo order_external_id con un pedido ya procesado pero cambias campos → 409 order_external_id ya fue usado con otro contenido; use otro id o reenvíe el mismo cuerpo.
• Si envías la misma Idempotency-Key para otro order_external_id ya procesado o en proceso → 409. Si el intento anterior con esa clave falló, la clave se libera automáticamente y el nuevo pedido se registra.
• Mientras un registro está en proceso, otra petición equivalente recibe 409 Este pedido se está procesando; espere y reintente con el mismo payload. Si el proceso quedó interrumpido (reinicio del servidor), el estado "en proceso" expira a los 5 minutos y el reintento lo retoma.
• Regla v2 — un intento fallido nunca bloquea: si un intento previo terminó en error (400 tardío o 5xx), el order_external_id queda libre. Reenvía con el contenido corregido (misma o nueva Idempotency-Key) y el registro se ejecuta; nada quedó a medias (la creación es transaccional).
• Los errores de validación (400) —incluidos los que requieren base de datos (cobertura, agencia, tarifa XL)— se detectan antes de reservar el order_external_id: corrige y reenvía con el mismo id.
• Garantía anti-duplicado: el pedido y su marca de idempotencia se confirman en una sola transacción. No existe ningún escenario (crash, reinicio, timeout) en el que el pedido quede creado sin su marca: si tu reintento reejecuta el registro es porque nada persistió; si el pedido existe, obtienes el replay. Reintentar nunca produce pedidos duplicados.

Recomendación: usa siempre la cabecera Idempotency-Key única por intento lógico (p. ej. UUID) y reintenta con la misma clave si hay timeout de red.

11.Respuestas exitosas

11.1 HTTP 200 — Pedido registrado

{
  "message": { "description": "Ok", "title": "OK OK", "code": "90200" },
  "data": {
    "order_external_id": "ORD-2026-778295",
    "message": "Pedido guardado exitosamente",
    "id_route": 231472,
    "id_route_type": 1,
    "code_tracking": "GSG-E-231472",
    "route_type_code": "DELIVERY",
    "size_code": "XL_PLUS",
    "service": "XL",
    "date_route": "2026-09-04 10:30:00",
    "after_cutoff": false,
    "status": { "id": 3, "code": "REGISTRADO", "name": "REGISTRADO", "final": false },
    "service_cost": {
      "currency": "PEN",
      "total": 28,
      "base_cost": 28,
      "package_extra_cost": 0,
      "agency_handling_cost": 0,
      "agency_registration_cost": 0,
      "agency_labeling_cost": 0,
      "pricing_rule": "XL_ZONE_TARIFF_V1"
    },
    "tracking_url": null,
    "open_policy": "SEALED"
  }
}

11.2 HTTP 200 — Replay idempotente

Si el pedido ya fue procesado correctamente con el mismo order_external_id y el mismo cuerpo, la respuesta es igual a la almacenada la primera vez (misma estructura que arriba, incluidos los campos nuevos si el pedido se registró con esta versión).

11.3 HTTP 200 — Caso marginal sin cuerpo guardado

En situaciones excepcionales podría devolverse un objeto mínimo { "replay": true, "route_id": 231472 }; no es el flujo normal tras un registro completo.

12.Errores (referencia)

Todas las respuestas de error siguen el patrón (sin data):

{
  "message": {
    "description": "Texto explicativo",
    "title": "Error | Unauthorized Error | Too Many Requests | Error Server",
    "code": "90400 | 90401 | 90409 | 90429 | 90500"
  }
}

La tabla consolidada de todos los endpoints está en Referencia de errores. Resumen para el registro:

12.1 HTTP 401 — Autenticación / credenciales

Un fallo interno al validar credenciales (p. ej. base de datos caída) responde 500 Error validando credenciales de integración, no 401. Un 401 siempre significa que las credenciales enviadas son inválidas.

12.2 HTTP 400 — Validación de negocio / payload

12.3 HTTP 409 — Conflictos / idempotencia

12.4 HTTP 429 — Rate limit

Dos límites: por cliente de integración (Demasiadas peticiones: máximo 300 por minuto por cliente de integración. Espere y reintente con backoff., evaluado tras autenticar con tu API key) y por IP (Demasiadas peticiones desde esta IP; espere y reintente con backoff, 900/min, evaluado antes de autenticar). Revisa las cabeceras RateLimit / RateLimit-Policy. Detalle en Guía de inicio § 7.

12.5 HTTP 500 — Error de servidor

Los 500 llevan siempre un texto fijo; el detalle interno del servidor nunca se expone al integrador.

Ante un 500 puedes reintentar con el mismo order_external_id y el mismo cuerpo: nada quedó registrado a medias.

12.6 Reintento tras un fallo previo

• 400: el id queda libre; corrige los datos y reenvía con el mismo order_external_id. Reenviar el mismo contenido inválido devuelve el mismo 400.
• 5xx: reintenta con el mismo cuerpo; el registro se reejecuta. No se devuelve el error almacenado.

13.Ejemplo curl (tipo 1, modo detallado)

curl -X POST "https://{BASE_URL}/api/v1/orders/integration" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gsg_PREFIJO_SECRETO_COMPLETO" \
  -H "X-Store-Token: st_TOKEN_DE_TIENDA" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "order_external_id": "PED-2026-0001",
    "route_type": 1,
    "full_name": "María Pérez",
    "telephone": "987654321",
    "address": "Av. Ejemplo 123",
    "address_reference": "Frente al parque",
    "district": "MIRAFLORES",
    "date_route": "04-09-2026 10:30",
    "code_pay_method": "EFECTIVO",
    "cost": "150.00",
    "advance": "0.00",
    "product": "Pedido ecommerce",
    "number_packages": 1,
    "size": "S"
  }'

Integración directa: omite -H "X-Store-Token: …".

14.Buenas prácticas para el integrador

1. Guarda la API key en un vault o variables de entorno; nunca en repositorios ni frontends.
2. Por tienda, guarda el store_token de forma segura (o que el negocio lo pegue en su panel privado).
3. Cotiza antes de registrar con POST /quote si tu flujo muestra el costo de envío al negocio, y valida distritos y agencias contra GET /catalogs (cacheado 5 min).
4. Reintentos con backoff ante 409 "en proceso", 429 o errores de red, siempre con la misma Idempotency-Key.
5. Registra order_external_id, id_route, code_tracking y service_cost.total devueltos para trazabilidad, conciliación y soporte.
6. Usa siempre HTTPS y valida certificados en producción.
7. Para el estado del pedido, webhooks primero y consulta por API como respaldo.
8. Tolera campos nuevos en las respuestas: el contrato crece de forma aditiva.
9. Respeta la hora límite del día (GET /catalogs → order_cutoff): después de esa hora propone al negocio la fecha del día siguiente y avísale si un pedido volvió con after_cutoff: true.

15.Contacto

Para URL base de producción, ambiente de pruebas, ampliación de tipos de ruta o dudas de negocio, coordina con GSG (integraciones directas: desde el panel; plataformas: con el administrador de integraciones que entregó la API key). Esta documentación describe el comportamiento técnico del endpoint implementado.

16.Historial de cambios