{"info":{"_postman_id":"aeb0fdbe-a4bb-4512-bc1b-e501ace4a8d6","name":"Booking API Documentation","description":"

Overview

This API provides a comprehensive interface for third-party applications to interact with our internal booking system. It enables seamless integration, allowing external systems to retrieve product (ticket) information, initiate booking requests, and manage booking data.

Base URL

All API endpoints are relative to the following base URL:

https://dev-api.habitat.id/dev\n\n

The base URL provides a foundation for all API requests. By separating the static portion of the URL from the dynamic endpoint, we improve the modularity and maintainability of the API. This also allows for easier updates to the base URL in the future.

Example:

To create a booking, you would send a POST request to the following URL:

https://dev-api.habitat.id/dev/booking\n\n

Note:

Replace https://dev-api.habitat.id/dev with the appropriate base URL for your environment.
\n
The base URL is subject to change. Please refer to the latest documentation for the most up-to-date information.
\n

Dengan menambahkan section ini, Anda memberikan panduan yang jelas kepada pengguna API tentang bagaimana mengakses endpoint yang berbeda dan membantu mereka memahami struktur API secara keseluruhan.

Authentication

Authentication Mechanism:

We've implemented a token-based authentication system where the token is generated by the third-party application. This system relies on two primary parameters: app_name and app_key.

app_name****: This parameter uniquely identifies the third-party application. Each application registered with our system is assigned a distinct app_name, serving as a form of user identification.
\n
app_key****: The app_key is a secret key associated with the app_name. It acts as a password or credential, used to verify the authenticity of the app_name during each API request.
\n

Authentication Process:

Third-party Application Generation:
\n
1. The third-party application generates a token using their unique app_name and app_key.
  \n
2. This token is typically included in the request header for each API call.
  \n
\n
Server-Side Validation:
\n
1. Upon receiving a request, our server extracts the app_name and token from the request header.
  \n
2. The server then:
  \n
  1. Verifies the existence of the specified app_name in its registered applications.
    \n
  2. Uses a secure hashing algorithm to generate a hash of the app_name and app_key.
    \n
  3. Compares the generated hash with the hash stored in our system.
    \n
  \n
\n

Benefits of this approach:

Security: The use of app_key as a secret ensures that only authorized applications can access the API.
\n
Scalability: The system can easily accommodate a large number of third-party applications.
\n
Flexibility: The token-based approach allows for easy integration with various client-side technologies.
\n

Additional Considerations:

Token Expiration: To enhance security, consider implementing a token expiration mechanism, requiring third-party applications to regenerate tokens periodically.
\n
Token Revocation: Provide a mechanism to revoke tokens in case of security breaches or unauthorized access.
\n
Token Storage: Store app_keys securely using strong encryption and avoid storing them in plain text.
\n

Example Request Header:

token:

By following this authentication mechanism, we ensure that only authorized third-party applications can interact with our booking system, safeguarding our data and services.

Authentication error response

When a request fails to authenticate, the server should return an appropriate error response. This typically includes:

HTTP Status Code:
\n
- 401 Unauthorized: This indicates that the client must authenticate itself to get the requested response.
  \n
- 403 Forbidden: This means that even if the client is authenticated, they do not have the necessary permissions to access the resource.
  \n
\n
Error Message:
\n
- A clear and concise message describing the reason for the authentication failure. For example:
  \n
  - \"Invalid app_name or app_key.\"
    \n
  - \"Token has expired.\"
    \n
  - \"Authentication required.\"
    \n
  \n
\n
Additional Details:
\n
- Depending on the specific error, you may include additional details such as:
  \n
  - The timestamp of the error.
    \n
  - The specific endpoint that was requested.
    \n
  - The client's IP address.
    \n
  \n
\n

\n
copyright © WIT.ID 2024
\n

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Overview","slug":"overview"}],"owner":"19659454","collectionId":"aeb0fdbe-a4bb-4512-bc1b-e501ace4a8d6","publishedId":"2sAXqneQ79","public":true,"customColor":{"top-bar":"C42A0A","right-sidebar":"303030","highlight":"C42A0A"},"publishDate":"2024-09-13T08:42:43.000Z"},"item":[{"name":"Token","item":[{"name":"Generate Token","id":"b9c9b88e-b4da-4ef1-abe2-e2a82fdcee78","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"app_name\": \"wit-dev-open\",\n \"app_key\": \"w1t-d3V-0p3n\"\n}","options":{"raw":{"language":"json"}}},"url":"{{host_booking}}/generate-token","description":"

Endpoint

URL: {{host_booking}}/token
Method: POST

Request Body

A JSON object containing the following fields:

app_name****: The unique identifier of the third-party application.
\n
app_key****: The secret key associated with the app_name.
\n

Response

Success: A JSON object containing the following fields:
\n
- data****: An object with the following properties:
  \n
  - name****: The name of the third-party application.
    \n
  - token****: The generated token.
    \n
  - token_expired****: The timestamp when the token will expire.
    \n
  \n
- message****: The message \"Success\".
  \n
\n
Failure: A JSON object containing the following field:
\n
- message****: An error message indicating the reason for the failure.
\n

Error Handling

Invalid Credentials: If the provided app_name or app_key are incorrect, the API will return a 401 Unauthorized error with the message \"invalid app key\".

Additional Notes

Token Usage: The generated token must be included in the request header of subsequent API calls to authenticate the request.
\n
Token Expiration: The token_expired field indicates the timestamp when the token will become invalid. Third-party applications should request new tokens before the current one expires.
\n
Security: The app_key should be kept confidential to prevent unauthorized access.
\n

\n","auth":{"type":"apikey","apikey":{"value":"{{token}}","key":""},"isInherited":true,"source":{"_postman_id":"aeb0fdbe-a4bb-4512-bc1b-e501ace4a8d6","id":"aeb0fdbe-a4bb-4512-bc1b-e501ace4a8d6","name":"Booking API Documentation","type":"collection"}},"urlObject":{"path":["generate-token"],"host":["{{host_booking}}"],"query":[],"variable":[]}},"response":[{"id":"ca62bfda-b16f-43fe-bcd1-31dcfc690d66","name":"(Success) Generate Token","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"app_name\": \"wit-open-dev\",\n \"app_key\": \"w1t-d3V\"\n}","options":{"raw":{"language":"json"}}},"url":"{{host_booking}}/generate-token"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"name\": \"wit-dev\",\n \"token\": \"slek93laskvn100slaoe23lsmc009.eyJhcHBfbmFtZSI6IndpdC1kZXYiLCJkZXZpY2VfaWQiOiJwb3N0bWFuIiwiZGV2aWNlX3R5cGUiOiIwMDAwMDAxIiwiZXhwIjoxNzI2MjkzODE3fQ.9Xf48KEKe5rALUTe-HC5irGTUGeUG6L4GswjpfK8G3w\",\n \"token_expired\": \"2024-09-14T06:03:37.005128Z\"\n },\n \"message\": \"Success\"\n}"},{"id":"1f1d016d-2108-471d-b309-ab5545d662e9","name":"(Failed) Generate Token app-key","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"app_name\": \"wit-open-dev\",\n \"app_key\": \"w1t-deV\"\n}","options":{"raw":{"language":"json"}}},"url":"{{host_booking}}/generate-token"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"invalid app key\"\n}"},{"id":"4c21fece-89b3-4d4e-a48d-6fbdd812241c","name":"(Failed) Generate Token app-name","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"app_name\": \"wit-open-d3v\",\n \"app_key\": \"w1t-d3V\"\n}","options":{"raw":{"language":"json"}}},"url":"{{host_booking}}/generate-token"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"invalid app name\"\n}"},{"id":"1f3471f2-051a-4e93-8865-4817c8b23d2b","name":"(Failed) Generate Token bad-request","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"app_name\": \"\",\n \"app_key\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"{{host_booking}}/generate-token"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"bad request: app_key is required field;app_name is required field: bad request payload\"\n}"}],"_postman_id":"b9c9b88e-b4da-4ef1-abe2-e2a82fdcee78"}],"id":"98ad7654-527b-4a10-9811-9b9f8044b4a8","description":"

Token

Purpose: Tokens are unique identifiers generated by our system to verify the authenticity of each request.
\n
Process:
\n
- When a third-party application initiates a request to generate a token, it must provide its unique app_name and app_key as credentials.
  \n
- Our system validates these credentials against its records.
  \n
- Upon successful validation, a new token is generated using a secure hashing algorithm combined with a timestamp and other random elements.
  \n
- The generated token is then returned to the third-party application.
  \n
\n

\n","_postman_id":"98ad7654-527b-4a10-9811-9b9f8044b4a8","auth":{"type":"apikey","apikey":{"value":"{{token}}","key":""},"isInherited":true,"source":{"_postman_id":"aeb0fdbe-a4bb-4512-bc1b-e501ace4a8d6","id":"aeb0fdbe-a4bb-4512-bc1b-e501ace4a8d6","name":"Booking API Documentation","type":"collection"}}},{"name":"Booking","item":[{"name":"Ticket","id":"3eb45811-9142-4155-a75c-c619578416be","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{host_booking}}/booking/ticket","description":"

List Available Tickets

Endpoint: {{host_booking}}/tickets
Method: GET

Response

Success: A JSON object containing an array of ticket objects. Each ticket object includes the following properties:
\n
- is_bundle****: Indicates whether the ticket is a bundle of multiple tickets.
  \n
- ticket_id****: The unique identifier of the ticket.
  \n
- ticket_name****: The name of the ticket.
  \n
- description****: A description of the ticket.
  \n
- price****: The price of the ticket.
  \n
- stock****: The number of available tickets.
  \n
- image****: An optional URL to an image of the ticket.
  \n
- ticket_detail****: If is_bundle is true, an array of objects representing the individual tickets included in the bundle.
  \n
- is_active****: Indicates whether the ticket is currently active.
  \n
- is_online****: Indicates whether the ticket can be purchased online.
  \n
\n

Error Handling

Invalid Request: If the request contains invalid parameters or is malformed, the API will return a 400 Bad Request error.

Additional Notes:

You can customize the response fields to include additional information about the tickets, such as valid dates, restrictions, or special offers.
\n
Consider using pagination to handle large result sets.
\n

Endpoint

URL: {{host_booking}}
Method: POST

Request Body

A JSON object containing the following fields:

ticket_id****: The unique identifier of the ticket (required).
\n
is_bundling****: Boolean flag indicating whether the ticket is a bundle (required). Set to true for bundled tickets, false for single tickets.
\n
quantity****: The total number of tickets to be booked (required).
\n
booking_date****: The desired booking date in ISO 8601 format (e.g., \"2023-12-25T12:34:56Z\") (required).
\n
parent****: An object containing information about the booking lead:
\n
- name****: The full name of the booking lead (required).
  \n
- email****: The email address of the booking lead (required).
  \n
- phone_number****: The phone number of the booking lead (required).
  \n
- gender****: (Optional) The gender of the booking lead.
  \n
\n
guest****: An array of objects containing information about any guests included in the booking:
\n
- name****: The full name of the guest (required).
\n

Response (Success)

A JSON object containing the following fields:

data****: An object containing detailed information about the created booking:
\n
- booking_id****: A unique identifier for the booking.
  \n
- grand_total****: The total amount to be paid for the booking.
  \n
- transaction_number****: A unique transaction number associated with the booking.
  \n
- user****: An object containing information about the booking lead:
  \n
  - email****: The email address of the booking lead.
    \n
  - guid****: A unique identifier for the booking lead.
    \n
  - name****: The full name of the booking lead.
    \n
  - phone****: The phone number of the booking lead.
    \n
  \n
- items****: An array of objects representing each item included in the booking:
  \n
  - subtotal****: The subtotal amount for the item.
    \n
  - tenant_category_id****: Unique identifier for the ticket category.
    \n
  - tenant_category_name****: Name of the ticket category (e.g., \"Main Tenant\").
    \n
  - tenant_id****: Unique identifier for the tenant associated with the ticket.
    \n
  - tenant_location_id****: Unique identifier for the location associated with the ticket.
    \n
  - tenant_location_name****: Name of the location associated with the ticket (e.g., \"Main Park\").
    \n
  - tenant_name****: Full name of the tenant associated with the ticket (e.g., \"(MAIN) SCBD Habitat\").
    \n
  - ticket_sub_total****: The subtotal amount for all tickets within the item.
    \n
  - ticket****: An array of objects representing each individual ticket within the item:
    \n
    - amount****: Price paid for the specific ticket instance.
      \n
    - booking_date****: Booking date for this specific ticket instance.
      \n
    - is_ticket_bundle****: Boolean flag indicating whether the ticket is a bundle (false for single tickets).
      \n
    - note****: (Optional) Any notes associated with the ticket instance.
      \n
    - quantity****: The number of units booked for this specific ticket instance.
      \n
    - ticket****: An object containing detailed information about the individual ticket:
      \n
      - category_guid****: Unique identifier for the ticket category.
        \n
      - category_name****: Name of the ticket category (e.g., \"Main Park\").
        \n
      - description****: A description of the ticket.
        \n
      - discount****: The discount applied to the ticket price (if any).
        \n
      - discount_type****: The type of discount applied (e.g., \"nominal\", \"percentage\").
        \n
      - guid****: Unique identifier for the ticket.
        \n
      - image_url****: URL of an image for the ticket.
        \n
      - name****: The name of the ticket (e.g., \"Main Park Entrance Ticket\").
        \n
      - pb_1****: (Optional) Additional ticket-specific data.
        \n
      - pb_1_value****: (Optional) Additional ticket-specific data.
        \n
      - price****: The base price of the ticket.
        \n
      - transaction_visitor_ticket_id****: Unique identifier for the ticket within the transaction system.
        \n
      \n
    - ticket_actor****: An array of objects representing the individuals associated with the ticket:
      \n
      - full_name****: Full name of the individual.
        \n
      - gender****: Gender of the individual.
        \n
      - guid****: Unique identifier for the individual.
        \n
      - is_guest****: Boolean flag indicating if the individual is a guest.
        \n
      - is_parent****: Boolean flag indicating if the individual is the booking lead.
        \n
      - is_redeemed****: Boolean flag indicating if the ticket has been redeemed.
        \n
      - phone_number****: Phone number of the individual.
        \n
      - visitor_member_id****: Unique identifier for the individual within the visitor management system.
        \n
      \n
    \n
  \n
\n
message****: The message \"Success\".
\n

Additional Notes:

The specific fields and their values may vary depending on your application's requirements.
\n
The items array can contain multiple items if the booking includes tickets from different categories or locations.
\n
The ticket_actor array within each ticket can contain multiple entries for guests associated with the ticket.
\n

This enhanced response provides a more comprehensive view of the booking details, including information about the booking lead, guests, individual tickets, and the overall transaction.

The \\\"Main Park Entrance Ticket\\\" grants access to the Habitat, offering an immersive experience into the heart of nature's wonders.

Area : ENTRANCE, PLAYGROUND, PLAZA, SAOLA

\",\n \"discount\": 0,\n \"discount_type\": \"nominal\",\n \"guid\": \"0101a4ba-cf77-4e71-98a2-12e4a112fc50\",\n \"image_url\": \"https://storage.googleapis.com/scbd-habitat-bucket/45836012-f937-455e-ad68-9576e0d6e5f1.png\",\n \"name\": \"Main Park Entrance Ticket\",\n \"pb_1\": 10,\n \"pb_1_value\": 3500,\n \"price\": 35000,\n \"transaction_visitor_ticket_id\": \"e7fa80d7-3947-4c4e-805a-c7a5c6cfa2a6\"\n },\n \"ticket_actor\": [\n {\n \"full_name\": \"John Doe\",\n \"gender\": \"\",\n \"guid\": \"01e5131c-2f91-46ef-94e3-3d4dc1360b0f\",\n \"is_guest\": false,\n \"is_parent\": true,\n \"is_redeemed\": false,\n \"phone_number\": \"+6281122223344\",\n \"visitor_member_id\": \"f8912687-8d0e-4890-b3ec-d83a6aadf6e6\"\n }\n ],\n \"ticket_bundling\": null\n }\n ],\n \"ticket_sub_total\": 38500\n }\n ],\n \"transaction_number\": \"INV-HABITAT-20240913-00001\",\n \"user\": {\n \"email\": \"johndoe@example.com\",\n \"guid\": \"f8912687-8d0e-4890-b3ec-d83a6aadf6e6\",\n \"name\": \"John Doe\",\n \"phone\": \"+6281122223344\"\n }\n },\n \"message\": \"Success\"\n}"}],"_postman_id":"af6b8d9c-7d5f-4a06-ab9f-e29ccd150d95"}],"id":"8ac9a543-99bb-48c6-8c08-14d6eb0e6462","description":"

Overview

This section details the endpoints and methods related to managing bookings. It includes creating new bookings, retrieving booking details, and listing available tickets for booking.

\n","_postman_id":"8ac9a543-99bb-48c6-8c08-14d6eb0e6462","auth":{"type":"apikey","apikey":{"value":"{{token}}","key":""},"isInherited":true,"source":{"_postman_id":"aeb0fdbe-a4bb-4512-bc1b-e501ace4a8d6","id":"aeb0fdbe-a4bb-4512-bc1b-e501ace4a8d6","name":"Booking API Documentation","type":"collection"}}},{"name":"Health Check","id":"dad2aa18-622e-4d89-aca9-a361294b4e18","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{host_booking}}/health-check","description":"

Health Check Endpoint

Purpose:
This endpoint is designed to provide a quick and easy way to check the health and availability of the booking system.

Method: GET
Endpoint: {{host_booking}}/health-check

Response:

Success: Returns a JSON object indicating that all essential services are operational.
\n
Failure: Returns a JSON object indicating that at least one service is not responding.
\n

Additional Notes:

The specific services included in the services object may vary depending on the application.
\n
The healthcheck endpoint can be used by monitoring tools to track the availability of the system.
\n
Consider implementing rate limiting to prevent abuse of the endpoint.
\n

Why is this important?

Monitoring: Helps identify issues early before they impact users.
\n
Debugging: Provides insights into the health of individual services.
\n
Automation: Can be used in automated deployment and monitoring pipelines.
\n