feat: Private Groups + Load-Templates
Private Groups enabled based on the following assumptions: * There is only one private group. * The companies added to the private group is able to find private loads in the directory. * The companies added to the private group is able to find private companies in the directory. * The driver requires a new endpoint to read load resources no matter the privacy rules (as long as they are added to the load as driver). * The private group can be updated by anyone within the company. * The privacy is enabled on the company information by enabling `privacy=true`. * The privacy is enabled on the loads information by enabling `privacy=true`. * When looking for loads/companies by default the search is with `privacy=false` which returns public elements. When `privacy=true`is given, the results are limited to private elements only (not including public elements). Load-Templates enabled based on the following assumptions: * Anyone can CRUD the templates, there is no find feature (for now). It is assumed that the number of templates is limited.
This commit is contained in:
Josepablo Cruz Baas
144
v1/README.md
144
v1/README.md
@@ -7,6 +7,11 @@ ETA Viaporte API
|
||||
- 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:
|
||||
@@ -18,6 +23,71 @@ Example:
|
||||
- `/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:
|
||||
|
||||
```http
|
||||
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`, `/load-templates`, `/proposals`, `/vehicles`, `/branches`, `/budgets`
|
||||
- Files and alerts: `/load-attachments`, `/notifications`
|
||||
- Company private list: `/groups`
|
||||
|
||||
## Public endpoints
|
||||
|
||||
Read registered resources:
|
||||
@@ -39,19 +109,19 @@ All these endpoints support the following parameters (except for those with `pub
|
||||
|
||||
- `/` : List registered resources with pagination.
|
||||
- `/:id` : Read specific resource identified by Id.
|
||||
- `/find?regex=xxx` : List resources that matches with regex (support pagination).
|
||||
- `/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__ 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 __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
|
||||
Login process, returns a JWT and renew token
|
||||
|
||||
Expects a body with the following data:
|
||||
```{.json}
|
||||
@@ -94,7 +164,7 @@ Returns:
|
||||
|
||||
#### 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.
|
||||
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.
|
||||
|
||||
@@ -116,7 +186,7 @@ Returns:
|
||||
#### 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.
|
||||
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.
|
||||
|
||||
@@ -140,7 +210,7 @@ Returns:
|
||||
|
||||
#### 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.
|
||||
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.
|
||||
|
||||
@@ -162,7 +232,7 @@ Returns:
|
||||
#### 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.
|
||||
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:
|
||||
|
||||
@@ -206,6 +276,7 @@ Returns:
|
||||
### 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.
|
||||
@@ -213,6 +284,7 @@ Get public fields from registered companies.
|
||||
### 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.
|
||||
|
||||
@@ -236,7 +308,15 @@ Get public fields from registered vehicles.
|
||||
The following list of endpoints requires a JWT.
|
||||
|
||||
- `GET /loads`: List loads related to my company.
|
||||
- `GET /load-templates/all`: List load templates from 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:
|
||||
|
||||
```http
|
||||
Authorization: Bearer <accessToken>
|
||||
```
|
||||
|
||||
### /public-load-tracking
|
||||
|
||||
@@ -343,21 +423,57 @@ This endpoint is part of /loads endpoint
|
||||
|
||||
- `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 /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
|
||||
- `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 a download 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.
|
||||
|
||||
### /load-templates
|
||||
|
||||
- `POST /new` : Create a new load template for my company.
|
||||
- `GET /all` : Get all load templates from my company.
|
||||
- `GET /:id` : Get a single load template by id.
|
||||
- `PATCH /:id` : Update a load template by id.
|
||||
- `DELETE /:id` : Delete a load template by id.
|
||||
|
||||
Fields accepted for create/update:
|
||||
|
||||
- template_name
|
||||
- alert_list
|
||||
- origin_warehouse
|
||||
- destination_warehouse
|
||||
- origin
|
||||
- origin_geo
|
||||
- destination
|
||||
- destination_geo
|
||||
- categories
|
||||
- product
|
||||
- truck_type
|
||||
- tyre_type
|
||||
- weight
|
||||
- estimated_cost
|
||||
- distance
|
||||
- actual_cost
|
||||
- notes
|
||||
|
||||
### /loads
|
||||
|
||||
- `GET /find` : Find a list of elements with any of the following fields:
|
||||
@@ -381,10 +497,12 @@ This endpoint is part of /loads endpoint
|
||||
- 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 grater than.
|
||||
- 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.
|
||||
@@ -444,7 +562,7 @@ Work In Progress
|
||||
|
||||
__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:
|
||||
- `GET /find` : Find a list of elements (from the company itself only) with any of the following fields:
|
||||
- is_available,
|
||||
- categories,
|
||||
- active_load,
|
||||
@@ -490,7 +608,7 @@ __This endpoint is only valid for carriers.__
|
||||
|
||||
### Public
|
||||
|
||||
The following endpoints doesn't require a JWT authorization
|
||||
The following endpoints do not require JWT authorization.
|
||||
|
||||
#### observers/account/
|
||||
|
||||
|
||||
Reference in New Issue
Block a user