Seller-Hub-API

Inicio

Bienvenidos a la documentación de nuestra API para Proveedores, diseñada para facilitar y optimizar la interacción entre su empresa y nuestros servicios. En este documento, encontrará información detallada y ejemplos prácticos que le permitirán integrar eficientemente nuestras funcionalidades en sus sistemas.

Esta API tiene como objetivo principal proporcionar una interfaz clara y eficiente para la automatización de procesos entre proveedores y nuestra plataforma. A través de esta interfaz, los proveedores podrán gestionar información relacionada con pedidos, inventarios, y otros aspectos cruciales del negocio.

Requisitos previos de integración

Para integrar con SellerHub API, es importante cumplir con los siguientes requisitos:

Requisito	Descripción
Credenciales	Las credenciales son claves únicas que te proporcionamos para que puedas configurar tu información y acceder a consumir los servicios. Estas son proporcionadas por el equipo de GoodMeal y las debes resguardar de manera segura.
Tiendas	Las tiendas, son donde cargaras tus productos, para ello estas serán configuradas por GoodMeal, quien luego te hará entrega de los accesos a cada una, para que puedas utilizar con la integración.
Parámetros de cuenta	Son algunos parámetros necesarios para funcionar, uno es para poder cotizar delivery con tu servicio (Si es que es necesario) y otro para que podamos hacer ingreso de las órdenes de compra en tus sistemas. De esto se hace cargo GoodMeal.

Configuración de la integración

La integración con SellerHub API es simple de utilizar y solo requiere contar con el token de uso, y toda la configuración previa que hace GoodMeal, con eso listo, podemos ir a configurar parámetros esenciales para funcionar.

Configuración de token de uso

Todas las llamadas a la API deben hacer uso del header:

X-API-TOKEN : <token-de-uso>

Y además, el {clientId}, que es un valor que te entregamos, como identificador de usuario.

Configurar parámetros de tu cuenta

Hay dos parámetros que son esenciales para operar, a continuación como configurar cada uno.

Configuración de cotización de delivery

Para poder cotizar delivery con tus servicios, debemos ser capaces de llamarlos, para ello deberás configurar el parámetro: base_url_notification_trip , para ello debes llamar al método:

POST /{clientId}/accounts/params

{
  'type': 'base_url_notification_trip',
  'value': '<url-de-acceso-para-cotizar-delivery>',
  'access': {
    'method': 'TOKEN',
    'token': {
        'api-token': '<api-token>'
    } 
  }
}

Esto es solo para configurarlo, luego en la sección de Gestión de orden, se comenta su utilización.

Configuración de envío de órdenes de compra

Ahora necesitamos saber a donde te enviaremos las órdenes de compra, para ello debemos configurar el siguiente parámetro: base_url_notification_purchase, para ello debes llamar al método:

POST /{clientId}/accounts/params

{
  'type': 'base_url_notification_purchase',
  'value': '<url-de-acceso-para-ordenes-de-compra>',
  'access': {
    'method': 'TOKEN',
    'token': {
        'api-token': '<api-token>'
    } 
  }
}

Esto es solo para configurarlo, luego en la sección de Gestión de orden, se comenta su uso.

Tipos de respuesta

Basamos todas las respuestas en el estándar HTML, por ende todas las respuestas de la API van por los códigos:

200: Cuando todo está OK, se responde este valor, en conjunto con la respuesta.
4XX: Cuando hay un recurso que falla por temas de request, se retorna un 4XX, ya sea porque no se encontró el recurso (404), porque está prohibido acceder a él (401), etc.
5XX: Cuando el servicio encuentra un problema interno, responderá un 5XX y nuestro equipo técnico debe revisarlo.

Publicar productos

Ahora que ya has configurado tu tienda, vamos a cargar información en tu tienda, para que puedas vender.

Cargar y editar productos

Para poder vender a través de GoodMeal, debes cargar productos dentro de la tienda, para ello vamos a utilizar este método:

 {
  "method": "POST",
  "url": "/{clientId}/products",
  "headers": {
    "Content-Type": "application/json",
    "X-API-TOKEN": "",
  },
  "body": {
    "store_code": "<string>",
    "products": [
      {
        "category": "<string>",
        "description": "<string>",
        "discount_percent": "<number>",
        "external_id": "<string>",
        "name": "<string>",
        "price_regular": "<number>",
        "quantity": "<number>",
        "size": "<string>",
        "sku": "<string>",
        "unit": "<string>",
        "upc_ean": "<string>"
      },
      {
        "category": "<integer>",
        "description": "<string>",
        "discount_percent": "<number>",
        "external_id": "<string>",
        "name": "<string>",
        "price_regular": "<number>",
        "quantity": "<number>",
        "size": "<string>",
        "sku": "<string>", 
        "unit": "<string>",
        "upc_ean": "<string>"
      }
    ]
  }
}

Este es un ejemplo, puedes ir a la definición de la API, para ver cada parte en detalle.

Cantidad y unidades

El campo unit y quantity_unit, corresponde a la unidad de medida y la cantidad de esa unidad, no son obligatorios, pero puede ayudar a mejorar la busqueda de un cliente.

Lista de unidades:

gr: Gramos
kg: Kilogramos
lb: libras
lt: litros
ml: mililitros
oz: Onza
un: Unidad

Actualizar stock

Ya agregaste los productos, ahora debemos agregar el stock necesario para poder vender, para ello debemos hacer uso de esta llamada:

 {
  "method": "PUT",
  "url": "/{clientId}/products/stock",
  "headers": {
    "X-API-TOKEN": "",
    "Content-Type": "application/json"
  },
  "body": {
    "store_code": "<number>",
    "products": [
      {
        "sku": "<string>",
        "stock": "<number>"
      },
      {
        "sku": "<string>",
        "stock": "<number>"
      }
    ]
  }
}

Cuidado!

Una vez cargues stock, estos comenzaran aparecer en la tienda, para su venta, asi que ten cuidado con cargar stock, si no quieres vender.

Gestión de orden de compra

Ahora que publicaste productos, debemos procesar las órdenes de compra que te lleguen, de tus usuarios.

Cotizar delivery

Lo primero, si estás ofreciendo delivery, el usuario cotizará tu servicio, de todas las opciones que configuraste, tu deber es responderle un precio a cobrar y el usuario decidirá si lo acepta o no, esto lo veremos en el siguiente apartado.

Para ello te llegará una llamada a tu servicio de delivery configurado con lo siguiente:

{
    "code_id": "<string>",
    "delivery": {
      "address": "<string>",
      "delivery_code": "<string>",
      "detailed_address": {
        "aditional_address_information": "<string>",
        "city": "<string>",
        "comuna": "<string>",
        "country": "<string>",
        "state": "<string>",
        "street_address_1": "<string>",
        "zip_code": "<string>"
      },
      "location": {
        "lat": "<string>",
        "log": "<string>"
      }
    },
    "products": [
      {
        "category": "<integer>",
        "description": "<string>",
        "discount_percent": "<number>",
        "external_id": "<string>",
        "name": "<string>",
        "price_regular": "<number>",
        "quantity": "<number>",
        "size": "<string>",
        "sku": "<string>",
        "unit": "<string>",
        "upc_ean": "<string>"
      },
      {
        "category": "<integer>",
        "description": "<string>",
        "discount_percent": "<number>",
        "external_id": "<string>",
        "name": "<string>",
        "price_regular": "<number>",
        "quantity": "<number>",
        "size": "<string>",
        "sku": "<string>",
        "unit": "<string>",
        "upc_ean": "<string>"
      }
    ],
    "store_code": "<string>"
}

Para el objeto delivery:

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "direccion del usuario, calle y numero"
    },
    "delivery_code": {
      "type": "string",
      "description": "el codigo del tipo de delivery que ingresaste al configurar tu cuenta"
    },
    "aditional_address_information": {
      "type": "string",
      "description": "informacion extra de la direccion, ej. Depto 101"
    },
    "city": {
      "type": "string",
      "description": "Ciudad del delivery"
    },
    "comuna": {
      "type": "string",
      "description": "Comuna del delivery (CL)"
    },
    "country": {
      "type": "string",
      "description": "Pais del delivery (CL)"
    },
    "street_address_1": {
      "type": "string",
      "description": "Direccion completa"
    },
    "zip_code": {
      "type": "string",
      "description": "codigo ZIP de la direccion"
    },
    "lat": {
      "type": "string",
      "description": "Latitud de la direccion"
    },
    "log": {
      "type": "string",
      "description": "Longitud de la direccion"
    }
  }
}

Luego se incluye un arreglo de productos, para que se pueda calcular la capacidad del delivery, lo más importante de aquí:

external_id: que corresponde al ID que utilizan en sus sistemas para identificar el producto.
quantity: que es la cantidad del producto que se quiere comprar
sku: que es el SKU del producto tuyo.

Recepcionar una orden de compra

Ahora que ya se pudo concretar la venta, debemos enviarte la orden de compra a la url que configuraste previamente.

el objeto delivery, solo aparece cuando la tienda tiene custom delivery activado.

Purchare type: Retiro	Delivery	Custom Delivery
Order status: ACCEPTED	CANCELED

Para ello, te enviaremos esto:

{
    "order_id": "<string>",
    "purchase_type": "<string>",
    "buyer_name": "<string>",
    "buyer_email": "<string|null>",
    "order_product_price": <number>,
    "created_at": "<string>",
    "store_code": "<string>",
    "order_status": "<string>",
    "delivery": {
      "address": "<string>",
      "delivery_code": "<string>",
      "detailed_address": {
        "aditional_address_information": "<string>",
        "city": "<string>",
        "comuna": "<string>",
        "country": "<string>",
        "state": "<string>",
        "street_address_1": "<string>",
        "zip_code": "<string>"
      },
      "location": {
        "lat": "<string>",
        "log": "<string>"
      }
    },
    "products": [
      {
        "name": "<string>",
        "quantity": <number>,
        "sku": "<string>",
        "price": <number>,
        "type": "<string>"
      },
      {
        "name": "<string>",
        "quantity": <number>,
        "sku": "<string>",
        "price": <number>,
        "type": "<string>"
      }
    ]
}

Donde se incluye el {order_id}, que corresponde al ID de la orden, para poder identificarla más adelante, para hacer cambios.

Dentro hay dos objetos importantes:

delivery: El objeto previamente utilizado para definir el delivery, que corresponde a la cotización previa.
products: un arreglo con todos los productos comprados en la orden

Como respuesta se espera lo siguiente (o simplemente un 200 OK, sin body):

{
  "order_status": "string",
  "detail_order_status": "string",
  "delivery_status": "string",
  "detail_delivery_status": "string",
  "quote_id": "string",
  "tracking_url": "string"
}

Donde:

order_status: puede ser uno de los siguientes estados:
- PENDING: orden está siendo procesada, te permite dar una revisión más exhaustiva de la orden, antes de aceptarla, puedes cambiar algunas cosas de la orden, estando aquí.
- ACCEPTED: orden aceptada, ya solo puedes actualizar información de delivery y la url de la boleta, entre otros.
- CANCELED: orden cancelada, le avisamos al cliente, que no puedes procesar la orden.
detail_order_status: Un comentario interno, no será visto por el cliente.
delivery_status (opcional): para el caso que quieras actualizar el estado del delivery,
- PREPARING: preparando el pedido
- ONGOING: en camino a entregar el pedido
- NEAR: llegando a destino
- COMPLETED: entregado
- CANCELED: cancelado
quote_id: ID de cotizacion de delivery
tracking_url: url para tracking, si es que hay delivery asociado.

Actualizar una orden de compra

Mientras una orden de compra, este en estado PENDING, puedes editar cierta información

PUT /{clientId}/orders
{
  "value": {
    "orders": [
      {
        "delivery": {
          "quote_id": "QWEDW-IJEDA-JWED",
          "status": "PREPARING",
          "tracking_url": "https://..."
        },
        "order": {
          "invoice_url": "https://...",
          "order_id": "asdasd-asdasda-asdad-",
          "status": "PENDING"
        },
        "products": [
          {
            "available_quantity": 50,
            "quantity": 100,
            "sku": "23423423"
          }
        ],
        "store_code": "QQW@#D@D@#D"
      }
    ]
  }
}

Los campos que puedes editar, estando en estado PENDING son:

delivery.status: puedes actualizar el estado del delivery
delivery.tracking_url: Puedes agregar la URL de tracking para delivery
order.invoice_url: Puedes agregar la URL de la boleta de la orden
order.status: Puedes dejarlo siempre en PENDING, para seguir editando, luego pasarlo a ACCEPTED o CANCELED.
products.available_quantity: IMPORTANTE aquí debes agregar la cantidad de stock que tienes disponible para esta orden, si tienes el stock, no hay necesidad de modificarlo, pero si tienes menos, debes actualizar ese producto, para que podamos hacer la devolución al comprador.

Actualizar información de delivery

Una vez una orden este en estado ACCEPTED, puedes editar el objeto delivery con información relacionada con el estado del delivery:

PREPARING: preparando el pedido
ONGOING: en camino a entregar el pedido
NEAR: llegando a destino
COMPLETED: entregado
CANCELED: cancelado

Con el mismo método anterior (PUT /{storeId}/orders), pero además, cuando cambies el estado, se enviarán notificaciones PUSH al usuario, para que este sepa en qué estado está su pedido.

Cancelar una orden de compra

Puedes cancelar una orden por cualquier motivo, de diversas formas:

Cuando recibes una orden, puedes enviarnos el estado CANCELED
```
{
  "order_status": "CANCELED",
...
}
```

Cuando quieras actualizar la orden, nos envías el estado CANCELED:

PUT /{clientId}/orders
{
  "value": {
 "orders": [
   {
     "delivery": {
      ...
     },
     "order": {
       "order_id": "asdasd-asdasda-asdad-",
       "status": "CANCELED"
     },
     "products": [
       ...
     ],
     "store_code": "QQW@#D@D@#D"
   }
 ]
  }
}

Llamando al método de API, donde puedes enviar varias:

PUT /{clientId}/orders/canceled
{
  "orders": [
 {
   "order_id": "aasdasd-asdasda-",
   "store_code": "QQW@-#D@D-@#D"
 }
  ]
}
{
  "orders": [
 {
   "order_id": "aasdasd-asdasda-",
   "store_code": "QQW@-#D@D-@#D"
 }
  ]
}

Cuando tu orden esta aceptada y envias un estado de delivery CANCELED:

PUT /{clientId}/orders/canceled
{
  "value": {
 "orders": [
   {
     "delivery": {
       "status": "CANCELED",
     },
     "order": {
      ...
     },
     "products": [
      ...
     ],
     "store_code": "QQW@#D@D@#D"
   }
 ]
  }
}

Validacion final

Una vez integrado con un ambiente previo, se hace un flujo de compra normal para validar que todos los puntos de integración están funcionando correctamente.

Cuando se autorice la integración por ambas partes, se procederá a mover configuraciones hacia un ambiente productivo para comenzar a operar.