{"info":{"_postman_id":"d902a3d1-a6f9-4eb2-8ec8-6c21b08bc330","name":"Supplier Portal API","description":"

This documentation offers a comprehensive guide to working with the Yucopia Supplier API and integrating your environment with our platform.

What is Yucopia

Yucopia is a platform that enables businesses, federations & governments to manage their suppliers, contracts and purchases. A user does not need to know from which supplier a certain product should be bought. The user can just search in our marketplace for that product and order it like in any regular e-commerce.
When an order is created, the purchase processes of the company are enforced by the software. When the correct validation and administrative steps are completed, the order is sent to the supplier.

Key concepts

Marketplace: A customer can have multiple marketplaces active in Yucopia. First of all, there is the “Yucopia marketplace” where all suppliers can be found that have a direct agreement with Yucopia. Secondly, the “Contract marketplace” exists where all suppliers are present that have a contract with the customer. Lastly, other marketplaces can be created. For example, a local marketplace with only local suppliers.

Catalogs: As a supplier it is possible to upload multiple catalogs to Yucopia. This makes it possible to set specific products at custom prices available for certain customers. A catalog can be available for one or multiple customers or can be a general catalog that is available to everyone.

Order: An order is created by a customer. This order contains a list of order lines. An order can contain products from multiple suppliers. Every order gets a unique PO number (= GCO Number).

Supplier order: A supplier order is the order that is sent to the supplier. When the customer creates an order that has products of 3 different suppliers, that order will be split up into 3 supplier orders. Every supplier then gets notified about their specific supplier order.

Validation workflow: When an order is created, the order might need to go through a validation process. This process can be fully configured by the customer. The order is only sent to suppliers when the order is approved in the validation flow.

Getting started

Below we describe the steps that need to be taken in order to offer your products on Yucopia.

Introduction

The Yucopia supplier API is a REST API. It uses resource based urls, accepts JSON-encoded request bodies and returns JSON encoded responses in combination with HTTP response codes.

The base URL for the API is: https://api.yucopia.com

We also support a testing environment on: https://accept-api.yucopia.com

Before you can use the Supplier API you need to request access. This access can be requested by sending an email to support@yucopia.com. When this is granted, you will receive a unique API key that can be used to authenticate yourself. This is necessary to access all authorized endpoints.

Product catalog import

In order to offer products on Yucopia, a product catalog needs to be uploaded. The following
information should always be present in a product catalog for each product:

Internal reference
GTIN (= EAN, UPC, ISBN or other global unique product identifier)
Product title
Product description
Price excl. VAT
VAT %
Optional: End date (=how long this product can be sold at this price. If date is reached, the product is
no longer offered on Yucopia, until the end date is updated)
1 – 10 image urls

It is possible to provide multiple catalogs. You can upload your general catalog or customer-specific catalogs. When no customer VAT number is provided, we view the
catalog as your general catalog (more on how to provide customer VAT later). This catalog will be offered to every customer that does not have a
personal catalog.

When a specific customer VAT number is provided, the catalog is only available for that specific
customer. This makes it possible to offer the same product to multiple customers, with different
prices.

The uploaded product catalog is not immediatly processed for performance reasons, your product catalog will be processed within the hour. After that period your products will become available in Yucopia.

How to upload a product catalog is described below.

A: Upload a product catalog using the API endpoint

If you want to supply a product catalog for a specific customer you can use the customerVat query parameter.

An array of product objects can be sent in the request body. New products must have the fields described above and may also contain additional data fields which will also be processed and saved in the Yucopia system. When your products are already in Yucopia, the endpoint only requires the internal reference field and will update the existing products with the additional fields you supply for that product.

We recommend sending a request body size of maximum 15MB. You can make multiple requests to upload/update your full product catalog in the Yucopia system.

An additional endpoint is available in the docs to retire products using your internal reference.

B: Upload a product catalog using .csv or .xslx file

First, download the template through the following link: https://asset.cloudinary.com/dkcrk6eho/4e4e77107d0df8e8c042a4183cfbae41

The .xslx file contains 5 tabs :

Company information : this is the information about your company that we need in order to
create your company as a supplier
Fields: This describes the product information that our system expects.
Example: This gives an example about how the Articles tab should be filled in
Articles: The action product data should be filled in here
Yucopia categories: Every product of the Articles tab should be in one of the Yucopia
categories in order to be offered on Yucopia. If you cannot find a relevant Yucopia category,
contact support@yucopia.com to request new categories.

When the .xlsx file is fully filled in with all product that should be offered on Yucopia. The file can be
sent to leveranciers@yucopia.com. Our system will then process this file and offer the products on
the platform.

To upload a catalog for a specific customer, give the file the VAT number of that company as a name.
F.ex. BE0123456789.xslx

Multiple languages

It is possible to provide the product title and description in multiple language. Yucopia supports
Dutch, French and English at the moment.

Update product offer via excel/csv

Updating your catalogs can be done using the exact same method as described above. It is
important, however, to use the full catalog with the updated data.

When sending an updated catalog, our system will:

Add all products that were not previously present in the catalog
Update the products that have been altered
Set the products inactive that are no longer present in your catalog

This means that, whenever you try to update your products, it is important to send the full catalog
with the updated data. All products that are not present in the csv/xslx file, will no longer be
available on Yucopia.

Stock

In order to make sure that products are only ordered when they are in stock, you can keep track of your stock in Yucopia. We provide an API endpoint which can be used to let us know how much stock you have for a certain product (or list of products).

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"18799737","collectionId":"d902a3d1-a6f9-4eb2-8ec8-6c21b08bc330","publishedId":"2s84DkV5ps","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2024-05-23T08:45:13.000Z"},"item":[{"name":"Product catalog","id":"c3fa075d-35fd-4c0d-8fcf-f591d372c19a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"api-key","value":"string","description":"

required

\n","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"products\": [\r\n {\r\n \"internalReference\": \"string\",\r\n \"description_NL\": \"string\",\r\n \"description_FR\": \"string\",\r\n \"description_EN\": \"string\",\r\n \"title_NL\": \"string\",\r\n \"title_FR\": \"string\",\r\n \"title_EN\": \"string\",\r\n \"priceExclVAT\": 0,\r\n \"VAT\": 0,\r\n \"YucopiaCategory\": \"string\",\r\n \"offerEndDate\": \"ISO 8601 date\",\r\n \"images\": [\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\"\r\n ]\r\n }\r\n ]\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.yucopia.com/api/v2/supplier-articles/product-catalog?customerVat=string","description":"

Formatting rules:

Prices with dot notation and max 2 numbers after comma => 2.21

VAT can be supplied as integers, eg. 0, 6 or 21.

optional

\n","type":"text/plain"},"key":"customerVat","value":"string"}],"variable":[]}},"response":[{"id":"28c9919b-ae2c-429a-9aa4-4d609c84d083","name":"supplier-catalog","originalRequest":{"method":"POST","header":[{"key":"api-key","value":"string","description":"required","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"products\": [\r\n {\r\n \"internalReference\": \"string\",\r\n \"description_NL\": \"string\",\r\n \"description_FR\": \"string\",\r\n \"description_EN\": \"string\",\r\n \"title_NL\": \"string\",\r\n \"title_FR\": \"string\",\r\n \"title_EN\": \"string\",\r\n \"priceExclVAT\": \"number\",\r\n \"VAT\": \"number\",\r\n \"YucopiaCategory\": \"string\",\r\n \"images\": [\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n ]\r\n }\r\n ]\r\n}"},"url":{"raw":"https://api.yucopia.com/api/v2/supplier-articles/product-catalog?customerVat=string","protocol":"https","host":["api","yucopia","com"],"path":["api","v2","supplier-articles","product-catalog"],"query":[{"key":"customerVat","value":"string","description":"optional"}]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"[\r\n {\r\n \"internalReference\": \"string\",\r\n \"description_NL\": \"string\",\r\n \"description_FR\": \"string\",\r\n \"description_EN\": \"string\",\r\n \"title_NL\": \"string\",\r\n \"title_FR\": \"string\",\r\n \"title_EN\": \"string\",\r\n \"priceExclVAT\": \"number\",\r\n \"VAT\": \"number\",\r\n \"YucopiaCategory\": \"string\",\r\n \"images\": [\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\",\r\n \"string\"\r\n ]\r\n }\r\n]"}],"_postman_id":"c3fa075d-35fd-4c0d-8fcf-f591d372c19a"},{"name":"Delete Product Catalog","id":"cd78272e-9076-46eb-83ec-ec23dc7bddc5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"api-key","value":"string","type":"text"}],"url":"https://api.yucopia.com/api/v2/supplier-articles/product-catalog/:internalReference?customerVat=string","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"api-key"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"d902a3d1-a6f9-4eb2-8ec8-6c21b08bc330","id":"d902a3d1-a6f9-4eb2-8ec8-6c21b08bc330","name":"Supplier Portal API","type":"collection"}},"urlObject":{"path":["api","v2","supplier-articles","product-catalog",":internalReference"],"host":["https://api.yucopia.com"],"query":[{"description":{"content":"

optional

\n","type":"text/plain"},"key":"customerVat","value":"string"}],"variable":[{"id":"ecca6808-a342-4514-8f14-f97139cd1e50","description":{"content":"

required

\n","type":"text/plain"},"type":"any","value":"string","key":"internalReference"}]}},"response":[{"id":"fa9a18e5-d339-4108-a3f2-0825c454fdf1","name":"removeFromCatalog","originalRequest":{"method":"DELETE","header":[],"url":{"raw":"https://api.yucopia.com/api/v2/supplier-articles/product-catalog/:articleNumberSupplier?customerVat=string","protocol":"https","host":["api","yucopia","com"],"path":["api","v2","supplier-articles","product-catalog",":articleNumberSupplier"],"query":[{"key":"customerVat","value":"string","description":"optional"}],"variable":[{"key":"articleNumberSupplier","value":"string","description":"required"}]}},"code":204,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"cd78272e-9076-46eb-83ec-ec23dc7bddc5"},{"name":"Stock","id":"776dd6f7-34fb-4ed1-bc72-5ec8a6cf16fc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"[\r\n {\r\n \"articleNumberSupplier\": \"string\",\r\n \"stockNumber\": \"number\"\r\n }\r\n]","options":{"raw":{"language":"json"}}},"url":"https://api.yucopia.com/api/stock","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"api-key"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"d902a3d1-a6f9-4eb2-8ec8-6c21b08bc330","id":"d902a3d1-a6f9-4eb2-8ec8-6c21b08bc330","name":"Supplier Portal API","type":"collection"}},"urlObject":{"path":["api","stock"],"host":["https://api.yucopia.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"776dd6f7-34fb-4ed1-bc72-5ec8a6cf16fc"},{"name":"Get supplier orders","id":"c7ecb546-6219-4e73-ae4a-4f3e5b844a5d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"body":{"mode":"raw","raw":"[\r\n {\r\n \"gcsNumber\": \"string\",\r\n \"orderNumberSupplier\": \"string\",\r\n \"clientValidated\": true,\r\n \"supplierOrderLines\": [\r\n {\r\n \"supplierArticle\": {\r\n \"articleNumberSupplier\": \"string\",\r\n \"price\": \"string\",\r\n \"currency\": \"string\",\r\n \"tax\": \"string\",\r\n \"shortDescriptions\": [\r\n {\r\n \"description\": \"string\",\r\n \"languageCode\": \"string\"\r\n }\r\n ],\r\n \"longDescriptions\": [\r\n {\r\n \"description\": \"string\",\r\n \"languageCode\": \"string\"\r\n }\r\n ],\r\n \"stock\": 0\r\n },\r\n \"quantity\": 0,\r\n \"chargedUnitPrice\": \"string\",\r\n \"lineNumber\": 0,\r\n \"quantityToBeDelivered\": 0,\r\n \"replacement\": true,\r\n \"unitPriceExcl\": \"string\",\r\n \"vat\": \"string\"\r\n }\r\n ],\r\n \"supplierId\": \"string\",\r\n \"orderDate\": \"string\",\r\n \"orderStatus\": \"string\",\r\n \"deliveryAddress\": {\r\n \"id\": \"string\",\r\n \"countryCode\": \"string\",\r\n \"street\": \"string\",\r\n \"houseNumber\": \"string\",\r\n \"bus\": \"string\",\r\n \"zipCode\": \"string\",\r\n \"city\": \"string\",\r\n \"description\": \"string\",\r\n \"addressee\": \"string\",\r\n \"defaultAddress\": \"boolean\",\r\n \"department\": \"string\"\r\n },\r\n \"customer\": {\r\n \"name\": \"string\",\r\n \"vatNumber\": \"string\",\r\n \"juridicalFrom\": \"string\",\r\n \"generalEmail\": \"string\"\r\n },\r\n \"relatedOrders\": [\r\n {\r\n \"gcoNumber\": \"string\",\r\n \"budgetReference\": \"string\",\r\n \"totalPriceExcl\": \"number\"\r\n }\r\n ]\r\n }\r\n]","options":{"raw":{"language":"json"}}},"url":"https://api.yucopia.com/api/order-flow/supplier-orders?date=2022-09-15T08:50:44.203842Z","description":"

By default this endpoint will return the orders from the past 7 days.

(optional) format: ISO 8601, if present the endpoint will only return supplier orders later than the given date

\n","type":"text/plain"},"key":"date","value":"2022-09-15T08:50:44.203842Z"}],"variable":[]}},"response":[],"_postman_id":"c7ecb546-6219-4e73-ae4a-4f3e5b844a5d"},{"name":"Confirm orders","id":"f706e31d-43f4-47f2-8e02-7756dc510e06","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"orderNumber\": \"string\",\r\n \"orderResponseLines\": [\r\n {\r\n \"articleNumberSupplier\": \"string\",\r\n \"delivery\": {\r\n \"quantityToBeDelivered\": 2\r\n }\r\n }\r\n ] \r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.yucopia.com/api/order-flow/supplier-order-confirmed","description":"

When our system notifies you about a new order, you can send an order confirmation to the Yucopia system. This lets the user know that the order was successfully received and will be processed.

OrderNumber= the order number you received from Yucopia (gcsNumber)

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"api-key"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"d902a3d1-a6f9-4eb2-8ec8-6c21b08bc330","id":"d902a3d1-a6f9-4eb2-8ec8-6c21b08bc330","name":"Supplier Portal API","type":"collection"}},"urlObject":{"path":["api","order-flow","supplier-order-confirmed"],"host":["https://api.yucopia.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"f706e31d-43f4-47f2-8e02-7756dc510e06"},{"name":"Confirm deliveries","id":"16731ae5-a038-42f5-bb12-cf55cb4d6854","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"orderNumberBuyer\": \"string\",\r\n\r\n \"orderNumberSupplier\": \"string\",\r\n\r\n \"deliveryDate\": \"date\",\r\n\r\n \"deliveryID\": \"string\",\r\n\r\n \"lines\": [\r\n {\r\n \"articleNumberSupplier\": \"string\",\r\n \"despatchQuantity\": \"string\"\r\n }\r\n ],\r\n\r\n \"trackingUrl\": \"string\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.yucopia.com/api/order-flow/desadv-received","description":"

Delivery information can be sent via the DESADV. This is an electronic package slip, which contains delivery and shipment information. This can be used to let the customer know which products will be delivered when and how.

The body of the endpoint is based on the DESADV D01B standard.

Additional info:

orderNumberBuyer= order number from Yucopia

orderNumberSupplier = order number from the supplier

Date format example: DTM+137:20220226:104 (as defined by the DESADV D01B standard)

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"api-key"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"d902a3d1-a6f9-4eb2-8ec8-6c21b08bc330","id":"d902a3d1-a6f9-4eb2-8ec8-6c21b08bc330","name":"Supplier Portal API","type":"collection"}},"urlObject":{"path":["api","order-flow","desadv-received"],"host":["https://api.yucopia.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"16731ae5-a038-42f5-bb12-cf55cb4d6854"}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"api-key"},{"key":"value","value":""}]}},"event":[{"listen":"prerequest","script":{"id":"1d2138eb-4123-4286-8ba7-7210953b2855","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"ed933c0f-5583-46be-a9d7-e12add2461b0","type":"text/javascript","exec":[""]}}],"variable":[{"key":"baseUrl","value":"https://api.yucopia.com","type":"string"}]}