Rest API: Proveedores
Cada centro de coste puede tener muchos proveedores y cada proveedor nos trae una lista de artículos. 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.
Podríamos tener toda la lista de artículos del proveedor en el sistema y solo asociar a nuestros productos aquellos que compramos habitualmente
Rest API: Login
Para poder hacer llamadas a nuestras api's lo primero que necesitamos es identificarnos mediante una llamada de login.
Esa llamada nos retornará una token que después debemos asociar en cada llamada posterior.
Este shell script muestra como autenticarnos 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
Rest API: Seleccionar un centro de coste/restaurante
Las peticiones que se describen en los apartados siguientes hacen referencia a un centro de coste, 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 artículo Rest API: Centros de coste.
El identificador de centro de coste se corresponde al campo idOrderCenter de la clase 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
Rest API: Listar todos proveedores
Tenemos dos llamadas:
GET:
https://www.tspoonlab.com/recipes/api/listVendorsPaged
Podemos pasar los siguientes request parameters:
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 ningún proveedor.
idType y descrType nos identifica el tipo de proveedor. Cada proveedor se puede agrupar por tipos de proveedores. 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.
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 siguientes request parameters:
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;
}
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
Rest API: Crear un proveedor
Para crear un proveedor:
POST:
https://www.tspoonlab.com/recipes/api/vendor
Pasando en el body la siguiente estructura:
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 es el código del proveedor.
nif es la identificación fiscal del proveedor.
address, city y cp nos indican la dirección y código postal del mismo.
creditor indica si se trata de un acreedor y no de un proveedor.
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;
}
Rest API : Borrar un proveedor
Un proveedor solo se puede borrar si no tiene ninguna compra. Si ya tiene compras podemos 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.
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 ningún 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 es el código del proveedor.
nif es la identificación fiscal 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.
listOther son aquellos artículos del proveedor no vinculados a ningún producto.
VendorOther serian los artículos del proveedor que no están 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 modificó 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 corresponderá 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 está vinculado y del formato. Cuando el producto estaba desvinculado la información del formato podía 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 está 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 crean 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 es un comentario.
codi es el 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 sería 5.
unitFormat y idUnitFormat serían 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 realizó la compra.
type es el estado de la compra. Una compra puede estar pendiente de enviar(0), pendiente de recibir(1) y recibida(2).
En Vendor siempre retorna las últimas 10 compras al proveedor. Pero si quisiéramos obtener más podemos llamar a:
GET:
https://www.tspoonlab.com/recipes/api//vendor/{idVendor}
Con los siguientes parámetros en la petición:
idVendor(String): Identificador 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.
Rest API : Añadir/eliminar un artículo no vinculado
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 campos 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}
Rest API : Añadir/eliminar un articulo vinculado
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
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;
}
Es aconsejable, como se ha explicado antes, que cada vendor tenga solo un formato. En caso de tener más de un formato se generarían 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 artículo.
cost es el coste del artículo que debe ir expresado en la unidad del component.
defecte será true si queremos que éste 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 artículo Rest API: Unidades se explica cómo 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) sería 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}
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 tenía un idProveidorComanda.
Vamos a explicar cómo está estructurado:
La clase Pedido es una agrupación de compras. Por ejemplo: todas las compras que se realizan en un día. Cada una de ellas tiene una lista de compras a distintos proveedores. Cada una de esas compras se identifica con un idProveidorComanda.
Por lo tanto, lo primero es acceder y crear pedidos.
GET:
https://www.tspoonlab.com/recipes/api/listOrdersPagedExt
Podemos pasar los siguientes request parameters:
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 es el año del pedido.
month es el mes del pedido.
pendingSend cuántas compras están pendientes de enviar al proveedor.
pendingReceive cuántas compras están 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 (no de la compra).
idProviedorComanda 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 envió el pedido al proveedor.
dateReceptionFlat es la fecha en que se recibió el pedido.
cost es 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 línea.
idVendorComponent es el identificador del artículo para el proveedor.
comment es el comentario.
rebut si es true indica que se ha recibido la mercancía.
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 el 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 (idProveidorComanda):
IdWrapper {
String id;
}
Para añadir artículos 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 el 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.
¿Te ha resultado útil este artículo?
Si necesitas más ayuda, contacta con soporte haciendo clic en el Chat de Soporte Integrado en la esquina inferior derecha de tu pantalla.