Integration Guide Details

Integration guide for NTMP

Context
1. General instruction ……………………………………………………………….. 3
2. First APIs : Create or Update Booking ……………………………………..4
3. Second APIs : Cancel Booking …………………………………………………18
4. Third APIs : Expenses Details ………………………………………………….23
5. Forth APIs : Occupancy Update …………………………………………….31

2 Integration guide
 Integration guide for NTMP

 Before we start, below are General instruction for API to be used:

 To apply API , you have to contact your resource system provider to help with
that
 If any assistant needed, use “Contact Us” form to provide support.
 This documents in pure technical documents, so you may need assistants by
information technology specialist or your IT team.
 To ensure proper integration please follow below guidelines:
 There are four API’s listed in this Manual which are
1. Create or Update booking
2. Cancel booking services
3. Booking Expensive details
4. Occupancy update
 Create or Update booking is first API should be consumed according to below
details and there are 4 key filed should be considered

• TransactionID: Not Mandatory in case of First Transaction (Booking or

Direct Check In) but needed in Check Out or Cancellation process.

• If Sequence is Booking  Check In  Check out, then at the time of

Booking, this will be generated by SCTH and consumer receives as response,
consumer should later provide in both Check In and Check Out Process.

• If Sequence Check In  Check out, then at the time of Check In this will be
generated by SCTH and consumer receives as response, consumer should
later provide in Check Out Process.

• UserID (Your User ID, you have to provide it other than providing
authentication headers).

• CUFlag (C = Create = 1, U = Update = 2)

- You have to integrate using staging first , once SCTH verify the
integration you will be provided production details

3 Integration guide
 Integration guide for NTMP

API’s Details

First API: Create or update booking

This service provides capabilities to get all booking information required

Service Property Description

Service Name CreateOrUpdateBooking
Version 1
Service Owner SCTH
Architectural Style REST Web Service
Support Message Exchange Request-Response (Synchronous)
Patterns
Supported Transport Protocol HTTP
Request Authentication Basic + API Key
Request Authorisation ACL( Access Control List) Based

1 REST Service Capabilities

CreateOrUpdateBooking:
Interface description
The interface can be used to create or update the hotel booking with the initial required
details from customer.

Existing Service Name

N/A

Service Endpoint (Base URL)

Environment URL
Sandbox (DEV) https://dev-
hotelsapi.scth.gov.sa/gateway/CreateOrUpdateBooking/1.0/createOrUpdateBo
oking
Test (e.g. SIT) https://api-
stg.ntmp.gov.sa/gateway/CreateOrUpdateBooking/1.0/createOrUpdateBooking
Production https://api.ntmp.gov.sa/gateway/CreateOrUpdateBooking/1.0/createOrUpdate
Booking

4 Integration guide
 Integration guide for NTMP

Request
Customer should hit the above URL’s to get the response and no input query-parameters
required

Query Parameters

Name Requi Type Allowed Values Description

red?
NA

Request Body

Property Type Required Description

BookingNo String Yes BookingNo contains only English & Numeric
characters.(15 digits)
NationalityCode Numeric Yes Nationality Code Lookup
CheckInDate Numeric Yes Format YYYYMMDD (20190430)
CheckOutDate Numeric Yes Format YYYYMMDD (20190505)
TotalDurationDays Numeric Yes Length Min-1 Max-3
AllotedRoomNo Numeric No Length Min-1 Max-4
RoomRentType String Yes Room Rent Type Lookup
DailyRoomRate Double Yes Length Min-1 Max-10
TotalRoomRate Double Yes Length Min-1 Max-10
VAT Double Yes Length Min-1 Max-10
MunicipalityTax Double Yes Length Min-1 Max-10
Discount Double Yes Length Min-1 Max-10
GrandTotal Double Yes Length Min-1 Max-10
TransactionTypeId Numeric Yes TransactionTypeId Lookup
Gender Numeric Yes Gender Lookup
TransactionID String Not GUID – 16 chars
Mandatory in Not mandatory for CuFlag=1 and
case of First TransactionTypeid =1 or 2
Transaction Mandatory for cuFlag=1 &&
TransactionTypeId=3
cuFlag=2 && TransactionTypeId=1,
cuFlag=2 && TransactionTypeId=2,
cuFlag=2 && TransactionTypeId=3
CheckIn_Time Numeric Yes default value; 0 otherwise provide in 24hrs
format . Length Min-5 Max-6 HHMMSS (70135
= 7hrs, 01 minutes and 35 seconds) or
(143456 = 14hrs, 34 minutes and 56 seconds)
CheckOut_Time Numeric Yes default value; 0 otherwise provide in 24hrs
format . Length Min-5 Max-6 HHMMSS
CustomerType Numeric Yes Customer Type Lookup
NoOfGuest Numeric Yes default 1 but cannot be 0. Length Min-1 Max-2
RoomType Numeric Yes Room Type Lookup
PurposeOfVisit Numeric Yes PurposeOfVisit Lookup

5 Integration guide
 Integration guide for NTMP
DateOfBirth Numeric No YYYYMMDD format, default 0
PaymentType Numeric Yes Payment Type Lookup
NoOfRooms Numeric Yes Default 1 and can be up to 99 Length Min-1
Max-2
CUFlag Numeric Yes 1 =New, 2=Update

HTTP Headers

Property Name Required? Allowed Description

Values
Accept Yes application/json Indicator from consumer regarding
the accepted format as a response.

Response

Response Body

Property Type Description

Success Response
ErrorCode StringLis 0 for success
t
TransactionID String TransactionID generated at webMethods(Optional)
CorrelationID String CorrelationID generated at webMethods
Failure Response
ErrorCode StringLis Refer to Response Code Table below
t
CorrelationID String CorrelationID generated at webMethods

HTTP Headers

Response Required Allowed Description

Property Name ? Values

Content-Type Yes application/json Describes the format of the response

message

6 Integration guide
 Integration guide for NTMP

Response Codes

This section covers all the success and failure response codes.

Category HTTP Error Code Error Description in English

Code
Success 0 0 NA
Validation 200 1 Book No is required and should be numeric
Error only
Validation 200 2 Invalid Nationality Code. It must be numeric
Error and available in lookup list.
Validation 200 3 Invalid Check In Date. It must be numeric in
Error YYYYMMDD format
Validation 200 4 Invalid Check Out Date. It must be numeric
Error in YYYYMMDD format
Validation 200 5 Invalid Total Duration Days. It must be
Error Numeric
Validation 200 6 Invalid Room No. It must be Numeric.
Error
Validation 200 7 Invalid Room Rent Type. It must be numeric
Error and available in lookup list.
Validation 200 8 Invalid Daily Room Rate. It must be numeric
Error
Validation 200 9 Invalid Total Room Rate. It must be numeric
Error
Validation 200 10 Invalid VAT Value. It must be numeric &
Error Amount only.
Validation 200 11 Invalid Municipality Tax. It must be numeric
Error & Amount only.
Validation 200 12 Invalid Discount. It must be numeric &
Error Amount only.
Validation 200 13 Invalid Grand Total. It must be numeric &
Error Amount only.
Validation 200 14 Invalid Grand Total. The total must be equal
Error to Sum of (Total Room Rate + VAT +
Municipality Tax) – Discount.
Validation 200 15 Invalid Transaction Type Id. It must be
Error numeric and can be only following values (1
= booking, 2 = CheckIn & 3 = Checkout).
Valid values 1, 2 & 3.
Validation 200 16 Invalid Gender. It must be Numeric and can
Error be only three values (0 = Not Found, 1 =
Male , 2 = Female) , Check Lookup for more
values if any.
Validation 200 17 Invalid User Id or UserId not found.
Error
Validation 200 18 Invalid Transaction No or this Transaction No
Error not found in SCTH database. It must be of
type GUID.

7 Integration guide
 Integration guide for NTMP

Validation 200 19 Invalid Check In Time. It must be numeric

Error and could hold value 0 if not determined
yet in case of Transaction Type ID =1
(Booking), otherwise it should be in
following format. HHMMSS
Validation 200 20 Invalid Check Out Time. It must be numeric
Error and could hold value 0 if not determined yet
in case of Transaction Type ID =1 (Booking),
otherwise it should be in following format.
HHMMSS
Validation 200 21 Invalid Customer Type. It must be numeric
Error and available in lookup list.
Validation 200 22 Invalid No Of Guest. It must be numeric.
Error
Validation 200 23 Invalid Room Type. It must be numeric and
Error available in lookup list.
Validation 200 24 Invalid Purpose of Visit. It must be numeric
Error and available in lookup list.
Validation 200 25 Invalid Payment Type value. It must be
Error numeric and available in lookup list.
Validation 200 26 Invalid “No Of Rooms”. It must be numeric &
Error can contain value from 1 to 99.
Validation 200 27 Invalid Create or Update Flag. The value
Error must be 1 or 2.
Validation 200 28 Invalid Date Of Birth. It must be either 0 if not
Error found otherwise it should be always in
following format. YYYYMMDD
Validation 200 29 This TransactionID & TransactionTypeID
Error already exist. If you wish to update the same
record please send a request with
CUFlag=2.
This will be valid in case of new record for
Check-In & Checkout only with CUFlag=1 to
avoid duplications
Validation 200 30 Updates on Booking & Check In are not
Error allowed because Check out is created.
If transactionTypeID=3 found in our database
then Updates (CUFlag=2) will not be allowed
on corresponding TrasactionTypeID=1 &
TransactionTypeID=2 with same
TransationID
Validation 200 31 Updates on Booking are not allowed
Error because Check-In is created for same
booking.
If transactionTypeID=2 found only in our
database then Updates (CUFlag=2) will not
be allowed on corresponding
TrasactionTypeID=1 with same TransationID
Validation 200 32 No updates allowed on this TransactionID
Error because it is already cancelled.
If [TransactionCancellationId] is NOT Null
then Updates are not allowed.

8 Integration guide
 Integration guide for NTMP

Validation Error 200 33 You are trying to update a

record, which does not exist.
Please first create a record. It
means Transaction ID &
Transaction Type ID should
first exist in our DB if we are
receiving CUFlag =2 for above
combination.
This is true for booking, check
in and check out.
Validation Error 200 34 Booking number and Userid
combination should be unique.
This check is valid if
TransactionID is null and only
for new booking/checkin/check
out entry.
Technical Error 200 100 Invalid Credentials.
Authentication failed.
Technical Error 200 101 Internal Server Error. Please
try again later, if problem
persist, contact with SCTH
Support.
Hotelsapi.support@scth.gov.sa

2 SWAGGER Descriptor
TBU

3 Request and Response

Request Json Sample

"bookingNo" : "123",

"nationalityCode" : "630",

"checkInDate" : "20180201",

"checkOutDate" : "20180205",

"totalDurationDays" : "3",

"allotedRoomNo" : "1",

"roomRentType" : "1",

9 Integration guide
 Integration guide for NTMP

"dailyRoomRate" : "1000",

"totalRoomRate" : "3000",

"vat" : "10",

"municipalityTax" : "5",

"discount" : "5",

"grandTotal" : "5000",

"transactionTypeId" : "1",

"gender" : "1",

"transactionId" : "1234567891",

"checkInTime" : "120000",

"checkOutTime" : "120000",

"customerType" : "1",

"noOfGuest" : "2",

"roomType" : "2",

"purposeOfVisit" : "3",

"dateOfBirth" : "20010101",

"paymentType" : "1",

"noOfRooms" : "1",

"cuFlag" : "1"

Success Response Json Sample

"errorCode" : [ "0" ],

10 Integration guide
 Integration guide for NTMP

"transactionId" : "08ccc084-fd7e-4854-8f67-c379951c67b3",

“correlationId” : “8b9d9a00-4445-4c9e-bfbb-db13f794d5c2”

Error Response Json Sample

"errorCode" : [ "1", "2", "3" ],

“correlationId” : “5737e370-4a8a-41cc-a2b2-8f263336459a”

4 Lookups for this API

Purpose of Visit

PurposeOfVisit ID Purpose of Visit En Purpose of Visit AR

1 Tourism ‫السياحة‬
2 Family or Friends ‫زيارة األقاربأو األصدقاء‬
3 Religious ‫زيارة دينية‬
4 Business or Work ‫عمل‬
5 Sports ‫نشاط رياض‬
6 Entertainment ‫نشاط ترفيهي‬
7 Other ‫أخرى‬
8 Work (Royal Court) ‫موظف الديوان‬

11 Integration guide
 Integration guide for NTMP

Payment Types

Type ID Type EN Type AR

1 Cash ‫نقدي‬
2 Debit or Credit Card ‫بطاقة إتمانية‬
3 Paid by Company ‫المدفوعة من قِبل الشركة‬
4 Check ‫شيك‬
5 Other ‫أخرى‬
6 Online Channel ‫قناة إلكترونية‬
0 Not Applicable / No Payment ‫غير محدد ال يوجد دفع‬

Gender

Type ID Type EN Type AR

0 Not Found / Not applicable ‫ال يوجد‬
1 Male ‫ذكر‬
2 Female ‫انثى‬

Customer Types

Cust Type ID Cust Type EN Cust Type AR

1 Citizen ‫مواطن‬
2 Gulf Citizen ‫مواطن خليجي‬
3 Visitor ‫زائر‬
4 Resident ‫مقيم‬

12 Integration guide
 Integration guide for NTMP

Room Types

Type ID Type EN Type AR

1 Single Bed Room ‫غرفة نوم مفردة‬
2 Double Bed Room / Kind Bed Room ‫ غرفة نوم كنغ‬/ ‫غرفة نوم مزدوجة‬
3 Regular Suite ‫جناح عادي‬
4 Studio Apartment / Apartment with Single Room ‫ شقة مع غرفة فردية‬/ ‫شقة استوديو‬
5 Furnished Apartment with 2 rooms ‫وحدة سكنية بغرفتين‬
6 Furnished Apartment with 3 rooms ‫وحدة سكنية بثالث غرف‬
7 Villa ‫فيال‬
8 Room with 3 beds ‫أسرة‬
ّ ‫غرفة بثالث‬
9 Room with 4 beds ‫غرفة بأربعة أسرة‬
10 Room with 5 beds ‫أسرة‬
ّ ‫غرفة بخمس‬
11 Room with 6 beds ‫غرفة بست أسرة‬
12 Room with 7 beds or more ‫أسرة أو أكثر‬
ّ ‫غرفة بسبع‬
13 Other ‫آخرى‬
14 Executive / Luxury Suite ‫ فاخر‬/ ‫جناح تنفيذي‬

Transaction Type ID

Trn Type EN Type AR

Type ID
1 Booking ‫حجز‬
2 CheckIn ‫تسجيل دخول‬
3 CheckOut ‫تسجيل خروج‬

Room Rent Types

Rent Rent Type Name EN Rent Type Name AR

Type Id
1 Daily ‫يومي‬
2 Hourly ‫بالساعة‬
3 Weekly ‫اسبوعي‬
4 Monthly ‫شهري‬

13 Integration guide
 Integration guide for NTMP

Nationalities
CODE ARABIC_NAME ENGLISH_NAME CODE ARABIC_NAME ENGLISH_NAME
101 ‫االمارات العربية‬ Arab Emirates 318 ‫كوريا الجنوبية‬ South Korea
102 ‫االردن‬ Jordan 319 ‫مالييا‬ Malaysia
103 ‫البحرين‬ Bahrain 320 ‫نيبال‬ Nepal
104 ‫سوريا‬ Syria 321 ‫الهند‬ India
105 ‫العراق‬ Iraq 322 ‫هونج كونج‬ HONG KONG
106 ‫عمان‬ Oman 323 ‫اليابان‬ Japan
107 ‫فلسطي‬ Palestine 324 ‫بهوتان‬ Bhutan
108 ‫قطر‬ Country 325 ‫الصي الشعبية‬ China
109 ‫الكويت‬ Kuwait 326 ‫رقيص‬ Cyprus
110 ‫لبنان‬ Lebanon 328 ‫كوريا الشمالية‬ North Korea
111 ‫اليمن‬ Yemen 329 ‫الوس‬ Laos
112 ‫الجنوب‬
‫ر‬ ‫اليمن‬ Southern Yemen 143 ‫غي معروف‬/‫مقيم‬
113 ‫العربية السعودية‬ Saudi Arabia 901 ‫اخرى‬ OTHER
-‫جنوب‬
‫ر‬ ‫يمن‬ ‫ال يحمل‬/‫مقيم‬
114 ‫السالطي‬ Yemeni the sultans 144 ‫وثيقة‬
115 ‫بن حارث‬ Bani Harith 145 ‫قبيلة الصيعر‬ ALSAYAR
ALMNAHIL AND
116 ‫بدون‬- ‫الكويت‬ Kuwait - without 146 ‫المناهيل والمهرة‬ ALMAHRH
Member of the
117 ‫افراد القبائل‬ tribes 201 ‫تونس‬ Tunisia
118 ‫من سكان البحرين‬ Residents of Bahrain 202 ‫الجزائر‬ Algeria
‫قبائل مجاورة‬
119 ‫للعطفي‬ Tribes adj to Ataf 203 ‫ى‬
‫جيبوب‬ Djibouti
‫اجنن بجواز‬
‫ر‬
120 ‫سعودي‬ Alien KSA Passprt 204 ‫السودان‬ Sudan
‫فلسطين بوثيقة‬
121 ‫مرصية‬ Palestinian Egyptian 205 ‫الصومال‬ Somalia
‫فلسطين‬
122 ‫بوثيقةلبناب‬ Palestinian Lebanese 206 ‫ليبيا‬ Libya
‫فلسطين‬
123 ‫بوثيقةاردنية‬ Palestinian Jordan 207 ‫مرص‬ Egypt
‫فلسطين‬
124 ‫بوثيقةعراقية‬ Palestinian Iraqi 208 ‫المغرب‬ Morocco
‫فلسطين بوثيقة‬
125 ‫سورية‬ Palestinian Syria 209 ‫موريتانيا‬ Mauritania
126 ‫وثيقة قطريه‬ document Syria 301 ‫افغانستان‬ Afghanistan

14 Integration guide
 Integration guide for NTMP

‫مكررلقرغييا‬
348 ‫اليستخدم‬ Kyrgyzstan not used 435 ‫نيجييا‬ Nigeria
349 ‫الشقية‬‫تيمور ر‬ East Timor 436 ‫النيجر‬ Niger
350 ‫مقيم‬ Resident 437 ‫افريقيا الوسىط‬ Central Africa
351 ‫مقيم‬/‫ميانمار‬ 438 ‫انجوال‬ Angola
‫جواز‬/‫ميانمار‬
352 ‫باكستان‬ - 439 ‫الراس االخرص‬ Cape Verde
‫جوازبنجال‬/‫ميانمار‬
353 ‫دش‬ - 440 ‫غينيا االستوائية‬ Equatorial Guinea
401 ‫اثيوبيا‬ Ethiopia 441 ‫مالجاس‬ Mlajasi
Sao
402 ‫اوغندة‬ Uganda 442 ‫برنسن‬
‫ر‬ /‫ساوتوم‬ Tome/FranceBank
403 ‫بوتسوانا‬ Botswana 443 ‫جزر سيشل‬ Seychelles Islands
404 ‫بورندي‬ Burundi 444 ‫سوزيالند‬ Swaziland
405 ‫تشاد‬ Chad 445 ‫بوفثاتسوانا‬ Bovthatswana
406 ‫تيانيا‬ Tanzania 446 ‫رينيون‬ Reunion
407 ‫توجو‬ Togo 447 ‫ترانسك‬ Transkei
408 ‫جابون‬ Answer 448 ‫فيندا‬ Venda
409 ‫غامبيا‬ Gambia 449 ‫ارتييا‬ Eritrea
Other African
410 ‫جزر القمر‬ Comoros 450 ‫دول افريقية اخري‬ States
411 ‫جنوب افريقيا‬ South Africa 451 ‫سانت هيالنة‬ Saint Helena
412 ‫ناميبيا‬ Namibia 452 ‫جزيرةمايوت‬ Comorian island
‫جمهورية جنوب‬
413 ‫بني‬ Benin 453 ‫السودان‬ Republic of South
414 ‫رواندا‬ Rwanda 454 ‫كاب فيد‬ CAPE VERDE
415 ‫زمبابوي‬ Zimbabwe 501 ‫اسبانيا‬ Spain
503 ‫المانيا‬ Germany 502 ‫البانيا‬ Albania
Bosnia /
504 ‫ايرلندا‬ Ireland 545 ‫البوسنة والهرسك‬ Herzegovina
505 ‫ايطاليا‬ Italy 546 ‫كرواتيا‬ Croatia
506 ‫المملكة المتحدة‬ United Kingdom 547 ‫سلوفينيا‬ Slovenia
‫رصبيا والجبل‬ Serbia /
507 ‫اليتغال‬
‫ر‬ Portugal 548 ‫األسود‬ Montenegro
508 ‫بلغاريا‬ Bulgaria 549 ‫مقدونيا‬ Macedonia
509 ‫بلجيكا‬ Belgium 550 ‫كوسوفوا‬ Kosovo
‫رمزقديم للجبل‬ code to
510 ‫بولندا‬ Poland 551 ‫االسود‬ Montenegro

15 Integration guide
 Integration guide for NTMP

‫رمزقديم‬
511 ‫تشكوسلوفاكيا‬ old to Czechoslovak 552 ‫تشيك‬ CZECH REPUBLIC
512 ‫الدانمارك‬ Denmark 553 ‫سلوفاكيا‬ Slovakia
513 ‫رومانيا‬ Romania 554 ‫جزر فيو‬ Faroe Islands
‫ى‬
‫مييوبوليتان‬ FRANCE
514 ‫السويد‬ Sweden 555 ‫فرنسية‬ METROPOLITAN
515 ‫سويشا‬ Switzerland 601 ‫الواليات المتحدة‬ United States
516 ‫فرنسا‬ France 602 ‫االرجنتي‬ Argentina
517 ‫فنلندا‬ Finland 603 ‫بربادوس‬ Barbados
518 ‫رصبيا‬ SERBIA 604 ‫اليازيل‬
‫ر‬ Brazil
519 ‫هولندا‬ Netherlands 605 ‫بنما‬ Panama
Trinidad and
520 ‫يوغسالفيا‬ Yugoslavia 606 ‫ترينداد وتوباجو‬ Tobago
521 ‫اليونان‬ Greece 607 ‫جامايكا‬ Jamaica
522 ‫اندورا‬ Andorra 608 ‫جوانا‬ Joanna
523 ‫النمسا‬ Austria 609 ‫فيويال‬ Venezuela
524 ‫الجبل األ سود‬ MONTENEGRO 610 ‫كندا‬ Canada
525 ‫هنغاريا‬ Hungary 611 ‫كولمبيا‬ Columbia
526 ‫ايسلندا‬ Iceland 612 ‫جزر البهاما‬ Bahamas
527 ‫ليختنشتي‬ Liechtenstein 613 ‫كوستاريكا‬ Costa Rica
528 ‫لوكسمبورغ‬ Luxembourg 614 ‫كوبا‬ Cuba
529 ‫مالطا‬ Malta 615 ‫دومينيكا‬ Dominica
Republic
530 ‫موناكو‬ Monaco 616 ‫جمهورية دمينكان‬ Dominica
531 ‫اليوي ج‬ Norway 617 ‫السلفادور‬ El Salvador
532 ‫سان مورينو‬ San Moreno 618 ‫جرانادا‬ Granada
533 ‫مدينة الفاتيكان‬ Vatican City 619 ‫جواتيماال‬ Guatemala
534 ‫جبل طارق‬ Gibraltar 620 ‫ى‬
‫هاين‬ Haiti
536 ‫اوكرانيا‬ Ukraine 621 ‫هوندوراس‬ Honduras
537 ‫روسيا البيضاء‬ Byelorussia 622 ‫المكسيك‬ Mexico
539 ‫ارمينيا‬ Armenia 623 ‫نيكاراجوا‬ Nicaragua
540 ‫مولدافيا‬ Moldova 624 ‫سانت لوسيا‬ Saint Lucia
541 ‫جورجيا‬ Georgia 625 ‫سان فينسنت‬ Saintt Vincent
542 ‫ليتوانيا‬ Lithuania 626 ‫بوليفيا‬ Bolivia
543 ‫استونيا‬ Estonia 627 ‫شيل‬ Chile
544 ‫التفيا‬ Latvia 628 ‫اكوادور‬ Ecuador
629 ‫باراجواي‬ Paraguay 702 ‫نيوزيلندا‬ New Zealand
630 ‫بيو‬ Peru 703 ‫بابوا نيوغينا‬ Papua yoga

16 Integration guide
 Integration guide for NTMP

631 ‫سورينام‬ Suriname 704 ‫نيو‬ New

632 ‫اوراجواي‬ Orajoa 705 ‫انتاركتيكا‬ Antarctica
633 ‫س بييي وميكويلن‬ Saint Pierre Miquel 706 ‫جزر نورفولك‬ Norfolk Island
634 ‫جرينالند‬ Greenland 707 ‫توكيالو‬ Tokelau
635 ‫بيلي‬ Belize 708 ‫جزيرةكريسماس‬ Christmas Island
koko Island-
636 ‫بيمودا‬ Bermda 709 ‫كيلنج‬-‫جزيرةكوكو‬ Kellenj
‫فرنسا الجنوب‬
637 ‫ج ى‬
‫اليك والقوقاز‬ Turk/Caucasus Island 710 ‫القطبية‬ FRENCH SOUTH
‫جزيرة هيد‬ HEARD DONALD
638 ‫سان كريستوفرنيفز‬ San Cristovernivz 711 ‫وماكدونلد‬ ISLANDS
PITCAIRN
639 ‫انجويال‬ Anguilla 712 ‫جزر بيتكايرن‬ ISLANDS
640 ‫انتيكوا‬ Antiques 801 ‫فيج‬ ‫جزر ر‬ Fiji Islands
641 ‫الييطانية‬ ‫كي ى‬
‫ج فيجن ر‬ British Virgin 802 ‫يباب‬ Kiribati
642 ‫جزر كايمون‬ Cayman Islands 803 ‫نورو‬ Nauru
643 ‫مونت سيات‬ Monte Sirat 804 ‫جزر سليمان‬ Solomon Islands
644 ‫جيودي لوب‬ Gyude Lube 805 ‫تونجا‬ Tonga
645 ‫مارتينيكو‬ Martinico 806 ‫توفالو‬ Tuvalu
646 ‫عروبا‬ Arabism 807 ‫فانيوتو‬ Vanuoto
647 ‫بونيي‬ Bonaire 808 ‫ساموا الغربية‬ Western Samoa
648 ‫كيوراكو‬ Curako 809 ‫ساموا االمريكية‬ American Samoa
649 ‫سان استاتيوس‬ San Astatios 810 ‫جوام‬ Guam
650 ‫سابا‬ Saba 811 ‫جزر ماريانا‬ Mariana Islands
651 ‫سان مارتي‬ San Martin 812 ‫ميكرونيسيا‬ Micronesia
652 ‫بورتوريكو‬ Puerto Rico 813 ‫جزر ماريشال‬ Marechal Islands
653 ‫ج فيجن االمريكية‬ Virgin Islands of US 814 ‫بيلو‬ Belo
654 ‫جزر فاكالند‬ Falkland Islands 815 ‫بولينيسياالفرنسية‬ French Polynesia
655 ‫جيانا الفرنسية‬ French Guyana 816 ‫جزر والس وفوتونا‬ Islands Wallis
656 ‫االمم المتحدة‬ United Nations 817 ‫كاليدونيا الجديد‬ New Caledonia
657 ‫جزر كوك‬ Cook Islands 818 ‫مدغشقر‬ Madagascar
659 ‫باربودا‬ Barbuda 819 ‫قبيلة بالعبيد‬ Balobid
NETHERLANDS
660 ‫انتيل الهولندية‬ ANTILLES 820 ‫قبيلة النس‬ NULL

17 Integration guide
 Integration guide for NTMP

661 ‫جزر كوكوس‬ COCOS ISLAND 821

BRITISH INDIAN
662 ‫الييطانية ف المحيط‬
‫ر‬ OCEAN 822
663 ‫سانت كيتس ونافيس‬ SAINT KITTS & NEVIS 823
664 ‫جنوب جورجيا‬ SOUTH GEORGIA 824
701 ‫ى‬
‫اسياليا‬ Australia 825
900 ‫غي معروف‬ Unknown 826

Second API: Cancel Booking:

This service provides capabilities to get all cancel booking information companies.

Service Property Description

Service Name CancelBooking
Version 1
Service Owner SCTH
Architectural Style REST Web Service
Support Message Exchange Request-Response (Synchronous)
Patterns
Supported Transport Protocol HTTP
Request Authentication Basic + API Key
Request Authorisation ACL( Access Control List) Based

REST Service Capabilities

CancelBooking:
Interface description
The interface can be used to cancel the hotel booking.
Existing Service Name
N/A

18 Integration guide
 Integration guide for NTMP

Service Endpoint (Base URL)

Environme URL
nt
Sandbox https://dev-hotelsapi.scth.gov.sa/gateway/CancelBooking/1.0/cancelBooking
(DEV)
Test (e.g. https://api-stg.ntmp.gov.sa/gateway/CancelBooking/1.0/cancelBooking
SIT)
Production https://api.ntmp.gov.sa/gateway/CancelBooking/1.0/cancelBooking

Request
Customer should hit the above URL’s to get the response and no input query-parameters
required

Query Parameters

Name Requi Type Allowed Values Description

red?
NA

Request Body

Property Type Required Description

TransactionId Guid Yes GUID , length Min-16, Max-16
CancelReason Numeric Yes cancelReason Lookup, length Min-1, Max-2
CancelWithCharges Boolean Yes 1=Yes/2=No (If Yes fill the below information)
length Min-1, Max-1
ChargeableDays Numeric Yes If cancelwithcharges=1, then chargeable days
cannot contain 0. length Min-1, Max-99
RoomRentType Numeric Yes If cancelwithcharges=1, then RoomRent Type
cannot contain 0. RoomRent Type Lookup .
length Min-1, Max-2
DailyRoomRate Double Yes If cancelwithcharges=1, then DailyRoom Rate
cannot contain 0. length Min-1, Max-2
TotalRoomRate Double Yes If cancelwithcharges=1, then Total Room Rate
cannot contain 0. length Min-1, Max-2
VAT Double Yes If cancelwithcharges=1, then Vat cannot
contain 0. length Min-1, Max-2
MunicipalityTax Double Yes If cancelwithcharges=1, then Municipality Tax
cannot contain 0. length Min-1, Max-2
Discount Double Yes If cancelwithcharges=1, then Discount cannot
contain 0.. length Min-1, Max-2

19 Integration guide
 Integration guide for NTMP

GrandTotal Double Yes If

cancelwithcharges=1,
then GrandTotal
cannot contain 0.
length Min-1, Max-2
PaymentType Numeric Yes Payment Type Lookup
CUFlag Numeric Yes 1=Add, 2=Update

HTTP Headers
Property Name Required Allowed Values Description
?
Accept Yes application/json Indicator from consumer regarding the
accepted format as a response.

Response

Response Body

Property Type Description

Success Response
ErrorCode StringLis 0 for success
t
CorrelationID String CorrelationID generated at webMethods
Failure Response
ErrorCode StringLis Refer to Response Code Table below
t
CorrelationID String CorrelationID generated at webMethods

HTTP Headers
Response Required Allowed Description
Property Name ? Values

Content-Type Yes application/json Describes the format of the response

message

20 Integration guide
 Integration guide for NTMP

Response Codes

This section covers all the success and failure response codes.

Category HTTP Error Code Error Description in English

Code
Success 0 0 NA
Validation 200 1 Invalid Transaction ID or this Transaction ID
Error not found in SCTH database. It must be of
type GUID.
Validation 200 2 Invalid Cancel Reason. It must be numeric
Error and available in lookup list.
Validation 200 3 Invalid Cancel With Charges. It must be
Error numeric and can have only 2 values (1= Yes
with Charges, 0 = Cancel without Charges)
Validation 200 4 Invalid Chargeable Days. If Cancelled with
Error Charges then this field should not contain 0.
Validation 200 5 Invalid Room Rent Type. If Cancelled with
Error Charges then this field should not contain 0
& It must be numeric and available in lookup
list.
Validation 200 6 Invalid Daily Room Rate. If Cancelled with
Error Charges then this field should not contain 0.
It must be numeric only If provided.
Validation 200 7 Invalid Total Room Rate. If Cancelled with
Error Charges then this field should not contain 0.
It must be numeric only If provided.
Validation 200 8 Invalid VAT. If Cancelled with Charges then
Error this field should not contain 0. It must be
numeric (Amount) only If provided.
Validation 200 9 Invalid Municipality Tax. If Cancelled with
Error Charges then this field should not contain 0.
It must be numeric (Amount) only If provided.
Validation 200 10 Invalid Discount. If Cancelled with Charges
Error then this field should not contain 0. It must be
numeric (Amount) only If provided.
Validation 200 11 Invalid Grand Total. If Cancelled with
Error Charges then this field should not contain 0.
It must be numeric (Amount) only If provided.
Validation 200 12 Invalid User Id or UserId not found.
Error
Validation 200 13 Invalid Payment Type value. It must be
Error numeric and available in lookup list. If
Cancelled with Charges then this field should
not contain 0.
Validation 200 14 This operation is allowed only before Check
Error In.
Validation 200 15 Invalid CU Flag. The value must be 1 or 2.
Error

21 Integration guide
 Integration guide for NTMP

Validation 200 16 This transaction is already cancelled. If you

Error wish to update this transaction please use
CUFlag = 2 for updates.
Technical 200 100 Invalid Credentials. Authentication failed.
Error
Technical 200 101 Internal Server Error. Please try again later, if
Error problem persist, contact with SCTH Support.
Hotelsapi.support@scth.gov.sa

SWAGGER Descriptor
TBU

Request and Response

Request Json Sample

"transactionId" : "5737e370-4a8a-41cc-a2b2-8f263336459a",

"cancelReason" : "1",

"cancelWithCharges" : "1",

"chargeableDays" : "2",

"roomRentType" : "1",

"dailyRoomRate" : "500",

"totalRoomRate" : "1000",

"vat" : "200",

"municipalityTax" : "200",

"discount" : "400",

"grandTotal" : "1500",

"paymentType" : "1",

"cuFlag" : "1"

22 Integration guide
 Integration guide for NTMP

Success Response Json Sample

"errorCode" : [ "0" ],

“correlationId” : “8b9d9a00-4445-4c9e-bfbb-db13f794d5c2”

Error Response Json Sample

"errorCode" : [ "1", "2", "3" ],

“correlationId” : “5737e370-4a8a-41cc-a2b2-8f263336459a”

Look ups for this API

Room Rent Types

Rent Rent Type Name EN Rent Type Name AR

Type
Id
1 Daily ‫يومي‬
2 Hourly ‫بالساعة‬
3 Weekly ‫اسبوعي‬
4 Monthly ‫شهري‬

23 Integration guide
 Integration guide for NTMP

Third API: Expenses details:

Service Technical Interface

This service provides capabilities to get all booking expenses

Service Property Description

Service Name BookingExpenseDetails
Version 1
Service Owner SCTH
Architectural Style REST Web Service
Support Message Exchange Request-Response (Synchronous)
Patterns
Supported Transport Protocol HTTP
Request Authentication Basic + API Key
Request Authorisation ACL( Access Control List) Based

REST Service Capabilities

BookingExpenseDetails:
Interface description
The interface can be used to book expense details of the hotel booking .
Existing Service Name
N/A

Service Endpoint (Base URL)

Environme URL
nt
Sandbox https://dev-
(DEV)
hotelsapi.scth.gov.sa/gateway/BookingExpense/1.0/bookingExpe
nse
Test (e.g. https://api-stg.ntmp.gov.sa/gateway/BookingExpense/1.0/bookingExpense
SIT)
Production https://api.ntmp.gov.sa/gateway/BookingExpense/1.0/bookingExpense

24 Integration guide
 Integration guide for NTMP

Request
Customer should hit the above URL’s to get the response and no input query-parameters
required

Query Parameters
Name Requi Type Allowed Values Description
red?
NA

Request Body

Property Type Required Description

TransactionId String Yes GUID
ExpenseItems DocumentList Yes
ExpenseDate Numeric Yes Format YYYYMMDD (20190430), length
Min-8, Max-8
ItemNumber Numeric Yes Mandatory if Cuflag is 2 .value should be
unique across the table for a combination
userid and TransactionID, length Min-1,
Max-1
ExpenseTypeId Numeric Yes ExpenseTypeId Lookup, length Min-1, Max-
2
UnitPrice Double Yes It must be numeric only
length Min-1, Max-2
Discount Double Yes It must be 0 or Numeric value. length Min-
1, Max-10
VAT Double Yes It must be 0 or Numeric value. length Min-
1, Max-10
MunicipalityTax Double Yes It must be 0 or Numeric value. length Min-
1, Max-10
GrandTotal Double Yes It must be numeric only
length Min-1, Max-10
PaymentType Numeric Yes Payment Type Lookup
CUFlag Numeric Yes 1 =New, 2=Update

HTTP Headers
Property Name Required Allowed Values Description
?
Accept Yes application/json Indicator from consumer regarding the
accepted format as a response.

25 Integration guide
 Integration guide for NTMP

Response

Response Body

Property Type Description

Success Response
ErrorCode StringList 0 for success
CorrelationID String CorrelationID generated at webMethods
ExpenseItems DocumentLi
st
itemNumber String Distinct number of expense lineitem
errorCode StringList 0 for success of expense lineitem
Failure Response
ErrorCode StringList Refer to Response Code Table below
CorrelationID String CorrelationID generated at webMethods
ExpenseItems DocumentLi
st
itemNumber String Distinct number of expense lineitem
errorCode StringList Refer to Response Code Table below

HTTP Headers

Response Required Allowed Description

Property Name ? Values

Content-Type Yes application/json Describes the format of the response

message

26 Integration guide
 Integration guide for NTMP

Response Codes

This section covers all the success and failure response codes.

Category HTTP Error Code Error Description in English

Code
Success 0 0 NA
Validation 200 1 Invalid Transaction ID or this Transaction ID
Error not found in SCTH database. It must be of
type GUID.
Validation 200 2 Invalid Expense Date. It must be numeric in
Error YYYYMMDD format
Validation 200 3 Invalid Item Number. It must be numeric &
Error Unique for each expense Item
Validation 200 4 ItemNumber not found in SCTH Database.
Error (This case will be valid when CUFlag = 2 )
Validation 200 5 Invalid Expense Type ID. It must be numeric
Error and available in lookup list.
Validation 200 6 Invalid Unit Price. It must be numeric.
Error
Validation 200 7 Invalid Discount. It must be numeric only If
Error provided.
Validation 200 8 Invalid VAT. It must be numeric in Amount
Error only. It can contain 0.
Validation 200 9 Invalid Municipality Tax. It must be numeric
Error in Amount only. It can contain 0.
Validation 200 10 Invalid Grand Total. It must be numeric in
Error Amount only.
Validation 200 12 Invalid Payment Type value. It must be
Error numeric and available in lookup list.
Validation 200 13 No checkout data found for Transaction No.
Error Please call this api once the checkout is
done.
Validation 200 14 Invalid CU Flag Value. It must be 1=Add,
Error 2=Update
Validation 200 15 Same Transaction ID Found already found
Error with Item Number. Please send it with
CUFlag =2 if you wish to update.
Technical 200 100 Invalid Credentials. Authentication failed.
Error
Technical 200 101 Internal Server Error. Please try again later, if
Error problem persist, contact with SCTH Support.
Hotelsapi.support@scth.gov.sa

27 Integration guide
 Integration guide for NTMP

SWAGGER Descriptor

Request and Response

Request JSON Sample

"transactionId" : "AFE30234-9768-4EC8-9993-7FE1F3D814CA",

"expenseItems" : [ {

"expenseDate" : "20180205",

"itemNumber" : "220",

"expenseTypeId" : "1",

"unitPrice" : "200",

"discount" : "50",

"vat" : "40",

"municipalityTax" : "40",

"grandTotal" : "5000",

"paymentType" : "1",

"cuFlag" : "1"

}, {

"expenseDate" : "20180617",

"itemNumber" : "221",

"expenseTypeId" : "1",

"unitPrice" : "200",

"discount" : "50",

"vat" : "40",

28 Integration guide
 Integration guide for NTMP

"municipalityTax" : "40",

"grandTotal" : "5000",

"paymentType" : "1",

"cuFlag" : "1"

}]

Success Response JSON Sample

{
"correlationId": "58da01a5-5c92-4fae-9864-21e85af928bc",
"expenseItems": [
{
"itemNumber": "220",
"errorCode": [
"0"
]
},
{
"itemNumber": "221",
"errorCode": [
"0"
]
}
],
"errorCode": [
"0"
]
}
Error Response JSON Sample

"errorCode": ["1"] ,

"correlationId": "0e1d4630-33e8-4f9b-a498-17c080276557",

"expenseItems": [

29 Integration guide
 Integration guide for NTMP

"itemNumber": "221",

"errorCode": [ "15"]

},

"itemNumber": "222",

"errorCode": [

"0"

Note: Please refer below details about the header level “errorCode” field value to interpret the
overall response status.

 Header level “errorCode=0”: This respone means BookingExpense request get

processed successfully.
 Header level “errorCode!=0” : This respone indicates that REST service encounters some
exception while
Processing the request.

 Header level “errorCode=1” : This response says that REST service unable to process a
expense lineitem or lineitems due to business validation failure or technical
reason.Please refer above error reponse sample for reference.

30 Integration guide
 Integration guide for NTMP

Lookups for this API

Payment Type

Type Type EN Type AR

ID
1 Cash ‫نقدي‬
2 Debit or Credit Card ‫بطاقة إتمانية‬
3 Paid by Company ‫المدفوعة من قبل الشركة‬
4 Check ‫شيك‬
5 Other ‫اخرى‬
6 Online Channel ‫قناة إلكترونية‬
0 Not Applicable / No Payment ‫غير محدد ال يوجد دفع‬

Expense Types

ExpenseTypeID ExpenseTypeEn ExpenseTypeAr

‫ال يمكن تطبيقة‬
0 Not Applicable (For example charged for damage) ‫(مثل تعويض عن‬
) ‫رصر‬
1 Other ‫أخرى‬
2 Laundry ‫خدمة غسيل‬
‫ى‬
‫اإلنينت‬
3 Wifi - Internet

4 Car Parking ‫المواقف‬

5 Food ‫الطعام‬

‫ر‬
‫والمشوبات‬ ‫الطعام‬
6 Food & Beverages
‫ال ر‬
‫مشوبات‬
7 Beverages
‫ر‬
‫المشوبات الباردة‬
8 Cold Drinks
‫ال ر‬
‫مشوبات الساخنة‬
9 Hot Drinks

31 Integration guide
 Integration guide for NTMP

10 Breakfast ‫اإلفطار‬
11 Lunch ‫الغداء‬
12 Dinner ‫العشاء‬
13 Bakery & Cakes ‫المخبوزات‬
14 Swimming pool ‫المسبح‬
15 Gym ‫النادي الرياض‬
‫النادي الصج‬
16 SPA & Beauty Services
‫والتجميل‬
17 Pick & Drop (Transport Services) ‫خدمة المواصالت‬
18 Minibar ‫مين بار‬
‫قنوات فضائية‬
19 Cable - TV
‫إضافية‬
20 Extra Bed ‫رسيرإضاف‬
21 Hairdresser ‫العناية بالشعر‬
22 Shopping ‫تسوق‬
23 Organized Tours Services ‫تنظيم رحلة سياحية‬
24 Tour Guide Services ‫خدمة مرشد سياح‬

Forth API: occupancy update:

This service provides capabilities to create occupancy details of the hotels.

Service Property Description

Service Name OccupanyUpdate
Version 1
Service Owner SCTH
Architectural Style REST Web Service
Support Message Exchange Request-Response (Synchronous)
Patterns
Supported Transport Protocol HTTP
Request Authentication Basic + API Key
Request Authorisation ACL( Access Control List) Based

32 Integration guide
 Integration guide for NTMP

REST Service Capabilities

OccupancyUpdate:
Interface description
The interface can be used to create a occupancy details of the hotels for booking.
Existing Service Name
N/A

Service Endpoint (Base URL)

Environme URL
nt
Sandbox https://dev-hotelsapi.scth.gov.sa/gateway/OccupancyUpdate/1.0/occupancyUpdate
(DEV)
Test (e.g. https://api-stg.ntmp.gov.sa/gateway/OccupancyUpdate/1.0/occupancyUpdate
SIT)
Production https://api.ntmp.gov.sa/gateway/OccupancyUpdate/1.0/occupancyUpdate

Request
Customer should hit the above URL’s to get the response and no input query-parameters
required

Query Parameters
Name Requi Type Allowed Values Description
red?
NA

Request Body

Property Type Required Description

UpdateDate Numeric Yes Format YYYYMMDD (20190430), length
Min-8, Max-8
RoomsOccupied Numeric Yes yes, length Min-1, Max-3
RoomsAvailable Numeric Yes Yes, length Min-1, Max-3
RoomsBooked Numeric Yes Yes,length Min-1, Max-3
RoomsOnMaintenance Numeric Yes Yes,length Min-1, Max-3

33 Integration guide
 Integration guide for NTMP

HTTP Headers
Property Name Required Allowed Values Description
?
Accept Yes application/json Indicator from consumer regarding the
accepted format as a response.

Response

Response Body
Property Type Description
Success Response
ErrorCode StringLis 0 for success
t
CorrelationID String CorrelationID generated at webMethods
Failure Response
ErrorCode StringLis Refer to Response Code Table below
t
CorrelationID String CorrelationID generated at webMethods

HTTP Headers
Response Required Allowed Description
Property Name ? Values

Content-Type Yes application/json Describes the format of the response

message

Response Codes

This section covers all the success and failure response codes.

Category HTTP Error Code Error Description in English

Code
Success 0 0 NA
Validation 200 1 Invalid Update Date. It should be numeric in
Error following format YYYYMMDD.
Validation 200 2 Invalid Rooms Occupied. It must be numeric
Error only. It can contain 0.
Validation 200 3 Invalid Rooms Available. It must be numeric
Error only. It can contain 0.
Validation 200 4 Invalid Rooms Booked. It must be numeric
Error only. It can contain 0.
Validation 200 5 Invalid “RoomsOnMaintinance”. It must be
Error numeric only. It can contain 0.

34 Integration guide
 Integration guide for NTMP

Validation 200 6 Invalid UserId or User Id not found.

Error
Technical 200 100 Invalid Credentials. Authentication failed.
Error
Technical 200 101 Internal Server Error. Please try again later, if
Error problem persist, contact with SCTH Support.
Hotelsapi.support@scth.gov.sa

SWAGGER Descriptor
TBU

Request and Response

Request Json Sample

{
"updateDate" : "20180203",

"roomsOccupied" : "3",

"roomsAvailable" : "10",

"roomsBooked" : "2",

"roomsOnMaintenance" : "2"

Success Response Json Sample

"errorCode" : [ "0" ],

“correlationId” : “8b9d9a00-4445-4c9e-bfbb-db13f794d5c2”

Error Response Json Sample

"errorCode" : [ "1", "2", "3" ],

“correlationId” : “5737e370-4a8a-41cc-a2b2-8f263336459a”

35 Integration guide