# Getting Started


# Getting Started

Welcome to the Partner Connet APIs — your gateway to make property reservation via secured RESTful
APIs.
This guide walks you through the first steps: authentication, making your first call, and
understanding the response.

### 1. API Overview

Our APIs follow REST principles:

```
Base URL: https://qa-partner.momorooms.com/
Protocol: HTTPS (TLS 1.2+ required)
Format: JSON request and response bodies
Authentication: OAuth 2.0 Client Credentials Grant
Each request must include: A valid access token in the Authorization header
Content-Type: application/json                                   
Accept: application/json
```

Every Partner will be onboarded by momorooms by providing unique API client credentials (Client ID
and Client Secret) to access the API(s).

⚠️ **Be sure to secure your API client credentials!** Do not store your client ID or secret in
publicly accessible areas such as GitHub, client-side code, etc.

### 2. Authentication — OAuth 2.0 Client Credentials Flow

Authentication is handled via the Client Credentials Grant, using HTTP Basic Auth. <br>
You exchange your Client ID and Client Secret for a short-lived access token.

**Token Request**

```
POST /auth/oauth/token
```

**Headers**

```
Content-Type: application/x-www-form-urlencoded
```

**Body**

```
grant_type=client_credentials
```

**Sample Request (cURL)**

```
curl -X POST --location "https://qa-partner.momorooms.com/auth/oauth/token" \
       -H "Content-Type: application/x-www-form-urlencoded" \
       -d 'grant_type=client_credentials' \
       --basic --user YOUR_CLIENT_ID:YOUR_CLIENT_SECRET
```

**Sample Response**

```json
{
  "access_token": "eyJraWQiOiJabc123...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

⚠️ Important: Tokens expire after the expires_in duration. Implement token refresh logic in your
client.

### 3. Making an Authenticated Request

Example: Get Properties — Retrieve all contracted property IDs for your account.

**Request**

```
curl -X GET "https://qa-partner.momorooms.com/v1/properties" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJraWQiOiJabc123..." \
-H "Accept: application/json"
```

**Response**

```json
{
  "properties": [
    1000100101,
    1090099000
  ]
}
```

### 4. End-to-End Workflow

A standard booking integration will typically follow these steps:

| Step | API                    | Purpose                                                                    |
|:-----|:-----------------------|:---------------------------------------------------------------------------|
| 1    | Get Properties         | Retrieve all property IDs for the partner.                                 |
| 2    | Property Content       | Fetch property metadata and static assets (address, rating, images).       |
| 3    | Room Content           | Retrieve detailed room data for a property (room name, bed info, images).  |
| 4    | Multi-Property Search  | Find properties with list of PropertyId(s) matching guest search criteria. |
| 5    | Single Property Search | Get availability and rates for a specific property.                        |
| 6    | Property Quote Request | Confirm final pricing and availability for the chosen room.                |
| 7    | Create Reservation     | Complete the reservation.                                                  |
| 8    | Reservation Status     | Validate reservation status (confirmed, pending, failed).                  |
| 9    | Cancel Reservation     | Cancel the existing reservation with reason.                               |

### 5. Error Handling Strategy

All the application errors follow a standardized JSON structure:

```json
{
  "errors": [
    {
      "errorCode": 500,
      "errorDescription": "Unexpected server-side error."
    }
  ]
}
   ```

**Application Errors**

| HTTP Status | Code | Meaning                                           |
|:------------|:-----|:--------------------------------------------------|
| 400         | XXXX | Request is missing or has invalid parameters.     |
| 500         | 500  | Unexpected server-side error.                     |

**Common Errors**

| HTTP Status | Meaning                                           |
|:------------|:--------------------------------------------------|
| 401         | Missing, invalid, or expired access token.        |
| 403         | Client not authorized for the requested resource. |
| 404         | Resource not found.                               |
| 500         | Unexpected server-side error.                     |

**Best Practices**

* Always check HTTP status before parsing the response body.
* Implement retries with exponential backoff for 500 errors.
* Log errorCode and message for troubleshooting.

### 6. Recommended Development Flow

* Get Access Token using the OAuth 2.0 Client Credentials grant.
* Test in Sandbox with sample data.
* Integrate API Calls following the step-by-step workflow.
* Implement Error Handling and retry logic.
* Move to Production once validated in Sandbox.