# API Conventions

## Base URLs

Base URLs are provided per environment and per location. Refer to the relevant location section for the specific base URL applicable to your integration.

## Versioning

The CabFare Connect API is versioned. The current version is `v0.5.0`. The API version is included in the base URL path. When a new version is released, the previous version will remain available for a transition period. CabFare will notify integration partners of version changes with sufficient lead time to update their implementations.

## Request Format

All requests must:

- Use HTTPS
- Include the `Content-Type: application/json` header
- Include the `X-API-KEY` and `X-API-SECRET` authentication headers
- Send request bodies as valid JSON

## Response Codes

CabFare Connect uses standard HTTP status codes to indicate the outcome of every request.

| Code               | Meaning                                         | Common Cause                                                       |
| ------------------ | ----------------------------------------------- | ------------------------------------------------------------------ |
| `200 OK`           | Request successful, response body contains data | Ping, subsidy validation, trip end with subsidy                    |
| `202 Accepted`     | Request accepted with a notable condition       | Trip start where driver Subsidy Scheme status is not valid         |
| `204 No Content`   | Request accepted, no response body              | Driver logout, link request accepted, trip end without subsidy     |
| `400 Bad Request`  | Malformed or invalid request payload            | Missing required fields, incorrect data types, invalid enum values |
| `401 Unauthorized` | Missing or invalid credentials                  | Missing or incorrect `X-API-KEY` or `X-API-SECRET`                 |
| `403 Forbidden`    | Authenticated but operation not permitted       | Driver or vehicle not authorised for Subsidy Scheme trips          |
| `404 Not Found`    | Referenced resource not found                   | Unknown device ID, driver not currently logged in                  |
| `409 Conflict`     | Active session already exists                   | Duplicate `tripId`, existing active trip for vehicle               |
| `500 Server Error` | Internal CabFare Connect error                  | Contact [support@cabfare.com](mailto:support@cabfare.com)         |

## Error Response Format

For `4xx` responses, CabFare Connect returns a structured error body to help identify the cause.

```json
{
  "status": 400,
  "error": "Bad Request",
  "detail": [
    {
      "field": "driverId",
      "message": "must not be blank"
    }
  ]
}
```

Inspect the `detail` array for specific field-level errors when troubleshooting a `400` response.

## Currency Format

All monetary amounts in CabFare Connect are expressed in cents as integers, not dollars as floats.

> A fare of $10.00 must be submitted as `1000`

This applies to all fare amounts, subsidy amounts, lifting fees, and payment amounts across all endpoints.

## Identifiers

The following identifiers must be consistent across all API calls within a session:

| Identifier      | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| `taxiMeterId`   | Unique identifier for the Taxi Meter device or system            |
| `terminalId`    | Unique identifier for the Payment Terminal device or application |
| `driverId`      | Unique identifier for the accredited driver                      |
| `vehiclePlate`  | Registered vehicle plate number                                  |
| `tripId`        | Unique identifier for a single trip — must be unique per trip    |
| `transactionId` | Unique identifier for a single payment transaction               |

Inconsistent identifiers across the Taxi Meter and Payment Terminal are the most common cause of linking failures and session errors.

---
Source: https://docs.cabfare.com/api/api-conventions