1. Proveedores

Cada centro de coste puede tener muchos porveedores y cada proveedor nos trae una lista de árticulos. Cada uno de esos artículos tiene un código y descripción propio del proveedor, un formato de compra y un precio. Un artículo de un proveedor puede estar relacionado con un producto de tspoonlab o no.

Podriamos tener toda la lista de artículos del proveedor en el sistema y solo asociar a nuestros productos aquellos que compramos habitualmente

1.1. Rest API : Login

Para poder hacer llamadas a nuestas api's lo primero que ncesitamos es identificarnos mediante una llamada de login

Esa llamada nos retornara una token que después debemos asociar en cada llamada posterior.

Este shell script muestra como authenticar-nos mediante curl

[email protected]
password=XXXXXXX

url=https://www.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password

echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt

En las llamadas posteriores debemos añadir a nuestros headers el token recibido de la llamada de login

curl -X PUT -v -H "$(cat rememberme.txt)" $url/integration/llamada

1.2. Rest API : Seleccionar un centro de coste/restaurante

Las peticiones que se describen en los apartados siguientes hacen referencia a un centro de coste. Que en la mayoría de los casos se correspondería con un restaurante

Para recuperar la lista de centros de costes y sus identificadores consulta el documento

http://documents.tspoonlab.com/es/articles/4197646-rest-api-obtener-una-lista-de-centros-de-coste

El identificador de cenetro de coste se corresponde al campo idOrderCenter de la classe UserOrderCenter

Una vez tenemos el identificador este deberá añadirse a los headers para que sea utilizado en llamadas posteriores

echo -n 'order:351583444167656299610202XXXXXXXXXXXX' >> rememberme.txt

Por tanto en nuestros request headers debemos especificar tanto el token devuelto por el login como el identificador del centro de coste

rememberme:aGVucnkudXBzYWxsLmRAZXXXXXXXXXXXXXXXXXX
order:351583444167656299610202XXXXXXXXXXXX

1.3. Rest API : Listar todos proveedores

Tenemos dos llamadas

GET: 
https://www.tspoonlab.com/recipes/api/listVendorsPaged

Podemos pasar los siguentes request params

start (int). Número de la primera fila a retornar. Es obligatorio
rows (int). Número de filas a retornar. Es obligatorio
filter (String). Cadena para filtrar los proveedores Es opcional
hidden (Boolean). Retorna solo los ocultos. Es opcional

Retorna

retorna una List<TypeEntry> 

TypeEntry {
  String id;
  String descr;
  String codi;
  boolean defecte;
  String descrType;
  String idType;
  EntityBaseDescr orderCenter;
}

EntityBaseDescr {
  String id;
  String descr;
}

Donde

id es el identificador del proveedor

descr el nombre del proveedor

codi el código del proveedor

defecte es true cuando es el proveedor por defecto. Un proveedor por defecto es aquel donde vamos a enviar una compra si en ella uno de sus productos no tiene asociado ningun proveedor

idType y descrType nos identificat el tipo de proveedor. Cada proveedor se puede agrupar por tipos de forma que podemos clasificarlos. En el apartado siguiente se explica el funcionamiento

orderCenter tendrà valor si este proveedor está relacionado con un cliente de otro centro de coste. Normalmente en entornos donde hay un centro de producción

1.4. Rest API : Listar todos los tipos de proveedores

Para listar los tipos de proveedor

GET: 
https://www.tspoonlab.com/recipes/api/listVendorTypesPaged

Podemos pasar los siguentes request params

start (int). Número de la primera fila a retornar. Es obligatorio
rows (int). Número de filas a retornar. Es obligatorio
filter (String). Cadena para filtrar los proveedores Es opcional

Retorna

retorna una List<EntityBaseBoolCodi> 

EntityBaseBoolCodi {
  String id;
  String descr;
  String codi;
}

1.5. Rest API : Crear y eliminar un tipo de proveedor

Para crear un tipo de proveedor

POST: 
https://www.tspoonlab.com/recipes/api/vendorType

Pasando en el request body la siguiente estructura

NewVendorType {

 String descr;
 String codi;
 String comment;
}

Retorna el identificador del nuevo tipo de proveedor

IdWrapper {
  String id;
}

Para eliminar un tipo de proveedor

DELETE: 
https://www.tspoonlab.com/recipes/api/vendorType/{idVendorType}

Donde idVendorType es el identificador del tipo de proveedor

1.6. Rest API : Crear un proveedor

Para crear un proveedor

POST: 
https://www.tspoonlab.com/recipes/api/vendor

Pasando en el body la siguiente estrucutra

NewVendor {

 String descr;
 Boolean defecte;
 String comment;
 String mailcc;
 String web;
 String codi;
 String nif;
 String address;
 String city;
 String cp;
 boolean creditor;
 String idVendorType;
 List<NewVendorContact> listContact;
 List<NewVendorMail> listMail;
}

Donde

descr es el nombre del proveedor

defecte nos indica si el proveedor es el proveedor por defecto. Aquel al que compraremos un producto si no tiene asociado ningun artículo de ningún proveedor

comment un comentario sobre el proveedor

mailcc al enviar pedidos por correo al proveedor se enviará una copia a este mail

web dirección http de la web del proveedor

codi código del proveedor

nif idenficación fiscar del proveedor

address, city y cp nos indican la dirección postal del mismo

creditor indica si se trata de un acreedor y no de un proveeodor

idVendorType es el tipo de proveedor al que pertenece. Nulo si no queremos asociar ninguno

listContact es la lista de contactos de ese proveedor

listMail son todos los mails de contacto con ese proveedor

class NewVendorContact {

 String descr;
 String phone;
}

public class NewVendorMail {

  String descr;
}

Para NewVendorContact descr es el nombre del contacto y para NewVendorMail descr es el mail

Retorna el identificador del nuevo proveedor

IdWrapper {
  String id;
}

1.7. Rest API : Borrar un proveedor

Un proveedor solo se puede borrar si no tiene ninguna compra. Si ya tiene compras lo que podemos hacer es ocultarlo

DELETE: 
https://www.tspoonlab.com/recipes/api/vendor/{idVendor}

idVendor es el identificador del proveedor

Para ocultar un proveedor

PUT: 
https://www.tspoonlab.com/recipes/api//vendor/{idVendor}/hide

idVendor es el identificador del proveedor

Para volver a hacer visible

PUT: 
https://www.tspoonlab.com/recipes/api//vendor/{idVendor}/unhide

idVendor es el identificador del proveedor

1.8. Rest API : Obtener los datos de un proveedor

Para obtener los datos de un proveedor

GET: 
https://www.tspoonlab.com/recipes/api/vendor/{idVendor}

idVendor es el identificador del proveedor

Nos retorna

class Vendor {
 String id;
 String descr;
 Boolean defecte;
 String comment;
 String mailcc;
 String web;
 String codi;
 String nif;
 boolean creditor;
 String address;
 String city;
 String cp;
 List<VendorContact> listContact;
 List<VendorMail> listMail;
 List<VendorComponent> listComponent;
 List<VendorOther> listOther;
 List<VendorOrder> listOrders;
}

Donde

id es el identificador del proveedor

descr es el nombre del proveedor

defecte nos indica si el proveedor es el proveedor por defecto. Aquel al que compraremos un producto si no tiene asociado ningun artículo de ningún proveedor

comment un comentario sobre el proveedor

mailcc al enviar pedidos por correo al proveedor se enviará una copia a este mail

web dirección http de la web del proveedor

codi código del proveedor

nif idenficación fiscar del proveedor

creditor indica si es un proveedor o un acreedor

address, city y cp nos indican la dirección postal del mismo

idVendorType es el tipo de proveedor al que pertenece. Nulo si no queremos asociar ninguno

listContact es la lista de contactos de ese proveedor

listMail son todos los mails de contacto con ese proveedor

VendorContact {
  String id;
  String descr;
  String phone;
}

VendorMail {
  String id;
  String descr;
}

En VendorContact descr es el nombre del contacto y en VendorMail descr es el la dirección de correo electrónico

Vamos a analizar con más detalle algunos campos de la clase Vendor

....

 List<VendorComponent> listComponent;
 List<VendorOther> listOther;
....

listComponent son todos los artículos vinculados a productos

y listOther aquellos artículos del proveedor no vinculados a ningún producto

VendorOther serian los artículos del proveedor que no estan asociados a ningún producto.

class VendorOther {

 String id;
 String descr;
 String codi;
 Double cost;
 String comment;
 String lastModified;
}

id es el identificador del artículo

descr es el nombre del artículo para el proveedor

codi es el código del artículo para el proveedor

cost es el coste del artículo

lastModified es la fecha en formato texto de cuando se modifico por última vez el coste de este artículo

El coste normalmente se expresa en una unidad básica. Es decir si compro aceite de girasol en garrafas de 5L unit sera L y el coste se correspondera a 1L

En comment podemos expresar información del artículo como por ejemplo el formato de compra

VendorComponent son los artículos vinculados a un producto de ese proveedor

Tiene los mismos campos que VendorOther pero además tiene información del producto al que esta vinculado y del formato. Cuando el producto estava desvinculado la información del formato podia aparecer en comment pero cuando lo vinculamos a un producto debemos detallar con más precisión ese formato

public class VendorComponent {

 String id;
 String descr;
 String codi;
 Double cost;
 String comment;
 String lastModified;
 String unit;
 String idUnit;

 Boolean defecte;
 String idComponent;
 String component;
 List<Format> listFormat;
}

idComponent es el identificador del producto al que esta vinculado

component es el nombre del producto

Si ese producto tiene más de un proveedor asociado el camp defecte nos indica si este proveedor es el proveedor por defecto al que compraremos habitualmente

listFormat debe tener siempre solo un registro. A pesar de ser una lista se aconseja que si un proveedor trae un producto en dos artículos cada uno con su propio formato se creen dos entradas de VendorComponent cada una con un formato

class Format  {

 String id;
 String descr;
 String comment;
 String codi;
 Double costFormat;
 String lastModified;
 Double quantityFormat;
 String unitFormat;
 String idUnitFormat;
}

id es el identificador del formato

descr es el nombre que para el proveedor tiene ese formato de compra

comment comentario

codi código del proveedor para ese formato de compra

costFormat es el coste del formato (En el caso anterior de la garrafa de 5L es el coste de la garrafa)

lastModified es la fecha en texto de la fecha de la última modificación del coste

quantityFormat es el tamaño del formato expresado respecto a la unit de VendorComponent en el caso de la garrafa de 5L de aceite de girasol seria 5.

unitFormat y idUnitFormat serian la unidad del formato en nuestro ejemplo Garrafa

En la clase vendor también tenemos

....

 List<VendorOrder> listOrders;

....

listOrders son las últimas compras a este proveedor

public class VendorOrder extends EntityBaseDescr {

 String idProveidorComanda;
 Double cost;
 String dateGenerated;
 int type;
}

idProveidorComanda es el identificador de la compra

cost el importe sin iva de la compra.

dateGenerated la fecha en texto de cuando se realizo la compra

type es el estado de la compra. Una compra puede estar pendinte de enviar (0), pendiente de recibir (1) y recibida (2)

En Vendor siempre retorna las últimas 10 comrpas al proveedor. Pero si quisieramos obtener más podemos llamar a

GET: 
https://www.tspoonlab.com/recipes/api//vendor/{idVendor}

Con los siguientes párametros en la petición

idVendor(String). Idenitificador del proveedor

start (int). Número de la primera fila a retornar. Es obligatorio

rows (int). Número de filas a retornar. Es obligatorio

filter (String). Cadena para los pedidos

1.9. Rest API : Añadir / eliminar un articulo no vinculado a ningun produto

Para añadir un artículo al proveedor

POST: 
https://www.tspoonlab.com/recipes/api/vendor/{idVendor}/components/other

En el body de la petición pasaremos la estructura

public class NewVendorOther {

 String descr;
 String codi;
 Double cost;
 String comment;

}

Donde

descr es el nombre del artículo para el proveedor

codi es el código del artículo para el proveedor

cost es el coste del artículo

comment normalmente información de formato

Retorna el nuevo elemento creado en la clase VendorOrder explicada anteriormente. Uno de los camps de VendorOrder es el id del nuevo artículo creado

Para eliminar un artículo.

DELETE: 
https://www.tspoonlab.com/recipes/api/vendor/{idVendor}/component/{idVendorComponent}

1.10. Rest API : Añadir / eliminar un articulo vinculado a un producto

Para añadir artículos podemos añadir varios artículos con una sola llamada

POST: 
https://www.tspoonlab.com/recipes/api/vendor/{idVendor}/components/add

Donde en el body pasaremos la siguiente estructura

class NewVendorComponentWrapper {
 List<NewVendorComponent> components;
}

class NewVendorComponent {

 String codi;
 String descr;
 String comment;
 String idComponent;
 Double cost;
 Boolean defecte;
 List<NewFormat> listFormat;
}

public class NewFormat {
 String codi;
 String descr;
 String comment;
 String idUnit;
 Double quantity;
 Double cost;
}

Cada vendor es aconsejable como se ha explicado antes que tenga solo un formato. En caso de tener más de un formato se generarian varias entradas

Para NewVendorComponent

codi, descr, comment son como en los casos anteriores la información del proveedor para el producto

idComponent es el producto al que asociamos este articulo

cost es el coste del artículo que debe ir expresado en la unidad del component

defecte sera true si queremos aque este sea el proveedor y artículo a comprar por defecto para un producto (component)

Para NewFormat

codi, descr, comment son como en los casos anteriores la información del proveedor para el producto

idUnit y unit son las unidades del formato. Para nuestro caso anterior de la Garrafa de 5L de aceite de girasol seria Garrafa. En el documento relativo a como trabajar con la Api de unidades se explica como crear esa unidad en caso de que no existiera.

quantity es la cantidad del formato relativa a la unidad del formato y la unidad del producto. En nuestro ejemplo (1 Garrafa = 5L) seria 5

cost es el costo del formato en nuestro caso el coste de 1 Garrafa

Para eliminar un artículo.

DELETE: 
https://www.tspoonlab.com/recipes/api/vendor/{idVendor}/component/{idVendorComponent}

1.11. Rest API : Gestionar compras

Al recuperar el proveedor para la clase Vendor hemos visto que nos retornaba una lista de compras VendorOrder donde cada compra tenia un idProveidorComada.

Vamos a explicar como está estrucurado.

La clase Pedido es una agrupación de compras. Por ejemplo todas las compras que se realizan en un dia. Cada una de ellas tiene una lista de compras a distindos proveedores. Cada una de esas compras se identifica con un idProveidorComada

Por tanto lo primero es acceder y crear pedidos

GET: 
https://www.tspoonlab.com/recipes/api/listOrdersPagedExt

Podemos pasar los siguentes request params

start (int). Número de la primera fila a retornar. Es obligatorio
rows (int). Número de filas a retornar. Es obligatorio
filter (String). Cadena para filtrar los pedidos Es opcional

Retorna una List<OrderEntry>

class OrderEntry  {

  string id;
  string descr;
  String data;
  Integer year;
  Integer month;
  Short pendingSend;
  Short pendingReceive;
}

donde id es el identificador del pedido

descr es el nombre del pedido

data es la fecha en texto del pedido

year año del pedido

month mes del pedido

pendingSend cuantas compras estan pendientes de enviar al proveedor

pendingReceive cuandas compras estan pendientes de recibir del proveedor

Para crear un pedido

POST: 
https://www.tspoonlab.com/recipes/api/order

Donde en el body pasamos un NewOrder

class NewOrder {
 String descr;
 Date data;
}

descr es el nombre del pedido y data la fecha del pedido

Para eliminar un pedido

DELETE: 
https://www.tspoonlab.com/recipes/api/order/{idOrder}

Para acceder a todas las compras de un pedido

POST: 
https://www.tspoonlab.com/recipes/api/order/{idOrder}

Retorna la clase Order

class Order {

 String id;
 String descr;
 String dateGenerated;
 Date data;
 Double cost;
 Double taxes;
 List<OrderVendor> listComandes;
}

id, descr es la descripción del pedido

dateGenerated es la fecha del pedido en texto y data es la fecha del pedido.

cost es la suma de la base imponible de todas compras

taxes es la suma de todos los impuestos

listComandes incluye OrderVendor que es cada una de las compras

class OrderVendor {

 Strign id;
 String idProveidorComanda;
 String idVendor; 
 short status;
 String comment;
 
 String dateGenerated;
 String dateReceptionFlat;


 Double cost;
 Double taxes;

 List<OrderVendorComponent> listComponents;

id es el identificador del pedido (Ojo no de la compra)
idProvieodrComada es el identificador de la compra

idVendor es el identificador del proveedor

status nos indica si la compra está pendiente de enviar al proveedor (0), si está pendiente de recibir (1) o si ya está recibida (2)

dateGenerated es la fecha en que se envio el pedido al proveedor

dateReceptionFlat es la fecha en que se recibio el pedido

cost es la la base imponible

taxes es la suma de todos los impuestos

listComponents es la lista de artículos que le compramos al proveedor

class OrderVendorComponent {

 Strign id;
 String idVendorComponent;
 String comment;
 boolean rebut;
 Double cost;
 
 Double quantity;
 Double quantityFormat;
 String idUnit;
 String idUnitFormat;
 String idFormat;
}

id es el identificador de la linia

idVendorComponent es el identificador del artículo para el proveedor

comment es el comentario

rebut si true indica que se ha recibido la mercancia

cost es el coste unitario del producto

Este coste hay que multiplicarlo por quantity o quantityFormat.

En caso que hayamos escogido un formato idFormat toma valor y la cantidad se refleja en quantityFormat y la unidad en idUnitFormat

En caso de que no haya formato (es decir idFormat es null) quantity refleja la cantidad y idUnit la unidad de compra.

Para crear una compra primero añadiremos el proveedor al pedido

POST: 
https://www.tspoonlab.com/recipes/api/order/{idOrder}/vendor/{idVendor}

Nos retorna un IdWrapper con el identificador del OrderVendor (ProveidorComanda)

IdWrapper {
  String id;
}

Para añadir articulos a la compra

PUT: 
https://www.tspoonlab.com/recipes/api/orderVendor/{idOrderVendor}/edit

En el body pasamos la siguiente estructura

class NewOrderComponentData {

 List<NewOrderComponent> components;
}

class NewOrderComponent {

 String idVendorComponent;
 Double quantity;
 Double quantityFormat;
 String idUnit;
 String idUnitFormat;
 String idFormat;
 Double cost;
 String comment;
}

idVendorComponent es el identificador del artículo para el proveedor

comment es el comentario

cost es el coste unitario del producto

Este coste hay que multiplicarlo por quantity o quantityFormat.

En caso que hayamos escogido un formato idFormat toma valor y la cantidad se refleja en quantityFormat y la unidad en idUnitFormat

En caso de que no haya formato (es decir idFormat es null) quantity refleja la cantidad y idUnit la unidad de compra.

Para borrar una compra debemos realizar la siguiente llamada

DELETE: 
https://www.tspoonlab.com/recipes/api/orderVendor/{id}

Donde id es el identificador de la compra