Skip to main content

Marketplace API

Marketplace API will typically be used to implement platform custom frontends, therefore is designed from the Platform user perspective, that is, marketplace participants. Although some of the APIs are public (registration, login, etc) most of them will require previous call to login API and providing their personal credentials (email and password, as well as corresponding keys).

Marketplace context

The implicit context for all the APIs in this section is single marketplace user, rather than the marketplace as a whole.

Authentication

On the top if this login mechanism, all API use is based on api key usage. Refer to Authentication section for more details

For more information about Backoffice API, used to automate backend tasks and extend the randevu logic, please refer to Backoffice API section.

Public API#

registerMarketplaceOwner#

This open service will register a new marketplace and its first user - a marketplace owner.

Endpoint for signing-up as marketplace owner
type Mutation {  registerMarketplaceOwner(    marketplace_name: String!    email: String!    first_name: String!    last_name: String!  ): Boolean!}
  • marketplace_name a unique marketplace name
  • email valid email address
  • first_name marketplace owner's first name
  • last_name marketplace owner's last name

registerParticipant#

This service is called by users to join the platform. As a response to calling this method, an email will be sent to the provided email, for user confirmation reasons.

A valid public key must be provided with this call. Refer to Authentication section for more details

Endpoint for signing-up as marketplace user a.k.a. marketplace participant
type Mutation {  registerParticipant(    id_type: ID!    email: String!    first_name: String!    last_name: String!  ): Boolean!}
  • id_type a unique identifier of the MarketplaceUserType of this user.
  • email valid email address
  • first_name marketplace owner's first name
  • last_name marketplace owner's last name

requestParticipantPasswordReset#

This service is used to request a password reset for a user with a given email. This is a typical implementation of a "Forgot your password?" feature. In case when a user with the given email exists, an email is sent with a link for password reset.

A valid public key must be provided with this call. Refer to Authentication section for more details

Hint

Use this service followed by resetMyPassword to fully reset user's password

Endpoint to request password reset a.k.a. 'Forgot your password?'. 
type Mutation {  requestParticipantPasswordReset(email: String!): Boolean!}
  • marketplace_name marketplace name
  • email existing user's email address

resetParticipantPassword#

Use this API to permanently reset user's password. Both token and marketplace_name are encoded within URL query parameter data which is attached to the reset password link received per email as result of a previous call to requestPasswordReset

A valid public key must be provided with this call. Refer to Authentication section for more details

Endpoint which persists user's new password
type Mutation {  resetParticipantPassword(token: String!, password: String!): Boolean!}
  • token token received per email, needed for authentication
  • password new password

loginParticipant#

Use this service to login to randevu as Participant (Marketplace User)

A valid public key must be provided with this call. Refer to Authentication section for more details

Endpoint which signs-in user a Participant into randevu
type Mutation {  loginParticipant(email: String!, password: String!): Session!}
  • email user's email
  • password user's password

This API will return a Session structure.

getGuestToken#

In order to support so called "guests" on the platform, a guest session is needed. It works the similar way as a usual session, created during a successful login - a token needs to be provided in each request.

A valid public key must be provided with this call. Refer to Authentication section for more details

Endpoint to open a guest's session
type Query {  getGuestToken: Session!}

Users API#

me#

This method returns a User object, belonging to the logged in user.

type Query {  me: User!}

API requires no parameters.

logoutMe#

Calling this API will terminate the current User session.

type Query {  logoutMe: Boolean!}

updateUser#

This API is for updating User's attributes, including basic ones and custom defined ones (Fields)

type Mutation {  updateUser(    id: ID!    first_name: String    last_name: String    password: String    fields: [FieldInput!]  ): Boolean!}
input FieldInput {  id: ID!  value: JSON}
  • id user's unique identifier
  • first_name user's first name
  • last_name user's last name
  • password user's new password
  • fields are object's custom Fields. value should be provided in the correct format, depending on the FieldType's input_type (e.g. )

createInvitedMarketplaceUser#

This API is creating an "invited" user. The implicit "inviting" user is the logged in User.

Invited users

Invited users are acting on behalf of the corresponding "inviting" user. They have the same rights as their "inviting" users have.

Both "invited" and "inviting" users are MarketplaceUsers, although "invited" ones are lacking reference to MarketplaceUserType

type Mutation {  createInvitedMarketplaceUser(    email: String!    first_name: String!    last_name: String!  ): User! @isMPUser}
  • email user's email
  • first_name user's first name
  • last_name user's last name

Supply API#

Supply APIs are there for marketplace users to create, update and manage their Supply or to browse and discover Supply created by other users.

createSupply#

This API allows Marketplace users, configured as provider in a MatchType, to create new Supply and offer it over the platform.

It is also open to Backoffice users, to create Supply on behalf of marketplace users, configured as provider.

type Mutation {  createSupply(id_supply_type: ID!, name: String!, id_provider: ID): Supply!}
  • id_supply_type
  • name
  • id_provider

updateSupply#

This service updates a concrete Supply's data, including basic properties (name) and its Fields

type Mutation {  updateSupply(id: ID!, name: String, fields: [FieldInput!]): Boolean!}
input FieldInput {  id: ID!  value: JSON}
  • id is a unique identifier of an existing Supply
  • name is an internal alias for the Supply. It is not visible to other marketplace users.
  • fields are object's custom Fields. value should be provided in the correct format, depending on the FieldType's input_type (e.g. )

mySupplyTypes#

This service returns all the SupplyTypes that the logged user can create.

"My supply"

A marketplace user is granted a permission to create a Supply of a certain SupplyType via MatchType. A MarketplaceUserType, set as PROVIDER in any MatchType, automatically receives the right to create Supply of a SupplyType attached to that MatchType.

mySupplyTypes returns all the SupplyTypes, attached to the MatchTypes, the logged user is PROVIDER in.

type Query {  mySupplyTypes: [SupplyType!]}

mySupplyType#

Similarly to the previous query, this one returns all the details of a single [SupplyType]{#supply_type}, belonging to the logged in user.

type Query {  mySupplyType(id: ID!): SupplyType}
  • id is a unique identifier of an existing SupplyType that belongs to the logged user

mySupplies#

This query returns all the Supply instances, created by the logged user.

type Query {  mySupplies: [Supply!]}

mySupply#

This query returns an exact Supply, created by the logged user.

type Query {  mySupply(id: ID!): Supply}
  • id is a unique identifier of an existing Supply that belongs to the logged user

discoverSupply#

This is the main Supply searching service. It is used by the marketplace users set as CONSUMER within a context of a [Match]{../schema#match}.

The service returns just a limited information on Supply, needed to display the results of the discovery process. Therefore it is usually used along with discoverSupplyDetails in order to get full list of Supply's Fields.

Open Supply discovery

This type of discovery will return the Supply that match ALL the provided filters. See MatchingTools for more options

type Query {  discoverSupply(    id_match_type: ID!    id_supply_type: ID!    filter: [FieldFilterInput!]!    availability: AvailabilityRecordInput  ): [Supply!]}
input FieldFilterInput {  id_target_field_type: ID!  value: JSON}
input AvailabilityRecordInput {  quantity: Int # not null if MatchingUnitKind==PER_UNIT/PER_EVENT  start_datetime: DateTime # not null if MatchingUnitKind==PER_HOUR  end_datetime: DateTime # not null if MatchingUnitKind==PER_HOUR  start_date: DateTime # not null if MatchingUnitKind==PER_DAY  end_date: DateTime # not null if MatchingUnitKind==PER_DAY}
  • id_match_type is a unique identifier of a 'MatchType', based on which this discovery is made
  • id_supply_type is a unique identifier of a 'SupplyType', based on which this discovery is made
  • filter is an array of field filters. Each one contains a value, depending on the FieldType of the target Field. More details about this here
  • availability holds additional data, which depends on the MatchingUnitKind, defined in the corresponding MatchType. This additional data will be used to filter out Supply which is not available on that days or in the required quantity.

discoverSupplyDetails#

Use this service right after 'discoverSupply', in order to fetch all the details of the discovered Supply.

type Query {  discoverSupplyDetails(    id_match_type: ID!    id_supply_type: ID!    id_supply: ID!  ): Supply!}
  • id_match_type is a unique identifier of a MatchType, based on which this discovery is made
  • id_supply_type is a unique identifier of a SupplyType, based on which this discovery is made
  • id_supply is a unique identifier of a Supply, returned by discoverSupply

Matches API#

myMatches#

This service brings all the Matches belonging to the logged user. Only limited set of properties is fetched. See the following service for fetching more details.

type Query {  myMatches: [MatchLight!]}

myMatch#

Fetches full set of properties for a single Match instance, belonging to the logged user.

type Query {  myMatch(id: ID!): Match!}
  • id is a unique identifier of an existing Match, visible by logged user

updateMatch#

This service updates a concrete Match's data.

type Mutation {  updateMatch(id: ID!, fields: [FieldInput!]): Boolean!}
input FieldInput {  id: ID!  value: JSON}
  • id is a unique identifier of an existing Match, visible by logged user
  • fields is an array of this Match's Fields, with their new values

acceptMatch#

This service is executed by either CONSUMER or PROVIDER of a Match, if it is required to accept the match.

Look at auto_consumer_acceptance and auto_provider_acceptance properties of [MatchType]{../schema#match_type} for more clarity.

type Query {  acceptMatch(id: ID!): Boolean!}
  • id is a unique identifier of an existing Match, visible by logged user

declineMatch#

This service is executed by either CONSUMER or PROVIDER of a Match, when they want to decline the Match.

Look at auto_consumer_acceptance and auto_provider_acceptance properties of [MatchType]{../schema#match_type} for more clarity.

type Query {  declineMatch(id: ID!): Boolean!}
  • id is a unique identifier of an existing Match, visible by logged user

Matching tools API#

activateMatchingTool#

This API is called by a user to activate their MatchingTool. A MatchingTool must be activated in order to be able to execute it.

type Mutation {  activateMatchingTool(id: ID!): Boolean!}

deactivateMatchingTool#

This API is called by a user to deactivate their MatchingTool. Deactivated MatchingTool cannot be executed.

deactivateMatchingTool(id: ID!): Boolean!

addSupplyToSupplyBag#

This service is for adding Supply to a Supply bag

addSupplyToSupplyBag(  id_supply_bag: ID!  id_supply: ID!  quantity: Int = 1): Boolean!

  • id_supply_bag indicates the instance of Supply Bag

  • id_supply is a reference to a concrete Supply to be stored in the bag

  • quantity lets memorize the quantity of stored Supply

updateMatchingTool#

This service sets the Fields of a MatchingTool and prepares it for the execution. This will typically be done after preparing a new Transaction (prepareSingleDirectTransaction, prepareReverseAuctionTransaction, etc.) and before initiating the same transaction, via initiateTransaction](#initiate_transaction).

  updateMatchingTool(    id: ID!    name: String    supply_filter: [FieldFilterInput!]    provider_filter: [FieldFilterInput!]    consumer_filter: [FieldFilterInput!]    availability: AvailabilityRecordInput    fields: [FieldInput!]  ): Boolean! @isParticipantOrGuest @hasAPIKey

  • id is a unique matching tool ID

  • name is an informal name

  • supply_filter, provider_filter and consumer_filter define different filters for matching purposes

  • availability is a reference to the AvailabilityRecord

  • fields is a collection of the Fields defined for this Matching tool

Transactions API#

myTransactionTypes#

This service brings all the TransactionTypes that the logged user is able do execute, directly or indirectly.

type Query {  myTransactionTypes: [TransactionType!]}

myTransactions#

This service brings all the Transactions, the logged user is participating in.

type Query {  myTransactions: [Transaction!]}

prepareSingleDirectTransaction#

This service is the first step of executing a Transaction, the logged user is participating in. This is a basic form of transaction, which features direct matching process. This transaction type internally handles a MatchingTool of a type DIRECT_MATCHER.

This type of transaction is typically executed after calling discoverSupply and followed by initiateTransaction.

  prepareSingleDirectTransaction(    id_transaction_type: ID!    id_supply: ID!    availability: AvailabilityRecordInput # availability reqs  ): PreparedTransaction! @isOnboardedParticipant @hasAPIKey

prepareReverseAuctionTransaction#

This service is the first step of executing a Transaction, the logged user is participating in. This is a basic form of transaction, which features indirect matching process. This transaction type internally handles a MatchingTool of a type MATCHING_ORDER.

This type of transaction will typically require a call to updateMatchingTool, prior to initiating it, in order to set the Matching Order relevant data. As always Transaction preparation is followed by initiateTransaction.

  prepareReverseAuctionTransaction(    id_transaction_type: ID!    supply_filter: [FieldFilterInput!] = []    availability: AvailabilityRecordInput # availability reqs  ): PreparedTransaction! @isOnboardedParticipant @hasAPIKey

initiateTransaction#

This service launches a fresh Transaction, previously prepared by calling some of the several available prepare-Transaction APIs.

  initiateTransaction(id: ID!): TransactionLight!
  • id is this transaction's unique identifier

Transactions API#

myTransactionTypes#

This service brings all the TransactionTypes that the logged user is able do execute, directly or indirectly.

type Query {  myTransactionTypes: [TransactionType!]}

myTransactions#

This service brings all the Transactions, the logged user is participating in.

type Query {  myTransactions: [Transaction!]}

Files API#

prepareFileUpload#

This service is called to prepare a File upload to randevu. It returns a structure with an URL, to upload a file to.

prepareFileUpload(  name: String!  type: FileKind!  extension: String = ""): FileUpload! @isAuthed

  • name is the name of a file to be uploaded

  • type indicates the file's type

  • extension is the extension of a file to be uploaded (e.g. 'jpg')

Payment API#

requestPaymentProviderConnection#

Calling this service is a first step of the connection of randevu with user's account in the external payment provider's system (e.g. STRIPE).

It is usually called by a frontend app, in order to request an URL. User should be then redirected to this URL, in order to finish the account connection process

requestPaymentProviderConnection(  provider_type: PaymentProviderKind!  refresh_url: String  return_url: String): PaymentProviderConnection!

  • provider_type identifies the payment provider to be used

  • refresh_url and return_url are ...

preparePayment#

This service prepares the structures to execute a payment in the system. Returned Payment object should be used to request a payment checkout connection.

preparePayment(  id_payment_type: ID!  id_sender: ID!  id_recipient: ID  description: String  ids_matches: [ID!]  id_transaction: ID): Payment!

  • id_payment_type is a reference to the payment's type

  • id_sender references the user who will make the payment.

  • id_recipient is the user to receive the payment.

  • description is the description of this payment

  • ids_matches is an array of Match objects. They are used to calculate the Payment's amount

  • id_transaction is sent, so that Payment can be related with the corresponding Transaction. This feature makes it possible for Flows to "wait" on payment related events.

requestPaymentCheckoutConnection#

This service is called to initiate the payment checkout process. Based on previously prepared Payment, it will generate an return an URL. The payer user should be redirected to this URL to complete the payment process.

requestPaymentCheckoutConnection(  id_payment: ID!  success_url: String  cancel_url: String): PaymentCheckoutConnection!

  • id_payment is a unique identifier of this object

  • success_url and cancel_url are...