# ETA API

ETA Viaporte API

# Dependencies

 - NodeJS v18
 - Docker

# Endpoints

All endpoints that return a list of elements is paginable with the following queries:
 - `elements`: Number of elements for each page.
 - `page`: Page number (from 0 to n)

Example:
 - `/endpoint?elements=50&page=2` : Get page 2 with 50 elements per page.
 - `/endpoint?page=2` : Get page 2 with default (10) elements per page.
 - `/endpoint?elements=50` : Get page 0 with 50 elements.

## Public endpoints

Read registered resources:

 - `GET /account`: At this location you can: register, login, recover password, renew JWT.
 - `GET /countries`: List registered countries.
 - `GET /cities`: List registered cities.
 - `GET /meta-data`: List registered meta-data.
 - `GET /meta-groups`: List registered meta-data.
 - `GET /product-categories`: List registered product-categories.
 - `GET /public-companies`: List registered companies. Pagination limited to 100 elements and page 0.
 - `GET /public-loads`: List registered loads.
 - `GET /public-load-attachments/download/:id`: Downloads the attachment of the load identified by Id.
 - `GET /public-vehicles`: List registered vehicles.
 - `GET /states`: List registered states.
 - `POST /contact-email`: Send an email from the Landing Page.

All these endpoints support the following parameters (except for those with `public-` as prefix, for example `public-vehicles`):

 - `/` : List registered resources with pagination. 
 - `/:id` : Read specific resource identified by Id.
 - `/find?regex=xxx` : List resources that matches with regex (support pagination).

### /account

This endpoint provides mechanisms to register, login, recover password and renew JWT.

The __Login__ and __Renew__ process will return 2 tokens, the `accessToken` (JWT) which is used in every further request to authorize access to private endpoints. And the 2nd is the `session_token` (renew token), which should be used after the expiration of the JWT, in order to generate another _JWT_ and _session token_ without the need of use the _email_ and _password__.

The _session token_ expiration is typically 30 days after its generation. Every renewal replaces the token in the DB and the expiration is reset again to 30 days.

#### POST /account/authorize

Login process, returns a JWT and Renew Token

Expects a body with the following data:
```{.json}
{
    "email":"testing@etaviaporte.com",
    "password":"PasswordExample"
}
```

Returns:
```{.javascript}
{
    "accessToken" : "JWT",
    "payload" : "Content in the JWT",
    "session_token": "Renew token",
    "session_token_exp": "Expiration of renew token in UNIX epoch format",
    "user" : { ... }
}
```

#### GET /account/authorize/:session_token

Renewal of JWT with session token, will return the new session token and a new JWT only if the session token is not expired, otherwise the request will fail and the login process should be used instead.

Example of usage:
```
    GET /account/authorize/"HERE_GOES_THE_SESSION_TOKEN"
```

Returns:
```{.json}
{
    "accessToken" : "JWT",
    "payload" : "Content in the JWT",
    "session_token": "Renew token",
    "session_token_exp": "Expiration of renew token in UNIX epoch format",
    "user" : { ... }
}
```

#### POST /account/signup

Create a new user. This will trigger an email with the OTP (one time password) to verify the email. There is no expiration time, but it is expected that the Fron End removes the checksum from the local storage after an expiration time defined in the Front End. 

This will return a checksum string to be used in the confirmation process.

Expects a body with the following data:
```{.json}
{
    "email":"testing@etaviaporte.com",
    "password":"PasswordExample"
}
```

Returns:
```{.javascript}
{
    "checksum" : "JWT"
}
```

#### PATCH /account/signup

Confirms registration of new user. This will trigger a welcome email to the user.
There is no timeout to confirm the email, but it is expected that the Fron End removes the checksum from the local storage after an expiration time defined in the Front End.

If the checksum matches but the user is already registered, then this request will be rejected.

Expects a body with the same data as the POST request, but adding the OTP received in the email, the company type decided by the user and the checksum generated by the POST request. Here is an example:

```{.json}
{
    "email":"testing@etaviaporte.com",
    "password":"PasswordExample",
    "otp":"OTP string",
    "checksum":"Checksum generated in the POST request"
}
```

Returns:
```{.json}
{
    "msg" : "User created successfully!"
}
```

#### POST /account/recover

Reset password request. This will trigger an email with the OTP (one time password) to verify the email. There is no expiration time, but it is expected that the Fron End removes the checksum from the local storage after an expiration time defined in the Front End. 

This will return a checksum string to be used in the confirmation process.

Expects a body with the following data:
```{.json}
{
    "email":"testing@etaviaporte.com",
    "password":"new password"
}
```

Returns:
```{.javascript}
{
    "checksum" : "JWT"
}
```

#### PATCH /account/recover

Confirms the email to recover the password.
There is no timeout to confirm the email, but it is expected that the Fron End removes the checksum from the local storage after an expiration time defined in the Front End.

Expects a body with the same data as the POST request, but adding the OTP received in the email, and the checksum generated by the POST request. Here is an example:

```{.json}
{
    "email":"testing@etaviaporte.com",
    "password":"New Password Example",
    "otp":"OTP string",
    "checksum":"Checksum generated in the POST request"
}
```

Returns:
```{.json}
{
    "msg" : "Password is reset!"
}
```

### POST /contact-email

Send an email from the Landing Page:

Body content:

```{.json}
{
    "email":"josepablo134@gmail.com",
    "name":"Josepablo C.",
    "message":"This is a test"
}
```

Returns:
```{.json}
{
    "msg": "Email sent!"
}
```

### GET /public-companies

Get public fields from registered companies.

 - `GET /shipper`: List registered shippers that are not hidden only.
 - `GET /carrier`: List registered carriers that are not hidden only.

### GET /public-loads

Get public fields from registered loads.

 - `GET /`: List only loads with status Published.

### GET /public-vehicles

Get public fields from registered vehicles.

 - `GET /published`: List only latest published vehicles.
 - `GET /location`: List only location from vehicles in status Free.

### /news

 - `GET /` : Get a list of elements with pagination.
 - `GET /find` : Find a list of elements with any of the following fields:
    - regex
 - `GET /:id` : Get data from specific element.
 - `GET /download/:image_name`: Download image from DB.

## Private Endpoints

The following list of endpoints requires a JWT.

 - `GET /loads`: List loads related to my company.
 - `GET /load-attachments`: List load attachments related to my company or load id.

### /public-load-tracking

 - `GET /:id`: Get tracking data from load id

### Test Endpoint

A private endpoint to test the JWT and the api response.

 - `POST /apitest`: Return whatever is sent on the body, queries and parameters.
 - `GET /version`: Return the API version.

 ### /account

Complete the register process

 - `POST /register` : Creates the company from the body data provided and assigns account to this new company.

#### POST /account/register

Send company data to complete the register.

After this process, the logged user will receive the flag "isVerified" and the company id will be associated, at the same time, the role will be set to "owner" and the permissions will be set according to the company type: `role_shipper` or `role_carrier`.

This request can only happen once, since this process is the creation of a new company in the DB.
After setting up the company, the updates can be handled in the `/companies` endpoint.

Body content:

```{.json}
{
    "company_type":"carrier|shipper",
    "company_name" : "Company Name",
    "company_description" : "This is a description example"
}
```

Returns a company object

```{.json}
{
    "_id": "company_id",
    "company_type":"carrier|shipper",
    "company_name" : "Company Name",
    "company_description" : "This is a description example"
}
```

### /branches

 - `GET /find` : Find a list of elements with any of the following fields:
        - categories
        - branch_name
        - phone
        - city
        - state
        - truck_type
 - `POST /new` : Creates a new element.
 - `PATCH /:id` : Updates data from specific element.
 - `DELETE /:id` : Delete element from company. Returns the element data.
 - `GET /:id` : Get data from specific element.

### /budgets

 - `GET /find` : Find a list of elements with any of the following fields:
        - client
        - material
        - origin
        - destination
        - truck_type
        - num_tons
        - price_per_ton
        - tonnage
        - pickup_distance
        - delivery_distance
        - warehouse_distance
        - total_km_travel
        - cost_per_liter
        - fuel_price_per_liter
        - other_fuel_expenses
        - total_fuel_consumed
        - total_cost_fuel
        - driver_salary
        - accomadation_allowance
        - other_administrative_expenses
        - total_before_tax
        - total_utility_per_km
        - total_profit
        - profit_percentage
        - total_administrative_expenses
 - `POST /new` : Creates a new element.
 - `PATCH /:id` : Updates data from specific element.
 - `DELETE /:id` : Delete element from company. Returns the element data.
 - `GET /:id` : Get data from specific element.

### /calendars

This endpoint is part of /loads endpoint

### /companies

 - `GET /own` : Get own company data.
 - `PATCH /own` : Update own company data.
 - `GET /shipper` : Get list of shipper companies with pagination using the following filters: company_type, company_name, truck_type, categories, company_state, company_city
 - `GET /carrier` : Get list of carrier companies with pagination using the following filters: company_type, company_name, truck_type, categories, company_state, company_city
 - `GET /users/:companyId` : Get the list of users within a company.
 - `GET /:id` : Get data from specific company.

### /load-attachments

 - `POST /loading/:id` : Upload/Update a loading attachment.
 - `POST /downloading/:id` : Upload/Update a download attachment
 - `GET /load/:id` : Get the list of attachment ids from load.
 - `GET /:id` : Get attachment file.
 - `GET /` : Get attachment list from company.

### /loads

 - `GET /find` : Find a list of elements with any of the following fields:
    - company
    - carrier
    - vehicle
    - driver
    - status
    - posted_by_name
    - load_status
    - published_date
    - loaded_date
    - transit_date
    - categories
    - product
    - shipment_code
    - $sort[ field ] : -1/1 ; Sort result by field name
 - `GET /calendar` : Find a list of elements with any of the following fields:
    - load_status_updated[gte] : Date grater than.
    - load_status_updated[lte] : Date less than.
    - load_status : string enumerator ['Published', 'Loading', 'Transit', 'Downloading', 'Delivered'].
    - $sort[ field ] : -1/1 ; Sort result by field name
 - `POST /new` : Creates a new element.
 - `PATCH /:id` : Updates data from specific element.
 - `DELETE /:id` : Delete element from company. Returns the element data.
 - `GET /:id` : Get data from specific element.

##### Example of filter and sort:

 - `GET /calendar?$sort[createdAt]=-1&load_status_updated[gte]=2022-08-25&load_status_updated[lte]=2022-05-25&load_status=Loading`: Get loads within date range 2022-08-25 -> 2022-05-25 with load_state "Loading" and sort it by createdAt field.

 - `GET /loads/find?$sort[createdAt]=-1&load_status=Loading`: Get loads with status "Loading" sorted by createdAt.

### /proposals

 - `GET /find` : Find a list of elements with any of the following fields:
    - load
    - categories
    - branch_name
    - phone, city
    - state
    - truck_type
 - `POST /new` : Creates a new element.
 - `PATCH /:id` : Updates data from specific element.
 - `DELETE /:id` : Delete element from company. Returns the element data.
 - `GET /:id` : Get data from specific element.

### /upload

Work In Progress

### /users

 - `GET /find` : Look for a user within ETA.
 - `POST /member` : Create a new user within the company (only for owner or manager users).
 - `PATCH /member/:id` : Update member data (except permissions, company, job_role and password).
 - `DELETE /member/:id` : Delete member but keep metadata for future references. The user will be disabled and won't be able to log in again.
 - `GET /profile` : Read profile data.
 - `PATCH /profile` : Update profile data (except permissions, company, job_role and password).
 - `GET /:id` : Get user information with its ID.

### /vehicles

__This endpoint is only valid for carriers.__

 - `GET /find` : Find a list of elements with any of the following fields:
    - categories,
    - active_load,
    - load_shipper,
    - driver,
    - vehicle_code,
    - vehicle_name,
    - vehicle_number,
    - circulation_serial_number,
    - truck_type,
    - tyre_type,
    - city,
    - state,
    - status,
    - destino
 - `POST /new` : Creates a new element.
 - `PATCH /:id` : Updates data from specific element.
 - `DELETE /:id` : Delete element from company. Returns the element data.
 - `GET /:id` : Get data from specific element.