API Despachos

El equipo de Bsale ha puesto a disposición de la comunidad de desarrolladores endpoints y webhooks para la comunicación con distintos tipos de courriers de envíos. Pudiendo notificar despachos, estados de éstos y obtención de sus detalles.
Para autenticar las peticiones en todos los endpoints se debe enviar en la cabecera el parámetro access_token.

url base: https://courier.bsale.io

Endpoints

GET una orden

GET /v1/couriers/orders/:id.json

Endpoint que retorna la información de una orden para un courier

Parámetros

  • id: id de la orden (Integer)

  • expand: indicar opcional para expandir nodos (String)

Ejemplos

  • GET /v1/couriers/orders/:idOrder.json?expand=orders.details

  • GET /v1/couriers/orders/:idOrder.json?expand=orders.deliveryType

Respuesta

{

"code": 200,

"data": {

"id": 32,

"origin": {

"country": "Chile",

"state": "Región Metropolitana",

"city": "Santiago",

"district": "Buin",

"address": "Camino Padre Hurtado 5696",

"zipcode": "",

"latitude": "0.0",

"longitude": "0.0"

},

"destination": {

"country": "Chile",

"state": "Región Metropolitana",

"city": "",

"district": "Vitacura",

"address": "mar jonico 7995",

"buildingNumber": "",

"zipcode": "",

"latitude": "0.0",

"longitude": "0.0"

},

"packagingType": 0,

"contact": {

"firstName": "Stefany Milagros",

"lastName": "Palma Giron",

"email": "sgcobranzas@gmail.com",

"code": "",

"phone": "941257211"

},

"comment": "A dos cuadras del colegio Sagrado Corazon de Jesús",

"deliveryType": {

"id": 3,

"name": "Overnight",

"code": "over001",

"courierId": 2

},

"courierId": 2,

"sellerId": 1,

"stateId": 6,

"label": "",

"trackingNumber": "",

"details": [

{

"id": 2,

"description": "el ananá de Pablo HUESO",

"quantity": 1.0,

"weight": 5.0,

"length": 5.0,

"width": 5.0,

"height": 5.0

}

]

}

}


Donde:

  • id(Integer): id de la orden

  • origin(Object): objeto con la información desde donde se despachará

  • country(String): país

  • state(String): región(Chile)/departamento(Perú)

  • city(String): ciudad

  • district(String): comuna(Chile)/distrito(Perú)

  • address(String): dirección

  • zipcode(String): código postal

  • latitude(String): latitud

  • longitude(String): longitud

  • destination(Object): objeto con la información de destino del despacho

  • country(String): país

  • state(String): región(Chile)/departamento(Perú)

  • city(String): ciudad

  • district(String): comuna(Chile)/distrito(Perú)

  • address(String): nombre de la calle

  • buildingNumber(String): numero de la propiedad

  • zipcode(String): código postal

  • latitude(String): latitud (no disponible actualmente)

  • longitude(String): longitud (no disponible actualmente)

  • contact(Object): objeto con la información de contacto del destinatario

  • firstName(String): nombre

  • lastName(String): apellido

  • email(String): email de contacto

  • code(String): código del destinatario

  • phone(String): teléfono

  • seller(Object): información de contacto del remitente

  • firstName(String): nombre

  • lastName(String): apellido

  • email(String): email de contacto

  • code(String): código

  • phone(String): teléfono

  • comment(String): comentario opcional

  • packagingType(Integer): despacho en múltiples paquetes(0-no/1-si)

  • deliveryTypes(Object): tipo de despacho (expand: orders.deliveryType)

  • courierId(Integer): id del courier

  • sellerId(Integer): id del seller

  • stateId(Integer): id del estado del despacho

  • label(String): etiqueta del pedido

  • trackingNumber(String): numero de seguimiento

  • details(Object): detalle del despacho (expand: orders.details)

  • description(String): descripción del detalle

  • quantity(Float): cantidad

  • weight : Peso en kg (Float)

  • length : Largo en cm (Float)

  • width : Ancho en cm (Float)

  • height : Altura en cm(Float)

POST estados del despacho

POST /v1/logs.json

Endpoint que registra de movimientos y estados del despacho

Parámetros

  • id: id de la orden (Integer)

  • description: descripción del detalle (String)

  • stateId: id del estado (Integer)

Estados disponibles

1 Por retirar

2 En tránsito

3 Entregado

4 Problema con la entrega

5 Problema con los datos

6 Anulado

Respuesta

{

"orderId": 2,

"description": "paquete despachado",

"stateId": 1

}


POST url seguimiento y etiqueta (opcional)

POST /v1/couriers/orders/:id/label.json

Endpoint que registra la etiqueta y número de seguimiento

Parámetros

  • orderId: id de la orden (Integer)

  • trackingNumber: Código de seguimiento (String)

  • label: Url externa de etiqueta (Integer)

Respuesta

{

"orderId": 14861,

"trackingNumber": "909981888-F",

"label": "http://courierdemo.com/storage/img9099decode.jpg"

}


GET información de empresa

GET /v1/couriers/sellers.json

Endpoint que retorna las empresas asociadas al courier

Parámetros

  • id: id de la empresa (Integer)

  • name: nombre de la empresa (String)

  • code: rut de la empresa (String)

Respuesta

{

"code": 200,

"href": "https://courier.bsale.io/v1/couriers/sellers/all.json",

"count": 1,

"limit": 25,

"offset": 0,

"data": [

{

"id": 1,

"name": "empresa",

"code": "11.111.111-1"

}

]

}


Webhooks

Estructura JSON

Se realizará una petición POST al endpoint que designe el Courier, la cual contendrá en su cuerpo el siguiente detalle:

{

"cpnId": 33250,

"sellerId": 7,

"userToken": "5882317a9a3555abc25e582ac585e94f5b792494",

"resource": "/v1/couriers/orders/17170.json",

"resourceId": "17170",

"topic": "courierOrder",

"action": "post",

"send": 1629741015

}

  • sellerId: id de la empresa que solicita la orden (Integer)

  • resource: Endpoint para obtener la información del recurso (String)

  • resourceId: id del recurso notificado (String)

  • topic: motivo o recurso de la notificación (String)

  • action: verbo REST de la notificación (String)

  • send: UNIX Timestamp de la notificación (Integer)

Diagrama de flujo

Ver ejemplos