Obtener métodos de envío

1. Crear un Endpoint

Crear un API REST de tipo POST, este endpoint debe poder recibir tanto el body como un parámetro en su URL, donde el order_id será el Identificador de la orden.

POST https://your-host.com/getShippingMethods/{order_id} HTTP/1.1
Content-Type: application/json

Los datos que recibirá el endpoint getShippingMethods siempre tendrá la siguiente estructura, la cual llamaremos Address para más adelante referirnos a ella.

{
  "address1": "Quito, Ecuador",
  "first_name": "First Name",
  "last_name": "Last Name",
  "lat": -0.1806532,
  "lng": -78.4678382,
  "identity_document": "",
  "zipcode": "234234",
  "phone": "99999999999",
  "address2": "Quito, Ecuador",
  "state_name": "Pichincha",
  "country": "EC",
  "address_type": "home",
  "additional_description": "",
  "state_code": "PICHINCHA",
  "is_default": true,
  "is_billing_address": false,
  "city": "Quito",
  "is_default_address": true,
  "is_last_address": true,
  "created_at": "2022-06-27T15:51:17.941Z",
  "updated_at": "2022-06-27T15:51:17.941Z",
  "country_iso": "EC"
}

Obtén más información de Address y cada uno de sus parámetros.
Con los datos de Address puedes obtener información de la dirección donde se tendrá que entregar los artículos al cliente y según sea la ubicación puedas retornar una lista de métodos de envíos con sus respectivos costos.

🚧

NOTA:

Antes que avancemos tenemos que recordarte que al momento de tokenizar una orden en tu servidor debes guardar en tu base de datos tanto el token como el orderId para luego ser usado.

2. Obtener la orden tokenizada

Obtener el token de la orden previamente almacenado en tu base de datos mediante el order_id que es enviado como parámetro en la URL de tu Merchant API, con el token se debe realizar una petición al servidor para obtener la orden tokenizada.

3. Obtener los métodos de envío

Los *shipping_methods o métodos de envío corresponden a las tarifas de envíos que dispone tu comercio dependiendo de la ubicación indicada por el usuario dentro de Address.
Los shipping_methods deben mantener la siguiente estructura siempre.

"shipping_methods": [
    {
      "code": "100B2",
      "name": "Simple",
      "min_delivery_date": "",
      "max_delivery_date": "",
      "cost": 250,
      "tax_amount": 0,
      "scheduler": []
    }
  ]

Información de cada uno de los atributos de un ShippingMethod:

4. Editar precios de la orden

Edita los atributos de la orden según los respectivos cálculos tomando los valores del primer ShippingMethod de la lista obtenida en el punto 3.

📘

UN PEQUENO EJEMPLO

Pepe tiene un comercio y su cliente a quien llamaremos Juan tiene seleccionado los siguientes productos:

1 Papa Fritas con valor unitario de $5.50.
2 Hamburguesa con valor unitario de $15.00.

Entonces el valor total de la orden será de $35.50.

Bien! ahora Juan tiene seleccionado como dirección de entregar En el paseo de San Miguel en algún lugar de México, para lo cual el comercio de Pepe determina dos métodos de envíos:

100B2 | Simple | $250
C10B2 | Premiun | $350

Juan se decide por el método Premiun de pago con código C10B2
los cambios en la orden serán los siguientes:

{
  "order": {
    "store_code": "STORE2B2",
    "tax_amount": 137,
    "shipping_amount": 250,
    "items_total_amount": 1144,
    "sub_total": 1007,
    "total_amount": 1394,
     ...
  },
  "token": "...",
  "shipping_methods": [
    {
      code: "100B2",  // Identificador del método de envío dentro del comercio.
      name: "Simple", // Nombre que aparecera en el checkout.
      cost: 250,      // Costo de envío.
      tax_amount: 40, // Impuesto del envío, si existe.
    },
    {
      code: "C10B2",
      name: "Premium",
      cost: 350,
      tax_amount: 960,
    },
	]
}

5. Respuesta del Endpoint

Una vez realizado los cálculos según el ShippingMethod se debe devolver la orden actualizada, el token, y la lista shipping_methods respetando la siguiente estructura.

{
  "order": {...},
  "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  "shipping_methods": [...]
}

6. Qué pasa si debo retornar un Error?

Si por algun motivo, sucede algun error en el proceso o no tenemos cobertura para la dirección seleccionada, debemos retornar una estructura de error con el siguiente formato:

{
  "code": "EM-4000", // error de cobertura
  "message": "no tenemos cobertura para la dirección seleccionada" // descripción de error
}

Los códigos de error disponibles para retorno son los siguientes: