# Getting Started with Yolcu360 Agency API

## Overview

Yolcu360 Agency API is a RESTful API that allows our business partners to easily integrate with our car rental services. With this API, you can:

- Search for locations
- Query available vehicles
- Create reservations
- Process payments
- Manage orders


## Quick Start

### 1. Obtaining an API Key

To use the API, you first need to obtain an API key and secret. To do this, log in to the agency portal at [pro.yolcu360.com](https://pro.yolcu360.com) and create a new key from the API Keys section.

### 2. Authentication

You need to obtain a JWT token using your API key:


```bash
curl -X POST https://staging.api.pro.yolcu360.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_API_KEY",
    "secret": "YOUR_API_SECRET"
  }'
```

Successful response:


```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "dGhpc2lzYXJlZnJlc2h0b2tlbg...",
  "accessTokenExpireAt": "2024-12-26T10:30:00Z",
  "refreshTokenExpireAt": "2024-12-27T10:00:00Z"
}
```

### 3. API Calls

Use the `accessToken` you received in the `Authorization` header for all API calls:


```bash
curl -X GET https://staging.api.pro.yolcu360.com/api/v1/locations?query=istanbul \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Environments

Our API serves in two different environments:

| Environment | Base URL | Purpose |
|  --- | --- | --- |
| Staging | `https://staging.api.pro.yolcu360.com/api/v1/` | Testing and development |
| Production | `https://api.pro.yolcu360.com/api/v1/` | Live operations |


⚠️ **Important:** Reservations made in the staging environment are not real and no payment is processed.

## Error Handling

The API uses standard HTTP status codes:

- `200 OK` - Request successful
- `201 Created` - Resource created
- `400 Bad Request` - Invalid request
- `401 Unauthorized` - Authentication error
- `403 Forbidden` - Authorization error
- `404 Not Found` - Resource not found
- `429 Too Many Requests` - Rate limit exceeded
- `500 Internal Server Error` - Server error


Error responses are in the following format:


```json
{
  "code": 1001,
  "description": "Invalid request parameters",
  "details": {
    "field": "checkInDateTime",
    "message": "Must be a future date"
  }
}
```

## Flow Diagram


```mermaid
graph TD
    A[Start] --> B[Authentication]
    B --> |API Key & Secret| C[Get JWT Token]
    C --> D[Location Search]
    D --> |Search Query| E[Get Location Details]
    E --> F[Search Available Cars]
    F --> |Search Results| N{Findeks Required?}
    N --> |Yes| O[Findeks Check]
    N --> |No| G[Get Extra Products]
    O --> |Positive| G
    O --> |Negative| X[Process Terminated]
    G --> H[Create Order]
    H --> |Order Created| I[Process Payment]
    I --> |Credit Card| J[3D Secure Flow]
    I --> |Credit Limit| K[Direct Payment]
    J --> L[Payment Complete]
    K --> L
    L --> M[End]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style M fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:2px
    style C fill:#bbf,stroke:#333,stroke-width:2px
    style D fill:#dfd,stroke:#333,stroke-width:2px
    style E fill:#dfd,stroke:#333,stroke-width:2px
    style F fill:#fdd,stroke:#333,stroke-width:2px
    style N fill:#ffe,stroke:#333,stroke-width:2px
    style O fill:#ffe,stroke:#333,stroke-width:2px
    style X fill:#fee,stroke:#333,stroke-width:2px
    style G fill:#fdd,stroke:#333,stroke-width:2px
    style H fill:#ddf,stroke:#333,stroke-width:2px
    style I fill:#ffd,stroke:#333,stroke-width:2px
    style J fill:#ffd,stroke:#333,stroke-width:2px
    style K fill:#ffd,stroke:#333,stroke-width:2px
    style L fill:#dff,stroke:#333,stroke-width:2px
```

## Support

For technical support:

- Email: api-support@yolcu360.com
- Documentation: [api-docs.yolcu360.com](https://api-docs.yolcu360.com)