Knowledge BaseAPI Reference
SupplierXM platform

Understanding tenders (suppliers)

Suggest Edits

Introduction

Definitions

Tenders are composed of 4 interlinked objects:

Event ("événement” or “opération" in French): A commercial event has a beginning and an end date, it can last a day, a week, 2 weeks… and during this event the retailer will promote certain products in its shops, eg: Valentine’s day, Summer holidays prep, Back to School week, Black Friday, Christmas…

Unit of need - UoN ("unité de besoin" in French, also called Business Unit (BU) in the API): when structuring a tender for a specific event, the retailer will define units of need to categorize its needs in terms of products, promo type etc. and invite specific suppliers to each of those. e.g. for the event Christmas: there might be a UoN turkeys, a UoN chocolates, a UoN Christmas trees and a UoN Champagne.

Request for proposals - RFP ("appel d'offres" in French): the retailer will invite 1 to n suppliers per UoN, each couple UoN / supplier is an RFP. The retailer will then send those RFPs, and each supplier can decide to participate by sending back proposals per UoN. e.g. for the event Christmas, with 2 UoNs : chocolates and champagne. For the UoN chocolates, Leclerc invites 3 suppliers Milka, Cote d’or, Ferrero (so 3 RFPs), and for the UoN Champagne, Leclerc invites 2 suppliers, Moet and Ruinard (so 2 RFPs). There are in total 5 RFPs for that event.

Proposals (also called responses or answers, “propositions” or “réponses” in French)- a supplier invited to participate to an RFP can create and send 1 to n proposals attached to a UoN, each proposal is made of a product page associated with commercial conditions specific to the event for the RFP (based on proposals attributes requested by the supplier). e.g for the event Christmas, Ferrero has been invited to 3 UoNs: black chocolate, white chocolate and milk chocolate. Ferrero can decline the UoN white chocolate (doesn’t want to participate), can send 2 proposals (“Ferrero Rondnoir Pralines (3 x 138g)”and “Boite Ferrero Rocher Origins x36”) for the UoN black chocolate and 1 (“Raffaelo 180 (x3)”) for the UoN white chocolate.

Generic workflow

1120

How to...

How to display received tenders (events and their UoNs)

  • Call the list API: /rfp/public/v1/events, method: GET (List Event) (max 1000 events listed at a time)
  • Filters:
    • Filter list to only see events and their UoNs that have been updated within 2 dates, eg. /rfp/public/v1/events?from_last_updated_date=2021-01-30T11:24:59.3239&to_last_updated_date=2021-12-30T11:24:59.3239
    • Filter list with event UUID, eg. /rfp/public/v1/events?uuids=52eb9be1-bccc-4de7-b4ff-cf1fdf47b0aa

How to answer to a tender in 5 minutes

1. Create proposals

  • Call the API: /rfp/public/v1/answer, method: POST (Create proposals)
  • Mandatory fields:
    • business_unit_uuid to attach the proposal to
    • answers.product.gtin for each proposal
  • It is possible to create proposals in bulk in 1 call (for 1 UoN only and max 200 proposals at a time)
  • API response: it includes
    • UUID of new proposal created
    • sendable (true or false or pending - after a proposal update, the sendable status is rechecked, therefore the status pending)
    • non_sendable_reason for which the possible values are: No product, Blocking error on product (the product that is attached to the proposal), Blocking error on proposal
  • Controls:
    • It is not possible to create a proposal with a product that is not published and shared to the retailer
    • It is not possible to create 2 proposals with the same GTIN product / GTIN LH for the same UoN
    • It is not possible to create a proposal when the UoN is closed or declined

2. Send proposals

  • Call the API /rfp/public/v1/business_units/send/answers, method POST (Send proposals), filtered on the UoN’s UUID, eg. /rfp/public/v1/business_units/send/answers?uuid=37105fb1-a3a9-4b30-9409-f481889356d8
  • Mandatory field: UoN UUID in the URL
  • The send of proposals can be done in bulk via 1 API call
  • Controls:
    • It is not possible to send a proposal attached to a UoN that is declined
    • It is not possible to send a proposal attached to a UoN that is closed

3. Decline a UoN

  • Call the API /rfp/public/v1/business_units/{{UonUuid}}/decline, method POST (Decline UoN)
  • Mandatory field:
    • UoN UUID in the URL
    • declined (true to decline, false to undecline)
  • Controls:
    • It is not possible to decline a UoN that has answers sent
    • It is not possible to decline a UoN that is closed

How to manage my proposals

1. List proposals

  • Call the list API: /rfp/public/v1/answers, method: GET (List Proposals), max 1000 listed at a time
  • Filters:
    • Filter list with UoN UUID, eg. /rfp/public/v1/answers?business_unit_uuids=8dfc0131-bcdc-4785-8281-62df13f819c7
    • Filter list with proposals UUIDs, eg. /rfp/public/v1/answers?answer_uuids=6562d5d4-5f92-4624-ac10-62e6734fc836
  • API response includes:
    • Proposals selection statuses: DRAFT, UPDATE_TO_BE_SENT, SEND_ERROR, SENT, UPDATE_REQUESTED, REJECTED, SELECTED
    • update_requested_message : when the proposal status is Update requested, this field with the update request message will be returned

2. Update proposals

  • Call the API: /rfp/public/v1/answer, method: PUT (Update proposals)
  • Mandatory fields:
    • same as for the create : business_unit_uuid and answers.product.gtin for each proposal
    • answers.uuid to indicate the proposal to update
  • It is possible to update proposals in bulk in 1 call (for 1 UoN only, max 200 at a time)
  • No patch of data:
    • Have all the fields of an object in the post, not just the ones you wish to update.
    • If certain fields of an object are missing in the post, then those fields' values will be considered as “null”.
  • Controls:
    • It is not possible to create a proposal with a product that is not published and shared to the retailer
    • It is not possible to update a proposal when the UoN is closed or declined
    • It is not possible to update a proposals when the proposal is rejected or selected

3. Delete proposals

  • Call the API: /rfp/public/v1/answer, method: DELETE (Delete proposals)
  • It is possible to delete proposals in bulk in 1 call, eg. /rfp/public/v1/answers?uuids=fec0af69-0a2a-43e4-8d28-464c5f3eb5ec, fec0af69-0a2a-43e4-8d28-464c5f3eb5ed
  • Controls:
    • It is not possible to delete a proposal when the UoN is closed or declined
    • It is not possible to delete a proposal when the proposal is rejected or selected

How to display messages received for a UoN

If you want to display the messages received from the retailer for a certain UoN:

  • Call the API /rfp/public/v1/messages, method: GET (List messages), filtered on the UoN uuid, eg: /rfp/public/v1/messages?business_unit_uuid=992696e0-203b-4380-ab04-5e0b14ac355d
  • Mandatory field: UoN uuid.

NB: no calls should be done in parallel, but one after the other.

It is possible to subscribe to webhooks, in order to receive notifications when new tenders are received or updated, reminders are received, messages are received, proposals statuses change... Please go here to find how to use Tender webhooks.

Updated about 1 year ago