Linio Seller Center API

Version Author Description Email

1.0 Javier Lopez Release 1 javier.lopez@linio.com.mx

1

Manual de usuario Seller Center API

1. Descripcin 2. Herramientas 3. Mecanismo 4. Opciones y ejemplos 5. Recursos 6. Apndice

1. Descripcin:

Este documento describe los pasos a seguir para conectarse a Linio SellerCenter usando nuestra API. La conexin a nuestra API se realiza mandando una serie de parmetros y en ocasiones un archivo xml con cierta definicin, lo cual al ser procesado realizar una accin y obtendremos un resultado exitoso o fallido, dependiendo de la informacin que enviemos. Ponemos a tu disposicion las DevTools, que es una plataforma para probar el servicio y tambin para poder descargar las librerias necesarias para hacer la conexin con la API, las cuales tambin las puedes hacer por cuenta propio, sin embargo nosotros te las proporcionamos

2. Herramientas:

Seller Center Api Wrapper: Es una herramienta que permite hacer una prueba conectndose directamente a la API se Sellercenter y, desde una interfaz intuitiva permite probar en tiempo real el servicio, incluso genera los archivos necesarios para poder hacer, la misma conexin desde tu propio servidor Web (El cdigo que se descarga est en PHP y funciona en versiones 5.3 o superior, al igual que las bibliotecas).

3. Mecanismo La comunicacin se realiza de la siguiente manera

2

1. Debemos de tener una cuenta creada en el seller center de Linio (https://sellercenter.linio.com.mx)

2. Dentro de la cuenta hay que entrar a Configuracin y ah dar click en Manejar usuarios, ah podrs obtener tu Api key.

3. Debes de entrar a (http://162.248.53.24/ ) y colocar esos datos en donde corresponde, dependiendo de la accin que desees ejecutar.

4. Cuando realices una accin dentro del Devtools de Sellercenter estars afectando a un entorno de produccin (por favor toma tus debidas precauciones). Por otro lado el sistema te permitir descargar los scripts necesarios para replicar el proceso (en PHP) con las respectivas libreras necesarias.

5. Para poder entender completamente todos los procesos que se pueden realizar dentro del Devtools, vamos a explicar las capacidades de cada scope del API

6. En algunas ocasiones necesitars especificar un xml el cual puede llevar informacin para crear o hacer update de algn producto, en la seccin 6 Apndice encontrars ms informacin sobre como crear un xml a partir de un archivo csv.

Scope Descripcin Producto Este scope significa que podremos realizar acciones

sobre un producto como crearlo, actualizarlo, csambiar imgenes y borrarlo

Feed Todas las peticiones que recibe el API son organizadas mediante una cola (queue), y usando este scope podemos realizar ciertas acciones sobre ella.

Sales Order Usando las acciones de este scope podemos obtener informacin de rdenes ya sea por fecha, lmite o por d especfico de cada orden y de sus tems que lo componen.

Orderprocessing Las acciones del scope orderprocessing permiten avisar al sellercenter sobre status cambiados como cancelado, enviado entre otras

7. Actualmente existen las siguientes acciones que se pueden realizar:

Scope Accin Descripcin Producto ProductCreate Aqu podrs entrar a crear un producto

nuevo

3

Producto ProductUpdate Permite la actualizacin de un producto, identificado mediante sku del proveedor

Producto ProductImage Nos permite reemplazar la imagen del producto

Producto ProductRemove Elimina un producto de nuestro catalogo.

Feed FeedList Retorna una lista de los las acciones realizadas los ltimos 30 dias

Feed FeedOffsetList Esta accin es similar a FeedList, pero acepta parmetros de bsqueda / filtrado adicionales en la URL de solicitud.

Feed FeedCount FeedCount devuelve una lista del conteo de feeds de los ltimos 30 das

Feed FeedCancel Esta accin permite cancelar los feeds enviados que an estn encolados

Sales Order GetOrders Retorna una lista de ordenes creadas o actualizadas, durante un periodo de tiempo

Sales Order GetOrder Retorna la informacin detallada de una orden, solicitada mediante su OrderId

Sales Order GetOrderItems Esta accin retorna todos los items contenidos dentro de una orden

Orderprocessing SetStatusToCanceled

Esta accin informa al sellercenter que un item ha sido cancelado

Orderprocessing SetStatusToShipped

Informa a SellerCenter que el artculo ha sido enviado

Orderprocessing SetStatusToFailedDelivery

Informa al sellercenter cuando la entrega de un artculo fall

Orderprocessing SetStatusToDelivered

Informa al sellerCenter cuando un artculo ha sido entregado

4

Orderprocessing GetFailureReasons La accin GetFailureReasons devuelve todas las razones fallidas para SetToCancelled y SetToFailedDelivery

Orderprocessing GetShipmentProviders

La accin GetShipmentProviders devuelve todos los proveedores de envo activos

4. Opciones y ejemplos

A continuacin se describen ejemplos de cada una de las opciones del Devtools para la comunicacin con la API.

1. Producto Creacin de producto

Para crear un producto necesitamos usar la accin ProductCreate la cual nos permitir crear un producto nuevo, y tambin necesitaremos un XML el cual contiene toda la informacin necesaria para la creacin de una producto. La estructura bsica el xml es de la siguiente forma

Dentro de los tags Product, necesitaremos introducir toda la informacin respecto a nuestro producto, a continuacin veremos cada tag, y que significado tiene.

Campo tipo requerido Descripcin

SellerSku String Si Este campo permite ingresar el Sku del proveedor

ParentSku String no Este campo es el sku del producto principal cuando se da de alta una variacion de un producto

Status String no Es el status del producto y puede ser de 3 tipos, enabled, disabled o deleted, por default es enabled

5

Name String si Es una cadena de texto con una longitud de entre 2 y 255 caracteres

Variation String no Es una cadena, la cual indica una variacin del artculo por ejemplo XXL

PrimaryCategory Integer si Este es el id de la categora principal

Categories String si Es una lista separada por comas para especificar de 1 a 3 categoras

Description String si Este campo es la descripcin del artculo, y puede contener desde 6 hasta 25000 caracteres, tambin soporta tags HTML

Brand String si Contiene la marca del producto

Price Decimal si Precio del producto

SalePrice Decimal no Precio de venta

SaleStartDate DateTime no Fecha de inicio del precio de venta

SaleEndDate DateTime no Fecha de fin del precio de venta

TaxClass String si Identificador de Tax, usualmente es default

ShipmentType String no Tipo de envio, puede ser crossdocking o dropshipping

ProductId String no EAN/UPC/ISBN del producto

Condition String no Es la condicin del producto y puede ser 'new', 'used' o 'refurbished'

ProductData Section no Aqu podemos poner algunos atributos del producto como PackageType o ShortDescription

Quantity Integer no El inventario disponible del producto

En base a la tabla anterior podemos crear un xml de la siguiente manera:

324235456JVL enabled Producto de prueba XXL 501 1

6

Este es un producto de prueba Adidas 100.11 32.5 2014-01-03T11:31:23+0000 2014-05-03T11:31:23+0000 default dropshipping 1234 new parcel Hello World 10

Dicho XML se inserta en el DevTools, y se puede realizar el test ah mismo, con este cdigo obtendremos un XML con un 200 de respuesta y un xml con mensaje success. Edicin de producto

Para editar el producto necesitaremos un XML con la siguiente definicin:

324235456JVL 124 32423rgrgt5456JVL 5

En donde como vemos solo necesitamos poner la caracterstica que deseamos modificar, buscar el producto por el SellerSku y es lo nico que necesitamos para poder actualizar el producto. Agregar imagen al producto

7

Para agregar una imagen al producto necesitaremos un XML con la siguiente definicin:

324235456JVL http://www.rocket-internet.de/sites/default/files/header_bg_imgs/_mexio_03.jpg

En donde como vemos solo necesitamos poner una imagen que deseamos agregar al producto, el cual se identifica por SellerSku. Eliminar el producto.

Para eliminar el producto necesitaremos un XML con la siguiente definicin:

324235456JVL 32423rgrgt5456JVL

Donde con el SellerSku podemos eliminar varios productos.

2. Feed Lista de Feeds Para ver las ltimas acciones realizadas, solo se necesita indicar la accin FeedList a la peticin.

8

Lista de Feeds con parmetros Esta accin es similar a FeedList, pero acepta parmetros de bsqueda / filtrado adicionales en la URL de solicitud, dichos parmetros son los siguientes, importante no son parte de un XML, si no parmetros para enviar por GET: Campo Tipo Descripcin Offset Integer ndice de la primera entrada para recuperar de la lista

total de los Feeds PageSize Integer Nmero de entradas para recuperar Status String Recupera feeds con el status especificado

Lista de Feeds Count Esta accin FeedCount devuelve una lista del conteo de feeds de los ltimos 30 das. Feed Cancel Esta accin FeedCancel permite cancelar los feeds enviados que an estn encolados usando el FeedID.

3. Sales Order

Lista de rdenes Esta accin GetOrders devuelve una lista de las rdenes, sin requerir un xml, pero adems de eso tenemos bastantes parmetros para poder filtrar el resultado que deseemos. Campo Tipo Descripcin Created after

DateTime Devuelve todas las rdenes despus de la fecha indicada, en formato (aaaa-mm-dd hh:mm:ss) ejemplo 2014-02-05 18:46:30

9

Created before

DateTime Devuelve todas las rdenes antes de la fecha indicada, en formato (aaaa-mm-dd hh:mm:ss) ejemplo 2014-02-05 18:46:30

Updated after

DateTime Devuelve todas las rdenes modificadas despus de la fecha indicada, en formato (aaaa-mm-dd hh:mm:ss) ejemplo 2014-02-05 18:46:30

Updated before

DateTime Devuelve todas las rdenes modificadas antes de la fecha indicada, en formato (aaaa-mm-dd hh:mm:ss) ejemplo 2014-02-05 18:46:30

Limit Integer Es el lmite de rdenes entre 1 y 100 Offset Integer Indica el nmero con el cual inicia el resultado

Importante que al menos uno ya sea CreatedAt or UpdateAfter est especificado.

Detalle de orden En la accin GetOrder nos devuelve la orden con detalle, en este caso solo necesitamos especificar el id de la orden. Lista de items de una orden Esta accin GetOrderItems es similar a la anterior, solo que en este caso devuelve todos los items que contiene la orden.

4. OrderProcessing

Enviar status Cancelado Para la accin SetStatusToCanceled nos devuelve la orden con detalle, en este caso solo necesitamos especificar el id de la orden.

Campo tipo requerido Descripcin

OrderItemId Integer Si Es el id del item

Reason String Si En este campo debemos de especificar la razn de la cancelacin (La lista de opciones viene ms adelante sobre el mismo apartado de order processing en la accin GetFailureReasons)

ReasonDetail String no Descripcin de la razn por la que fue cancelado el item

10

Enviar status Shipped En la accin SetStatusToShipped Informa a SellerCenter que el artculo ha sido enviado y podemos especificar los siguiente parmetros.

Campo tipo requerido Descripcin

OrderItemIds Array si Lista de itemIds que sern enviadas en este formato (1,2,3,4)

DeliveryType String si Tenemos que especificar el tipo de envo, entre dropship, pickup o send_to_warehouse

ShippingProvider String si(solo si es dropship el envo)

Debe de especificarse un Shipping provider vlido solo si el tipo de envio es dropship, dicha lista se proporcionar en la accin GetShipmentProviders detalla posteriormente en el mismo apartado de orderprocessing

TrackingNumber String si(solo si es dropship el envo)

Es el tracking id del paquete sol para envio tipo dropshipping

PickUpDate DateTime

si(si el tipo de envio es pickup)

Fecha y hora para recoger el paquete

Enviar status fall la entrega En la accin SetStatusToFailedDelivery informa al sellercenter cuando la entrega de un artculo fall y acepta los siguientes parmetros.

Campo tipo requerido Descripcin

OrderItemId Integer Si Es el id del item

Reason String Si En este campo debemos de especificar la razn por la cual fall la entrega(La lista de opciones viene ms adelante sobre el mismo apartado de order processing accin GetFailureReasons)

11

ReasonDetail String no Descripcin de la razn por la que fall item

Enviar status entregado En la accin SetStatusToDelivered informa al sellercenter cuando ha sido entregado un artculo y nicamente necesita el siguiente parmetros.

Campo tipo requerido Descripcin

OrderItemId Integer Si Es el id del item

Lista de razn por la cual pudo fallar En la accin GetFailureReasons nos devuelve todas las razones fallidas para las acciones SetToCancelled y SetToFailedDelivery y no requiere parmetros. Lista de Shipment providers La accin GetShipmentProviders devuelve todos los proveedores de envo activos.

5. Recursos

Con toda la informacin anterior podemos ya hacer pruebas con la DevTools, y al final se obtendr un resultado similar a este

12

Donde podremos ver la peticin que se realiz, el xml que se envi (si aplica envo de xml), la respuesta con headers y una seccin de download files, la cual es sumamente importante y veremos por qu. Download Files Ponemos a disposicin el cdigo necesario para poder replicar las mismas acciones que se realizaron en las devtools, en tu propio servidor (Servidor con Linux y PHP 5.3x corriendo), el archivo a descargar incluye 3 archivos, los cuales son:

1. El archivo index.php que tiene toda la configuracin necesaria para la conexin como xml, parmetros y credenciales.

2. El archivo Authentication.php que tiene el algoritmo para poder generar las llaves de acceso.

3. El archivo Curl.php unicamente es una capa de abstraccin para hacer las llamadas CURL al servidor.

13

6. Apndice

Obtener un XML a partir de un CSV. Para obtener un xml desde un archivo de datos csv, tenemos varias maneras, puede ser mediante cdigo o bien usando algn servicio online

Servicios online En cuanto a servicios online tenemos varios para elegir

1. http://www.luxonsoftware.com/converter/csvtoxml 2. http://tools.daemonservices.com/csv_to_xml/ 3. http://www.freeformatter.com/csv-to-xml-converter.html 4. http://www.convertcsv.com/csv-to-xml.htm

Usando Cdigo

Si preferimos escribir cdigo para hacer la conversin de csv a xml, tambin existen varias libreras que nos puede ayudar mucho, inclusive se podran conectar con algn otro sistema como algn framework (Yii, symfony, zend, kohana, CodeIgniter, Laravel) o con un ecommerce como magento o prestashop, o quizs un software propio, y tambin tenemos varios para elegir.

1. https://github.com/crosbymichael/php-csv-to-xml-json 2. https://github.com/keboola/php-csv 3. https://github.com/elidickinson/php-export-data 4. https://github.com/faisalman/simple-excel-php 5. http://faisalman.github.io/simple-excel-php/api/0.3/

14