Create New Tour

Endpoint: POST /createnew
Description: Creates a new tour resource with the provided details.

Request

Method: POST
URL: https://your-domain.com/createnew
Headers:

• Content-Type: application/json
• Authorization: Bearer YOUR_API_KEY (if authentication is required)

Request Body:
A JSON object containing the tour details. package_name is required; all other fields are optional. MasterCompanyId is set automatically from the server context and should not be included in the request.

Request Body Fields

Top-Level Fields:

Example Request Body

{
  "package_name": "Seoul City Tour",
  "summary": "Explore the vibrant city of Seoul.",
  "description": "A day-long tour covering major attractions in Seoul.",
  "themes": ["Culture", "History"],
  "country": [
    {
      "name": "South Korea",
      "countryid": 82,
      "countryUID": "KR82",
      "isocode": "KR"
    }
  ],
  "city": [
    {
      "name": "Seoul",
      "cityid": 1,
      "cityUID": "SEOUL001"
    }
  ],
  "packageOptions": {
    "AvailableOn": ["Monday", "Wednesday", "Friday"],
    "currencyCode": "KRW",
    "Options": [
      {
        "optionId": "opt001",
        "optionName": "Standard Tour",
        "maxPax": "20",
        "minPax": "1",
        "status": true,
        "optionPrice": {
          "forAdults": "50000",
          "forChild": "30000"
        }
      }
    ]
  }
}

Response

Status Codes:

• 201 Created: The tour was successfully created.
• 400 Bad Request: The request body was invalid or missing required fields.
• 401 Unauthorized: If authentication is required and credentials are invalid/missing.
• 500 Internal Server Error: An unexpected error occurred on the server.

Response Body:
Returns a JSON object indicating success, the created tour data, and a message.

Example Response Body

{
  "success": true,
  "data": {
    "_id": "64f9c0fa8b1234567890abcf",
    "package_name": "Seoul City Tour",
    "duration": {
      "totalDuration": "3",
      "durationType": "days"
    },
    "TagsCountries": ["South Korea"],
    "TagsLocation": ["Seoul"],
    "TagsTheme": [],
    "TagsAttraction": [],
    "MasterCompanyId": "master-123-company",
    "confirmation_type": null,
    "cancelation_type": null,
    "voucher_usage": null,
    "type": null,
    "category": [],
    "themes": ["Cultural", "Historical"],
    "ticket_type": null,
    "activity_id": null,
    "rating": null,
    "uniqueid": "PID110184", // Generated by pre-save hook if not provided
    "package_sub_name": null,
    "slug": null,
    "summary": null,
    "longsummary": null,
    "description": "Explore the vibrant city of Seoul with guided tours, local cuisine, and cultural experiences.",
    "author": [],
    "date": "2024-12-07T12:00:00.000Z",
    "voucher_type": null,
    "published": "1",
    "image": {
      "id": null,
      "imgurl": null,
      "externalimage": null,
      "gallery": []
    },
    "country": [
      {
        "name": "South Korea",
        "countryid": 82,
        "countryUID": null,
        "isocode": "KR"
      }
    ],
    "city": [
      {
        "name": "Seoul",
        "cityid": 11,
        "cityUID": null
      }
    ],
    "geo": {
      "latitude": null,
      "longitude": null
    },
    "seo": {
      "metatitle": null,
      "metadesc": null,
      "metakeywords": null
    },
    "policies": [],
    "itinerary": [],
    "suplierinfo": {
      "sup_name": null,
      "sup_id": null,
      "productlink": null,
      "attributes": {
        "isActive": "0"
      }
    },
    "highlights_expect": [],
    "otherinfos": {
      "inclusions": [],
      "exclusions": [],
      "highlightspoints": []
    },
    "packageOptions": {
      "AvailableOn": [],
      "HolidaysOn": [],
      "isTimeApplicable": null,
      "TimesAvailable": [],
      "currencyCode": null,
      "Options": []
    },
    "attributes": {
      "duration": {
        "durationLength": null,
        "durationType": null
      },
      "languages": [],
      "pickupType": null,
      "voucherType": null,
      "TourType": null,
      "cancellationType": {
        "isFree": null,
        "priorDuration": null,
        "remarks": null
      }
    },
    "deleted": {
      "status": false,
      "date": null
    },
    "status": false,
    "createdAt": "2024-12-07T12:00:00.000Z",
    "updatedAt": "2024-12-07T12:00:00.000Z",
    "__v": 0
  },
  "message": "Tour created successfully"
}

Get Tours

Endpoint: POST /gettours
Description: Fetches a paginated list of tours based on provided filters. If clientside=true, it transforms the tour data into a client-friendly format.

Request

Method: POST
URL: https://your-domain.com/gettours
Headers:

• Content-Type: application/json
• Authorization: Bearer YOUR_API_KEY (if required)

Query Parameters: (All are optional unless stated otherwise)

Note:

• MasterCompanyId is automatically applied from the server context and must not be passed in the request.
• Provide tags as JSON arrays if multiple tags are needed. For example, TagsCountries=["South Korea","Japan"].

Example Request (Raw Format)

curl -X POST "https://your-domain.com/gettours?byCity=Seoul&byCountry=South%20Korea&Type=Adventure&limit=10&page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Status Codes:

• 200 OK: Returned when the tours are successfully fetched.
• 401 Unauthorized: If authentication is required and credentials are invalid/missing.
• 500 Internal Server Error: An unexpected error occurred on the server.

Response Body (Raw Result):
Returns a paginated object (if clientside is not true).

{
  "docs": [
    {
      "_id": "tour_id",
      "package_name": "Seoul City Tour",
      "TagsCountries": ["South Korea"],
      "TagsLocation": ["Seoul"],
      "packageOptions": {
        "currencyCode": "USD",
        "Options": [
          {
            "optionId": "opt001",
            "optionPrice": {
              "forAdults": "100",
              "forChild": "50"
            }
          }
        ]
      },
      "city": [
        {
          "name": "Seoul",
          "cityid": 11,
          "cityUID": null
        }
      ],
      "country": [
        {
          "name": "South Korea",
          "countryid": 82,
          "countryUID": null,
          "isocode": "KR"
        }
      ],
      "rating": null,
      "image": {
        "gallery": [
          {
            "fileName": "tour_image.jpg",
            "imgurl": "https://example.com/images/tour_image.jpg"
          }
        ]
      },
      "attributes": {
        "duration": { "durationLength": null, "durationType": null },
        "languages": [],
        "pickupType": null,
        "voucherType": null,
        "TourType": null,
        "cancellationType": {
          "isFree": null,
          "priorDuration": null,
          "remarks": null
        }
      },
      "createdAt": "2024-12-07T12:00:00.000Z",
      "updatedAt": "2024-12-07T12:00:00.000Z",
      // ... other fields
    }
  ],
  "totalDocs": 1,
  "limit": 10,
  "page": 1,
  "totalPages": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": false,
  "prevPage": null,
  "nextPage": null
}

Response Body (Client Side Format):
If clientside=true, the response is transformed to a simpler format:

{
  "results": [
    {
      "price": 100,
      "MinPackagePrice": 100,
      "PackageCurrency": "USD",
      "package_name": "Seoul City Tour",
      "uniqueId": "PID110184",
      "attributes": {
        "duration": { "durationLength": null, "durationType": null },
        "languages": [],
        "pickupType": null,
        "voucherType": null,
        "TourType": null,
        "cancellationType": {
          "isFree": null,
          "priorDuration": null,
          "remarks": null
        }
      },
      "slug": null,
      "city": "Seoul",
      "country": "South Korea",
      "rating": null,
      "image": [
        {
          "fileName": "tour_image.jpg",
          "imgurl": "https://example.com/images/tour_image.jpg"
        }
      ]
    }
  ],
  "page": 1,
  "limit": 5,
  "totalPages": 1,
  "totalResults": 1
}

Notes

• Changing clientside to true returns a simplified data structure suitable for displaying tours in a frontend application.
• usercurrency can be used in a future enhancement to convert prices from the base currency to the specified currency. Currently, prices remain as-is.
• Pagination (limit, page) and filtering (e.g., byCity, byCountry, TagsCountries, etc.) allow fine-grained control over the returned dataset.

Get Tour by Identifier

Endpoint: POST /gettours/:identifierType
Description: Retrieves a single tour based on an identifier type (id, uniqueid, or slug) and a corresponding value provided in the request body.

Request

Method: POST
URL: https://your-domain.com/gettours/{identifierType}

Path Parameter:

• identifierType (String, Required): The type of identifier to use for fetching the tour.
  Possible values:
  • id: Matches the MongoDB _id of the tour.
  • uniqueid: Matches a case-insensitive unique ID of the tour.
  • slug: Matches the slug field of the tour.

Headers:

• Content-Type: application/json
• Authorization: Bearer YOUR_API_KEY (if required)

Request Body:
A JSON object containing a single key corresponding to the identifierType parameter and its value.

Example Request Body (Using id)

{
  "id": "64f9c0fa8b1234567890abcf"
}

Example Request Body (Using uniqueid)

{
  "uniqueid": "PID110184"
}

Example Request Body (Using slug)

{
  "slug": "seoul-city-tour"
}

Note

You must provide a value in the request body that matches the identifierType in the URL.
MasterCompanyId is automatically applied from the server context and should not be included in the request.

Response

Status Codes:

• 200 OK: The tour was found and is returned in the response.
• 400 Bad Request: If identifierType is invalid or if the corresponding value is not provided in the request body.
• 401 Unauthorized: If authentication is required and credentials are invalid/missing.
• 404 Not Found: If no tour matches the provided identifier value.
• 500 Internal Server Error: An unexpected error occurred on the server.

Response Body:
Returns the requested tour object.

Example Successful Response

{
  "_id": "64f9c0fa8b1234567890abcf",
  "uniqueid": "PID110184",
  "package_name": "Seoul City Tour",
  "duration": {
    "totalDuration": "3",
    "durationType": "days"
  },
  "MasterCompanyId": "master-123-company",
  "description": "Explore the vibrant city of Seoul with guided tours, local cuisine, and cultural experiences.",
  "published": "1",
  "country": [
    {
      "name": "South Korea",
      "countryid": 82,
      "countryUID": null,
      "isocode": "KR"
    }
  ],
  "city": [
    {
      "name": "Seoul",
      "cityid": 11,
      "cityUID": null
    }
  ],
  "createdAt": "2024-12-07T12:00:00.000Z",
  "updatedAt": "2024-12-07T12:00:00.000Z",
  "__v": 0
}

Notes

• Ensure the identifierType matches the field in your request body.
• The provided identifierType must be one of: id, uniqueid, or slug.
• Filtering by MasterCompanyId is handled internally and does not require additional input.

Update Tour by ID

Endpoint: POST /update/:tourId
Description: Updates an existing tour resource identified by tourId with the provided fields.

Request

Method: POST
URL: https://your-domain.com/update/{tourId}

Path Parameter:

• tourId (String, Required): The unique identifier (_id) of the tour to be updated.

Headers:

• Content-Type: application/json
• Authorization: Bearer YOUR_API_KEY (if authentication is required)

Request Body:
A JSON object containing the fields to be updated. You can include any fields described in the tour schema that are allowed to be modified. MasterCompanyId should not be provided; it’s applied internally.

Example Request

curl -X POST "https://your-domain.com/update/64f9c0fa8b1234567890abcf" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "package_name": "Updated Seoul City Tour",
    "description": "An updated description with more details."
  }'

Example Request Body

{
  "package_name": "Updated Seoul City Tour",
  "description": "An updated description with more details."
}

Response

Status Codes:

• 200 OK: The tour was successfully updated.
• 400 Bad Request: If the request body is invalid.
• 401 Unauthorized: If authentication is required and credentials are invalid/missing.
• 404 Not Found: If no tour matches the provided tourId.
• 500 Internal Server Error: An unexpected error occurred on the server.

Response Body:
Returns the updated tour object with the new values.

Example Successful Response

{
  "_id": "64f9c0fa8b1234567890abcf",
  "uniqueid": "PID110184",
  "package_name": "Updated Seoul City Tour",
  "description": "An updated description with more details.",
  "MasterCompanyId": "master-123-company",
  "updatedAt": "2024-12-07T12:05:00.000Z"
}

Notes

• Only fields included in the request body will be updated.
• Ensure that tourId is a valid identifier of an existing tour.
• MasterCompanyId is applied from the server context and must not be included in the request.