Add and manage facilities

This resource describes facilities of a customer, e.g. stores, micro hubs, warehouses, etc.. In general, a facility is a place where fulfillment processes take place or should be considered.

This page is outdated. Please go to our new documentation under https://docs.fulfillmenttools.com/documentation.

Example of different facilities

The facilities in fulfillmenttools platform have some basic data to them: an address, provided services, etc.. They are also an important component to the Distributing Order Management System: an Order, which is supplied to the system, is routed to a facility based on configurations and data present at the time of the routing.

In a facility operative processes like Picking, Packing, Handovers, etc. are taking place to fulfill the consumers' order.

Creating a minimal facility

To create a facility there is very little data required. Please see the following call which contains only the required fields.

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/facilities' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Darkstore Number 3 in Cologne",
    "address": {
        "companyName": "OC fulfillment GmbH",
        "country": "DE",
        "postalCode": "51063",
        "city": "Köln",
        "street": "Schanzenstr.",
        "houseNumber": "30"
    }
}'


Response:
201 Created.

{
    "name": "Darkstore Number 3 in Cologne",
    "address": {
        "companyName": "OC fulfillment GmbH",
        "country": "DE",
        "postalCode": "51063",
        "city": "Köln",
        "street": "Schanzenstr.",
        "houseNumber": "30"
    },
    "fulfillmentProcessBuffer": 240,
    "locationType": "STORE",
    "capacityEnabled": false,
    "status": "ONLINE",
    "created": "2023-02-22T10:53:44.101Z",
    "lastModified": "2023-02-22T10:53:44.101Z",
    "version": 1,
    "id": "0d556132-a115-4250-8576-5582899ba115"
}

To understand which kind of optional parameters can be used when creating a facility please see the REST API documentation of facilities.

The API offers a delete endpoint for facilities. Handle with care: Issuing a request similar to

DELETE /api/facilities/<Facility ID>

will delete all data related to the facility (such as listings and configurations)!

Reviewing standard- & adding new configurations

Right after the creation of a minimal Facility a couple of configurations are added by default. Please refer to the REST API documentation to get information about their respective meaning.

This section only covers attributes & configurations worth mentioning. Please refer to REST API documentation to get a full overview of the attributes and their meaning.

In most cases it makes sense to provide additional information to the facility. We suggest you add the following information to the facility - either when creating or issuing an update request (see below).

Setting a tenantFacilityId

The attribute tenantFacilityId might come in handy and we suggest you use it. It is the reference of this facility in potentially existing customer systems - for example the primary key of the according database row in some legacy system.

It also aids in finding a facility by an ID / reference known to connectors, etc..

In order to set the tenantFacilityId the following call has to be issued:

curl -sSL -X PATCH 'https://your.api.fulfillmenttools.com/api/facilities/0d556132-a115-4250-8576-5582899ba115' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "version": 2,
    "actions": [
        {
            "action": "ModifyFacility",
            "tenantFacilityId":"23065"
        }
    ]
}'

The tenantFacilityId could, as explained above, for example be used to query via the /api/facilities endpoint like this:

curl -sSL 'https://your.api.fulfillmenttools.com/api/facilities?tenantFacilityId=23065' \
--header 'Authorization: Bearer <TOKEN>'

Response:
200 OK

{
    "facilities": [
        {
            "id": "0d556132-a115-4250-8576-5582899ba115",
            "name": "Darkstore Number 3 in Cologne",
            "version": 5,
            "tenantFacilityId": "23065",
            "status": "ONLINE",
            "created": "2023-02-22T10:53:44.101Z",
            "lastModified": "2023-02-22T14:12:09.993Z",
            "city": "Köln",
            "country": "DE",
            "houseNumber": "30",
            "street": "Schanzenstr.",
            "postalCode": "51063"
        }
    ],
    "total": 1
}

Adding information about operational times

Attribute	Why should I add this?	Example Value
closingDays	To give information about holidays or "non operational times" in general, like public holiday or peak days where this facility should not be part of operational business.	[
{

"date":"2023-01-01T12:00:00.000Z",
"reason":"Happy new year",
"recurrence":"YEARLY"

}, { "date":"2023-03-10T12:00:00.000Z", "reason":"Renovation", "recurrence":"NONRECURRING" } ] | | pickingTimes |

Adding capacities & picking times per facility allows you to narrow down the operational effort you are willing to invest within a facility. The capacity in this case is the pure number of pickjobs this facility can handle - regardless of their size.

If not provided the platform will assume, that you are willing to fulfill any order at any time (which works in many cases as well!) in this facility.

|

{
"friday":[
{
"start":{
"hour":7,
"minute":0
},
"end":{
"hour":16,
"minute":0
},
"capacity":9
}
]
}

|

Changes to an existing facility is generally applied via a PATCH operation. The above values would be issued as follows:

curl -sSL -X PATCH 'https://your.api.fulfillmenttools.com/api/facilities/0d556132-a115-4250-8576-5582899ba115' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "version": 3,
    "actions": [
        {
            "action": "ModifyFacility",
            "closingDays":[
              {
                "date":"2023-01-01T12:00:00.000Z",
                "reason":"Happy new year",
                "recurrence":"YEARLY"
              },
              {
                "date":"2023-03-10T12:00:00.000Z",
                "reason":"Renovation",
                "recurrence":"NONRECURRING"
              }
            ],
            "pickingTimes": {
                "friday": [{
                    "start": {
                        "hour": 7,
                        "minute": 0
                    },
                    "end": {
                        "hour": 16,
                        "minute": 0
                    },
                    "capacity":9
                }]
            }  
        }
    ]
}'

Handling geo-coordinated manually

When a user adds a facility using a POST request, they have the option to specify longitude and latitude coordinates. If provided, these user-defined coordinates persist and are not altered by the system, even in the event of subsequent updates to the facility.

Facilities added through the frontend fulfillment tools undergo coordinate resolution using external services such as Google Maps. However, users have the ability to manually overwrite these backend-generated coordinates, if desired. Once manually overwritten you cannot fall back to the google maps coordinates.

Users also have the option to delete coordinates associated with a facility. In such cases, the backend resolver generates new coordinates to ensure compliance with system requirements.