Documentación Técnica
En este documento se hace una explicación de la importación y exportación de objetos. Estas acciones se puede realizar mediante el panel de control o mediante el Webservice. También está explicado los campos de los diferentes objetos a importar y/o exportar.
Nota previa: en este documento un objeto es producto, cliente, pedido o media files.
Importación de datos
La importación mediante fichero consiste en crear un fichero CSV, XLS o XLSX con los campos requeridos de cada objeto (véase más arriba). Un fichero XLS de ejemplo sería este.
Una vez creado el fichero existen dos formas de incorporar estos datos a la base de datos de CatalogPlayer. Por una parte mediante las funciones del panel de control de cada objeto (producto, fotos, etc.).
Por otra parte se puede utilizar los métodos del WEBSERVICE de CatalogPlayer.
Exportación de datos
La exportación puede realizarse, igual que la importación, des de dos lugares posibles. El primero se realiza mediante el panel de control. Dentro de cada objeto hay la opción de exportar.
La otra opción es utilizar los métodos del WEBSERVICE de CatalogPlayer.
Webservice
Toda petición del webservice se tendrá que realizar en una dirección URL concreta. En este caso para cada cliente es diferente, pero todas siguen la misma estructura:
http/https://[companyCode].mycpl.net/webservice.php/method/[action]
El [companyCode] es el código de la empresa que se ha facilitado.
Aunque se recomienda el uso del protocolo HTTPS también se puede utilizar el HTTP
¿Cómo funciona? (paso a paso)
- Como primera acción tenemos que identificarnos en el webservice, para poder obtener un hash de usuario (getSincroCredentials).
- Una vez finalizado el proceso de identificación, ya podemos utilizar los métodos que nos facilita el webservice. Para poder realizar una
petición en un método tenemos que generar la URL anterior comentada y cambiar [action] por el método que queramos llamar.
Por ejemplo para realizar un sincro.getSuncroCredentials generaríamos la URL http/https://[companyCode].mycpl.net/webservice.php/method/sincro.getSincroCredentials.
Métodos WS
Action | Parameters (Input) | Response (Output) | Observations |
sincro.getSincroCredentials |
{ "user":"username", "password":"user password" } |
{ "hash":"userhash", "consumer":"consumer ssid" } |
Este método sirve para identificarse en el webservice. |
exportProducts |
{ "hash":"userhash", "consumer":"consumer ssid" , "json":"true or false" } |
Format product object | Este método sirve para exportar los productos. En caso del parámetro de input 'json':'true' el formato de exportación será en formato JSON. En caso de 'json':'false' el formato de exportación será en CSV. |
categories.import attributes.import products.import prices.import files.import |
{ "hash":"userhash", "consumer":"consumer ssid", [ { "file":"filenameImport", "type":"typeFile", "log":"logName", }, { "file":"filenameImport2", "type":"typeFile2", "log":"logName2", }, ] } |
{ "transaction_id":"userhash", "files": [ { "file":"pathfile/filenameImport", "type":"typeFile", "log":"pathlog/logName", "obj":"object import", }, { "file":"pathfile/filenameImport2", "type":"typeFile2", "log":"pathlog/logName2", "obj":"object import2", }, ] } |
Este método sirve para crear la tarea de importar categorías, atributos, productos, precios y archivos (no realiza la importación).
Antes de hacer el proceso de importación los archivos tienen que subirse al directorio 'sincro'.
En este caso, se han importado dos ficheros. Se pueden importar todos los objetos deseados. |
sincro.startSincro |
{ "hash":"userhash", "consumer":"consumer ssid" } |
{ "transactions":[1,2] } |
Este método sirve para empezar las tareas antes enviadas. Retorna una array con las tareas que se han activado. |
sincro.statusSincro |
{ "hash":"userhash", "consumer":"consumer ssid", "id":"transaction id" (optional) } |
with id input: [ { "file":"pathfile/filenameImport", "logFile":"logName", "status_id":"-1 | 1 | 2 | 3", "log":"log lines", } ] without id input: { "pending":[id transactions], "inprogress":[id transactions], "errors":[id transactions] } status_id = -1 -> error status_id = 3 -> pending status_id = 2 -> in progress status_id = 1 -> ok |
Este método sirve para consultar el estado de una tarea o de todas las tareas (depende del parámetro id). |
Mensajes de error del WS
Todos los mensajes de error del webservice tienen la misma estructura:
"error":{
"code":"integer",
"message":"error message"
}
}
Definición de objetos
Objeto: Producto
Parámetros de entrada del fichero | Tipo |
Explicación |
Token | Texto (255 carácteres) | El ID único de esa referencia |
ProductPrimaryToken | Texto (255 carácteres) | El producto primario al que pertenece esa referencia |
Reference | Texto (255 carácteres) | La referencia del producto que se va a visualizar en la ficha de ese producto |
Alias_es | Texto (255 carácteres) | Descripción de la referencia |
Name_es | Texto (255 carácteres) | Nombre producto en español , para otros idiomas utilizar los códigos ( _EN, _CA etc etc |
Category_token_1 | Texto (255 carácteres) | Token de la categoría de ese producto , con opción a indicar mas categorías ( _2, _3 ) |
Description_es | Texto (255 carácteres) | Description product con opción a múltiples idiomas -> memo |
Precio_1 | float 8,2 | Indicamos los 1..n precios que tenemos para ese producto |
Atribute_token_1 | Texto (255 carácteres) | Indicamos el ID del atributo ( p.j talla, color ) |
AttributeValue_es_1 | Texto (255 carácteres) | Indicamos el valor de ese atributo ( p.j talla = XXL, color = ROJO ) |
Objeto: Cliente
Parámetros de entrada del fichero | Tipo | Explicación |
Token | Texto (50 carácteres) | El ID único de esa referencia |
Name | Texto (255 carácteres) | Nombre cliente |
CIF | Texto (255 carácteres) | CIF cliente |
Phone | Texto (255 carácteres) | Teléfono cliente |
Texto (255 carácteres) | Email cliente | |
Web | Texto (255 carácteres) | Web cliente |
DefaultPricelistToken | Texto (255 carácteres) | Listado de precios que tiene por defecto |
Comments | Texto | Comentarios de cliente |
Address_1_Name | Texto (255 carácteres) | Nombre personalizado de la dirección |
Address_1_Address | Texto (255 carácteres) | Dirección de cliente |
Address_1_City | Texto (255 carácteres) | Ciudad de la dirección de cliente |
Address_1_Cp | Texto (6 carácteres) | Código postal dirección |
Address_1_Phone | Texto (255 carácteres) | Teléfono de la dirección de cliente |
Address_1_Fax | Texto (255 carácteres) | Fax de la dirección de cliente |
Address_1_Email | Texto (255 carácteres) | Email de la dirección de cliente |
Address_1_CountryState | Texto (255 carácteres) | Nombre de la provincia o país |
Address_1_CountryCode | Texto (5 carácteres) | Código de país |
Address_1_Geoposition | Texto (255 carácteres) | Geoposición ( ej: 41.60994, 2.278072) |
Contact_1_name | Texto (255 carácteres) | Nombre del contacto |
Contact_1_email | Texto (255 carácteres) | Email del contacto |
Contact_1_phone | Texto (255 carácteres) | Teléfono del contacto |
Objeto: Pedido
Parámetros de entrada del fichero | Tipo | Explicación |
Token | Texto (50 carácteres) | El ID único pedido |
Name | Texto (255 carácteres) | Nombre cliente |
DateAt | Data Hora [DD/MM/YY HH:MM] | Fecha de creación |
CompanyToken | Texto (50 carácteres) | Token de la empresa |
AddressName | Texto (255 carácteres) | Nombre empresa (opcional) |
ContactName | Texto (255 carácteres) | Nombre contacto (opcional) |
ContactEmail | Texto (255 carácteres) | Email del contacto (opcional) |
UserToken | Texto (55 carácteres) | Token comercial (usuario) que ha realizado el pedido |
Username | Texto (255 carácteres) | Nombre comercial que ha realizado el pedido |
Total | double | Total del pedido |
ProductToken | Texto (100 carácteres) | Token del producto |
Reference | Texto (100 carácteres) | Referencia del producto |
ProductName | Texto (100 carácteres) | Nombre del producto |
Items | double | Cantidad de producto |
SystemUnits | Texto (10 carácteres) | Unidades de medida |
Price | double | Precio unidad |
TotalLine | double | Total de línea |
OrderComment | Texto (250 carácteres) | Comentario pedido |
Objeto: Media/Docs
Parámetros de entrada del fichero | Tipo | Explicación |
Token | Texto (50 carácteres) | El ID único del fichero |
ProductPrimaryToken | Texto (255 carácteres) | Token de producto |
File | Texto (100 carácteres) | Fichero ubicado en la ftp o referenciado a través de una URL ( http://dominio.com/imagen.jpg ) |
FileTypeid |
Númerico 1 (Photo [jpg, png, gif]) 2 (Video [mp4]) 3 (Pdf) |
Tipo de fichero. En el caso de foto, resolución recomendada 1024x768. En el caso de vídeo, resolución recomendada 480x320. |
Section_n |
Númerico 1 (Photo principal) 2 (Video) 3 (File) 4 (Photo gallery) |
Sección donde pertenece el archivo |
Objeto: Stock
Parámetros de entrada del fichero | Tipo | Explicación |
Product Token | Texto (255 carácteres) | Identificador único por referencia |
WarehouseToken | Texto (255 carácteres) | Identificador único por almacén |
Quantity | Númerico | URL con la ubicación y nombre del archivo |
Comments_es | Texto | Mensaje informativo adicional para cada línea de stock con opción a multidioma (_en, _ca, etc.) |
Objeto: Productos Relacionados
Parámetros de entrada del fichero | Tipo | Explicación |
ProductPrimaryToken | Texto (255 carácteres) | Identificador único por producto |
RelatedToken_1 | Texto (255 carácteres) | Identificador único para productos relacionados, puedes indicar mas de uno (RelatedToken_2, RelatedToken_3...) |
Objeto: Familias
Parámetros de entrada del fichero | Tipo | Explicación |
Token | Texto (255 carácteres) | Identificador único para cada familia |
Name_es | Texto (255 carácteres) | Nombre de cada familia con opción multi-idioma ( _en, _ca, etc.) |
CategoryToken | Texto (255 carácteres) | Identificador único de la familia padre en el caso que exista |
Position | Númerico | Posición global de de cada familia |
Objeto: Tasks
Parámetros de entrada del fichero | Tipo | Explicación |
Token | Texto (255 carácteres) | |
Name_es | Text (255 varchar) | |
Date | date time) | |
Description | Text ( varchar ) | |
Form Token | Texto (255 varchar) | |
StatusToken | Text (255 varchar) | |
CompanyToken | Text (255 varchar) | |
UserToken | Text (255 varchar) | |
Regular | boolean ( default 0 ) | |
Priority | int ( 1,2,3) | |
Address | Text (255 varchar) | |
CP | Text (255 varchar) | |
City | Text (255 varchar) | |
Countrystate | Text (optional) | |
Geoposition | ( latitude,longitude ) | |
ContactName | Text (optional) | |
ContactPhone | Text (optional) | |
ContactEmail | Text (optional) | |
Active | boolean | |
TokenGroup | text ( varchar) |