ETAApi/v1

ETA API

ETA Viaporte API

Dependencies

• NodeJS v18
• Docker

Audience

This document is oriented to front-end developers integrating with the ETA API. Use the Quick Start section first, then go to the endpoint section you need.

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.

Quick Start For Front-End Integration

Authentication

Private endpoints require JWT authorization.

1. Login with POST /account/authorize.
2. Store accessToken and session_token.
3. Send JWT in request headers:

Authorization: Bearer <accessToken>

4. When JWT expires, request a new token with GET /account/authorize/:session_token.

Account Lifecycle (Common Front-End Flow)

1. Signup request: POST /account/signup returns checksum.
2. Signup confirmation: PATCH /account/signup with otp + checksum.
3. Login: POST /account/authorize.
4. Register company profile: POST /account/register.

Pagination

Pagination is available on list endpoints using:

• elements: page size
• page: page index (starts at 0)

Examples:

• /loads?elements=20&page=0
• /loads?page=1
• /loads?elements=100

Filters And Sorting

Many find endpoints support dynamic filters and Mongo-style operators.

Common patterns:

• field[$regex]=text
• field[$options]=i
• date[gte]=2026-01-01
• date[lte]=2026-01-31
• privacy=true
• $sort[createdAt]=-1

Quick Endpoint Map

Public resources:

• Account and auth: /account
• Catalogs: /countries, /cities, /states, /meta-data, /meta-groups, /product-categories
• Public business data: /public-companies, /public-loads, /public-vehicles
• Contact: /contact-email

Private resources:

• Company and members: /companies, /users
• Operations: /loads, /proposals, /vehicles, /branches, /budgets
• Files and alerts: /load-attachments, /notifications
• Company private list: /groups

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 match a regex (supports pagination).

/account

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

The Login and Renew processes return 2 tokens: accessToken (JWT), used for private endpoint authorization, and session_token (renew token), used after JWT expiration to generate a new JWT and session token without sending email and password again.

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 triggers an email with an OTP (one-time password) to verify the email. There is no expiration time, but it is expected that the Front End removes the checksum from local storage after a client-defined timeout.

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 Front End removes the checksum from local storage after a client-defined timeout.

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 triggers an email with an OTP (one-time password) to verify the email. There is no expiration time, but it is expected that the Front End removes the checksum from local storage after a client-defined timeout.

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 Front End removes the checksum from local storage after a client-defined timeout.

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. This endpoint only returns non-private companies (privacy=false or missing).

• 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. This endpoint only returns published, non-private loads (privacy=false or missing).

• 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.
• GET /groups/private: Get the private group for my company.

Recommended header for all private endpoint calls:

Authorization: Bearer <accessToken>

/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, privacy.
  • $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, privacy.
  • $sort[ field ] : -1/1 ; Sort result by field name
  • privacy=true: return only private companies that explicitly granted visibility to my company through groups.
  • privacy=false or unset: return only non-private companies.
• GET /users/:companyId : Get the list of users within a company.
• GET /:id : Get data from specific company.

/groups

• GET /private : Get the private group list from my company. If it does not exist, it will be created.
• PATCH /private/:id : Add a company (company id) to the private group list.
• DELETE /private/:id : Remove a company (company id) from the private group list.

/load-attachments

• POST /loading/:id : Upload/Update a loading attachment.
• POST /downloading/:id : Upload/Update an unloading 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
  • privacy : true to list private loads shared with my company through groups; false or unset to list non-private loads.
  • $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 /driver : Find a list of loads for driver views with the same filter and pagination behavior used in /find. Doesn't take privacy into account (already handled by driver assignation).
• GET /calendar : Find a list of elements with any of the following fields:
  • date[gte] : Date greater 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 itself 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,
  • available_in[$regex],
  • $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 do not require 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