Rest API: Suppliers
Each cost center can have many suppliers, and each supplier brings a list of items. Each of those items has the supplier’s own code and description, a purchase format and a price. A supplier’s item may or may not be linked to a tspoonlab product. You could have the supplier’s whole item list in the system and only link to your products the ones you buy regularly.
System login
To make calls to our APIs, the first thing you need is to authenticate through a login call. That call returns a token that you must then attach to every subsequent call.
This shell script shows how to authenticate using curl:
[email protected]
password=XXXXXXX
url=https://app.tspoonlab.com/recipes/api
authenticate='username='$username'&password='$password
echo -n 'rememberme:' > rememberme.txt
curl -v --data $authenticate $url/login >> rememberme.txt
On later calls, add the token received from the login call to your headers:
curl -X PUT -v -H "$(cat rememberme.txt)" $url/integration/llamada
Rest API: Select a cost center/restaurant
The requests described in the following sections refer to a cost center, which in most cases corresponds to a restaurant. To retrieve the list of cost centers and their identifiers, see the REST API: Cost centers article. The cost center identifier corresponds to the idOrderCenter field of the UserOrderCenter class. Once you have the identifier, add it to the headers so it is used on subsequent calls.
echo -n 'order:351583444167656299610202XXXXXXXXXXXX' >> rememberme.txt
So in your request headers you must specify both the token returned by login and the cost center identifier.
rememberme:aGVucnkudXBzYWxsLmRAZXXXXXXXXXXXXXXXXXX
order:351583444167656299610202XXXXXXXXXXXX
Rest API: List all suppliers
There are two calls:
GET:
https://app.tspoonlab.com/recipes/api/listVendorsPaged
You can pass the following request parameters:
start (int). Required.
rows (int). Required.
filter (String), a string to filter the suppliers. Optional.
hidden (Boolean), returns only the hidden ones. Optional.
It returns:
retorna una List<TypeEntry>
TypeEntry {
String id;
String descr;
String codi;
boolean defecte;
String descrType;
String idType;
EntityBaseDescr orderCenter;
}
EntityBaseDescr {
String id;
String descr;
}
Where:
id is the supplier id.
descr is the supplier name.
codi is the supplier code.
defecte is true when it is the default supplier. A default supplier is the one a purchase is sent to when one of its products has no supplier associated.
idType and descrType identify the supplier type.
Each supplier can be grouped by supplier types (the next section explains how it works).
orderCenter has a value if this supplier is linked to a client of another cost center, typically in environments with a production center.
Rest API: List all supplier types
To list the supplier types:
GET:
https://app.tspoonlab.com/recipes/api/listVendorTypesPaged
You can pass the following request parameters:
start (int). Required.
rows (int). Required.
filter (String), a string to filter the suppliers. Optional.
It returns:
retorna una List<EntityBaseBoolCodi>
EntityBaseBoolCodi {
String id;
String descr;
String codi;
}
Rest API: Create and delete a supplier type
To create a supplier type:
POST:
https://app.tspoonlab.com/recipes/api/vendorType
Passing the following structure in the request body:
NewVendorType {
String descr;
String codi;
String comment;
}
It returns the id of the new supplier type:
IdWrapper {
String id;
}
To delete a supplier type:
DELETE:
https://app.tspoonlab.com/recipes/api/vendorType/{idVendorType}
Where idVendorType is the supplier type id.
Rest API: Create a supplier
To create a supplier:
POST:
https://app.tspoonlab.com/recipes/api/vendor
Passing the following structure in the body:
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;
}Where:
descr is the supplier name.
defecte indicates whether the supplier is the default one (the one you buy a product from if it has no item associated from any supplier).
comment is a comment about the supplier.
mailcc the address that receives a copy when orders are emailed to the supplier.
web the supplier’s website URL.
codi the supplier code.
nif the supplier’s tax ID.
address, city and cp the address and postcode.
creditor indicates whether it is a creditor rather than a supplier.
idVendorType the supplier type it belongs to (null if you don’t want to associate one).
listContact the supplier’s contact list.
listMail all the contact emails for that supplier.
class NewVendorContact {
String descr;
String phone;
}
public class NewVendorMail {
String descr;
}
For NewVendorContact: descr is the contact name; for NewVendorMail: descr is the email.
It returns the id of the new supplier:
IdWrapper {
String id;
}
Rest API: Delete a supplier
A supplier can only be deleted if it has no purchases. If it already has purchases, you can hide it.
DELETE:
https://app.tspoonlab.com/recipes/api/vendor/{idVendor}
idVendor is the supplier id. To hide a supplier:
PUT:
https://app.tspoonlab.com/recipes/api/vendor/{idVendor}/hide
idVendor is the supplier id. To make it visible again:
PUT:
https://app.tspoonlab.com/recipes/api/vendor/{idVendor}/unhide
idVendor is the supplier id.
Rest API: Get a supplier’s data
To get a supplier’s data:
GET:
https://app.tspoonlab.com/recipes/api/vendor/{idVendor}
idVendor is the supplier id. It returns:
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;
}
Where:
id is the supplier id.
descr is the supplier name.
defecte whether it is the default supplier (the one you buy a product from if it has no item associated from any supplier).
comment is a comment.
mailcc the copy address for emailed orders.
web the website URL.
codi the supplier code.
nif the tax ID.
creditor whether it is a supplier or a creditor.
address, city and cp the postal address.
idVendorType the supplier type (null if none).
listContact the contact list and listMail all the contact emails.
VendorContact {
String id;
String descr;
String phone;
}
VendorMail {
String id;
String descr;
}
In VendorContact: descr is the contact name; in VendorMail: descr is the email address.
Let’s look at some fields of the Vendor class in more detail:
....
List<VendorComponent> listComponent;
List<VendorOther> listOther;
....
listComponent holds all the items linked to products. listOther holds the supplier’s items not linked to any product. VendorOther are the supplier’s items not associated with any product.
class VendorOther {
String id;
String descr;
String codi;
Double cost;
String comment;
String lastModified;
}
id is the item id.
descr is the item name for the supplier.
codi is the item code for the supplier.
cost is the item cost.
lastModified the text-format date when the item’s cost was last changed.
The cost is normally expressed in a base unit: for example, if I buy sunflower oil in 5 L drums, unit will be L and the cost corresponds to 1 L.
In comment you can express item information such as the purchase format.
VendorComponent are the items linked to a product for that supplier. It has the same fields as VendorOther but also information about the linked product and the format. When the product was unlinked, the format information could appear in comment, but when we link it to a product we must detail that format more precisely.
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 is the id of the linked product, component the product name. If that product has more than one supplier associated, the defecte field indicates whether this supplier is the default one you usually buy from.
listFormat should always have only one record. Although it is a list, it is advised that if a supplier brings a product in two items, each with its own format, you create two VendorComponent entries, each with one format.
class Format {
String id;
String descr;
String comment;
String codi;
Double costFormat;
String lastModified;
Double quantityFormat;
String unitFormat;
String idUnitFormat;
}
id is the format id.
descr the name the format has for the supplier.
comment is a comment.
codi is the supplier code for that purchase format.
costFormat the format cost (in the 5 L drum case, the cost of the drum).
lastModified the text date of the last cost change.
quantityFormat the format size expressed relative to the unit of VendorComponent (for the 5 L drum of sunflower oil it would be 5), and unitFormat / idUnitFormat the format unit — in our example, Drum.
The Vendor class also includes:
....
List<VendorOrder> listOrders;
....
listOrders are the latest purchases to this supplier.
public class VendorOrder extends EntityBaseDescr {
String idProveidorComanda;
Double cost;
String dateGenerated;
int type;
}
idProveidorComanda is the purchase id.
cost the purchase amount excluding VAT.
dateGenerated the text date when the purchase was made.
type is the purchase status.
A purchase can be pending to send (0), pending to receive (1) or received (2).
Vendor always returns the last 10 purchases to the supplier, but if you want more you can call:
GET:
https://app.tspoonlab.com/recipes/api/vendor/{idVendor}
With the following request parameters:
idVendor (String), the supplier id. Required.
start (int). Required.
rows (int). Required.
filter (String), a string for the orders. Optional.
Rest API: Add/delete an unlinked item
To add an item to the supplier:
POST:
https://app.tspoonlab.com/recipes/api/vendor/{idVendor}/components/other
In the request body you pass the structure:
public class NewVendorOther {
String descr;
String codi;
Double cost;
String comment;
}
Where:
descr is the item name for the supplier.
codi the item code for the supplier.
cost the item cost.
comment usually format information.
It returns the new element created in the VendorOrder class explained earlier; one of the fields of VendorOrder is the id of the newly created item.
To delete an item:
DELETE:
https://app.tspoonlab.com/recipes/api/vendor/{idVendor}/component/{idVendorComponent}
Rest API: Add/delete a linked item
To add items, you can add several items with a single call:
POST:
https://app.tspoonlab.com/recipes/api/vendor/{idVendor}/components/add
In the body you pass the following structure:
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;
}
As explained before, it is advisable that each supplier item has only one format; if it has more than one, several entries would be generated.
For NewVendorComponent, codi, descr, comment are, as in the previous cases, the supplier’s information for the product.
idComponent is the product this item is associated with.
cost is the item cost, which must be expressed in the product’s unit.
defecte will be true if you want this to be the default supplier and item to buy for a product (component).
For NewFormat, codi, descr, comment are the supplier’s information for the product; idUnit and unit are the format units — for our earlier 5 L drum of sunflower oil case, Drum.
The REST API: Units article explains how to create that unit if it does not exist. quantity is the format amount relative to the format unit and the product unit — in our example (1 Drum = 5 L), it would be 5.
cost is the format cost — in our case, the cost of 1 Drum.
To delete an item:
DELETE:
https://app.tspoonlab.com/recipes/api/vendor/{idVendor}/component/{idVendorComponent}
Rest API: Manage purchases
When retrieving the supplier for the Vendor class, we saw it returned a list of purchases (VendorOrder), where each purchase had an idProveidorComanda. Let’s explain how it is structured:
the Order class is a grouping of purchases, for example, all the purchases made on one day. Each one has a list of purchases to different suppliers. Each of those purchases is identified by an idProveidorComanda. So the first thing is to access and create orders.
GET:
https://app.tspoonlab.com/recipes/api/listOrdersPagedExt
You can pass the following request parameters:
start (int). Required.
rows (int). Required.
filter (String), a string to filter the orders. Optional.
Retorna una List<OrderEntry>
class OrderEntry {
string id;
string descr;
String data;
Integer year;
Integer month;
Short pendingSend;
Short pendingReceive;
}
Where:
id is the order id.
descr is the order name.
data is the text date of the order.
year is the order year.
month is the order month.
pendingSend how many purchases are pending to send to the supplier. pendingReceive how many purchases are pending to receive from the supplier.
To create an order:
POST:
https://app.tspoonlab.com/recipes/api/order
Where in the body you pass a NewOrder:
class NewOrder {
String descr;
Date data;
}
descr is the order name and data the order date.
To delete an order:
DELETE:
https://app.tspoonlab.com/recipes/api/order/{idOrder}
To access all the purchases of an order:
POST:
https://app.tspoonlab.com/recipes/api/order/{idOrder}
It returns the Order class:
class Order {
String id;
String descr;
String dateGenerated;
Date data;
Double cost;
Double taxes;
List<OrderVendor> listComandes;
}
id, descr is the order description, dateGenerated the text date of the order and data the order date, cost the sum of the taxable base of all purchases, taxes the sum of all taxes, and listComandes includes OrderVendor, which is each of the purchases.
class OrderVendor {
Strign id;
String idProveidorComanda;
String idVendor;
short status;
String comment;
String dateGenerated;
String dateReceptionFlat;
Double cost;
Double taxes;
List<OrderVendorComponent> listComponents;
id is the order id (not the purchase).
idProveidorComanda is the purchase id.
idVendor is the supplier id.
status indicates whether the purchase is:
Pending to send (0), pending to receive (1) or already received (2).
dateGenerated is the date the order was sent to the supplier.
dateReceptionFlat the date it was received.
cost is the taxable base.
taxes is the sum of all taxes.
listComponents is the list of items bought from the supplier.
class OrderVendorComponent {
Strign id;
String idVendorComponent;
String comment;
boolean rebut;
Double cost;
Double quantity;
Double quantityFormat;
String idUnit;
String idUnitFormat;
String idFormat;
}
id is the line id.
idVendorComponent is the item id for the supplier.
comment is the comment.
rebut is true when the goods have been received.
cost is the product’s unit cost: this cost must be multiplied by quantity or quantityFormat.
If a format was chosen, idFormat takes the value, the amount is reflected in quantityFormat and the unit in idUnitFormat.
If there is no format (i.e. idFormat is null), quantity reflects the amount and idUnit the purchase unit.
To create a purchase, first add the supplier to the order:
POST:
https://app.tspoonlab.com/recipes/api/order/{idOrder}/vendor/{idVendor}
It returns an IdWrapper with the id of the OrderVendor (idProveidorComanda):
IdWrapper {
String id;
}
To add items to the purchase:
PUT:
https://app.tspoonlab.com/recipes/api/orderVendor/{idOrderVendor}/edit
In the body you pass the following structure:
class NewOrderComponentData {
List<NewOrderComponent> components;
}
class NewOrderComponent {
String idVendorComponent;
Double quantity;
Double quantityFormat;
String idUnit;
String idUnitFormat;
String idFormat;
Double cost;
String comment;
}
idVendorComponent is the item id for the supplier.
comment is the comment.
cost is the product’s unit cost: multiply it by quantity or quantityFormat.
If a format was chosen, idFormat takes the value, the amount is in quantityFormat and the unit in idUnitFormat.
If there is no format (idFormat is null), quantity reflects the amount and idUnit the purchase unit.
To delete a purchase, make the following call:
DELETE:
https://app.tspoonlab.com/recipes/api/orderVendor/{id}
Where id is the purchase id.
Did you find this article helpful?
If you need further assistance, contact support by clicking the built-in Support Chat in the bottom-right corner of your screen.