# Charter Party Bulk Upload Documentation

## Overview
This document describes the JSON format for bulk creation of Charter Parties (Ναυλοσύμφωνα) for Professional Pleasure Vessels. It allows for the optional pre-filling of crew and passenger manifests and includes a client-side ID for enhanced traceability.

## JSON File Structure

The JSON file must contain an array of charter party objects. Each charter party object represents a single charter agreement.

## Required vs Optional Fields by Usage Type

### Common Fields (All Usage Types)
- **authority** (required): Authority responsible for the charter party.
- **ship_call_sign** (required): The call sign of the vessel.
- **usage_type** (required): Type of usage for the vessel.
- **start_date** (required): Charter start date and time.
- **end_date** (required): Charter end date and time.
- **captain_first_name** (required): Captain's first name.
- **captain_last_name** (required): Captain's last name.
- **captain_email** (optional): Captain's email for system access.
- **client_id** (optional): A unique identifier (string or number) from your own system. This ID will be included in error messages to help you locate problematic records.
- **crew** (optional): An array of crew member objects. See **Manifest Structure** below.
- **passengers** (optional): An array of passenger objects. See **Manifest Structure** below.

### Port Fields
- **start_port_in_greece** (required): Boolean (`true`/`false`) indicating if departure port is in Greece.
- **end_port_in_greece** (required): Boolean (`true`/`false`) indicating if arrival port is in Greece.
- **start_port_code** (conditional): Required if `start_port_in_greece` is `true`.
- **end_port_code** (conditional): Required if `end_port_in_greece` is `true`.
- **start_port_foreign** (conditional): Required if `start_port_in_greece` is `false`.
- **end_port_foreign** (conditional): Required if `end_port_in_greece` is `false`.
- **start_port_exact** (optional): Fill it to define the exact place of departure
- **end_port_exact** (optional): Fill it to define the exact place of arrival

### Usage Type: "exploitation" (Εκμετάλλευση)
Additional required/optional fields:
- **parties** (required): Array of party objects (see **Party Structure** below). Must contain at least one `charterer`.
- **freight** (required): Total charter fee in EUR (must be a positive number).
- **execution_subtype** (optional): Exception subtype (`"ba"` or `"bb"`).
- **fuel_burden** (optional): Who pays for fuel (`"charterer"` or `"owner"`).
- **additional_expenses_on_owner** (optional): Boolean for additional expenses.
- **additional_terms** (optional): Additional terms and conditions text.

### Usage Type: "self_use" (Ιδιοχρησιμοποίηση)
- **parties** (optional): Parties are generally not applicable but can be provided.
- **passengers** can be pre-filled if known.

### Usage Type: "empty_run" (Empty Run)
- **empty_run_movement** (required): Type of empty run movement (see **Empty Run Movement Types**).
- **passengers** are not allowed for this usage type.

## Field Specifications

### usage_type
Allowed values:
- `"exploitation"`: Execution of total charter contract (Article 3, Law 4926/2022).
- `"self_use"`: Self-use (Article 15, Law 4926/2022).
- `"empty_run"`: Single empty run movement (Article 16, Law 4926/2022).

### Date Format
All dates must be in ISO 8601 format: `"YYYY-MM-DDTHH:MM:SS"`. You can include timezone information (e.g., ending with `Z` for UTC), otherwise dates will be interpreted in the server's local time (Europe/Athens).

Example: `"2026-06-15T10:00:00"`

### execution_subtype
Only applicable when `usage_type` is `"exploitation"`:
- `"ba"`: Charter contract execution per sub-case βα' of par. 5, art. 3, Law 4926/2022.
  - Duration: ≤ 12 hours.
  - No overnight stay.
  - Passengers ≤ maximum passenger capacity.
- `"bb"`: Charter contract execution per sub-case ββ' of par. 5, art. 3, Law 4926/2022.
  - Duration: > 12 hours.
  - Vessel length: ≤ 24 meters.
  - Passenger capacity: ≤ 12 passengers.

### fuel_burden
Who bears the fuel costs (including special consumption tax):
- `"charterer"`: Charterer pays.
- `"owner"`: Owner pays.

### empty_run_movement
Only applicable when `usage_type` is `"empty_run"`:
- `"CHANGE_BERTH"`: Change of berth position.
- `"MOORING_TRIAL"`: Mooring and trial voyage.
- `"SHIPYARD_MOVE"`: Movement to/from shipyard for maintenance/repair/construction.
- `"CHARTER_PORT"`: Departure/arrival to another port to start charter contract (within Greece).
- `"SUPPLYING"`: Vessel supply (fuel, water, provisions).
- `"EXHIBITION"`: Participation in specific marine tourism exhibition.
- `"OWNER_TRANSFER"`: Departure/arrival to another port for owner pickup for self-use (within Greece).

## Party Structure

Each party object in the **parties** array must have the following structure:

```json
{
  "party_role": "charterer",
  "party_type": "physical",
  "tax_id": "123456789",
  "name": "John Doe",
  "address": "123 Main Street, Athens",
  "id_number": "AB123456",
  "phone": "+30 210 1234567",
  "email": "johndoe@example.com",
  "legal_rep_name": ""
}
```

### Party Fields

- **party_role** (required): Role of the party.
  - `"charterer"`: Charterer (Ναυλωτής).
  - `"broker"`: Broker/Agent/Travel Agency (Ναυλομεσίτης/Ναυτικός Πράκτορας/Τουριστικό Γραφείο).
  - `"authorized"`: Authorized person (Εξουσιοδοτημένο πρόσωπο).
- **party_type** (required): Type of party.
  - `"physical"`: Physical person (Φυσικό πρόσωπο).
  - `"legal"`: Legal entity (Νομικό πρόσωπο).
- **tax_id** (optional): Tax identification number (ΑΦΜ).
- **name** (required): Full name (for physical) or company name (for legal).
- **address** (optional): Full address.
- **id_number** (optional): ID card number (for physical persons).
- **phone** (optional): Contact phone number.
- **email** (optional): Contact email address.
- **legal_rep_name** (optional): Legal representative name (for legal entities).

## Manifest Structure (for Crew and Passengers)

If you choose to provide `crew` or `passengers`, each object in the array must follow this structure:

```json
{
  "full_name": "Anna Vassiliou",
  "id_number": "AM445566",
  "sex": "F",
  "nationality": "GRC",
  "date_of_birth": "1990-09-01T00:00:00",
  "embarkation_date": "2026-07-01T08:00:00",
  "embarkation_port": "GRLAV",
  "notes": "Hostess/Chef"
}
```

### Manifest Fields
- **full_name** (required): Full name of the person.
- **id_number** (required): Passport or National ID number.
- **sex** (required): `"M"` for male or `"F"` for female.
- **nationality** (required): ISO 3166-1 alpha-3 nationality code (e.g. "GRC" for Greek, "GBR" for British). Accepts the 3-letter code only.
- **date_of_birth** (required): Date of birth in ISO 8601 format.
- **embarkation_date** (required): Date and time of embarkation in ISO 8601 format. This date must be within the charter's `start_date` and `end_date`.
- **embarkation_port** (required): Port of embarkation.
- **notes** (optional): Any relevant notes.

## Validation Rules

Your uploaded file will be checked against a formal schema and a set of business rules. If any validation fails, the entire upload will be rejected and you will receive a list of all errors.

1.  **Schema Validation:** Checks for required fields, correct data types (e.g., `boolean`, `string`, `number`), and valid enum values.
2.  **Date Validation:** `end_date` must be after `start_date`. Dates must not be in the past.
3.  **Port Validation:** If `start_port_in_greece` is `true`, a valid `start_port_code` must be provided. If `false`, `start_port_foreign` is required. The same logic applies to end ports.
4.  **Usage Type Validation:**
    - `exploitation`: `parties` array must contain at least one `charterer`. `freight` is required.
    - `empty_run`: `empty_run_movement` must be specified. `passengers` array is not allowed.
5.  **Manifest Validation:**
    - If `crew` or `passengers` arrays are provided, they must not be empty.
    - `embarkation_date` for each person must be between the charter's `start_date` and `end_date`.
    - The number of passengers cannot exceed the vessel's maximum capacity.
6.  **Ship Validation:** `ship_call_sign` must correspond to an existing, active vessel in the system that you have access to.
7.  **Overlap Validation:** The system will check for overlapping charter periods for the same vessel, both within the uploaded file and against existing charters in the database.

## Notes

- **Manifests are Optional:** If you do not provide the `crew` and/or `passengers` arrays, the charter will be created without them. The captain can then add them later via the web interface as usual.
- **Port Codes:** Port codes must match the UN/LOCODE for each port (e.g., `GRPIR` for Piraeus).
- **Authority Codes:** The `authority` must be specified using the correct system code (e.g., `"kl-peiraia"` for Piraeus Central Port Authority).
- **Captain's Email:** Providing the `captain_email` is important for granting the captain system access to edit the manifest after creation.