STR Uploader API

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).

OpenAPI Specification

View the complete OpenAPI specification

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:

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

Example with curl:

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:

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

Token refresh:

When your access token expires, use the refresh token:

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:

{
"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.

Authentication

Clients

Apartment Owners

Apartments

Reservations

STR Tasks

STR Submitted Declarations

TAKK Tasks

Welcome

OpenAPI Specification

Overview

Authentication

How to get a JWT token:

Example with curl:

Using the token:

Token refresh:

Response Formats

Error Responses

Error Values

Retryable vs. non-retryable

​Welcome

OpenAPI Specification

​Overview

​Authentication

​How to get a JWT token:

​Example with curl:

​Using the token:

​Token refresh:

​Response Formats

​Error Responses

​Error Values

​Retryable vs. non-retryable

Welcome

Overview

Authentication

How to get a JWT token:

Example with curl:

Using the token:

Token refresh:

Response Formats

Error Responses

Error Values

Retryable vs. non-retryable