Update entity

This API allows the update of an existing entity, modifying attributes such as descriptions, address, contact information, and social media links. It returns the internal code of the updated entity if the operation is successful.

This API endpoint allows external systems to update the details of an existing entity (e.g., a store or warehouse). This functionality is essential for maintaining up-to-date information about the entity's characteristics, including its location, contact information, and operational status.

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 document creation service, please refer to Authentication.

The entity_code provided must correspond to an existing entity in the system.

Languages

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

This API allows the update of an existing location's data. Locations can be stores or warehouses, and they have various attributes such as type, subtype, address, and other relevant details.

Best practice

Before performing an update on a location's data, it is recommended to retrieve the current data, make the necessary modifications, and then invoke the update operation. This ensures that you are working with the most recent and accurate data.

Retrieve Current Data

Use the GET endpoint Get entities to fetch the current details of the location.
If the GET endpoint does not return any result, use the POST endpoint Insert entity to create a new location.

Modify Data

Make the necessary changes to the retrieved data.

Update Location

Update Location: Use the PUT endpoint update entity to update the location with the modified data.

Main Success Scenario

The external system sends a PATCH request with a JSON body to the endpoint, specifying the entity_code and the fields to be updated.

The API validates the request, ensuring all required fields are correctly formatted and the entity_code matches an existing entity.

Upon successful update, the API returns the internal program ID (prog_id) and the entity_code in a JSON response.

Open, close Date

All Date information within the API is expressed in the GMT time zone.
API users are therefore responsible for converting dates to their desired time zone if needed.
Please refer to Date Handling

Alternate Flows

If any required field is missing or invalid, the API returns an error response specifying the missing or incorrect fields.

If the entity_code does not match an existing entity, an error response is returned indicating the entity was not found.

JSON Sample

{
    "entity_code": 0,
    "description_it": "string",
    "description_en": "string",
    "description_de": "string",
    "description_es": "string",
    "description_fr": "string",
    "description_pt": "string",
    "description_ru": "string",
    "description_ar": "string",
    "description_ja": "string",
    "description_zh": "string",
    "entity_subtype": "CORNER",
    "active": true,
    "opening_date": "2019-08-24",
    "closing_date": "string",
    "external_code": "string",
    "address1": "PIAZZA DEL DUOMO, 65",
    "address2": "Interno 3 scala 1",
    "zip_code": 0,
    "city": "string",
    "municipality": "string",
    "province": "TV",
    "region": "IT",
    "country": "IT",
    "phone_master": "string",
    "mobile_phone": "string",
    "email_address": "email@mail.com",
    "web_url": "http://prova.it",
    "social_whatsapp": "string",
    "social_instagram": "string",
    "social_facebook": "string",
    "social_twitter": "string"
}

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

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

Body Params application/json

Example

{
    "entity_code": 0,
    "description_it": "string",
    "description_en": "string",
    "description_de": "string",
    "description_es": "string",
    "description_fr": "string",
    "description_pt": "string",
    "description_ru": "string",
    "description_ar": "string",
    "description_ja": "string",
    "description_zh": "string",
    "entity_subtype": "CORNER",
    "active": true,
    "opening_date": "2019-08-24",
    "closing_date": "string",
    "external_code": "string",
    "address1": "PIAZZA DEL DUOMO, 65",
    "address2": "Interno 3 scala 1",
    "zip_code": 0,
    "city": "string",
    "municipality": "string",
    "province": "TV",
    "region": "IT",
    "country": "IT",
    "phone_master": "string",
    "mobile_phone": "string",
    "email_address": "email@mail.com",
    "web_url": "http://prova.it",
    "social_whatsapp": "string",
    "social_instagram": "string",
    "social_facebook": "string",
    "social_twitter": "string"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Update entity

Update Entity#

Actors#

Preconditions#

Languages#

Main Success Scenario#

Alternate Flows#

JSON Sample#

Sequence Diagram#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Update Entity

Actors

Preconditions

Languages

Main Success Scenario

Alternate Flows

JSON Sample

Sequence Diagram

Code Examples in Node.js