ETAApi/v1

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:

{
    "email":"testing@etaviaporte.com",
    "password":"PasswordExample"
}

Returns:

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

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

{
    "email":"testing@etaviaporte.com",
    "password":"PasswordExample"
}

Returns:

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

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

Returns:

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

{
    "email":"testing@etaviaporte.com",
    "password":"new password"
}

Returns:

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

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

Returns:

{
    "msg" : "Password is reset!"
}

POST /contact-email

Send an email from the Landing Page:

Body content:

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

Returns:

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

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

Returns a company object

{
    "_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 - zipcode - type (unloading, loading, both) - alert_list: List of emails to notify whenever there is a change to the object.
• 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.
  • $sort[ field ] : -1/1 ; Sort result by field name
• GET /carrier : Get list of carrier companies with pagination using the following filters: company_type, company_name, truck_type, categories, company_state, company_city
  • $sort[ field ] : -1/1 ; Sort result by field name
• 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:
  • companyId
  • carrierId
  • vehicle
  • driver
  • status
  • posted_by_name
  • load_status
  • published_date
  • loaded_date
  • transit_date
  • categories
  • product
  • shipment_code
  • shipper_warehouse : id of a company branch
  • est_loading_date[gte] : Date greater than.
  • est_loading_date[lte] : Date less than.
  • est_unloading_date[gte] : Date greater than.
  • est_unloading_date[lte] : Date less than.
  • company_name[$regex] : Regex string to find company_name
  • company_name[$options] : Regex options from MongoDB filter description
  • $sort[ field ] : -1/1 ; Sort result by field name
  • alert_list: List of emails to notify whenever there is a change to the object.
• GET /calendar : Find a list of elements with any of the following fields:
  • date[gte] : Date grater than.
  • date[lte] : Date less than.
  • load_status : string enumerator ['Published', 'Loading', 'Transit', 'Downloading', 'Delivered'].
  • global : 1 To return calendar of all company, or 0/undefined for personal calendar only.
  • $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&date[gte]=2022-08-25&date[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.

/notifications

• GET / : Get list of latest notifications:
• DELETE /:id : Delete a single notification.

In order to delete a list of notifications use the following query:

DELETE ?list[0]=66b6d50ce91a3a5b96686863&list[1]=66b6d50ce91a3a5b96686863&list[2]=66b6d50cf193e37bb1dd913d

/proposals

• GET /find : Find a list of elements with any of the following fields:
  • load
  • categories
  • branch_name
  • phone, city
  • state
  • truck_type
  • is_accepted
  • is_withdrawn
  • is_completed
• 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 (from the company it self only) with any of the following fields:
  • is_available,
  • categories,
  • active_load,
  • load_shipper,
  • driver,
  • vehicle_code,
  • vehicle_name,
  • vehicle_number,
  • circulation_serial_number,
  • truck_type,
  • tyre_type,
  • city,
  • state,
  • status,
  • destino
  • $sort[ field ] : -1/1 ; Sort result by field name
• GET /global/find : Find a list of elements (from all the system) with any of the following fields:
  • company, (company id)
  • categories,
  • active_load,
  • load_shipper,
  • driver,
  • vehicle_code,
  • vehicle_name,
  • vehicle_number,
  • circulation_serial_number,
  • truck_type,
  • tyre_type,
  • city,
  • state,
  • status,
  • destino
  • company_name[$regex] : Regex string to find company_name
  • company_name[$options] : Regex options from MongoDB filter description
  • $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.

Observers endpoints

Public

The following endpoints doesn't require a JWT authorization

observers/account/

The full endpoint is observers/account/, and serves for the account credentials management, the same way it works for the common users at the endpoint /public/account, by the process of creating an OTP when requesting a new user or recovering the account password.

• POST /client/authorize or POST /warehouse/authorize: Authorize the access to the user identified by email:password.
• GET /client/authorize/:session_token or GET /warehouse/authorize/:session_token: Authorize the access to the user identified by the session token.
• POST /client/signup or POST /warehouse/signup: Requests an OTP to create a new account.
• PATCH /client/signup or PATCH /warehouse/signup: Confirms the account OTP.
• POST /client/recover or POST /warehouse/recover: Requests an OTP recover the account password.
• PATCH /client/recover or PATCH /warehouse/recover: Confirms the new password OTP.

Private

The following endpoints require a JWT authorization

observers/loads/

/find

• /warehouse/find: Warehouse find loads

• /client/find: Client find loads

• GET /warehouse/find or GET /client/find : Find a list of elements with any of the following fields:

  • company: Id of the shipper company
  • carrier: Id of the carrier company
  • status: Status of the load
  • posted_by: Id of the user posting the load
  • load_status
  • published_date
  • loaded_date
  • transit_date
  • categories
  • product
  • shipment_code: ETA code
  • origin_warehouse: id of the warehouse
  • destination_warehouse: id of the warehouse
  • est_loading_date[gte] : Date greater than.
  • est_loading_date[lte] : Date less than.
  • est_unloading_date[gte] : Date greater than.
  • est_unloading_date[lte] : Date less than.
  • $sort[ field ] : -1/1 ; Sort result by field name