Get entities

Retrieve List of Entities by Type and Subtype

This API is used to retrieve an organized list of entities based on entity_type and entity_subtype. This allows users to access specific subsets of entities efficiently and is beneficial in scenarios where inventory, sales, or logistical data is required for specific types of locations (e.g., retail shops, warehouses, outlets).

The API supports pagination to navigate through large lists of entities.

Paginated Responses

The service is paginated to handle large sets of data efficiently.
For detailed information on how to handle pagination, refer to our Paginated Responses

Languages

The API response includes multilingual descriptions. The fields description_it and description_en provide Entity descriptions in Italian and English, respectively.

Manage languages

For detailed information on how to handle languages, refer to our Managing Languages

Actors

API Client: The system or user initiating the request.

4ws.trade: The backend system that processes the request.

Preconditions

The external system must have the necessary permissions and access to the service, please refer to Authentication.

entity_type and entity_subtype are specified to ensure precise data retrieval.

Type code	Type	Subtype code	Subtype
SHOP	Shop	NEGOZI	General shop
SHOP	Shop	OUTLET	Outlet
SHOP	Shop	CORNER	Corner
WRH	Warehouse	MAGAZZINI	General warehouse
WRH	Warehouse	TRANSITI	Transit warehouse

Main Success Scenario

The external system sends a GET request with entity_type, entity_subtype.

If the request is successful, the system will return an HTTP 200 response with the paginated list of entities and a nextCursor indicating whether there are more entities to retrieve. If nextCursor is setted, the external system must be call again, this service, setting cursor as nextCursor value.

Response Example

Entity type and subtype

Each entity, like shop or warehouse or employee registered in the suite is classified by a type and a subtype that are interdependent, with each subtype dependent on a single type.
The basic configuration is created at the tenant's initialization.

Type code	Type	Subtype code	Subtype
SHOP	Shop	NEGOZI	General shop
SHOP	Shop	OUTLET	Outlet
SHOP	Shop	CORNER	Corner
WRH	Warehouse	MAGAZZINI	General warehouse
WRH	Warehouse	TRANSITI	Transit warehouse

Languages

To understand how languages are managed, please refer to our Managing Languages Documentation.

Alternate Flows

Authentication Error: If the client does not provide valid credentials, an error response is returned.

Error Example

If entity_type or entity_subtype is incorrect or does not exist, the API will return an error.

Error Example: invalid `entity_type`

Error Example: `entity_subtype` not found

Empty Result: If no collections exist, the entities array will be empty.

Cursor & PageSize Used Together: Cursor and PageSize parameters in the request: If you specify a Cursor you cannot specify the page size. This information will already be contained within the cursor.

Error Example

Pagination Error: If invalid cursor parameters are provided, an error response is returned.

Rate Limiting: If the API rate limits are exceeded, the client must respect the retry interval indicated in the response headers Rate Limits.

Sequence Diagram

Best Practices

Please refer to Best Practices for Error Handling in External System for best practices on implementation.

Code Examples in Node.js

Responses

🟢200Success

application/json

Body

Example

{
    "entities": [
        {
            "prog_id": 27975001,
            "entity_code": "",
            "description_it": "Negozio NAPOLI",
            "description_en": "Negozio NAPOLI",
            "description_de": "Negozio NAPOLI",
            "description_es": "Negozio NAPOLI",
            "description_fr": "Negozio NAPOLI",
            "description_pt": "Negozio NAPOLI",
            "description_ru": "Negozio NAPOLI",
            "description_ar": "Negozio NAPOLI",
            "description_ja": "Negozio NAPOLI",
            "description_zh": "Negozio NAPOLI",
            "entity_type": "SHOP",
            "entity_subtype": "NEGOZI",
            "active": true,
            "opening_date": "2022-12-12 00:00:00",
            "closing_date": "2099-12-12 00:00:00",
            "external_code": 123,
            "address1": "Via Giustiniano",
            "address2": "",
            "zip_code": 80126,
            "city": "Napoli",
            "municipality": "",
            "province": "NA",
            "region": "",
            "country": "IT",
            "phone_master": "",
            "mobile_phone": "",
            "email_address": "",
            "web_url": "http://negozio.it",
            "social_whatsapp": "",
            "social_instagram": "",
            "social_facebook": "",
            "social_twitter": ""
        }
    ],
    "nextCursor": "eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTB2"
}

🟠404Entity not found with entity_code

🟠422Invalid pageSize

🟠422Unique constraint error

🟠401Authentication failed

🟠403Operation not allowed

Retrieve List of Entities by Type and Subtype

Languages

Actors

Preconditions

Main Success Scenario

Entity type and subtype

Languages

Alternate Flows

Sequence Diagram

Code Examples in Node.js

Request

Request Code Samples

Responses

Get entities

Retrieve List of Entities by Type and Subtype#

Languages#

Actors#

Preconditions#

Main Success Scenario#

Entity type and subtype#

Languages#

Alternate Flows#

Sequence Diagram#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Retrieve List of Entities by Type and Subtype

Languages

Actors

Preconditions

Main Success Scenario

Entity type and subtype

Languages

Alternate Flows

Sequence Diagram

Code Examples in Node.js