Skip to main content

Schema

In this section the relevant data types used by API services are explained. In order to get a high level overview of the defined types, please refer to domain model.

User types#

Both enumerators and data types related to randevu users are explained in this section.

Enumerators#

UserRoleKind#

enum UserRoleKind {  MARKETPLACE_USER  MARKETPLACE_OPERATOR  MARKETPLACE_ADMIN  MARKETPLACE_OWNER  API_USER}

AccountKind#

enum AccountKind {  PERSONAL  BUSINESS}

UserStatusKind#

enum UserStatusKind {  PENDING_EMAIL_VERIFICATION  ONBOARDING  PENDING_APPROVAL  ONBOARDED  REJECTED}

MarketplaceUserType#

Alternatively called ParticipantType is the definition of your platform's users, participants in its processes.

Hint

Name your MarketplaceUserType with short and meaningful name, preferably nouns in singular, to represent the whole user group.

Good examples are: Buyer, Seller, Driver, Consultant, etc.

type MarketplaceUserType {  id: ID!  name: String!
  id_onboarding_flow_type: ID
  fields: [FieldType!]!
  is_master_type: Boolean!  account_type: AccountKind  inviting_enabled: Boolean!  auto_backoffice_approval: Boolean!}

  • id a unique identifier

  • name unique name for the user type (e.g. 'Buyer', 'Seller', 'Driver', etc)

  • id_onboarding_flow_type is a reference to this User Types' FlowType. If set, then the corresponding Flow is triggered when user's email has been validated, to handle User onboarding process.

  • fields are references to this User Type's FieldTypes. Fields define the structure of all the Users of this type.

Only accessible to BACKOFFICE users

  • auto_backoffice_approval is set when Users of this type can registed and onboard to the platform without an explicit approval from backoffice.

  • inviting_enabled is set when this User account allows so called "invited users". Invited users can operate on behalf of the "inviting" user and have access to the same services and data as the "inviting user"

  • is_master_type is set when this User Type is main account holder (rather then "invited user")

  • account_type shows the User Type intended purpose

Session#

This helper object contains the session token. This token is used for authentication purposes and should be sent in each upcoming request to randevu backend.

Session token

Token should be provided with each request in Authorization header.

Refer to Authentication section for more details

type Session {  token: String!  pk_sandbox: String  pk_production: String}
  • token is a chain of characters, used to authenticate the logged in user with each request.
  • pk_sandbox is the sandbox public key, needed for API access to the sandbox system
  • pk_production is the production public key, needed for API access to the productive system

ParticipantOnboardingProgress#

This type is used for the onboarding purposes of marketplace participants. If the auto_pilot_mode is set to false, then a Flow will be applied during onboarding and its status is shown here.

Custom user onboarding

If this option is set, a Flow will be used to take new users through the onboarding journey. Overall user status during this process will be set to ONBOARDING, and the flow's step will deliver more information.

type ParticipantOnboardingProgress {  auto_pilot_mode: Boolean! # is true for EXPRESS and STANDARD onboarding  backoffice_approval_required: Boolean # if auto_pilot==true  status: String # if auto_pilot==false, is current flow status name}

User#

This type is representing any randevu User, independently on the concrete role.

type User {  id: ID!  role: UserRoleKind!  type: MarketplaceUserType # If role = MARKETPLACE_USER, type != null  account: Account  email: String!  first_name: String  last_name: String
  my_marketplace_name: String!  my_marketplace_display_name: String!
  status: UserStatusKind!
  invited_by: String @isBOUser
  created_at: DateTime! @isBOUser  email_verified_at: DateTime @isBOUser  approved_at: DateTime @isBOUser  rejected_at: DateTime @isBOUser  onboarded_at: DateTime @isBOUser
  onboarding_progress: ParticipantOnboardingProgress  id_onboarding_flow: ID
  fields: [Field!]!}

  • id is a User's unique identifier.

  • role is a User's role in randevu. See Enumerators for more details.

  • type is a reference to this user's MarketplaceUserType. It can be null, if a user is a backoffice user or invited user.

  • account references a User account.

  • email is a user's email.

  • first_name, last_name user's first and last name

  • my_marketplace_name short name of the user's marketplace

  • my_marketplace_display_name display name of the user's marketplace

  • status User's status. ONBOARDED is a state in which User is fully operational.

  • fields hold an array of all the Fields belonging to this User

  • onboarding_progress tells about the onboarding mode and status of this user. Look at ParticipantOnboardingProgress

  • id_onboarding_flow is the ID of the Flow handling this user's onboarding process. If 'null', the default onboarding process is applied

Only accessible to BACKOFFICE users
  • invited_by is a MarketplaceUser has been invited by another MarketplaceUser, a reference to the inviting user is stored.
  • created_at
  • email_verified_at
  • approved_at
  • rejected_at
  • onboarded_at

Supply types#

Enumarators#

SupplyStatusKind#

enum SupplyStatusKind {  ONBOARDING  PENDING_APPROVAL  ONBOARDED  REJECTED}

SupplyType#

Supply type is a definition of a product/service/listing, being offered and transacted on the marketplace. Many critical tasks in randevu are evolving around the SupplyType:

  • it defines the features that the potential consumers will be able to see
  • it enables discovery, browsing and filtering for the potential consumers
  • put in context of a MatchType, and together with provider and consumer sides, it specifies the basic building block for creating the network effect

SupplyType serves as a template for creating concrete Supply instances on a marketplace.

Hint

Try to choose a meaningful name for your supply types, the one that represent exactly what the consumers are looking for on the marketplace.

  • for product marketplaces: Book, Machine, Concert ticket, etc.
  • for service marketplace: Legal Advice, Ride, Design work, etc.
type SupplyType {  id: ID!  name: String!  fields: [FieldType]!
  id_onboarding_flow_type: ID
  auto_backoffice_approval: Boolean @isBOUser}

  • id a unique identifier

  • name unique, internal name for the supply type (e.g. 'Product', 'Room', 'Ride', etc)

  • id_onboarding_flow is the ID of the Flow handling this supply's onboarding process. If 'null', the default onboarding process is applied

  • fields are references to this Supply type's FieldTypes. Fields define the structure of all the Supply of this type.

Only accessible to BACKOFFICE users
  • auto_backoffice_approval is set when Supply of this type can onboarded and sold on the platform without an explicit approval from backoffice.

SupplyOnboardingProgress#

This type is user for the onboarding purposes of marketplace supply. If the auto_pilot_mode is set to false, then a Flow will be applied during onboarding and its status is shown here.

Custom supply onboarding

If this option is set, a Flow will be used to take new users through the onboarding journey. Overall supply status during this process will be set to ONBOARDING, and the flow's step will deliver more information.

type SupplyOnboardingProgress {  auto_pilot_mode: Boolean! # is true for EXPRESS and STANDARD onboarding  backoffice_approval_required: Boolean # is considered, if auto_pilot_mode==true  status: String # if auto_pilot_mode is false, is current flow status name}

Supply#

This type represents concrete Supply/product/listings', offered on the marketplace. They are typically created by their PROVIDERS, based on the definition established by SupplyType.

type Supply {  id: ID!  name: String!  type: SupplyType!  provider: User!  created_by: User
  status: SupplyStatusKind!
  onboarding_progress: SupplyOnboardingProgress
  fields: [Field]!
  created_at: DateTime! @isBOUser  approved_at: DateTime @isBOUser  rejected_at: DateTime @isBOUser  onboarded_at: DateTime @isBOUser}

  • id a unique identifier

  • name internal name for the supply, not visible to marketplace users.

  • type is a reference to the SupplyType, this Supply belongs to.

  • provider is a references to the user who owns and sells this Supply

  • created_by is a references to the user who created this Supply (may be an "invited" user, different from the owner)

  • status is one of the values of the SupplyStatusKind

  • onboarding_progress tells about the onboarding mode and status of this user. Look at SupplyOnboardingProgress

  • fields are references to this Supply's Fields

Only accessible to BACKOFFICE users
  • created_at
  • approved_at
  • rejected_at
  • onboarded_at

SupplyLight#

This is a lighter version of Supply, aimed for the services that returned only reduced info on Supply, like discoveries.

type SupplyLight {  id: ID!  name: String!  id_supply_type: ID!  id_provider: ID!}

  • id a unique identifier

  • name internal name for the supply, not visible to marketplace users.

  • id_supply_type is a unique ID of the SupplyType, this Supply belongs to.

  • id_provider is a unique ID of the user who owns and sells this Supply

Match types#

Enumarators#

MatchingUnitKind#

Matching unit refers to how a Supply is being transacted in the context of a Match.

In case of product marketplaces, consumers are normally selecting Supply by unit (PER_UNIT matching unit).

Some Supply are linked with a certain event (bus ticket, concert ticket). In randevu these are called PER_EVENT.

Finally, some services are typically booked or rented for a range of time (like Airbnb, Tour radar). PER_HOUR or PER_DAY

Matching Unit Kind and availability

Supply availability in randevu is handled based on MatchingUnitKind. See the following services, that use the AvailabilityRecord: discoverSupply, createDirectMatcher, createMatchingOrder.

enum MatchingUnitKind {  PER_UNIT  PER_EVENT  PER_HOUR  PER_DAY}

AvailabilityManagementKind#

In relation with MatchingUnitKind this enumarator sets the prefered Supply availability strategy for the context of a MatchType it is defined in.

enum AvailabilityManagementKind {  NONE  MANAGED_BY_RANDEVU  CUSTOM}

AvailabilityManagementKind#

In relation with MatchingUnitKind this enumarator sets the prefered Supply availability strategy for the context of a MatchType it is defined in.

enum AvailabilityManagementKind {  NONE  MANAGED_BY_RANDEVU  CUSTOM}

MatchTypeRoleKind#

enum MatchTypeRoleKind {  CONSUMER  PROVIDER  CONSUMER_OR_PROVIDER  GUEST}

MatchStatusKind#

enum MatchStatusKind {  PENDING  CLOSED  REJECTED  DECLINED}

MatchTypeVisibilityInfo#

As its name suggests, this structure is used to identify the arrays of FieldTypes, that will be visible/accessible to different participants in context of the MatchType that contains this object.

Since this data is on type-level (that is MatchType, rather than Match), the corresponding visibilities are related with pre-matching tasks, like discovery and filtering.

type MatchTypeVisibilityInfo {  provider_fields: [ID!]  consumer_fields: [ID!]  supply_fields: [ID!]  match_fields: [ID!]
  provider_fields_out_for_consumer: [ID!]  provider_fields_out_for_guest: [ID!]  consumer_fields_out_for_provider: [ID!]  consumer_fields_out_for_guest: [ID!]  supply_fields_out_for_consumer: [ID!]  supply_fields_out_for_guest: [ID!]}

  • provider_fields is an array of FieldTypes belonging to PROVIDER, that are visible to CONSUMER filtering purposes

  • consumer_fields is an array of FieldTypes belonging to CONSUMER, that are visible to PROVIDER filtering purposes

  • supply_fields is an array of FieldTypes belonging to SupplyType, that are visible to CONSUMER filtering purposes

  • match_fields is an array of FieldTypes belonging to MatchType, that are visible to both CONSUMER and PROVIDER filtering purposes

  • provider_fields_out_for_consumer is an array of FieldTypes belonging to PROVIDER, that are visible to CONSUMER after discovery

  • provider_fields_out_for_guest is an array of FieldTypes belonging to PROVIDER, that are visible to a guest after discovery

  • consumer_fields_out_for_provider is an array of FieldTypes belonging to CONSUMER, that are visible to PROVIDER after discovery

  • consumer_fields_out_for_guestis an array of FieldTypes belonging to CONSUMER, that are visible to a guest after discovery

  • supply_fields_out_for_consumer is an array of FieldTypes belonging to SupplyType, that are visible to CONSUMER after discovery

  • supply_fields_out_for_guest is an array of FieldTypes belonging to MatchType, that are visible to a guest after discovery

Filtering and discovery

Filtering fields: Use the following arrays to mark the FieldTypes you want to permit in discovery search filters in context of a MatchType: provider_fields, consumer_fields, supply_fields, match_fields

Discovered fields: Use the remaining arrays to mark the FieldTypes that should be shown after the discovery.

Filtering fields are most often a subset of discovered fields.

MatchVisibilityInfo#

This structure is similar to MatchTypeVisibilityInfo, but operates in the context of a Match, rather than MatchType.

It describes the visibility rules within a Match, that is who can see the Match object and which provider and consumer Fields can be accessed by the other side.

Match visibility is dynamical

Match visibility can be changed dynamically, either from the backoffice or using the Flows.

Match Fields, visible to either side, are define within the each Match Field itself.

type MatchVisibilityInfo {  match_by_consumer: Boolean  match_by_provider: Boolean  provider_by_consumer: Boolean  consumer_by_provider: Boolean  supply_by_consumer: Boolean  provider_fields: [ID!]  consumer_fields: [ID!]  supply_fields: [ID!]}

  • match_by_consumerif set to true, a just created Match is immediately visible to consumer

  • match_by_provider if set to true, a just created Match is immediately visible to provider

  • provider_by_consumer if set to true, provider is immediately visible to consumer in the context of just created Match is immediately visible to consumer

  • consumer_by_provider if set to true, consumer is immediately visible to provider in the context of just created Match is immediately visible to consumer

  • supply_by_consumer if set to true, supply is immediately visible to consumer in the context of just created Match is immediately visible to consumer

  • provider_fields is an array of Fields belonging to PROVIDER, that are visible to the CONSUMER

  • consumer_fields is an array of Fields belonging to CONSUMER, that are visible to the PROVIDER

  • supply_fields is an array of Fields belonging to matched Supply, that are visible to the CONSUMER

MatchType#

This is probably the most important and most complex type in randevu. It represents the definition of the basic matching building block in the system - Match.

MatchType defines the relationship between:

In addition, MatchType defines the basic features of this particular matching setup, it's style, approval procedure, etc. For more details, see the properties below.

About Matching Types

Marketplaces will usually start with a single MatchType and try to create a network effect around it.

Later on, marketplaces usually wish to extend the offer, introduce new participants and create more MatchTypes.

Try to find a meaningful name for your MatchType. It should represent the transaction behind the successful matching:

  • if your marketplaces is a cab booking app, a good name for the MatchType is "Booked ride"
  • if your marketplaces is selling products, a suitable MatchType name might be "Purchase" or "Product purchase"
type MatchType {  id: ID!  name: String!
  matching_unit_type: MatchingUnitKind!  availability_management_type: AvailabilityManagementKind!
  my_role: MatchTypeRoleKind @isMPUser
  provider_type: MarketplaceUserType!  consumer_type: MarketplaceUserType!  supply_type: SupplyType!
  supply_discovery_enabled: Boolean!  provider_discovery_enabled: Boolean!  consumer_discovery_enabled: Boolean!
  matching_tool_types: [MatchingToolType!]!  fields: [FieldType!]!
  type_visibility: MatchTypeVisibilityInfo! @isBOUser  initial_match_visibility: MatchVisibilityInfo! @isBOUser
  auto_backoffice_approval: Boolean! @isBOUser  auto_consumer_acceptance: Boolean! @isBOUser  auto_provider_acceptance: Boolean! @isBOUser
  allow_provider_guests: Boolean! @isBOUser  allow_consumer_guests: Boolean! @isBOUser
  consumers: [User!] @isBOUser  providers: [User!] @isBOUser  supplies: [Supply!] @isBOUser
  retired_at: DateTime}

  • id is a unique identifier of this object

  • name is an internal alias for this MatchType

  • matching_unit_type establishes a unit of matching in this MatchType. See MatchingUnitKind for more details.

  • availability_management_type defines the way Supply availibility is managed in context of this MatchType

  • my_role (only available to marketplace users) shows the role a user plays in the context of a MatchType. See MatchTypeRoleKind for more details.

  • provider_type references a MarketplaceUserType of the provider of this MatchType

  • consumer_type references a MarketplaceUserType of the consumer of this MatchType

  • supply_type references a SupplyType, offered by this MatchType

  • supply_discovery_enabled is set to true, when consumers can use the service discoverSupply to browse the Supply in context of this MatchType

  • provider_discovery_enabled is set to true, when consumers can use the service discoverProviders to browse the Supply in context of this MatchType

  • consumer_discovery_enabled is set to true, when providers can use the service discoverConsumers to browse the Supply in context of this MatchType

  • matching_tool_types is an array of MatchingToolType attached to this MatchType

  • fields is an array of Fields belonging to this MatchType

Only accessible to BACKOFFICE users

  • type_visibility defines the visibility relationships during the discovery phase of a MatchType. For more details, see MatchTypeVisibilityInfo

  • initial_match_visibility defines the visibility relationships after a match has been created for a MatchType. For more details, see MatchVisibilityInfo

  • auto_backoffice_approval if true, matches are automatically approved by Backoffice

  • auto_consumer_acceptance if true, matches are automatically accepted by consumer side

  • auto_provider_acceptance if true, matches are automatically accepted by provider side

  • allow_provider_guests is set when guests (not logged users) are allowed to partially use the system from CONSUMER perspective

  • allow_consumer_guests is set when guests (not logged users) are allowed to partially use the system from PROVIDER perspective

  • providers are all registered potential providers of SupplyType offered by this MatchType

  • consumers are all registered potential consumers of SupplyType offered by this MatchType

  • supply is all created Supply from the SupplyType offered by this MatchType

  • retired_at is a timestamp when this MatchType has been retired. Retired MatchTypes cannot be used any more.

MatchTypeLight#

This is a lighter version of MatchType, providing some IDs instead of full data structures.

type MatchTypeLight {  id: ID!  name: String!  style: MatchingStyleKind!
  my_role: MatchTypeRoleKind @isMPUser
  id_provider_type: ID!  id_consumer_type: ID!  id_supply_type: ID!
  supply_discovery_enabled: Boolean!  provider_discovery_enabled: Boolean!  consumer_discovery_enabled: Boolean!
  matching_tool_types: [MatchingToolType!]!}

  • id is a unique identifier of this object

  • name is an internal alias for this MatchType

  • style defines how consumers can see the offered SupplyTypes. See MatchingStyleKind for more details.

  • my_role (only available to marketplace users) shows the role a user plays in the context of a MatchType. See MatchTypeRoleKind for more details.

  • id_provider_type references a MarketplaceUserType of the provider of this MatchType

  • id_consumer_type references a MarketplaceUserType of the consumer of this MatchType

  • id_supply_type references a SupplyType, offered by this MatchType

  • supply_discovery_enabled is set to true, when consumers can use the service discoverSupply to browse the Supply in context of this MatchType

  • provider_discovery_enabled is set to true, when consumers can use the service discoverProviders to browse the Supply in context of this MatchType

  • consumer_discovery_enabled is set to true, when providers can use the service discoverConsumers to browse the Supply in context of this MatchType

  • matching_tool_types is an array of [MatchingToolType]s(#matching_tool_type) attached to this MatchType

Only accessible to BACKOFFICE users

  • type_visibility defines the visibility relationships during the discovery phase of a MatchType

  • initial_match_visibility defines the visibility relationships after a match has been created for a MatchType

  • auto_backoffice_approval if true, matches are automatically approved by Backoffice

  • auto_consumer_acceptance if true, matches are automatically accepted by consumer side

  • auto_provider_acceptance if true, matches are automatically accepted by provider side

  • allow_provider_guests is set when guests (not logged users) are allowed to partially use the system from CONSUMER perspective

  • allow_consumer_guests is set when guests (not logged users) are allowed to partially use the system from PROVIDER perspective

  • providers are all registered potential providers of SupplyType offered by this MatchType

  • consumers are all registered potential consumers of SupplyType offered by this MatchType

  • supply is all created Supply from the SupplyType offered by this MatchType

Match#

This type represents an essential building block of the randevu logic. It defines an abstract concept of a connection between a Consumer, a Supply and a Provider. It is created based in the definition expressed by the related MatchType object.

Match is typically related with the main marketplace transaction - the purpose of the marketplace.

type Match {  id: ID!
  type: MatchType!
  my_role: MatchTypeRoleKind @isMPUser
  provider: User!  consumer: User!  supply: Supply!
  quantity: Int # not null if MatchingUnitKine==PER_UNIT/PER_EVENT  start_datetime: DateTime # not null if MatchingUnitKine==PER_HOUR  end_datetime: DateTime # not null if MatchingUnitKine==PER_HOUR  start_date: DateTime # not null if MatchingUnitKine==PER_DAY  end_date: DateTime # not null if MatchingUnitKine==PER_DAY  matching_tool: MatchingTool  matching_score: Int
  status: MatchStatusKind!
  created_by: User
  fields: [Field]!
  created_at: DateTime!  consumer_accepted_at: DateTime  provider_accepted_at: DateTime  backoffice_approved_at: DateTime
  consumer_declined_at: DateTime  provider_declined_at: DateTime  backoffice_rejected_at: DateTime  closed_at: DateTime
  unlocked_to_consumer: Boolean! @isBOUser  unlocked_to_provider: Boolean! @isBOUser  unlocked_provider_fields: [ID!]! @isBOUser  unlocked_consumer_fields: [ID!]! @isBOUser  unlocked_supply_fields: [ID!]! @isBOUser}

  • id is a unique identifier of this object

  • type is a reference to the Match's MatchType

  • my_role (only available to marketplace users) shows the role a user plays in the context of a MatchType. See MatchTypeRoleKind for more details.

  • provider references the provider User within this Match

  • consumer references the provider User within this Match

  • supply references the matched Supply object

  • quantity, start_datetime, end_datetime, start_date, end_date are user for availibility purposes. See AvailabilityManagementKind for more details

  • matching_tool points to the MatchingTool that created this Match. If set to null, the Match is result of direct matching

  • matching_score shows the matching score in case of indirect matching (./marketplace/intro.mdx#matching_order)

  • status indicates this Match's current status.

  • created_by is a User who created this Match

  • consumer_accepted_at, provider_accepted_at, consumer_declined_at, provider_declined_at are corresponding timestamps

  • backoffice_approved_at, backoffice_rejected_at are backoffice actions timestamps

  • closed_at is the moment when this Match was successfully closed_at

Only accessible to BACKOFFICE users

  • unlocked_to_consumer is set if consumer party of the Match can see the Match (sometimes a Match is not directly visible to the participants)

  • unlocked_to_provider is set if provider party can see the Match.

  • unlocked_provider_fields is an array of provider's Fields, visible to the consumer of this Match

  • unlocked_consumer_fields is an array of consumer's Fields, visible to the provider of this Match

  • unlocked_supply_fields is an array of supply's Fields, visible to the consumer of this Match

MatchLight#

This is a lighter version of Match(#match), suitable for some searches.

type MatchLight {  id: ID!
  id_match_type: ID!
  my_role: MatchTypeRoleKind @isMPUser
  id_provider: ID!  id_consumer: ID!  supply: SupplyLight!
  matching_tool: MatchingTool
  matching_score: Int
  created_at: DateTime!  consumer_accepted_at: DateTime  provider_accepted_at: DateTime  backoffice_approved_at: DateTime
  consumer_declined_at: DateTime  provider_declined_at: DateTime  backoffice_rejected_at: DateTime
  closed_at: DateTime
  status: MatchStatusKind!}

  • id is a unique identifier of this object

  • id_match_type is a reference to the Match's MatchType

  • my_role (only available to marketplace users) shows the role a user plays in the context of a MatchType. See MatchTypeRoleKind for more details.

  • id_provider references the provider User within this Match

  • id_consumer references the provider User within this Match

  • supply references the matched Supply object

  • matching_tool points to the MatchingTool that created this Match. If set to null, the Match is result of direct matching

  • matching_score shows the matching score in case of indirect matching (./marketplace/intro.mdx#matching_order)

  • created_by is a User who created this Match

  • consumer_accepted_at, provider_accepted_at, consumer_declined_at, provider_declined_at are corresponding timestamps

  • backoffice_approved_at, backoffice_rejected_at are backoffice actions timestamps

  • closed_at is the moment when this Match was successfully closed_at

  • status indicates this Match's current status.

Only accessible to BACKOFFICE users

  • unlocked_to_consumer is set if consumer party of the Match can see the Match (sometimes a Match is not directly visible to the participants)

  • unlocked_to_provider is set if provider party can see the Match.

  • unlocked_provider_fields is an array of provider's Fields, visible to the consumer of this Match

  • unlocked_consumer_fields is an array of consumer's Fields, visible to the provider of this Match

  • unlocked_supply_fields is an array of supply's Fields, visible to the consumer of this Match

Matching tool types#

Enumerators#

MatchingToolKind#

  • DIRECT_MATCHER is the simplest matching tool, used in conjunction with the service discoverSupply, to directly create a Match for a discovered Supply.
  • SUPPLY_BAG is an abstraction of a common "Shopping Cart", also used in conjunction with the service discoverSupply. It maintains a set of Supply. Execution of this MatchingTool leads to creation of a Match for each contained Supply
  • MATCHING_ORDER is used to indirectly order matches. If defines a Supply discovery filter and certain additional order information. On execution it creates a Match per each Supply hit by the filter. Provider will then typically accept or decline the Match (this part is subject to implementation)
  • AUCTION is randevu implementation of the typical auction procedure. It is naturally created and executed by providers.
enum MatchingToolKind {  DIRECT_MATCHER  SUPPLY_BAG  MATCHING_ORDER  AUCTION}

ExecutionSchedulingKind#

At this time, only MANUAL ExecutionSchedulingKind is supported. It means that the corresponding MatchingTool can only be executed manually, by invoking the executeMatchingTool API.

enum ExecutionSchedulingKind {  IMMEDIATE  PERIODIC  ON_NEW_SUPPLY  MANUAL}

MatchingToolType#

This type represents an extension of a MatchType, aimed to facilitate the matching process. Different types of MatchingToolType applies to different matching styles and offers different matching approach.

type MatchingToolType {  id: ID!  name: String!  type: MatchingToolKind!  execution_type: TaskExecutionKind!  scheduling_type: ExecutionSchedulingKind!  execution_config: JSONObject  is_active: Boolean!
  fields: [FieldType]!}

  • id is a unique identifier of this object

  • type establishes the type of the matching tool.

  • execution_type determines the WHEN and HOW this tool will be executed

  • execution_config some ExecutionSchedulingKinds require additional data.

  • is_active this needs to be set in order to be able to create the MatchingTool instances based on this type.

  • fields is an array of the FieldTypes assigned to this type.

MatchingTool#

This is an instance of a MatchingToolType, ready to be executed and create Matches.

type MatchingTool {  id: ID!  type: MatchingToolType!  name: String!
  supply_filter: [FieldFilter!]  consumer_filter: [FieldFilter!]  provider_filter: [FieldFilter!]
  supply_items: [SupplyBagItem!]
  created_at: DateTime!  creator: User!  last_execution_at: DateTime
  fields: [Field]!
  is_active: Boolean!}

  • id is a unique identifier of this object

  • type is a reference to this tool's MatchingToolType

  • name is an internal alias of this tool

  • supply_filter defines a searching filter for matching Supply

  • provider_filter defines a searching filter for matching provider

  • consumer_filter defines a searching filter for matching consumer

  • supply_items is a reference to Supply instances stored within this tool (only applicable to SUPPLY_BAG)

  • created_at is the timestamp of tool's creation

  • creator is the User who created this tool

  • last_execution_at is the timestamp of the last execution of this tool

  • is_active this needs to be set in order to be able to execute this tool

  • fields is an array of the Fields belonging to this tool.

SupplyBagItem#

This is a helper type, used by SUPPLY_BAG MatchingTools. It allows quantities to be assigned with each stored Supply.

type SupplyBagItem {  id_supply: ID!  quantity: Int!}

  • id_supply is a reference to a Supply

  • quantity stores the quantity of stored Supply

Field types#

Field types are basic building blocks for the definition of all so-called "container types": User, Supply, Match and MatchingTool. Field types have "types" and they define the structure of their corresponding containers.

For example, in a real-estate marketplace, Supply type might be House, and some relevant Field types that define this Supply might be Address (type LOCATION), Area (type DECIMAL), and NrOfRooms (INTEGER)

Enumerators#

InputKind#

enum InputKind {  BOOLEAN  TEXT  INTEGER  DECIMAL
  SELECT  MULTI_SELECT
  DOCUMENT  IMAGE  IMAGE_SET  DOCUMENT_SET
  DATE  DATETIME
  MONETARY_VALUE  LOCATION}

FieldAccessKind#

enum FieldAccessKind {  NONE  READ  WRITE}

FieldAccessClientKind#

This helper type is used to indicate a "role" of a user who has an access to a Field object.

Field access contexts

  • an "owned" object. This can be User or Supply. OWNER of a user is the User themselves, while the OWNER of a Supply is its provider

  • an external object. In context od a Match, FieldAccessClientKind is used to reference a role on the Match

enum FieldAccessClientKind {  OWNER  CONSUMER  PROVIDER}

FieldCategoryKind#

enum FieldCategoryKind {  # User type  FIRST_NAME  LAST_NAME  PROFILE_IMAGE
  # Supply type  NAME  DESCRIPTION  MAIN_IMAGE  BASE_PRICE  MAIN_DATETIME
  # Match type  START_DATETIME  END_DATETIME  START_DATE  END_DATE  QUANTITY}

FieldTypeContainerKind#

enum FieldTypeContainerKind {  USER_TYPE  SUPPLY_TYPE  MATCH_TYPE  MATCHING_TOOL_TYPE}

FieldContainerKind#

enum FieldContainerKind {  USER  SUPPLY  MATCH  MATCHING_TOOL}

FieldType#

FieldType is a definition of a basic piece of information on marketplace data. They are defined in the context of a FieldTypeContainer, which can be MarketplaceUserType, SupplyType, MatchType, MatchingToolType and so on.

Based on this definition are the created instances of corresponding MarketplaceUsers, Supply, Matches and so on. Look at the class Field for more information.

type FieldType {  id: ID!  name: String!  category: FieldCategoryKind  is_deletable_type: Boolean!  input_type: InputKind!  input_options: JSONObject!  is_required: Boolean!  is_nullable: Boolean!  initial_accesses: FieldAccessInfo! @isBOUser  matching_weight: Int  conditions: [Condition]!}
  • id is a User's unique identifier.
  • name is an internal alias for this type. It is not visible fo Marketplace users.
  • category labels a FieldType that is fulfilling some special purpose. See all possible values here
  • is_deletable_type is set to true, if this FieldType can be deleted.
  • input_options depends on the concrete input_type. Different types support different values. See here for details.
  • is_required marks a mandatory FieldType. The value for the corresponding Field will be required in order to finish the object creation (e.g. required Field in User will expect this Field to be provided during this User's onboarding)
  • matching_weight is used during the matching process
  • conditions set the rules to be fulfilled in order that the corresponding Field will be active and visible.
Only accessible to BACKOFFICE users
  • initial_accesses FieldAccessInfo structure defines the visibility aspects of this FieldType, just upon the corresponding Field's creation.

Field#

Fields are the basic building blocks for the so called FieldContainers (e.g. Users, Supply, Matches, etc). On each particular's FieldContainer's creation, a Field will be attached to it for every defined FieldType within its FieldTypeContainer

type Field {  id: ID!  field_type: FieldType!  value: JSON  current_accesses: FieldAccessInfo! @isBOUser  my_access: FieldAccessKind @isMPUser}
  • id is a User's unique identifier.
  • field_type holds a reference to the corresponding FieldType. This is very often used to inspect on what kind of value to expect for this Field.
  • value is a concrete value of this Field. E.g. if a FieldType's input_value is TEXT, a valid value would be 'This is a text')
  • my_access is only accessible to Marketplace Users and shows the current access of the logged user.
Only accessible to BACKOFFICE users
  • current_accesses is showing the current visibility of this Field, that is, who can handle it and how (READ, WRITE or NONE)

FieldAccessInfo#

This structure defines who can do what with a Field. It's legal values depend on the FieldType and the context.

type FieldAccessInfo {  to_owner: FieldAccessKind  to_provider: FieldAccessKind  to_consumer: FieldAccessKind  to_discoverer: FieldAccessKind  to_guest: FieldAccessKind}
About field access
  • for the isolated FieldContainers like User and Supply, the access to its Fields are usually given to its owner only, so the FieldAccessInfo will only have one property - to_owner.
  • in the context of a Match, the visibilities of User Fields (of consumer and provider side) and Supply Fields (of a matched Supply) are handled within the Match object.

FieldFilter#

This helper type is used for different filtering/discovery purposes. It defines a tool to query instance of a concrete FieldType

type FieldFilter {  id_target_field_type: ID!  value: JSON}
  • id_target_field_type is a target FieltType being filtered
  • value is a concrete filter. Its structure and valid format depends on the target FieldType's input_type

FavouriteFieldType#

This structure is a template for storing often used FieldType objects, to accelerate its creation.

type FavouriteFieldType {  name: String!  input_type: InputKind!  input_options: JSONObject!  is_required: Boolean!  is_nullable: Boolean!}

Flow types#

Flow in randevu is the main building block of dynamic aspects of the platform. It is an abstraction of a state machine, and enables Marketplace owners with a means to define things such onboarding processes, matching transactions, auctions or any kind of custom process.

Enumerators#

FlowPurposeKind#

enum FlowPurposeKind {  PARTICIPANT_ONBOARDING  SUPPLY_ONBOARDING  TRANSACTION  CUSTOM_FLOW}

FlowType#

Flow type defines the state machine that will handle certain behavior in randevu. It's main feature is purpose, which further determines flow's usage.

type FlowType {  id: ID!  name: String!
  purpose: FlowPurposeKind
  initiating_event: RandevuEventKind!  initiating_conditions: [FlowCondition!]
  root_type: FieldTypeContainerKind! # USER_TYPE, SUPPLY_TYPE...  id_root_type: ID!
  states: [StateType!]!  transitions: [TransitionType!]!  var_types: [FlowVariableType!]!
  is_active: Boolean!
  retired_at: DateTime}

  • id iis this flow type's unique identifier

  • name is a user friendly name of this Flow type

  • purpose determines the purpose of the Flow type

  • initiating_event sets the randevu event that will fire an instance of this Flow

  • initiating_conditions define additional restrictions for initiating the flow

  • root_type defines the flow initiating object type: USER_TYPE, SUPPLY_TYPE...

  • id_root_type identifies the exact root object type

  • states, transitions define the state machine to drive the flows of this type

  • var_types are advanced concepts enabling flow's definition

  • is_active if true, this flow can be instantiated

  • 'retired_at' this flow is retired

Flow#

Flow is a running instance of a Flow type. It can be in exactly one state at a time. Transitions will be triggered as defined to change state until the finishing state has been reached. The flow is then terminated.

type Flow {  id_flow_type: ID!
  initiated_at: DateTime!  terminated_at: DateTime
  current_state: String!}

  • id_flow_type is the reference to the Flow type

  • initiated_at, terminated_at are flow's timestamps

  • current_state marks the current flow's state

Transaction types#

Enumerators#

TransactionKind#

Transaction is an abstraction of a user-facing business process executed on randevu. Typically, a consumer and provider (or more of them) will participate in a Transaction.

SINGLE_DIRECT_CHECKOUT and SINGLE_INDIRECT_CHECKOUT are two simple Transaction Types defined by randevu Wizard. CUSTOM_TRANSACTION is fully customisable construct, based on Flows, for the definition of fully customised transaction types.

enum TransactionKind {  SINGLE_DIRECT_CHECKOUT  SINGLE_INDIRECT_CHECKOUT  CUSTOM_TRANSACTION}

TransactionStatusSchemeKind#

This value defines how the status of a Transaction will be displayed to consumer and provider participants. SYMMETRICAL means that all participants will see the same status - the one defined by the underlying Flow. If FLOW_MATCH option is taken, than the provider will "see" their Match's status instead.

enum TransactionStatusSchemeKind {  SYMMETRICAL  FLOW_MATCH}

TransactionType#

Transaction is an abstraction of a user-facing business process executed on randevu. Typically, a consumer and provider (or more of them) will participate in a Transaction.

Transaction type is a definition of such transactions.

type TransactionType {  id: ID!  type: TransactionKind!  status_scheme: TransactionStatusSchemeKind!
  name: String!
  my_role: MatchTypeRoleKind!
  flow_type: FlowType
  is_default: Boolean!  is_active: Boolean!
  root_type: MatchingToolType!  retired_at: DateTime}

  • id is the unique identifier

  • type marks this Transaction type's kind/purpose

  • status_scheme defines the end user transaction status resolution strategy

  • name is a user friendly name for this type

  • my_role is visible to participants and determins their own role in this Transaction type

  • flow_type if the type is CUSTOM_TRANSACTION, this transaction will be implemented by a FlowType

  • is_default is a pointer to a single "default" TransactionType. It can be used fo for example display a shortcut to the Transaction on the home page

  • is_active means that this Transaction can be instantiated

  • root_type defined a MatchingToolType user to initiate this type of Transaction

  • retired_at this transaction type is retired, cannot be used any more

Transaction#

Transaction is an abstraction of a user-facing business process executed on randevu. Typically, a consumer and provider (or more of them) will participate in a Transaction.

type Transaction {  id: ID!  type: TransactionType!  my_role: MatchTypeRoleKind! @isParticipantOrGuest
  root_object: MatchingTool!
  status: String
  created_at: DateTime!  terminated_at: DateTime}

  • id is the unique identifier

  • type marks this Transaction's type

  • my_role is visible to participants and determins their own role in this Transaction type

  • root_object refers to this Transaction's root object, which is always a MatchingTool

  • status shows this Transaction current status. Will typically be derived from the underlying Flow

  • created_at,terminated_at are the timestamps

TransactionLight#

This is a lighter representation of a Transaction, user by getter APIs.

type TransactionLight {  id: ID!  type: TransactionType!  my_role: MatchTypeRoleKind! @isParticipantOrGuest
  id_root_object: ID!  root_object_type: EventObjectKind!
  status: String
  created_at: DateTime!  terminated_at: DateTime}

  • id is the unique identifier

  • type marks this Transaction's type

  • my_role is visible to participants and determins their own role in this Transaction type

  • id_root_object refers to this Transaction's root object, which is always a MatchingTool

  • root_object_type refers to this Transaction's root object's type

  • status shows this Transaction current status. Will typically be derived from the underlying Flow

  • created_at,terminated_at are the timestamps

PreparedTransaction#

This is a lighter representation of a Transaction, used during Transaction preparation.

type PreparedTransaction {  id: ID!  type: TransactionType!  my_role: MatchTypeRoleKind! @isParticipantOrGuest
  root_object: MatchingTool!
  status: String
  created_at: DateTime!  terminated_at: DateTime}

  • id is the unique identifier

  • type marks this Transaction's type

  • my_role is visible to participants and determins their own role in this Transaction type

  • root_object refers to this Transaction's root object, which is always a MatchingTool

  • status shows this Transaction current status. Will typically be derived from the underlying Flow

  • created_at,terminated_at are the timestamps

Payment types#

Enumerators#

PaymentStatusKind#

enum PaymentStatusKind {  PREPARED  COMPLETED  FAILED}

CurrencyKind#

enum CurrencyKind {  EUR}

CurrencyUnitKind#

enum CurrencyUnitKind {  CENT}

PaymentServiceProvider#

Provider of the payment services on randevu (e.g. Stripe)

type PaymentServiceProvider {  type: PaymentProviderKind! # STRIPE  type: JSONObject!}
  • type is a provider kind
  • data is additional info on service provider

PaymentProviderConnection#

This structure is used when marketplace user (often a service/product provider) connects his randevu account with an account in an external payment provider's system (e.g. STRIPE).

As a return value of the corresponding service it delivers a direct URL to redirect the user to.

type PaymentProviderConnection {  url: String!}
  • url is a link to redirect the user to the payment provider's page

PaymentType#

Payment types define the payment flows in the system.

type PaymentType {  id: ID!  payment_provider_type: PaymentProviderKind!  config: JSONObject!}

  • id is a unique identifier of this object

  • payment_provider_type is a reference to the external provider for the PaymentStatusKind

  • config depends on the provider

MonetaryValue#

This structure is used to handle money in randevu. It carries the info about the currency and amount.

type MonetaryValue {  currency: CurrencyKind!  unit: CurrencyUnitKind!  amount: Int!}

  • currency indicated the currency (e.g. 'EUR')

  • unit indicates the unit of the currency, the amount is expressed in (e.g. 'CENT')

  • amount is the monetary amount, expressed in units of a currency

input MonetaryValueInput { currency: CurrencyKind! unit: CurrencyUnitKind! amount: Int! }

Payment#

This types represents a Payment in randevu.

type Payment {  id: ID!  payment_type: PaymentType!
  amount: MonetaryValue!  description: String
  id_sender: ID!  id_recipient: ID!  prepared_by: ID!
  ids_matches: [ID!]!
  status: PaymentStatusKind!
  prepared_at: DateTime!  completed_at: DateTime  failed_at: DateTime}

  • id is the unique identifier of the Payment

  • payment_type is [type]{#payment_type} of this payment

  • amount is payment's amount

  • description is this payment's description

  • id_sender references the payer user

  • id_recipient references the payee user

  • prepared_by references the user who prepared this payment

  • ids_matches is the array of Matches, involved in this payment

  • status is this payment's current status

  • prepared_at is a timestamp

  • completed_at is this payment successful completion timestamp

  • failed_at is this payment failure timestamp

PaymentCheckoutConnection#

This structure is user when a payment is to be executed. It should be requested by a frontend app, to initiate the payment process.

type PaymentCheckoutConnection {  id_payment: ID!  url: String!}

  • id is the unique identifier of the Payment

  • url is a link to redirect the payer towards the checkout page

File types#

Enumerators#

FileKind#

enum FileKind {  IMAGE  DOCUMENT}

FileUpload#

This type is exclusively used as a return value of an upload of a file.

type FileUpload {  id: ID!  type: FileKind!  name: String!  physical_name: String!  url: String!}

  • id is a unique object's identifier

  • type marks the file's type

  • name of the file

  • physical_name of the file

  • url is the direct link for the file upload