Introduction

Midoco is a mid-office specialized system, specifically optimized for the travel industry (www.midoco.de). Nezasa has partnered with Midoco to provide a complete offering, from the sales/distribution of your product to the accounting.

For more detailed information, please visit Midoco's website at https://www.midoco.de/en/erp-system-travel or contact Midoco directly.

TripBuilder and Midoco Integration 

The connector to Midoco is a paid add-on of TripBuilder which comes with a setup and a monthly license fee. To get the connector configured for your setup, please contact our support team for more details. 

 

Supported Use Cases

Automated Submission

The Midoco Connector supports automated submission for the following use cases:

  • Booking
  • Booking Change
  • Cancellation

Manual Submission

Furthermore, a submission can be triggered anytime manually in Cockpit from within the actions menu of a booking as shown below:

60d2f243c03a6.png

A manual transmission is for example required for the following use cases:

  • Status Change on Ad-Hoc Component
    When updating ad-hoc components manually, e.g., their status, then manual submission to Midoco must be triggered to have the update as well in Midoco.
  • Rest Payments
    Only the initial booking and thus down payment triggers an automatic submission to Midoco. When rest payments are received, a submission to Midoco must be triggered manually.

Submission History

In Customer Care, the executed submissions are visible:

60d2f2431f9ce.png

 

Midoco Connector Configuration

The following configuration options are available and can be found at TripBuilder -> Cockpit -> Settings -> Distribution Channel -> 3rd-Party Integrations -> Midoco.

Bildschirmfoto_2022-05-31_um_00.26.22.png

Setting Description
Enable Submission This switch controls if the itinerary bookings are submitted to Midoco

Midoco Unit Currency

The unit currency is configured in your Midoco instance.
Midoco Supplier ID The value to be used as the package supplier in Midoco. If not set, the uppercased ID of the tour operator in Nezasa's system is used as a fallback.
Midoco Order ID as External ID By enabling this feature flag, the Midoco order ID will be copied to the so-called external reference ID of the booking in TripBuilder. By doing so, bookings in customer care can be searched by the order ID and for travel documentation and vouchers, it can be configured to use the external reference ID which in turn then will show the Midoco Order ID.
Accommodations - Use Hotel ID as Midoco Supplier ID By default, the Midoco connector passes the ID of the underlying bed bank on hotel components (e.g., Expedia, Hotelbeds) as supplier ID to Midoco. If this feature flag is activated, the connector will use the hotel ID as defined by the bed bank instead. This is useful in case there is a direct contract between you as a tour operator and the hotel, and therefore the payment does not go via the bed bank.
Send Payment Data If enabled, the payment transactions registered in TripBuilder will be submitted to Midoco.
Send Promo Discount

BETA*

If enabled, discounts due to applied promo codes are sent to Midoco.

Additionally, if enabled, it is possible to define what supplier ID should be used on the promo code component created in Midoco. If nothing is defined, the ID of the tour operator will be used.

* the feature is beta because Midoco is currently looking into an issue that causes a non-zero net price value in Midoco on the voucher component.

Destination Target Key

Relevant for tour operators located in the European Union.

Sets the destination target key to "EU" if the first destination of the itinerary is an EU country, "NONEU" otherwise.

Send Channel ID

If enabled, the distribution channel ID will be sent to Midoco as broker ID.

Send Down Payment Amount

If enabled, the down payment amount is submitted to Midoco accordingly as the so-called deposit

Send Cancellation Policy  If enabled, the cancellation policy is sent as remarks to Midoco.

 

 

Data Model Mappings

Please find below the mappings between the two systems, Nezasa's TripBuilder and Midoco. The mapping applies if the information already exists in Nezasa's TripBuilder.

Midoco Documentation

The article is using the technical attribute names of Midoco. Please consult the Midoco documentation for further details about these attributes.

List of Mappings

The mapping tables below are kept up-to-date and cover the core mappings. Additional data might be submitted to Midoco that is not documented. The connector generally tries to pass as much information as possible. 

Midoco Booking Message

The Midoco Booking Message is the root object submitted by TripBuilder to Midoco. It holds all relevant information. The following attributes of that object are populated by Nezasa:

  • Package Info
    General package information about the booking. Also contains the list of PAX.
  • Agency Identity
    The underlying information of the agency for the booking.
  • Customer
    Contact details of the booking customer.
  • Payment Info
    The payment information, i.e., the payment transactions known to Nezasa's TripBuilder. Please note that, as not all payments might be handled via the TripBuilder, the information registered here might not be complete. Furthermore, only "closed" payment transactions are submitted to Midoco.
  • Booking
    Contains details of the booked components. Note that some pricing information is passed as well, but the main price information is passed on "Prices". The exact information depends on the component type (Nezasa terminology) resp. the service type (Midoco terminology).
  • Prices
    Contains an entry for each booked component to pass the sales and net price of that component. Additionally, the prices array contains one price entry passing the package price information (total booking price of the package). See "Midoco Booking Price" for the mappings.
  • Internal Treatment
    The information on this attribute makes sure that repeating calls to Midoco for the same booking update the existing entries in Midoco, and don't create new ones.

Midoco PackageInfo

Nezasa TripBuilder Midoco
Itinerary ID attrPackageId

Tour Operator ID

(converted to uppercase letters or ID configured on Midoco configuration)

attrPackageSupplierId
The PAX Info person

 

Midoco AgencyIdentity

It is recommended to use the agency features in Midoco in combination of setting the Midoco agency ID on the agency in TripBuilder as so-called "external reference" (go to Travel Agency Management in Cockpit Settings, then open "Travel Agency Settings", and there define an external reference of type Midoco holding the agency ID from your Midoco). 

Bildschirmfoto_2022-01-26_um_19.29.25.png

Nezasa TripBuilder Midoco
Agency Short Name AgencyInfo.shortName
Agency Legal Name AgencyInfo.name
Street Line 1 AgencyInfo.street
Street Line 2 AgencyInfo.streetNo
City AgencyInfo.city
Postal Code AgencyInfo.zipCode
Phone AgencyInfo.phone
Email AgencyInfo.email
Distribution Channel Ref ID

agent

(The ID needs to exist in Midoco, otherwise, Midoco will show a warning. This may also be called "Broker ID/Info".)

Agency External Ref ID of Type Midoco

(If the agency defines a Midoco external reference, this maps to its external reference ID)

agency_no

(The ID needs to exist in Midoco, otherwise, Midoco will show a warning.)

 

Midoco Customer

The main contact/billing contact of Nezasa is mapped on the Midoco Customer.

Nezasa TripBuilder Midoco
First Name privateData.forename
Last Name privateData.name
Gender mapped into a salutation privateData.salutation
Street1 street
City city
Country country ISO Code
Postal Code postalCode
Phone communication[ attrType = PHONE]
Email communication[ attrType = EMAIL]
Language language

Language is sent as 2-letter ISO code as lowercase with the exception of nl which is sent as "nl_NL".

 

Midoco Person (PAX)

The PAX data of TripBuilder are mapped to Midoco as follows.

Nezasa TripBuilder Midoco
First Name forename
Last Name name
Second or Middle Names middleName
Gender mapped into a salutation salutation
Birth Date birthday
The age of the person when the itinerary starts (start date of itinerary) age
Nationality (as 2-letter ISO code) nationality

 

 

 

Midoco External Payment

The payment information from Nezasa's TripBuilder is mapped to the respective Midoco objects ccPayment, debitPayment or advisedPayment. This is done for payment transactions with the status "closed" in TripBuilder. Open payment transactions, such as a down payment by invoice, is not submitted to Midoco.

Nezasa TripBuilder Midoco
Transaction Id transactionNumber

Date of the transaction

paymentDate

Transaction type. CCCAPTURE, PAYPAL

transactionType

 

Transaction amount

amount

 

Transaction currency

currency

The payment network. VISA, MASTERCARD, AMEX, DINERS, AIRPLUS

( MASTERCARD is used as a fallback when the mapping to another medium failed or the payment network was not defined at all. )

medium

Sent as a warning when MASTERCARD is used as a fallback.

comment

 

Midoco Booking Price

Nezasa TripBuilder Midoco

Supplier ID

(For components, if the component defines a supplier contact with a Midoco external reference, this maps to its external reference ID)

supplier

Booking ID of the itinerary on package level.

On the component level, it's either the booking reference of the third-party supplier or if not available, the Nezasa component ID

bookingId

Net/Sales Price - Amount

(For components, the net price. For the package info the sales price.)

totalPrice

 

Sales Price - Currency

(The sales currency. In the case of components, the net price value is converted.)

currency

 

Net Price - Amount

(Not set for package info. For components, this is the price as received from the supplier.)

original_price

 

Net Price - Currency

(Not set for package info. For components, this is the price as received from the supplier.)

original_currency

 

Sales price of the package

( Only set fo package info. )

sale_price

"false" vatIncluded
The pax information on the travellers passed as personAssignment in the related component persons
The exchange rate from net to sales currency. Only set for components. buyCurrencyRate

 

Booking Status

The mapping of the Nezasa status to the Midoco status.

Nezasa TripBuilder Midoco
on request RQ
cancelled XX
all other statuses OK

 

Accommodation

Nezasa AccommodationComponent - Midoco Booking[AccommodationServiceType]

The generic information of the accommodation booking. 

Nezasa TripBuilder Midoco

Supplier ID

(For components, if the component defines a supplier contact with a Midoco external reference, this maps to its external reference ID)

attrSupplier

Either the booking reference of the third-party supplier or if not available, the Nezasa component ID.

attrBookingId
Nezasa Component ID attrReferenceBookingId
"Nezasa" attrReferenceType
Product Name serviceDescription
Room Code accommodationCode
Room Name accommodationDescription
Room Name roomDescription
Product City area_description
Product City location_description
Product Country countryDescription
Amenities AdditionalServices
true if Component is in status "cancelled" attrPreventPrinting
one of AccommodationServiceType accommodationService
externally paid charges remarks

 

Midoco AccommodationServiceType

Nezasa TripBuilder Midoco
Hotel - Name (Product - Name) serviceDescription
Room Category - Code accommodation
Room Category - Name accommodationDescription
Meal Amenity - External ID catering
Meal Amenity - Name cateringDescription
PAX Assigned to Component personAssignment
Component Status serviceStatus
Net Price - Amount

totalPrice

(converted into sales currency)

Sales Price - Currency

currency

"false" vatIncluded
Start Date startDate
End Date endDate
Street Name address_line1
City address_line2
Country address_line3
Postal Code address_line4
Country country_description
City locationDescription
Hotel contact number emergency-Number

 

Activity

Nezasa Component - Midoco Booking[EventServiceType]

The generic information of the accommodation booking. 

Nezasa TripBuilder Midoco

Supplier ID

(For components, if the component defines a supplier contact with a Midoco external reference, this maps to its external reference ID)

attrSupplier
Either the booking reference of the third-party supplier or if not available, the Nezasa component ID. attrBookingId
Nezasa Component ID attrReferenceBookingId
"Nezasa" attrReferenceType
Product Name serviceDescription
Amenities AdditionalService
true if Component is in status "cancelled" attrPreventPrinting
Product City area_description
Product Country countryDescription
one of GenericServiceType eventService

 

Midoco EventServiceType

Nezasa TripBuilder Midoco
Product Name serviceDescription
Component Status serviceStatus

PAX Assigned to Component

(if available on Nezasa component, otherwise all pax are assigned)

personAssignment
Net Price - Amount

price

(converted into sales currency)

Sales Price - Currency currency
Street Name locationAddress1
City locationAddress2
Country locationAddress3
Postal Code locationAddress4
"false" vatIncluded

Start Date

startDate

End Date

endDate

Start Time

startTime

End Time

endTime
Nezasa service category ticketCategory

 

Upsell Item, Insurance, Ad-Hoc Components, Base Service

Upsell items, insurances, ad-hoc components, and base services are mapped on the generic service type of Midoco. 

Bildschirmfoto_2022-01-26_um_19.37.24.png

Nezasa Component - Midoco Booking[GenericServiceType]

Nezasa TripBuilder Midoco

Supplier ID

(For components, if the component defines a supplier contact with a Midoco external reference, this maps to its external reference ID)

attrSupplier
Either the booking reference of the third-party supplier or if not available, the Nezasa component ID. attrBookingId
Nezasa Component ID attrReferenceBookingId
"Nezasa" attrReferenceType
Product Name serviceDescription
Amenities AdditionalService
true if Component is in status "cancelled" attrPreventPrinting
Product City area_description
Product Country countryDescription
one of GenericServiceType genericService

 

Midoco GenericServiceType

Nezasa TripBuilder Midoco
Product Name and Service Category serviceDescription
Component Status serviceStatus

PAX Assigned to Component

(if available on Nezasa component, otherwise all pax are assigned)

personAssignment
Net Price - Amount

servicePrice

(converted into sales currency)

Sales Price - Currency serviceCurrency
"false" vatIncluded

Start Date

(if available on Nezasa component, otherwise set to start/end date of the itinerary because mandatory in Midoco)

startDate

End Date

(if available on Nezasa component, otherwise set to start/end date of the itinerary because mandatory in Midoco)

endDate

 

Rental Car

Bildschirmfoto_2022-01-26_um_19.35.46.png

Nezasa RentalCarComponent - Midoco Booking[CarServiceType]

Nezasa TripBuilder Midoco

Supplier

(For components, if the component defines a supplier contact with a Midoco external reference, this maps to its external reference ID)

attrSupplier
Either the booking reference of the third-party supplier or if not available, the Nezasa component ID. attrBookingId
Nezasa Component ID attrReferenceBookingId
"Nezasa" attrReferenceType
Product Name serviceDescription
true if Component is in status "cancelled" attrPreventPrinting
one of CarServiceType carService

 

Midoco CarServiceType

Nezasa TripBuilder Midoco
Supplier carSupplier
Component Status serviceStatus
ACRISS Description - Category Code category
ACRISS Description - Type Code carType
Product Name carDescription
Net Price - Amount

servicePrice

(converted into sales currency)

Sales Price - Currency currency
The driver personAssignment
"false" vatIncluded
Pickup - Location Code (IATA) or Coordinates pickupCode
Pickup - Location Name pickupDescription
Pickup - Country Code countryCode
Pickup - Country Name countryDescription
Pickup - Date pickupDate
Pickup - Time pickupTime
Drop-off - Location Code (IATA) or Coordinates returnCode
Drop-off - Location Name returnDescription
Drop-off - Country Code returnCountryCode
Drop-off - Country Name returnCountryDescription
Drop-off - Date returnDate
Drop-off - Time returnTime

 

Remark:

The following inputs have the associated maximum lengths:

pickupCode - 10
pickupDescription - 30
returnCode - 10
returnDescription - 30
countryCode - 3
countryDescription - 64
returnCountryCode - 3
returnCountryDescription - 64

 

Transfer

Nezasa TransferComponent - Midoco Booking[TransferServiceType]

Nezasa TripBuilder Midoco

Supplier

(For components, if the component defines a supplier contact with a Midoco external reference, this maps to its external reference ID)

attrSupplier
Either the booking reference of the third-party supplier or if not available, the Nezasa component ID. attrBookingId
Nezasa Component ID attrReferenceBookingId
"Nezasa" attrReferenceType

Concatenation of the name of the start and end location:

Start Location Name - End Location Name

serviceDescription
true if Component is in status "cancelled" attrPreventPrinting
one of TransferServiceType transferService

 

Midoco TransferServiceType

Nezasa TripBuilder Midoco

Concatenation of the ID of the start and end location:

Start Location ID - End Location ID

serviceCode
Component Status serviceStatus

Concatenation of the name of the start and end location:

Start Location Name - End Location Name

serviceDescription
Start Date startDate
End Date endDate
Start Location - ID departureCode
Start Location - Name departureDescription
End Location - ID destinationCode
End Location - Name destinationDescription

 

Transport

Nezasa TransportComponent - Midoco Booking[TransferServiceType, FlightServiceType, RailServiceType]

Nezasa TripBuilder Midoco

Supplier

(For components, if the component defines a supplier contact with a Midoco external reference, this maps to its external reference ID)

attrSupplier
Either the booking reference of the third-party supplier or if not available, the Nezasa component ID. attrBookingId
Nezasa Component ID attrReferenceBookingId
"Nezasa" attrReferenceType

Concatenation of the name of the start and end location:

Start Location Name - End Location Name

serviceDescription
true if Component is in status "cancelled" attrPreventPrinting
list of TransferServiceType (see below) transferService
list of FlightServiceType (see below) flightService
list of RailServiceType (see below) railService

 

Nezasa TransportBusSegment - Midoco TransferServiceType

Nezasa TripBuilder Midoco
Component Status serviceStatus

Concatenation of the name of the start and end location and service category:

Start Location Name - End Location Name ; Service category

serviceDescription

Concatenation of the ID of the start and end location:

Start Location ID - End Location ID

serviceCode
Departure Location - IATA Code departureCode
Departure Location - Name departureDescription
Departure Location - Date startDate
Arrival Location - IATA Code destinationCode
Arrival Location - Name destinationDescription
Arrival Location - Date endDate

 

Nezasa TransportTrainSegment - Midoco RailServiceType

Nezasa TripBuilder Midoco
Component Status serviceStatus

Concatenation of the name of the start and end location:

Start Location Name - End Location Name

serviceDescription
Transport Number serviceCode
"STANDARD_ONLINE" ticketCategory
Transport Class bookingClass
Departure Location - IATA Code departureCode
Departure Location - Name departureDescription
Departure Location - Date departureDate
Arrival Location - IATA Code arrivalCode
Arrival Location - Name arrivalDescription
Arrival Location - Date arrivalDate

 

Nezasa TransportFlightSegment - Midoco FlightServiceType

Nezasa TripBuilder Midoco
Component Status serviceStatus
Airline Code carrier
Flight Number flightNo
Booking Class Code bookingClass
Transport Class cabinClass
Departure Location - IATA Code departureCode
Departure Location - Name departureDescription
Departure Location - Date departureDate
Departure Location - Time departureTime
Arrival Location - IATA Code destinationCode
Arrival Location - Name destinationDescription
Arrival Location - Date arrivalDate
Arrival Location - Time arrivalTime

Bildschirmfoto_2022-01-26_um_19.33.57.png

Promo Code

The Midoco Connector now supports the submitting of TripBuilder promo codes. Please check your Midoco Connector configuration, the submission of promo code information to Midoco needs to be explicitly enabled.

How it works: the promo code will be mapped to a generic Midoco service with a negative sales price, the value of the reduction applied by the promo code. This service is added to the Midoco order, but outside of the travel package. By default, the supplier ID will be the ID of your tour operator instance in Nezasa. However, you can configure a dedicated supplier ID just for promo codes on your Midoco configuration in order to identify the promo code services in Midoco and define your accounting rules accordingly, if required.

 

Nezasa Component - Midoco Booking[GenericServiceType]

Nezasa TripBuilder Midoco

ID of tour operator or if defined, the supplier ID for promo codes as per Midoco Connector config

attrSupplier

The booking ID reflects the promo code itself, as well as for which booking it was redeemed. This is required because in Midoco, the booking ID needs to be globally unique.

Format: "promoCode.code-itinerary.refId"

attrBookingId

The booking ID reflects the promo code itself, as well as for which booking it was redeemed. This is required because in Midoco, the booking ID needs to be globally unique.

Format: "promoCode.code-itinerary.refId"

attrReferenceBookingId
"Nezasa" attrReferenceType

The service description is a readable description of the promo code. If available, the code and title are concatenated. Because the promo code title is an optional field in TripBuilder, that part may not be there ultimately in Midoco

Format: "promoCode.code: promoCode.title"

serviceDescription
not set AdditionalService
false attrPreventPrinting
one of GenericServiceType genericService

Promo Code Condition

remarks

 

BookingPrice

Nezasa TripBuilder Midoco

ID of tour operator or if defined, the supplier ID for promo codes as per Midoco Connector config

supplier

The booking ID reflects the promo code itself, as well as for which booking it was redeemed. This is required because in Midoco, the booking ID needs to be globally unique.

Format: "promoCode.code-itinerary.refId"

bookingId

0

original_price
Sales currency

original_currency

Promo value (negative value) in sales currency

totalPrice

Unit currency currency

Sales → Unit currency

buyCurrencyRate

Promo value (negative value) in sales currency

salePrice

Not set

vatIncluded

 

Midoco GenericServiceType

Nezasa TripBuilder Midoco

The service description is a readable description of the promo code. If available, the code and title are concatenated. Because the promo code title is an optional field in TripBuilder, that part may not be there ultimately in Midoco

Format: "promoCode.code: promoCode.title"

serviceDescription
OK serviceStatus

Not set

personAssignment
0

servicePrice

Sales currency serviceCurrency
Not set vatIncluded
Itinerary start date startDate
Itinerary end date endDate

 

Frequently Asked Questions

Are all Midoco setups compatible with the Nezasa Midoco Connector?

Generally yes. However, the Nezasa Midoco Connector always submits package information. Your Midoco configuration might not be yet ready for all use cases within Midoco. Please get in touch with your Midoco project manager, therefore.

The supplier IDs of Nezasa and the ones we already have set up in Midoco are different. Can this be mapped? 

Yes, in Midoco. Midoco has an option to map the supplier IDs. Please contact your Midoco project manager for details. For what is considered the "tour operator" in TripBuilder and which is used as the default supplier in Midoco on components, the ID to be used towards Midoco can be configured on the Midoco connector. 

Does the Midoco Connector pass the gender of PAX?

No, this is currently not supported by the Midoco API.

However, the Midoco Connector maps the gender to the salutation attribute of Midoco. Setting the salutation attribute takes into account the preferred language of the itinerary (e.g. for English: male -> Mister, female -> Miss). 

Also, note that the preferred language stored on the itinerary is passed as well to Midoco. In Midoco, in the section to manage the CRM master data, you'll find advanced mapping options for salutations. For detailed questions about that mapping, please contact your Midoco project manager.

The sales price of the package in Midoco is 0. Why?

The cause of this might be another error. Generally, Midoco doesn't show the package sales price if there is an error within the package. Another possible cause can be that the package was cancelled and there were no cancellation fees. In that case, the sales price is supposed to be 0. That would be correct.

Can I see what the Midoco Connector sends to the Midoco API?

Yes, this is indeed possible via the Nezasa Cockpit UI and can be very helpful to investigate on a more technical level. The XML requests sent to Midoco can be found in the system events.

Are cancellations supported?

Yes, upon cancellations, the status of components or the package is updated accordingly. Furthermore, the sales price of the package resp. the purchase price of components is updated to the remaining costs after the cancellation, i.e., the remaining price/fees after cancellation.

Certain components from TripBuilder are not visible in Midoco. Why?

Generally, the Midoco Connector submits all TripBuilder components to Midoco. A good way to verify this is to check the XML request sent to Midoco in the system events. A possible reason that a certain is not listed in Midoco, can be that the booking reference is not unique. In Midoco, supplier code and booking references need to be unique.

Sometimes, different bookings are merged together in the same midoco order. What might cause this?

One reason is when the same invoice address and the same travel dates are used for the different bookings. Midoco tries to merge them together automatically. This can happen more while testing different itineraries using the same dates and passenger information. 

 

Feature Limitations

Not all data available in TripBuilder is submitted to Midoco, nor is TripBuilder having an equivalent feature for the wide set of options Midoco supports. Please find below a list of functionality that were mentioned to Nezasa before but are currently not supported.

Agency Commissions

The TripBuilder has currently no support for agency commissions.

Rest Payments

Rest payments currently don't trigger automatically a new submission to Midoco. A manual submission can be triggered in these cases to update the payment status on Midoco’s side. Only the main booking actions such as book, cancel, booking change trigger an automatic transmission to Midoco. 

 

 

 

Comments

0 comments

Please sign in to leave a comment.