Insert entity

Create New Entity

This API allows the creation of a new entity, including essential details like type, description, address, contact information, and social media links. The response provides the internal code for the created entity if successful.

This API endpoint enables external systems to add a new entity (such as a store or warehouse) to the platform by specifying its unique details, location, contact information, and status. This function is vital for inventory management, point-of-sale setup, and logistical operations.

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 be unique and not already associated with an existing entity.

Main Success Scenario

The external system sends a POST request with a JSON body to the endpoint, including all necessary details of the new entity.

The API validates the request, ensuring all required fields are included and the entity_code is unique.

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

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 already exists, an error response is returned indicating a conflict.

Entity type and subtype

Each location is identified by a unique entity_type and entity_subtype a type is SHOP or WRH and subtype is CORNER or TRANSITI.

Type: the general category of the location, either "STORE" or "WAREHOUSE".

Store: A standard store directly operated by the company.

Outlet: A store offering products at discounted prices.

Corner: A smaller store, often located within a larger retail space.

Subtype: a more specific classification within the type, detailing the exact nature of the location.

Warehouse: A standard warehouse for storage.

Transit Warehouse: A warehouse used for temporary storage and goods transfer.

Type code	Type	Subtype code	Subtype
`SHOP`	Store	`CORNER`	Corner
`SHOP`	Store	`NEGOZI`	Store
`SHOP`	Store	`OUTLET`	Outlet
`WRH`	Warehouse	`MAGAZZINI`	Warehouse
`WRH`	Warehouse	`TRANSITI`	Transit warehouse

Store

A retail outlet that sells products directly to the public. Stores can operate in two ways:

Using the Mobile Shop app to issue receipts for in-person sales.

Using the Manager application to collect and fulfill e-commerce orders, issuing invoices.

Warehouse

A storage facility used for the collection, storage, and distribution of goods. Warehouses are generally not open to the public and are focused on inventory management and logistics.

Sample

Example Request Body (Outlet Store with Manager app)

{
  "entity_code": "ST124",
  "entity_type": "STORE",
  "entity_subtype": "OUTLET",
  "description_it": "Downtown Outlet",
  "address1": "456 Market St",
  "city": "Othertown",
  "zip_code": "67890",
  "country": "USA"
}

Example Request Body (Corner Store)

{
  "entity_code": "ST124",
  "entity_type": "STORE",
  "entity_subtype": "CORNER",
  "description_it": "Downtown Outlet",
  "address1": "456 Market St",
  "city": "Othertown",
  "zip_code": "67890",
  "country": "USA"
}

Example Request Body (Simple Warehouse)

{
  "entity_code": "ST125",
  "entity_type": "WRH",
  "entity_subtype": "MAGAZZINI",
  "description_it": "Mall Corner Store",
  "address1": "789 Shopping Mall",
  "city": "Malltown",
  "zip_code": "54321",
  "country": "USA"
}

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

Body Params application/json

Example

{
    "entity": {
        "entity_code": "383838",
        "description_it": "DA API - NON USARE 2",
        "description_en": "Inserting from API 2",
        "active": true,
        "opening_date": "2024-09-25T00:00:00.000Z",
        "closing_date": "2024-10-26T00:00:00.000Z",
        "external_code": "0",
        "address1": "PIAZZA DEL DUOMO, 6500",
        "address2": "Interno 3 scala 1000",
        "zip_code": 0,
        "city": "string",
        "municipality": "string",
        "province": "TV",
        "region": "IT",
        "state": null,
        "phone_master": "string",
        "mobile_phone": "string",
        "email_address": "email@lllllllll.com",
        "web_url": "http://prova.it",
        "social_whatsapp": "www.provaprovetta.comm",
        "social_instagram": "www.provaprovetta.comm",
        "social_facebook": "www.provaprovetta.comm",
        "social_twitter": "www.provaprovetta.comm",
        "entity_subtype": "CORNER",
        "entity_type": "SHOP",
        "country": "IT"
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Create New Entity#

Actors#

Preconditions#

Main Success Scenario#

Alternate Flows#

Entity type and subtype#

Store#

Warehouse#

Sample#

Example Request Body (Outlet Store with Manager app)#

Example Request Body (Corner Store)#

Example Request Body (Simple Warehouse)#

Sequence Diagram#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Create New Entity

Actors

Preconditions

Main Success Scenario

Alternate Flows

Entity type and subtype

Store

Warehouse

Sample

Example Request Body (Outlet Store with Manager app)

Example Request Body (Corner Store)

Example Request Body (Simple Warehouse)

Sequence Diagram

Code Examples in Node.js