{
  "info": {
    "name": "GSG Corp — API de integración (v1.3)",
    "_postman_id": "8f3c2a1e-6b7d-4c9a-9e21-20260903a1b2",
    "description": "Colección para integradores de GSG Courier (Perú). Variables: base_url (URL base que indica GSG, sin barra final), api_key (gsg_<prefijo>_<secreto>), store_token (st_…; obligatorio para plataformas multi-tienda, opcional en integración directa; envíalo siempre con la misma caja), order_external_id (usa siempre la misma caja: la comparación no distingue mayúsculas). Documentación: https://business.gsgcorp.pe/documentacion_publica/ . Versión de la colección: 1.3 (2026-09-25: el registro tipo 1 incluye los campos opcionales open_policy, pos_fee_included y url_maps; 2026-09-15: alias POST /api/v1/integration/orders y ejemplo XL automático por peso/medidas; 2026-09-03: X-Store-Token deshabilitado por defecto en /me y /catalogs).",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "base_url", "value": "https://API_BASE_URL_QUE_INDIQUE_GSG", "type": "string" },
    { "key": "api_key", "value": "gsg_PREFIJO_SECRETO", "type": "string" },
    { "key": "store_token", "value": "st_TOKEN_DE_TIENDA", "type": "string" },
    { "key": "order_external_id", "value": "PED-DEMO-0001", "type": "string" },
    { "key": "code_tracking", "value": "GSG-E-231472", "type": "string" }
  ],
  "auth": {
    "type": "apikey",
    "apikey": [
      { "key": "key", "value": "X-API-Key", "type": "string" },
      { "key": "value", "value": "{{api_key}}", "type": "string" },
      { "key": "in", "value": "header", "type": "string" }
    ]
  },
  "event": [
    {
      "listen": "prerequest",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// Idempotency-Key única por intento (solo la usa el registro de pedidos).",
          "pm.variables.set('idempotency_key', (typeof crypto !== 'undefined' && crypto.randomUUID) ? crypto.randomUUID() : String(Date.now()) + '-' + Math.random().toString(16).slice(2));"
        ]
      }
    }
  ],
  "item": [
    {
      "name": "1. Conexión y catálogos",
      "item": [
        {
          "name": "GET /me — verificar credenciales",
          "request": {
            "method": "GET",
            "header": [
              { "key": "X-Store-Token", "value": "{{store_token}}", "disabled": true, "description": "Actívalo solo si eres plataforma (o quieres ver la tienda); con un valor inválido responde 401 'store_token no vinculado a esta API key'. Obligatorio solo en endpoints con alcance de tienda para plataformas." }
            ],
            "url": { "raw": "{{base_url}}/api/v1/integration/me", "host": ["{{base_url}}"], "path": ["api", "v1", "integration", "me"] },
            "description": "Devuelve api_version, integration_client, api_key.prefix, store (si hay tienda), webhook, rate_limit y docs_url."
          },
          "response": []
        },
        {
          "name": "GET /catalogs — catálogos y tarifas",
          "request": {
            "method": "GET",
            "header": [
              { "key": "X-Store-Token", "value": "{{store_token}}", "disabled": true, "description": "Actívalo solo si eres plataforma (o quieres ver la tienda: your_courier_cost con descuento y business); con un valor inválido responde 401." }
            ],
            "url": { "raw": "{{base_url}}/api/v1/integration/catalogs", "host": ["{{base_url}}"], "path": ["api", "v1", "integration", "catalogs"] },
            "description": "route_types, package_sizes (S/M/L + XL), districts (courier_cost, your_courier_cost, xl), sedes, agencies (aliases, branches), payment_methods, states, logistic_states, limits, business. Cache 5 min."
          },
          "response": []
        },
        {
          "name": "POST /quote — cotizar entrega XL",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-Store-Token", "value": "{{store_token}}" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"route_type\": 1,\n  \"district\": \"MIRAFLORES\",\n  \"size\": \"XL_PLUS\"\n}"
            },
            "url": { "raw": "{{base_url}}/api/v1/integration/quote", "host": ["{{base_url}}"], "path": ["api", "v1", "integration", "quote"] },
            "description": "Cotización con la tarifa real del negocio. Mismos campos de precio que el pedido (route_type, district, size, sede, agency_*, package_registered, package_labeled). No exige number_packages_in."
          },
          "response": []
        },
        {
          "name": "POST /quote — cotizar agencia partner",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-Store-Token", "value": "{{store_token}}" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"route_type\": 2,\n  \"agency_code\": \"SHALOM\",\n  \"size\": \"M\",\n  \"package_registered\": 0,\n  \"package_labeled\": 1\n}"
            },
            "url": { "raw": "{{base_url}}/api/v1/integration/quote", "host": ["{{base_url}}"], "path": ["api", "v1", "integration", "quote"] }
          },
          "response": []
        }
      ]
    },
    {
      "name": "2. Registrar pedidos (POST /api/v1/integration/orders · alias /api/v1/orders/integration)",
      "item": [
        {
          "name": "Tipo 1 — Entrega a domicilio (courier)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-Store-Token", "value": "{{store_token}}" },
              { "key": "Idempotency-Key", "value": "{{idempotency_key}}" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"order_external_id\": \"{{order_external_id}}\",\n  \"route_type\": 1,\n  \"full_name\": \"María López Sánchez\",\n  \"telephone\": \"987654322\",\n  \"other_telephone\": \"987654323\",\n  \"address\": \"Jr. Los Olivos 456\",\n  \"address_reference\": \"Cerca al parque central\",\n  \"district\": \"MIRAFLORES\",\n  \"number_document\": \"40123456\",\n  \"observation\": \"Producto frágil, manejar con cuidado\",\n  \"date_route\": \"16-01-2027 14:30\",\n  \"code_pay_method\": \"TARJETA\",\n  \"cost\": \"500.00\",\n  \"advance\": \"200.00\",\n  \"product\": \"Laptop HP\",\n  \"product_detail\": \"Modelo HP Pavilion 15, color plateado\",\n  \"number_packages\": 1,\n  \"size\": \"M\",\n  \"pay_comments\": \"Cliente pagó adelanto con tarjeta, saldo pendiente\",\n  \"client_pays_delivery\": 1,\n  \"open_policy\": \"INSPECT\",\n  \"pos_fee_included\": 1,\n  \"url_maps\": \"https://maps.app.goo.gl/Xk4bQ2mNcP8vRt7w9\"\n}"
            },
            "url": { "raw": "{{base_url}}/api/v1/orders/integration", "host": ["{{base_url}}"], "path": ["api", "v1", "orders", "integration"] },
            "description": "Cambia order_external_id en cada prueba (o reenvía el mismo cuerpo para ver el replay 200; cambia un campo para ver el 409). open_policy, pos_fee_included y url_maps son opcionales (v1.3): quítalos si no los usas."
          },
          "response": []
        },
        {
          "name": "Tipo 1 — Entrega con tamaño GSG XL",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-Store-Token", "value": "{{store_token}}" },
              { "key": "Idempotency-Key", "value": "{{idempotency_key}}" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"order_external_id\": \"{{order_external_id}}-XL\",\n  \"route_type\": 1,\n  \"full_name\": \"Carla Ruiz Paredes\",\n  \"telephone\": \"987111222\",\n  \"address\": \"Av. Benavides 1890, Dpto. 402\",\n  \"address_reference\": \"Edificio con fachada blanca, frente a farmacia\",\n  \"district\": \"MIRAFLORES\",\n  \"date_route\": \"16-01-2027 10:30\",\n  \"code_pay_method\": \"PAGADO\",\n  \"cost\": \"0\",\n  \"advance\": \"0\",\n  \"product\": \"Silla de oficina ergonómica\",\n  \"product_detail\": \"Caja 58 x 55 x 40 cm, 12 kg\",\n  \"number_packages\": 1,\n  \"size\": \"XL_PLUS\"\n}"
            },
            "url": { "raw": "{{base_url}}/api/v1/orders/integration", "host": ["{{base_url}}"], "path": ["api", "v1", "orders", "integration"] }
          },
          "response": []
        },
        {
          "name": "Tipo 1 — XL automático por peso y medidas (alias /api/v1/integration/orders)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-Store-Token", "value": "{{store_token}}" },
              { "key": "Idempotency-Key", "value": "{{idempotency_key}}" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"order_external_id\": \"{{order_external_id}}-XLAUTO\",\n  \"route_type\": 1,\n  \"full_name\": \"Carla Ruiz Paredes\",\n  \"telephone\": \"987111222\",\n  \"address\": \"Av. Benavides 1890, Dpto. 402\",\n  \"address_reference\": \"Edificio con fachada blanca, frente a farmacia\",\n  \"district\": \"MIRAFLORES\",\n  \"date_route\": \"16-01-2027 10:30\",\n  \"code_pay_method\": \"PAGADO\",\n  \"cost\": \"0\",\n  \"advance\": \"0\",\n  \"product\": \"Silla de oficina ergonómica\",\n  \"product_detail\": \"Caja 58 x 55 x 40 cm, 12 kg\",\n  \"number_packages\": 1,\n  \"size\": \"XL\",\n  \"weight_kg\": 12,\n  \"width_cm\": 58,\n  \"height_cm\": 55,\n  \"depth_cm\": 40\n}"
            },
            "url": { "raw": "{{base_url}}/api/v1/integration/orders", "host": ["{{base_url}}"], "path": ["api", "v1", "integration", "orders"] }
          },
          "response": []
        },
        {
          "name": "Tipo 2 — Agencia partner por agency_code",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-Store-Token", "value": "{{store_token}}" },
              { "key": "Idempotency-Key", "value": "{{idempotency_key}}" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"order_external_id\": \"{{order_external_id}}-AGP\",\n  \"route_type\": 2,\n  \"agency_code\": \"SHALOM\",\n  \"full_name\": \"Ana Martínez Quispe\",\n  \"number_document\": \"87654321\",\n  \"pay_at_destination\": 1,\n  \"package_registered\": 0,\n  \"package_labeled\": 1,\n  \"destination_address\": \"Arequipa / Arequipa / Arequipa\",\n  \"date_route\": \"18-01-2027 09:00\",\n  \"code_pay_method\": \"TRANSFERENCIA\",\n  \"cost\": \"300.00\",\n  \"advance\": \"100.00\",\n  \"product\": \"Ropa y accesorios\",\n  \"product_detail\": \"3 polos, 2 pantalones, 1 par de zapatos\",\n  \"number_packages\": 2,\n  \"size\": \"L\",\n  \"pay_comments\": \"Adelanto transferido, saldo se cobrará en destino\"\n}"
            },
            "url": { "raw": "{{base_url}}/api/v1/orders/integration", "host": ["{{base_url}}"], "path": ["api", "v1", "orders", "integration"] },
            "description": "Partner: sin district, destination_address ni telephone obligatorios. Agrega agency_branch_id (agencies[].branches[].id del catálogo) si quieres una sucursal concreta."
          },
          "response": []
        },
        {
          "name": "Tipo 2 — Otra agencia por agency_name",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-Store-Token", "value": "{{store_token}}" },
              { "key": "Idempotency-Key", "value": "{{idempotency_key}}" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"order_external_id\": \"{{order_external_id}}-AGO\",\n  \"route_type\": 2,\n  \"agency_name\": \"Transportes Cruz del Sur Cargo\",\n  \"destination_address\": \"Av. Javier Prado Este 1155 (agencia Cruz del Sur Cargo)\",\n  \"district\": \"LA VICTORIA\",\n  \"full_name\": \"Luis Fernández Rojas\",\n  \"number_document\": \"45678912\",\n  \"pay_at_destination\": 0,\n  \"date_route\": \"18-01-2027 09:00\",\n  \"code_pay_method\": \"PAGADO\",\n  \"cost\": \"0\",\n  \"advance\": \"0\",\n  \"product\": \"Repuestos automotrices\",\n  \"number_packages\": 1,\n  \"size\": \"M\",\n  \"observation\": \"Entregar en ventanilla de encomiendas a nombre del destinatario\"\n}"
            },
            "url": { "raw": "{{base_url}}/api/v1/orders/integration", "host": ["{{base_url}}"], "path": ["api", "v1", "orders", "integration"] },
            "description": "Nombre desconocido para el catálogo → 'Otra agencia': district y destination_address obligatorios."
          },
          "response": []
        },
        {
          "name": "Tipo 3 — Cambio",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-Store-Token", "value": "{{store_token}}" },
              { "key": "Idempotency-Key", "value": "{{idempotency_key}}" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"order_external_id\": \"{{order_external_id}}-CAM\",\n  \"route_type\": 3,\n  \"full_name\": \"Pedro Gómez\",\n  \"telephone\": \"987654328\",\n  \"address\": \"Jr. Lima 147\",\n  \"address_reference\": \"Segundo piso, departamento 201\",\n  \"district\": \"BREÑA\",\n  \"date_route\": \"20-01-2027 15:30\",\n  \"code_pay_method\": \"YAPE\",\n  \"cost\": \"180.00\",\n  \"advance\": \"50.00\",\n  \"product\": \"Camisa para cambio\",\n  \"product_detail\": \"Camisa manga larga, color azul, talla M\",\n  \"number_packages\": 1,\n  \"number_packages_in\": 2,\n  \"size\": \"S\",\n  \"observation\": \"Recoger 2 camisas y entregar 1 camisa nueva\"\n}"
            },
            "url": { "raw": "{{base_url}}/api/v1/orders/integration", "host": ["{{base_url}}"], "path": ["api", "v1", "orders", "integration"] }
          },
          "response": []
        },
        {
          "name": "Tipo 4 — Recojo en sede GSG",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-Store-Token", "value": "{{store_token}}" },
              { "key": "Idempotency-Key", "value": "{{idempotency_key}}" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"order_external_id\": \"{{order_external_id}}-REC\",\n  \"route_type\": 4,\n  \"full_name\": \"Roberto Silva\",\n  \"telephone\": \"987654331\",\n  \"sede\": \"LOS OLIVOS\",\n  \"date_route\": \"22-01-2027 14:00\",\n  \"code_pay_method\": \"EFECTIVO\",\n  \"cost\": \"450.00\",\n  \"advance\": \"0.00\",\n  \"product\": \"Paquete con productos electrónicos\",\n  \"product_detail\": \"1 tablet, 2 auriculares, 1 cargador\",\n  \"number_packages\": 1,\n  \"size\": \"M\",\n  \"observation\": \"Verificar identidad del cliente al recoger\"\n}"
            },
            "url": { "raw": "{{base_url}}/api/v1/orders/integration", "host": ["{{base_url}}"], "path": ["api", "v1", "orders", "integration"] },
            "description": "sede: ATE | LOS OLIVOS | LA VICTORIA. address y district los fija la sede."
          },
          "response": []
        },
        {
          "name": "Tipo 7 — Entrega Flex",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-Store-Token", "value": "{{store_token}}" },
              { "key": "Idempotency-Key", "value": "{{idempotency_key}}" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"order_external_id\": \"{{order_external_id}}-FLX\",\n  \"route_type\": 7,\n  \"full_name\": \"Diana Torres Vega\",\n  \"telephone\": \"987222333\",\n  \"address\": \"Calle Los Cedros 250\",\n  \"address_reference\": \"Casa de dos pisos, portón negro\",\n  \"district\": \"SAN BORJA\",\n  \"latitude\": -12.0985,\n  \"longitude\": -77.0012,\n  \"date_route\": \"05-01-2027 08:00\",\n  \"code_pay_method\": \"PAGADO\",\n  \"cost\": \"0\",\n  \"advance\": \"0\",\n  \"product\": \"Zapatillas running talla 40\",\n  \"number_packages\": 1,\n  \"size\": \"S\",\n  \"order_number\": \"2000012345678\"\n}"
            },
            "url": { "raw": "{{base_url}}/api/v1/orders/integration", "host": ["{{base_url}}"], "path": ["api", "v1", "orders", "integration"] }
          },
          "response": []
        }
      ]
    },
    {
      "name": "3. Seguimiento y cancelación",
      "item": [
        {
          "name": "GET /orders/:orderExternalId — detalle",
          "request": {
            "method": "GET",
            "header": [
              { "key": "X-Store-Token", "value": "{{store_token}}" }
            ],
            "url": { "raw": "{{base_url}}/api/v1/integration/orders/{{order_external_id}}", "host": ["{{base_url}}"], "path": ["api", "v1", "integration", "orders", "{{order_external_id}}"] },
            "description": "Detalle completo: cabecera, recipient, agency, payment, current_state, logistic_state, timeline (fotos firmadas), payments, incidents, service_cost, cancellable, tracking_url."
          },
          "response": []
        },
        {
          "name": "GET /orders/tracking/:codeTracking — detalle por tracking",
          "request": {
            "method": "GET",
            "header": [
              { "key": "X-Store-Token", "value": "{{store_token}}" }
            ],
            "url": { "raw": "{{base_url}}/api/v1/integration/orders/tracking/{{code_tracking}}", "host": ["{{base_url}}"], "path": ["api", "v1", "integration", "orders", "tracking", "{{code_tracking}}"] },
            "description": "Acepta el code_tracking (GSG-E-231472) o el id_route numérico."
          },
          "response": []
        },
        {
          "name": "GET /orders — listado paginado",
          "request": {
            "method": "GET",
            "header": [
              { "key": "X-Store-Token", "value": "{{store_token}}" }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/integration/orders?from=2026-09-01&to=2026-09-03&page=1&limit=50",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "integration", "orders"],
              "query": [
                { "key": "from", "value": "2026-09-01", "description": "YYYY-MM-DD (default: to − 6 días)" },
                { "key": "to", "value": "2026-09-03", "description": "YYYY-MM-DD (default: hoy). Rango máx. 92 días" },
                { "key": "state", "value": "EN_RUTA", "description": "Opcional: code, nombre o id del estado", "disabled": true },
                { "key": "page", "value": "1" },
                { "key": "limit", "value": "50", "description": "1–100" }
              ]
            }
          },
          "response": []
        },
        {
          "name": "POST /orders/:orderExternalId/cancel — cancelar",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-Store-Token", "value": "{{store_token}}" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"reason\": \"El comprador anuló la compra\"\n}"
            },
            "url": { "raw": "{{base_url}}/api/v1/integration/orders/{{order_external_id}}/cancel", "host": ["{{base_url}}"], "path": ["api", "v1", "integration", "orders", "{{order_external_id}}", "cancel"] },
            "description": "Solo si el último estado es REGISTRADO o RECOJO_PENDIENTE, el ingreso sigue pendiente y el día no está liquidado → estado INACTIVO. Cualquier otro caso: 409 (ver seguimiento.html § 4)."
          },
          "response": []
        }
      ]
    },
    {
      "name": "4. Plataformas multi-tienda",
      "item": [
        {
          "name": "POST /api/integration/bindings/lookup — recuperar store_token",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"external_store_id\": \"ID_DE_LA_TIENDA_EN_TU_SISTEMA\"\n}"
            },
            "url": { "raw": "{{base_url}}/api/integration/bindings/lookup", "host": ["{{base_url}}"], "path": ["api", "integration", "bindings", "lookup"] },
            "description": "Solo API key. Devuelve store_token solo si el vínculo está activo. Rate limit 100/min por IP. No usar como polling."
          },
          "response": []
        }
      ]
    }
  ]
}