Método de envío

Proporcioná tarifas de envío en tiempo real para los comerciantes. Al utilizar estos endpoint, podés agregar Método de envío a una tienda y proporcionar tarifas de envío al finalizar la compra.

aviso

Tené en cuenta que el cliente debe tener configurado el centro de distribución desde su panel en:
Configuraciones → Envíos y entrega → Centro de distribución.
Si no está configurado, los envíos pueden no figurar en la tienda del cliente.

Propiedades

Propiedad	Descripción
id	Identificador único
title	titulo para el Método de envío.
callback_url	El endpoint de URL que para recuperar las obtener las tarifas de envío.
types	Los tipos permitidos pueden ser uno o ambos: ship o pickup.
status	Si el Método de envío esta activo.
created_at	Fecha en la que se creó el Método de envío.
updated_at	Fecha en la que el Método de envío se actualizó por última vez.

Opciones de envío

La mayoría de los métodos de envío incluyen distintas opciones, como estándar y exprés. Desde el administrador de tu tienda vas a poder configurar cada una de ellas, definiendo costos adicionales o si el envío estará disponible de forma gratuita. Es necesario configurar al menos una opción para que el método de envío funcione correctamente.

Propiedades opciones de envio

Propiedad	Descripción
id	Identificador único
code	Codigo asociado con las opciones de envio
name	Nombre de la opcion de envio que lo ve el vendedor
description	Descripcion del envio que lo ve el comprador en el checkout
additional_cost	Costo adicional que se sumará al precio final de esta opción de envío.
allow_free_shipping	Disponibilidad de envío gratis para esta opción de envío.
status	Indica si esta opción está activa.
type	Tipo de envio que es ship o pickup
created_at	Fecha en la que se creó el Método de envío.
updated_at	Fecha en la que el Método de envío se actualizó por última vez.

Provisión de tarifas a nuestros comerciantes

Al agregar un método de envío a una tienda, tenés que configurar endpoints POST en las propiedades de callback, donde podamos consultar las tarifas de envío.

Soportamos distintos tipos de envío: envíos a domicilio (entrega en la dirección del comprador) o retiros en punto de entrega (recogida por el comprador).

La respuesta de tarifas debe ser un array JSON de objetos, con los siguientes campos. Todos los campos son obligatorios para que la integración funcione correctamente.

Propiedades de tarifas a nuestros comerciantes

Propiedad	Descripción
name	Nombre de la tarifa que el comprador verá en el checkout.
code	Código asociado a la opción de envío. Se usa para aplicar la configuración sobre la tarifa. Debe ser un string.
price	Precio de la tarifa que pagará el comprador.
currency	Moneda de la tarifa `ARG`.
type	Tipo de envío: `ship` (envío a domicilio) o `pickup` (retiro en punto).
min_delivery_date	Fecha mínima estimada de entrega en formato ISO 8601.
max_delivery_date	Fecha máxima estimada de entrega en formato ISO 8601.
description	Descripción que vera acento A() el vendedor en su panel.
address	Dirección del punto de retiro (solo para `pickup`). Incluye calle, número, piso, localidad, ciudad, provincia, país y código postal.

Cache TTL (Time to Live)

Success responses (status code 200) expira después de 15 minutos.
Error responses (status code 422) expira después de 1 minuto.
Las demás respuestas no se almacenan en caché.

Disyuntor para métodos de envío inestables

Con el objetivo de proteger la plataforma y evitar sobrecargar la URL de devolución de llamada de un método de envío cuando presenta problemas de disponibilidad, se implementa un disyuntor (Circuit Breaker).

El disyuntor monitorea continuamente el comportamiento de las solicitudes enviadas a cada método de envío y se activa cuando se cumplen las siguientes condiciones:

Se realizaron al menos 500 solicitudes al método de envío durante una ventana continua de 30 minutos.
Al menos el 50% de esas solicitudes fueron consideradas fallidas.

Se considera una solicitud fallida cuando ocurre alguno de los siguientes casos:

La URL responde con un código de estado HTTP 5xx.
La URL no responde dentro de los 5 segundos establecidos como tiempo máximo de espera.

Mientras el circuito permanece abierto, no se envían nuevas solicitudes al método de envío.

Después de 5 minutos, el circuito pasa al estado de prueba y permite nuevamente el envío de solicitudes para verificar si el servicio se recuperó.

Si durante este período se reciben al menos 10 solicitudes exitosas, el circuito vuelve al estado Closed y se reanudan las solicitudes normalmente.

Si alguna de estas solicitudes vuelve a fallar, el circuito regresa inmediatamente al estado Open y permanecerá bloqueado durante otros 5 minutos, repitiendo el proceso hasta que el servicio vuelva a estabilizarse.

Manejo de respuestas HTTP

La siguiente tabla resume cómo afecta cada tipo de respuesta al disyuntor y cuál es el comportamiento de la plataforma.

Escenario	Impacto en el disyuntor	Comportamiento
HTTP 2xx	Se considera una solicitud exitosa	Se muestran las opciones de envío devueltas por el método de envío.
HTTP 4xx	Se considera una solicitud exitosa	Se utilizan las opciones de Acordar con el vendedor.
HTTP 5xx	Se considera una solicitud fallida	Se utilizan las opciones de Acordar con el vendedor.
Tiempo de espera (> 5 segundos)	Se considera una solicitud fallida	Se utilizan las opciones de Acordar con el vendedor.
Circuito abierto (Open)	No se envía la solicitud al método de envío	Se utilizan directamente las opciones de Acordar con el vendedor.

Ejemplos de requests para métodos de envío

POST /tu_callback_url

{
  "store_id": 1,
  "currency": "ARS",
  "language": "es",
  "origin": {
    "name": "Sucursal Avellaneda",
    "address": "Av. M itre",
    "number": "123",
    "floor": null,
    "city": "Avellaneda",
    "locality": "Avellaneda",
    "province": "Buenos Aires",
    "country": "Argentina",
    "postal_code": "1874",
    "phone": "1126592870"
  },
  "destination": {
    "locality": "Villa Domínico",
    "province": "Buenos Aires",
    "country": "Argentina",
    "postal_code": 1870
  },
  "items": [
    {
      "id": 101,
      "name": "Remera básica",
      "hash": "remera-basica-001",
      "sku": "REM-001",
      "quantity": 2,
      "free_shipping": false,
      "grams": 250,
      "price": 2500,
      "dimensions": {
        "width": 30,
        "height": 2,
        "depth": 25
      }
    }
  ],
  "carrier": {
    "id": 7,
    "name": "Envíos Express",
    "options": [
      {
        "id": 34,
        "title": "Moto express zona sur",
        "code": "express_sur",
        "allow_free_shipping": false,
        "additional_cost": {
          "amount": 150,
          "currency": "ARS"
        },
        "adittional_days": 1
      },
      {
        "id": 43,
        "title": "Envío estándar",
        "code": "standard",
        "allow_free_shipping": true,
        "additional_cost": {
          "amount": 0,
          "currency": "ARS"
        },
        "adittional_days": 3
      }
    ]
  }
}

HTTP/1.1 200 OK

{
  "rates": [
    {
      "name": "Envío express en moto",
      "code": "express_moto",
      "price": 850,
      "currency": "ARS",
      "type": "ship",
      "min_delivery_date": "2026-06-24T12:00:00.000Z",
      "max_delivery_date": "2026-06-25T18:00:00.000Z"
    },
    {
      "name": "Sucursal Centro - Retiro",
      "code": "pickup_centro",
      "price": 250,
      "currency": "ARS",
      "type": "pickup",
      "description": "Retiro en sucursal del centro",
      "min_delivery_date": "2026-06-26T09:00:00-0300",
      "max_delivery_date": "2026-06-27T18:00:00-0300",
      "address": {
        "address": "Av. Corrientes",
        "number": "1200",
        "floor": "1",
        "locality": "San Nicolás",
        "city": "Buenos Aires",
        "province": "Buenos Aires",
        "country": "AR",
        "zipcode": "1043"
      }
    },
    {
      "name": "Sucursal Norte - Retiro",
      "code": "pickup_norte",
      "price": 250,
      "currency": "ARS",
      "type": "pickup",
      "description": "Retiro en punto zona norte",
      "min_delivery_date": "2026-06-27T10:00:00-0300",
      "max_delivery_date": "2026-06-28T14:00:00-0300",
      "address": {
        "address": "Av. Maipú",
        "number": "3200",
        "floor": null,
        "locality": "Olivos",
        "city": "Vicente López",
        "province": "Buenos Aires",
        "country": "AR",
        "zipcode": "1636"
      }
    }
  ]
}

Endpoints

POST /shipping-carriers

Propiedad	Descripción
id	Identificador único
title	titulo para el Método de envío.
callback_url	El endpoint de URL que para recuperar las obtener las tarifas de envío.
types	Los tipos permitidos pueden ser uno o ambos: ship o pickup.
status	Si el Método de envío esta activo.(tambien afecta el status de las opciones)

POST /shipping-carriers

{
  "title": "Compania de envío",
  "callback_url": "https://example.com/shipping",
  "types": "ship,pickup",
  "status": true
}

HTTP/1.1 201 Created

{
  "id": 14,
  "title": "Compania de envío",
  "callback_url": "https://example.com/shipping",
  "types": "ship,pickup",
  "status": 1,
  "created_at": "2026-06-23T18:29:13.000Z",
  "updated_at": null
}

GET /shipping-carriers

Parámetro	Explicación
ids	Lista de IDs separados por coma (max 30)
q	Buscar Productos que contengan el texto indicado en su título o sku
page	Página a mostrar
per_page	Cantidad de resultados

HTTP/1.1 200 OK

{
  "pagination": {
    "total": 1,
    "page": 1,
    "per_page": 10,
    "next_page": null
  },
  "results": [
    {
      "id": 14,
      "title": "Compania de envío",
      "callback_url": "https://example.com/shipping",
      "types": "ship,pickup",
      "status": 1,
      "created_at": "2026-06-23T18:29:13.000Z",
      "updated_at": null
    }
  ]
}

GET /shipping-carriers/`{id}`

HTTP/1.1 200 OK

{
  "id": 14,
  "title": "Compania de envío",
  "callback_url": "https://example.com/shipping",
  "types": "ship,pickup",
  "status": 1,
  "created_at": "2026-06-23T18:29:13.000Z",
  "updated_at": null
}

PUT /shipping-carriers/`{id}`

{
  "title": "Nueva compania de envío ",
  "types": "ship,pickup",
  "status": true
}

HTTP/1.1 200 OK

{
  "id": 14,
  "title": "Nueva compania de envío ",
  "types": "ship,pickup",
  "type": "ship",
  "callback_url": "https://example.com/shipping",
  "created_at": "2026-06-23T18:29:13.000Z",
  "updated_at": "2026-06-23T18:50:29.000Z"
}

DELETE /shipping-carriers/`{id}`

El detele utiliza un borrado logico

HTTP/1.1 200 OK

{
  "message": "Shipping carrier deleted successfully"
}

POST /shipping-carriers/`{carrierId}`/options

Parámetro	Explicación
id	Id del metodo de envio

{
  "code": "internacional",
  "name": "word internacional",
  "description": "Por todo el mundo",
  "additional_cost": 1250,
  "allow_free_shipping": false,
  "status": true,
  "type": "ship"
}

HTTP/1.1 201 Created

{
  "id": 45,
  "code": "internacional",
  "name": "word internacional",
  "description": "Por todo el mundo",
  "additional_cost": 1250,
  "allow_free_shipping": false,
  "status": true,
  "created_at": "2026-06-23T19:04:36.000Z"
}

GET /shipping-carriers/`{carrierId}`/options

Parámetro	Explicación
carrierId	Id del metodo de envio
ids	Lista de IDs separados por coma (max 30)
q	Buscar Productos que contengan el texto indicado en su título o sku
page	Página a mostrar
per_page	Cantidad de resultados

HTTP/1.1 200 OK

{
  "pagination": {
    "total": 3,
    "page": 1,
    "per_page": 10,
    "next_page": null
  },
  "results": [
    {
      "id": 45,
      "code": "internacional",
      "name": "word internacional",
      "description": "Por todo el mundo",
      "additional_cost": 1250,
      "allow_free_shipping": false,
      "status": true,
      "created_at": "2026-06-23T19:04:36.000Z",
      "updated_at": null
    }
  ]
}

GET /shipping-carriers/`{carrierId}`/options/`{optionId}`

Parámetro	Explicación
carrierId	Id del metodo de envio
optionId	Id de la opcio nde envio

HTTP/1.1 200 OK

{
  "id": 45,
  "code": "internacional",
  "name": "word internacional",
  "description": "Por todo el mundo",
  "additional_cost": 1250,
  "allow_free_shipping": false,
  "status": true,
  "created_at": "2026-06-23T19:04:36.000Z",
  "updated_at": null
}

PUT /shipping-carriers/`{carrierId}`/options/`{optionId}`

{
  "additional_cost": 1000,
  "allow_free_shipping": true
}

HTTP/1.1 200 OK

{
  "id": 45,
  "code": "internacional",
  "name": "word internacional",
  "description": "Por todo el mundo",
  "additional_cost": 1000,
  "allow_free_shipping": true,
  "status": true,
  "created_at": "2026-06-23T19:04:36.000Z",
  "updated_at": "2026-06-23T19:21:50.000Z"
}

DELETE /shipping-carriers/`{carrierId}`/options/`{optionId}`

El detele utiliza un borrado logico

HTTP/1.1 200 OK

{
  "message": "Shipping carrier option deleted successfully"
}

PUT /ordersas/`{id}`/shipping-status

Propiedad	Descripción
shipping_status	Estado del envío (unpacked, packaged, shipped, delivered)

{
  "shipping_status": "shipped"
}

Propiedades​

Opciones de envío​

Propiedades opciones de envio​

Provisión de tarifas a nuestros comerciantes​

Propiedades de tarifas a nuestros comerciantes​

Cache TTL (Time to Live)​

Disyuntor para métodos de envío inestables​

Manejo de respuestas HTTP​

Ejemplos de requests para métodos de envío​

POST /tu_callback_url​

Endpoints​

POST /shipping-carriers​

POST /shipping-carriers​

GET /shipping-carriers​

GET /shipping-carriers/{id}​

PUT /shipping-carriers/{id}​

DELETE /shipping-carriers/{id}​

POST /shipping-carriers/{carrierId}/options​

GET /shipping-carriers/{carrierId}/options​

GET /shipping-carriers/{carrierId}/options/{optionId}​

PUT /shipping-carriers/{carrierId}/options/{optionId}​

DELETE /shipping-carriers/{carrierId}/options/{optionId}​

PUT /ordersas/{id}/shipping-status​

Propiedades

Opciones de envío

Propiedades opciones de envio

Provisión de tarifas a nuestros comerciantes

Propiedades de tarifas a nuestros comerciantes

Cache TTL (Time to Live)

Disyuntor para métodos de envío inestables

Manejo de respuestas HTTP

Ejemplos de requests para métodos de envío

POST /tu_callback_url

Endpoints

POST /shipping-carriers

POST /shipping-carriers

GET /shipping-carriers

GET /shipping-carriers/`{id}`

PUT /shipping-carriers/`{id}`

DELETE /shipping-carriers/`{id}`

POST /shipping-carriers/`{carrierId}`/options

GET /shipping-carriers/`{carrierId}`/options

GET /shipping-carriers/`{carrierId}`/options/`{optionId}`

PUT /shipping-carriers/`{carrierId}`/options/`{optionId}`

DELETE /shipping-carriers/`{carrierId}`/options/`{optionId}`

PUT /ordersas/`{id}`/shipping-status