Get entity

Retrieve Specific Entity Details

This API retrieves detailed information about a specific entity, identified by the {ENTITY_CODE} path parameter. The response includes detailed entity data such as description, contact information, address, social media links, and operational status, all paginated if necessary.

The purpose of this API is to retrieve information about a specific entity based on its unique code (ENTITY_CODE). This allows external systems to access complete and organized data for a specified entity, which is essential for inventory management, logistical support, or point-of-sale systems.

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 nd returns entity data matching the specified ENTITY_CODE..

Preconditions

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

The entity specified by ENTITY_CODE exists in the system.

Main Success Scenario

The external system sends a GET request to the endpoint, providing the ENTITY_CODE in the URL path.

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

Alternate Flows

If the specified ENTITY_CODE does not exist, the API returns an error.

If the page requested is out of range, the API provides an error response.

JSON Sample

{
    "entity": {
        "prog_id": 2490,
        "entity_code": "9871",
        "description_it": "API TEST turquoise",
        "description_en": "API TEST Hatchback EN",
        "description_de": "API TEST turquoise",
        "description_es": "API TEST turquoise",
        "description_fr": "API TEST turquoise",
        "description_pt": "API TEST turquoise",
        "description_ru": "API TEST turquoise",
        "description_ar": "API TEST turquoise",
        "description_ja": "API TEST turquoise",
        "description_zh": "API TEST turquoise",
        "active": false,
        "opening_date": "2024-10-10",
        "closing_date": "2024-10-20",
        "external_code": "state ",
        "address1": "071 Adonis Row",
        "address2": "Adress Southwest 2",
        "zip_code": 19909,
        "city": "Union City",
        "municipality": null,
        "province": null,
        "region": null,
        "state": null,
        "phone_master": "207.319.4732 x996",
        "mobile_phone": "1-636-657-2948",
        "email_address": "email@mail.com",
        "web_url": "http://prova.it",
        "social_whatsapp": "http://plump-sash.biz",
        "social_instagram": "http://silver-stylus.info",
        "social_facebook": "http://colossal-metal.info",
        "social_twitter": "http://sleepy-visitor.name",
        "entity_subtype": "CORNER",
        "entity_type": "SHOP",
        "country": "UY"
    }
}

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

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

🟠404Entity not found with entity_code

🟠422Invalid pageSize

🟠422Unique constraint error

🟠401Authentication failed

🟠403Operation not allowed

Retrieve Specific Entity Details

Languages

Actors

Preconditions

Main Success Scenario

Alternate Flows

JSON Sample

Sequence Diagram

Code Examples in Node.js

Request

Request Code Samples

Responses

Get entity

Retrieve Specific Entity Details#

Languages#

Actors#

Preconditions#

Main Success Scenario#

Alternate Flows#

JSON Sample#

Sequence Diagram#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Retrieve Specific Entity Details

Languages

Actors

Preconditions

Main Success Scenario

Alternate Flows

JSON Sample

Sequence Diagram

Code Examples in Node.js