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

How to import tenders

Create tenders in 5 minutes

In order to create tenders for a certain event, follow the steps below:

1. First create an event

• Call the API: URL: /rfp/public/v1/events , method: POST (Create event)
• Mandatory fields: unique code, data.descriptionText and data.startDate and data.startDate
• It is possible to create events in bulk in 1 call (max 1000 events at a time)
• API response: contains a UUID for each event created
• After creating an event via this API, a new line item will appear on the event tab of the tender module here :

2. Then create the UoN(s) of this event

• Call the API: URL: /rfp/public/v1/business_units, method: POST (Create BU)
• Mandatory fields: event.uuid (the event must be created first), and the following UoN fields: code, data.descriptionText and data.limitDate
• It is possible create UoNs in bulk in 1 call (for the same event or for different events - max 1000 UoN at a time))
• API response: contains a UUID for each UoN created
• After creating UoN(s) via this API, a new line item will appear for each created UoN on the Unit of need tab of the tender module:

3. Finally create the RFP(s) for each UoN

• Call the API: URL: /rfp/public/v1/rfp, method: POST (Create RFP)
• Mandatory fields: business_unit.uuid (the UoN must be created first), retailer's supplier.id. Note:
  --> The retailer’s supplier must be reconcilied with at least 1 Alkemics supplier.
  --> If the retailer’s supplier is reconciled with n Alkemics suppliers, then n RFPs will be created
  --> If n retailer’s suppliers are reconciled with 1 Alkemics supplier, then 1 RFP is created (using the RFP data of the latest retailer’s supplier in the API call)
• It is possible to create RFPs in bulk in 1 call (for 1 or multiple UoNs, of the same event or not, max 1000 RFPs at a time)
• API response: includes UUID for each RFP created
• After creating RFP(s) via this API, a new line item will appear for each RFP created under the UoN their are linked to, with the status “Not sent”, in the Unit of need tab of the tender module:

📘

Notes

• It is not possible to create in one call events with its UoNs and RFPs.
• Only users with the rights to create those objects can do so.

Manage tenders you have created

1. How to list created events / UoNs / RFPs

• Call the list APIs (max 1000 objects at a time):
  Events: URL: /rfp/public/v1/events, method: GET (List Event)
  UoNs: URL: /rfp/public/v1/business_units, method: GET (List BU)
  RFP: URL: /rfp/public/v1/rfps, method: GET (List RFP). Note: the response includes the RFP status with the field "status" with the following values: NOT_SENT, ANSWERED, SENT, DECLINED

• Filters:
  Filter list event with event UUID (eg. /rfp/public/v1/events?uuids=17de8700-02ee-475a-97f4-249143fbffcb)
  Filter list UoN with UoN UUID (eg. /rfp/public/v1/business_units?uuids=378526b8-d838-462b-b9e0-6b91b001e997)
  Filter list RFP with RFP UUID (eg. /rfp/public/v1/rfps?uuids=323456b8-d838-462b-b9e0-6b91b001e997)
  Filter list events with from_last_updated_at and to_last_updated_at (eg. /rfp/public/v1/events?from_last_updated_at=2023-03-23T16:10:25&to_last_updated_at=2023-03-23T18:10:25)
  Filter list UoNs with from_updated_at and to_updated_at (eg. /rfp/public/v1/business_units?from_updated_at=2023-03-19T16:10:25&to_updated_at=2023-03-25T16:10:25)
  Filter list RFPs with from_updated_at and to_updated_at (eg. /rfp/public/v1/rfps?from_updated_at=2023-03-19T16:10:25&to_updated_at=2023-03-25T16:10:25)
  Filter list answers updated by manufacturer with start_date and end_date (eg. /rfp/public/v1/answers?start_date=2023-03-19T16:10:25&end_date=2023-03-25T16:10:25)
  Filter list answers for which the retailer selection status has been updated with target_status_updated_at_from and target_status_updated_at_to (eg. /rfp/public/v1/answers?target_status_updated_at_from=2023-03-01T16:10:25&target_status_updated_at_to=2023-03-28T16:10:25)

2. How to update events / UoN / RFP

• Call those APIs with the UUID of the object to update :
  Event: URL: /rfp/public/v1/events, method: PUT (Update Event)
  UoN: URL: /rfp/public/v1/business_units, method: PUT (Update BU)
  RFP: URL: /rfp/public/v1/rfps, method: PUT (Update RFP)

• Update in bulk:
  It is possible to update events / UoN / RFPs in bulk (max 1000 objects at a time)
  It is not possible to update in one call events, UoNs and RFPs together.

• 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”.
  Only fields that can be missing in the update call: the event code and UoN code.

3. How to delete events / UoN / RFP

• Calls those APIs with the UUID of the object to delete:
  Event: URL: rfp/public/v1/events?event_uuids=UUID1,UUID2' , method DELETE (Delete Event)
  UoN: URL: rfp/public/v1/business_units?event_uuids=UUID1,UUID2' , method DELETE (Delete BU)
  RFP: URL: rfp/public/v1/rfps?rfp_uuids=UUID1,UUID2' , method DELETE (Delete RFP)

• Delete in bulk:
  It is possible to delete events / UoN / RFPs in bulk (max 100 objects at a time)
  It is not possible to delete in one call events, UoNs and RFPs together.
  Note: Not possible delete an RFP / event / UB when proposal received

4. How to send tenders (RFPs)

• Call URL: /v1/rfps/send, method: POST (Send RFP)
• Mandatory field: uuids of the RFPs to send

📘

Notes:

• Only users with the rights to see those objects can do so → those APIs responses are empty if the user doesn’t have the permissions.
  • Only users with the rights to update those objects can do so.
  • Only users with the rights to delete those objects can do so.
  • Only users with the rights to send RFPs can do so.

How to export proposals

How to list received proposals:

• Call URL: /rfp/public/v1/answers, method: GET (List Answer) (max 1000 proposals listed at a time)
• Response data :
  --> Proposal UUID (answers.uuid),
  --> RFP UUID (answers.rfp.uuid),
  --> Last update date of each proposal's data (answers.last_received_at),
  --> Proposal selection status (answers.status with the following values: NEED_REVIEW, UPDATE_REQUESTED, UPDATE_RECEIVED, SELECTED, REJECTED, SELECTED_NOTIFIED, REJECTED_NOTIFIED), update_requested_message when the proposal status is Update requested, and all proposals fields part of the retailer’s data model
  --> Last update date of each proposal's selection status (answers.target_status_updated_at)
• Filter:
  --> With start_date and end_date, to only see proposals that have been updated between those 2 date by the manufacturer
  --> With target_status_updated_at_from and target_status_updated_at_to, to only see proposals for which the selection status has been updated between those 2 dates
  --> With statuses, to only see proposals with a certain selection status
  --> With UoN uuid to only see proposals for that UoN
  --> With proposal uuid to only see that proposal
• Permissions: Only proposals of the UoNs that the user has access to will be returned.

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