> ## Documentation Index
> Fetch the complete documentation index at: https://docs.str.keroshospitality.com/llms.txt
> Use this file to discover all available pages before exploring further.

# STR Uploader API

> REST API for uploading reservations to the Greek STR registry

## Welcome

The Taxis uploader API provides endpoints for uploading reservations to Government's Short Term Rental Registry and filing the Climate Crisis Resilience Fee Statement (TAKK).

<Card title="OpenAPI Specification" icon="code" href="/docs/openapi.json">
  View the complete OpenAPI specification
</Card>

## Overview

This API allows you to:

* Upload short-term rental records
* Query an STR task's upload status
* Upload Climate Crisis Resilience Fee Statement
* Query a TAKK statement's upload task status

## Authentication

All API endpoints require JWT Bearer token authentication. The applicable roles for this API are: `str-uploader`, `takk-uploader`, `client-manager`.

### How to get a JWT token:

1. Use your client ID and client secret obtained from your administrator
2. Send a POST request to `/auth/token` with your credentials
3. Use the returned `access_token` in the Authorization header: `Bearer <access_token>`

### Example with curl:

```bash theme={null}
curl -X POST {server}/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{
"clientId": "your-client-id",
"secret": "your-client-secret"
}'
```

### Using the token:

```bash theme={null}
curl -X GET {server}/api/v1/clients \
-H "Authorization: Bearer <your-access-token>"
```

### Token refresh:

When your access token expires, use the refresh token:

```bash theme={null}
curl -X POST {server}/api/v1/auth/refresh \
-H "Content-Type: application/json" \
-d '{
"refreshToken": "your-refresh-token-here"
}'
```

**Note:** Replace `{server}` with your actual server URL (e.g., `https://api.yourdomain.com` or `http://localhost:8080` for local development).

## Response Formats

All responses are in JSON format. Successful responses use HTTP 2xx status codes:

* 200: Successful operation with response body
* 201: Resource created
* 202: Request accepted for processing
* 204: Successful operation with no response body

## Error Responses

Unsuccessful requests return a response with an error-indicating status code, and a json object with a 'errorMessage' and requestId field:

```json theme={null}
{
"errorMessage": "Not found",
"requestId": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890"
}
```

## Error Values

When upload tasks fail, the system provides specific error classifications through the `errorValue` field. These help identify the cause of the failure:

| Error Value                        | Description                                                                                                                                                                                                                                                                                |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `duplicate_declaration`            | The reservation has already been declared in the system                                                                                                                                                                                                                                    |
| `tax_id_not_found`                 | The provided tax ID could not be found or validated                                                                                                                                                                                                                                        |
| `invalid_guest_name`               | The provided guest name is invalid (contains non-alphabetic characters)                                                                                                                                                                                                                    |
| `timed_out`                        | The upload operation exceeded the allowed time limit                                                                                                                                                                                                                                       |
| `failed_to_authenticate`           | Authentication with the government portal failed                                                                                                                                                                                                                                           |
| `failed_to_navigate`               | Unable to navigate through the government portal interface                                                                                                                                                                                                                                 |
| `concurrent_modification`          | This usually happens when there is a database conflict. The error message from the registry is: ORA-30006: resource busy                                                                                                                                                                   |
| `not_a_short_term_booking`         | The reservation is not a short term booking (must be less than 60 days. The error message from the registry is: ως βραχυχρόνια μίσθωση ορίζεται η μίσθωση ή υπεκμίσθωση ακινήτου, με χρονική διάρκεια μικρότερη των εξήντα (60) ημερών.                                                    |
| `invalid_end_date`                 | The end date is invalid. Corresponds to this registry error: Η ημερομηνία αναχώρησης δεν μπορεί να είναι μεταγενέστερη της 01/01 του επόμενου έτους από την ημερομηνία άφιξης.                                                                                                             |
| `property_not_finalized`           | The property registration in the registry is incomplete — the property setup has not been finalized in the portal. Registry error: "Property could not be finalized". **Retryable** (transient during registration workflows).                                                             |
| `property_discontinued`            | The property's registration number (Α.Μ.Α.) has been permanently discontinued after a Lease Termination Declaration. No further declarations are accepted. Registry error: Ο Α.Μ.Α. έχει διακοπεί βάσει της υποβληθείσας Δήλωσης Λύσης Μίσθωσης. **Non-retryable.**                        |
| `property_cessation_date_exceeded` | The reservation's arrival date is after the property's cessation date on the registry. Any booking past that date is rejected. Registry error: Η ημερομηνία άφιξης δεν μπορεί να είναι μεγαλύτερη της ημερομηνίας διακοπής του ακινήτου(DD/MM/YYYY). **Non-retryable.**                    |
| `session_expired`                  | The Taxis.net session expired mid-upload. **Retryable** — a new session is established on retry.                                                                                                                                                                                           |
| `field_value_too_long`             | A field value exceeds the maximum length the registry accepts (e.g. a UUID sent as the guest ID instead of a real document number). Registry error: ORA-06502: PL/SQL: numeric or value error: character string buffer too small. Fix the offending field and resubmit. **Non-retryable.** |
| `portal_ajax_stuck`                | The registry portal's AJAX loading overlay never cleared, blocking form interaction. **Retryable** — usually transient portal load.                                                                                                                                                        |
| `internal_error`                   | An internal system error occurred                                                                                                                                                                                                                                                          |
| `unknown`                          | An unclassified error occurred                                                                                                                                                                                                                                                             |

### Retryable vs. non-retryable

Uploads are retried up to 8 times with exponential backoff for *retryable* errors. *Non-retryable* errors fail immediately on the first attempt so the system doesn't waste cycles on a guaranteed failure.

**Non-retryable** (fail fast): `duplicate_declaration`, `tax_id_not_found`, `invalid_guest_name`, `not_a_short_term_booking`, `invalid_end_date`, `failed_to_authenticate`, `property_discontinued`, `property_cessation_date_exceeded`, `field_value_too_long`.

**Retryable** (up to 8 attempts): `timed_out`, `failed_to_navigate`, `concurrent_modification`, `property_not_finalized`, `session_expired`, `portal_ajax_stuck`, `internal_error`, `unknown`.