SAP BNAC Fulfillment Service
Warning
SAP BNAC Fulfillment Service is currently in experimental state and should only be used for prototypes / experimentation.
Known limitations
- SAP BNAC expects one
DocumentVersionper document. It accepts a document with several, for example one per language, but your customer then sees only the one listed first in the Handover Documentation, with its title, language and file. See Document languages. This is not about the versions SAP BNAC adds when a line item is delivered again: your customer gets each of those, see Documents. - SAP BNAC import limits apply. SAP BNAC accepts packages smaller than 400 MB only.
twinsphere Cloud offers first-class integration with SAP Business Network Asset Collaboration (SAP BNAC), so that your customers receive the digital twins of the devices they ordered from you directly in SAP BNAC, built from the asset administration shells you already maintain in twinsphere.
In SAP BNAC, a customer who has ordered devices from you asks for their digital data by sending you an equipment request. The request lists one line item per device, identified by the device's ID Link when your customer enters one, and by the purchase order and the line within it.
The SAP BNAC Fulfillment Service answers these requests from your twinsphere tenant. twinsphere picks up the equipment requests your customers send you, finds the shell for each line item, delivers it to SAP BNAC as equipment, shares that equipment with the customer and assigns it to the line item. Once every line item is answered, the request is handed back to your customer for review. You keep your device data in twinsphere, and you do not have to enter anything in SAP BNAC by hand.
The following terms are used throughout this page:
| Term | Meaning |
|---|---|
| Equipment request | A customer's request in SAP BNAC for the data of the devices it ordered from you |
| Line item | One requested device within an equipment request |
| ID Link | The device's identifier according to IEC 61406, the URL behind the QR code on its nameplate |
| Equipment | The SAP BNAC record of a device, created from the shell and submodels twinsphere delivers |
| Partner | A customer you accept equipment requests from. You name it by your own Fulfillment Partner Id; SAP BNAC identifies it by its business partner id |
| Authorization group | The SAP BNAC group equipment is shared into, so that only the partner of that group can see it |
| Fulfillment | twinsphere's record of one equipment request: its state, its line items and what was delivered for each |
Refer to the Sphere Server Swagger documentation (available on your tenant at /sphere/swagger/index.html) for
detailed information on each parameter and return value.
Prerequisites
- An SAP BNAC subscription with API access. SAP BNAC runs as an instance in a subaccount of your SAP Business Technology Platform (SAP BTP) account. Create a service key on that instance; it holds the connection details and credentials twinsphere needs (see Configuration).
- An authorization group for each partner. Equipment is shared into the partner's authorization group, so the group has to exist in SAP BNAC before anything can be delivered to that partner.
- SAP BNAC Fulfillment Service activated for your tenant. Contact us to have it activated.
- One of the following roles on the tenant:
| Role | Access |
|---|---|
tenant-bnac-fulfillment-viewer |
Read the configuration, the fulfillments and the jobs |
tenant-bnac-fulfillment-operator |
Everything the viewer can, plus changing the configuration and starting syncs, deliveries and finalizations |
tenant-administrator, tenant-global-writer and the organization owner have operator access as well;
tenant-global-reader has viewer access. See Roles for how roles are assigned.
Configuration
A tenant has exactly one BNAC configuration. It specifies how twinsphere reaches SAP BNAC, your identity in BNAC, how equipment requests are processed, and which partners you accept equipment requests from.
Configure in the Manage UI
In the Manage UI, open the tenant and go to Settings → SAP BNAC. The page takes you through the configuration in three steps: Configuration, Credentials and Validate connection, the validation of what you stored. Users with viewer access see the settings read-only.
The fields are the same as in the API, described below.
Configure with the API
| Operation | Method | Endpoint | Description |
|---|---|---|---|
| Get configuration | GET |
/sphere/api/v1/bnac/configuration |
Returns the configuration, with the client secret masked |
| Set configuration | PUT |
/sphere/api/v1/bnac/configuration |
Creates or replaces the configuration, except the credentials |
| Set credentials | PUT |
/sphere/api/v1/bnac/configuration/credentials |
Sets or rotates the credentials |
| Validate configuration | POST |
/sphere/api/v1/bnac/configuration/validate |
Checks the stored configuration and credentials against SAP BNAC |
Set the configuration
PUT https://{twinsphereTenantURL}/sphere/api/v1/bnac/configuration
Example Request
PUT /sphere/api/v1/bnac/configuration
Authorization: Bearer {token}
Content-Type: application/json
{
"bnacApiBaseUrl": "...",
"myBnacBusinessPartnerId": "{your-business-partner-id}",
"processing": "automatic",
"autoFinalize": false,
"partners": [
{
"id": "musterchemie",
"bnacBusinessPartnerId": "{partner-business-partner-id}",
"authorizationGroupId": "{partner-authorization-group-id}",
"documentLanguages": ["de"]
}
]
}
| Field | Required | Description | Hint |
|---|---|---|---|
bnacApiBaseUrl |
yes | Base URL of the SAP BNAC API | In the SAP BTP cockpit, open your subaccount → Services → Instances and Subscriptions → Instances, and view the service key of your SAP BNAC instance (the link in the Credentials column). Take the value of endpoints.ain.url |
myBnacBusinessPartnerId |
yes | Your own business partner id in SAP BNAC | In SAP BNAC, open the Company Profile app → External IDs and take the Object ID. It is a 32-character hexadecimal id |
processing |
no | automatic or manual, see Processing modes. Defaults to automatic |
|
autoFinalize |
no | Marks the equipment request as "done" from your side, as soon as every line item is answered. Must be false with manual processing. Defaults to false |
|
partners[].id |
yes | Your Fulfillment Partner Id for the partner, shown on its fulfillments and named by the shells meant for it. 3 to 128 lowercase letters, digits and single hyphens between them, unique across partners | Your own choice, for example musterchemie |
partners[].bnacBusinessPartnerId |
yes | The partner's business partner id in SAP BNAC. Equipment requests are attributed to a partner by it, so it must be unique across partners | The partner's own id from its Company Profile app, so ask the partner for it. Or configure the other fields first: a request from a partner that is not configured yet appears as a partner-not-configured fulfillment |
partners[].authorizationGroupId |
yes | The authorization group equipment for this partner is shared into | In SAP BNAC, open the Network Authorizations app → Groups and select the group; the id is part of the page URL |
partners[].documentLanguages |
no | The languages of the handover documentation the partner receives, as 2- or 3-letter ISO 639 codes such as de or eng; region tags such as en-US are refused. Omitted or empty: all languages. See Document languages |
Agree on it with the partner |
Note
autoFinalize is off by default on purpose. Marking an equipment request as "done" cannot be undone
from your side; only the customer can send it back to you. Review a few requests before you switch it on.
An equipment request from a business partner that is not in partners is recorded, but nothing is
delivered for it. Add the partner to the configuration, and the request is processed with the next sync.
Fulfillment Partner Id
A partner has two ids. The id is your Fulfillment Partner Id: you choose it, and your shells name the partner
they are meant for by it (see Matching shells). The bnacBusinessPartnerId is the partner's
id in SAP BNAC, by which an equipment request is attributed to the partner.
Your shells carry the Fulfillment Partner Id, so treat it as permanent:
- Renaming it leaves the shells that name the old id unmatched.
- Never give an id to another
bnacBusinessPartnerId: the shells meant for the first partner would answer the requests of the other one.
Set the credentials
PUT https://{twinsphereTenantURL}/sphere/api/v1/bnac/configuration/credentials
twinsphere signs in to SAP BNAC with the OAuth client credentials of a BNAC service key.
All values are in the service key of your SAP BNAC instance. In the SAP BTP cockpit, open your subaccount → Services → Instances and Subscriptions → Instances, and view the key through the link in the Credentials column. If the instance has no key yet, select it and create one under Service Keys.
Example Request
PUT /sphere/api/v1/bnac/configuration/credentials
Authorization: Bearer {token}
Content-Type: application/json
{
"authenticationBaseUrl": "https://...",
"clientId": "{client-id}",
"clientSecret": "{client-secret}"
}
| Field | Description | Hint |
|---|---|---|
authenticationBaseUrl |
Base URL of the OAuth server of your SAP BTP subaccount | uaa.url in the service key |
clientId |
OAuth client id | uaa.clientid in the service key |
clientSecret |
OAuth client secret | uaa.clientsecret in the service key |
The client secret is stored encrypted and is never returned. Getting the configuration shows its first 6 characters followed by a mask, or only the mask for a secret shorter than 12 characters.
Validate the configuration
POST https://{twinsphereTenantURL}/sphere/api/v1/bnac/configuration/validate
Checks the stored configuration and credentials against SAP BNAC. It needs operator access, and it only reads in SAP BNAC, changing nothing there.
In the response, the validation steps always come in this order, the last two once per partner:
| Step | Checks |
|---|---|
credentials |
SAP BNAC's OAuth server issues a token for authenticationBaseUrl, clientId and clientSecret |
api-access |
The SAP BNAC API responds at bnacApiBaseUrl with that token |
business-partner |
myBnacBusinessPartnerId is a business partner in SAP BNAC |
partner-business-partner |
The partner's bnacBusinessPartnerId is a business partner in SAP BNAC |
partner-authorization-group |
The partner's authorizationGroupId is an authorization group in your SAP BNAC |
A step is passed, failed or skipped.
How a request is processed
Once an hour, and whenever you start a sync yourself, twinsphere asks SAP BNAC for the equipment requests that are waiting for you. A request it sees for the first time is stored as a fulfillment. Every fulfillment that is not finished yet is then synced: twinsphere reads the request and its line items from SAP BNAC again and brings the fulfillment in line with them.
In automatic processing, the sync then takes the request as far as it can:
it finds a shell for each line item, delivers it, and, with autoFinalize, finalizes the request once every
line item is answered.
In manual processing, the sync stops after reading, and you trigger each of these steps yourself.
Delivering a line item takes the following steps in SAP BNAC:
- The shell and the submodels SAP BNAC imports are uploaded to BNAC as equipment, see Data requirements.
- The equipment is published and shared into the partner's authorization group.
- The equipment is assigned to the line item.
Finalizing a request (the Recommend action in the SAP BNAC UI) hands it back to your customer for review. Your customer then either confirms the result, or sends the request back to you. A request that comes back is picked up by the next sync and processed again like any other.
Equipment request status (BNAC side)
The requestStatusCode of a fulfillment is the status of the equipment request in SAP BNAC, as of
lastSyncedAt. Deliveries and finalizations change the status in SAP BNAC; the fulfillment shows the new
status after the next sync.
| BNAC Code | Status | What it means for you |
|---|---|---|
1 |
Draft | Your customer is still editing the request. It is not picked up yet. |
2 |
Author Action | The request is back with your customer. Nothing can be delivered until it is submitted again. |
3 |
Rejected | The request was rejected. The fulfillment is closed. |
4 |
Completed | The request was finalized and waits for your customer's review. |
5 |
In Process | The request is being answered. The first equipment twinsphere assigns moves a submitted request to in process. |
6 |
Submitted | Your customer has sent the request to you, and nothing has been answered yet. This is the state before "in process". |
7 |
Confirmed | Your customer has confirmed the result. The request has ended. |
9 |
Deleted | The request was deleted. The fulfillment is closed. |
Only requests in 5 In Process or 6 Submitted are processed. A request that returns to one of them, for
example because your customer sent it back, is processed again.
Fulfillment states (twinsphere side)
| State | Meaning |
|---|---|
open |
No line item carries equipment yet |
partially-fulfilled |
Some line items carry equipment |
fulfilled |
Every line item carries equipment |
partner-not-configured |
The request comes from a business partner that is not in your configuration. Nothing is delivered until you add the partner |
finalized |
The request was finalized and handed back to your customer |
closed |
The request ended without being finalized by twinsphere, for example because it was rejected, deleted, or completed in SAP BNAC directly |
The first three states follow from the line items and change whenever a line item does, including when
SAP BNAC reports line items that were added or removed. A finalized or closed fulfillment becomes
open, partially-fulfilled or fulfilled again when its request returns to In Process or Submitted.
The lastError of a fulfillment tells why the last sync or finalization of the request as a whole did not
succeed. It is absent once a later attempt succeeds.
Line item states
| State | Meaning |
|---|---|
unmatched |
No shell answers the line item yet |
matched |
A shell answers the line item, but it has not been delivered yet |
equipment-shared |
The equipment was created and shared, but not yet assigned to the line item |
equipment-assigned |
The equipment is assigned to the line item |
matchSource says how the shell was chosen:
| Value | Meaning |
|---|---|
automatic |
Found by its ID Link or its shell extensions, see Matching shells |
manual |
Pinned through the mapping endpoint |
external |
The line item already carried equipment in SAP BNAC that twinsphere did not deliver |
matchedOn says what an automatic match rested on:
| Value | The shell |
|---|---|
id-link |
has the line item's ID Link as its globalAssetId |
purchase-order-and-operator-equipment-id |
names the purchase order, the line and the line item's operator equipment id |
purchase-order |
names the purchase order and the line, and no operator equipment id |
matchedOn is set for automatic matches only.
twinsphere never overwrites equipment it did not deliver. An external line item is shown as
equipment-assigned and cannot be mapped or delivered. It returns to unmatched once the equipment is
removed from the line item in SAP BNAC.
Every sync compares the line items with what SAP BNAC reports for them. The lastError of a line item tells
why its last delivery did not succeed, or which difference the sync found, for example:
- Your customer rejected the equipment. The line item stays
equipment-assignedand keeps the error. Correct the data and deliver the line item again, or pin another shell. - The equipment was removed from the line item in SAP BNAC. The line item returns to
matched. In automatic processing, the same sync delivers it again; in manual processing, deliver it yourself. - SAP BNAC reports equipment other than the one twinsphere assigned. The line item keeps the error, so that you can check the line item in SAP BNAC.
The warnings of a line item list what your customer receives differently from what the shell holds, see
Warnings.
A line item that SAP BNAC no longer reports is removed from the fulfillment.
Processing modes
The processing field of the configuration decides whether twinsphere answers
equipment requests on its own, or only when you ask it to.
Automatic processing
With processing set to automatic, every sync matches, delivers and, with autoFinalize, finalizes on
its own. Give your shells the ID Link of their device, or mark them with the extensions below, and requests are
answered without any further action.
Line items that cannot be answered stay open, and the sync tries again the next time. A line item whose
delivery failed carries the reason in its lastError and is delivered again by the next sync.
With autoFinalize set to true, a sync finalizes a request once it is fulfilled and no line item carries
an error. A request whose customer rejected one of the equipment is therefore not finalized again until
that line item is corrected.
Matching shells
A sync finds the shell for a line item by the line item's ID Link, or by the extensions on the shell.
ID Link. Your customer can enter the device's ID Link on a line item in SAP BNAC, or scan it from the QR
code on the nameplate. A shell whose assetInformation.globalAssetId is that ID Link answers the line item,
without any of the extensions below. The two are compared exactly, including case, trailing slashes and
percent-encoding. SAP BNAC takes the globalAssetId of a delivered shell as the ID Link of the equipment, so
your customer finds the equipment under the ID Link they entered.
Extensions. Add them to the shell itself, not to one of its submodels:
| Extension name | Required | Value |
|---|---|---|
twinsphere.io/bnac/purchase-order |
yes | The purchase order number of the line item |
twinsphere.io/bnac/purchase-order-line-item |
yes | The line within the purchase order |
twinsphere.io/bnac/operator-equipment-id |
no | Your customer's own identifier for the device, when the line item names one |
twinsphere.io/bnac/partner-id |
once you have more than one partner | The Fulfillment Partner Id of the partner the shell is meant for. With more than one partner, also required on a shell matched by its ID Link |
{
"id": "https://example.com/shells/pump-4711",
"extensions": [
{ "name": "twinsphere.io/bnac/purchase-order", "valueType": "xs:string", "value": "4500012345" },
{ "name": "twinsphere.io/bnac/purchase-order-line-item", "valueType": "xs:string", "value": "00010" },
{ "name": "twinsphere.io/bnac/operator-equipment-id", "valueType": "xs:string", "value": "P-101" },
{ "name": "twinsphere.io/bnac/partner-id", "valueType": "xs:string", "value": "musterchemie" }
],
"assetInformation": { "assetKind": "Instance", "globalAssetId": "https://id.example.com/0815/4711" }
}
A blank extension value counts as no extension. Each shell answers at most one line item of a request. For every line item:
- ID Link: a shell whose
globalAssetIdis the line item's ID Link answers it, even when its extensions name another purchase order or operator equipment id: the ID Link identifies the device itself. - Purchase order: otherwise, a shell answers when both the purchase order and the line match exactly. They
are compared as text, so
00010and10are different lines. Use the values exactly as your customer entered them in SAP BNAC. A shell that names an operator equipment id the line item does not name is meant for another device and is never used for it; one that names the line item's operator equipment id is preferred over one that names none. This step also answers a line item whose ID Link no shell carries, or whose ID Link's shell already answers another line item.
In both steps, a shell that names another partner is never used, and a shell that names no partner is used only
while you have a single partner. When the partner rule is all that keeps shells from a line item, its lastError says
so. When several shells are equally suitable, the one with more twinsphere.io/bnac/ extensions is used; the
choice is always the same for the same shells.
Only its ID Link can match a line item that lacks the purchase order or the line.
Matching only fills line items that have no shell yet. Changing the extensions of a shell later does not change a line item it already answers. To have such a line item matched again, release its shell, or pin another one.
Manual processing
With processing set to manual, the syncs still pick up new requests once an hour and keep every
fulfillment in line with SAP BNAC, but they never change anything in SAP BNAC. Shells are not matched
automatically, neither by their ID Link nor by their extensions. Each step is an operation you call yourself, so
you see its outcome and its errors directly. autoFinalize must be false in this mode.
A typical client does the following:
- Find open work:
GET /sphere/api/v1/bnac/fulfillments?state=open&state=partially-fulfilled. A fulfillment that has just been discovered has no line items yet; they appear with its first sync, shortly after. - Prepare the data: create the shell and its submodels, see Data requirements. The
shell needs no BNAC extensions, but one that names another partner with
twinsphere.io/bnac/partner-idcannot be pinned. - Pin the shell to the line item, see Pin a shell.
- Deliver the line item, see Deliver a line item, and follow the job until it has
succeededorfailed. - Finalize the request, see Finalize a request, once every line item is answered.
Data requirements
SAP BNAC creates the equipment from the AAS package twinsphere delivers. The package contains the shell and
those of its submodels SAP BNAC imports; every other submodel is left out, and so are the shell's references
to it. A package SAP BNAC does not accept fails the delivery with SAP BNAC's reason in lastError.
| Submodel | Delivered version |
|---|---|
| Digital Nameplate | V3.0 (SemanticId https://admin-shell.io/idta/nameplate/3/0/Nameplate), otherwise V2.0. Required: SAP BNAC creates the equipment from it |
| Handover Documentation | V2.0 (SemanticId 0173-1#01-AHF578#003), otherwise V1.2 (SemanticId 0173-1#01-AHF578#001). SAP BNAC accepts only one Document in V1.2, so prefer V2.0 |
| Technical Data | V2.0 |
Only the highest version of each submodel is delivered, and only one submodel of each, so a shell with two of the delivered version is refused with an error on the line item, and so is a shell without a nameplate. Other submodels, for example a Carbon Footprint, are left out, because SAP BNAC would ignore them.
SAP BNAC identifies equipment by the serial number of the device. Delivering a shell again therefore updates the existing equipment instead of creating a second one.
Documents
Your customer receives the documents of the Handover Documentation with the equipment, together with their files. Delivering a line item again adds a new SAP BNAC version of each document, and your customer gets every one of these versions, listed with its version number. The document SAP BNAC creates for the imported package itself is not shared.
Document languages
With documentLanguages set, a partner receives only the handover documentation in its languages. The filter
works on the DocumentVersions of the Handover Documentation:
- A
DocumentVersionis delivered, together with its files, when one of its languages matches a configured code exactly, ignoring case. ADocumentVersionin several languages is delivered whole. - A
DocumentVersionthat names no language is always delivered. - A document left without
DocumentVersions is left out.
Write the codes as they appear in the documentation: en does not match eng. Handover Documentation V1.2
allows three-letter codes, so list both when your data mixes them.
SAP BNAC expects one DocumentVersion per document. Of several that one delivery holds for a document, your
customer sees only the one listed first in the Handover Documentation, with its title, language and file, and
never the others. Without documentLanguages, your customer therefore sees
whichever language comes first in your data, and of several revisions in the same language the first one. One
language per partner gives a predictable result whenever your documentation has one DocumentVersion per
language. The versions SAP BNAC adds when a line item is delivered again are not affected, see
Documents.
Warnings
What SAP BNAC would reject the whole package for is refused before the upload, with a lastError on the line
item that names every element to fix:
- a File without a value, or one whose attachment no longer exists,
- a Blob in any delivered submodel,
- an attached file whose name has a space, the shell's thumbnail included.
Everything else SAP BNAC takes, even where your customer then receives less than the shell holds. The delivery goes ahead, and the line item gets a warning for each kind of problem, listing every file or document it concerns:
| Code | When | What your customer receives |
|---|---|---|
file-without-extension |
A file without a file extension, such as Manual01 |
No file, and none of the equipment's documents |
file-not-in-package |
A file the package only references: an http(s) URL, any other value that is no attachment in twinsphere, or an attachment without a content type | The document without its content |
file-name-not-supported |
A file name with characters such as umlauts | The document without its file |
several-document-versions |
A document with more than one DocumentVersion in the delivered Handover Documentation, see Document languages |
Only the first DocumentVersion |
sap-import-warning |
A finding SAP BNAC reports on the import, such as a shell without a display name | Depends on the finding |
Warnings describe the latest delivery of the line item. The next delivery replaces them, and they are removed
when the line item gives up its equipment. Unlike lastError, they never hold back autoFinalize. They are in
every line item (warnings: [{ "code": …, "message": … }]) and in the result of the deliver-item job.
Endpoints
Operations marked async answer 202 Accepted right away and run as a job in the background; all
others answer directly with their result. The complete OpenAPI specification of these endpoints is available in
the Sphere Server Swagger documentation on your tenant, at /sphere/swagger/index.html.
| Operation | Method | Endpoint | Execution | Description |
|---|---|---|---|---|
| List fulfillments | GET |
/sphere/api/v1/bnac/fulfillments |
sync | Lists the fulfillments, newest first |
| Get fulfillment | GET |
/sphere/api/v1/bnac/fulfillments/{fulfillmentId} |
sync | Returns one fulfillment with its line items |
| List line items | GET |
/sphere/api/v1/bnac/fulfillments/{fulfillmentId}/items |
sync | Returns the line items of a fulfillment |
| Get line item | GET |
/sphere/api/v1/bnac/fulfillments/{fulfillmentId}/items/{itemId} |
sync | Returns one line item |
| Sync all | POST |
/sphere/api/v1/bnac/fulfillments/sync |
async (job) | Queues a sync of all equipment requests |
| Sync fulfillment | POST |
/sphere/api/v1/bnac/fulfillments/{fulfillmentId}/sync |
async (job) | Queues a sync of one fulfillment |
| Pin a shell | PUT |
/sphere/api/v1/bnac/fulfillments/{fulfillmentId}/items/{itemId}/mapping |
sync | Sets the shell that answers a line item |
| Release a shell | DELETE |
/sphere/api/v1/bnac/fulfillments/{fulfillmentId}/items/{itemId}/mapping |
sync | Removes the shell from a line item |
| Deliver a line item | POST |
/sphere/api/v1/bnac/fulfillments/{fulfillmentId}/items/{itemId}/deliver |
async (job) | Queues the delivery of one line item |
| Finalize a request | POST |
/sphere/api/v1/bnac/fulfillments/{fulfillmentId}/finalize |
async (job) | Queues the finalization of a request |
| List jobs | GET |
/sphere/api/v1/bnac/fulfillments/jobs |
sync | Lists the jobs, newest first |
| Get job | GET |
/sphere/api/v1/bnac/fulfillments/jobs/{jobId} |
sync | Returns one job |
List fulfillments
GET https://{twinsphereTenantURL}/sphere/api/v1/bnac/fulfillments
| Parameter | Description |
|---|---|
state |
Fulfillment state, see Fulfillment states |
partnerId |
Fulfillment Partner Id of the requesting partner |
bnacBusinessPartnerId |
Business partner id of the requester in SAP BNAC, which also finds requests from partners that are not configured |
equipmentRequestId |
Id of the equipment request in SAP BNAC |
caseId |
Case number SAP BNAC shows for the equipment request |
limit |
Page size, at most 50. Defaults to 25 |
cursor |
Cursor from paging_metadata of the previous page, see Pagination |
Repeat a parameter to match any of its values, for example ?state=open&state=partially-fulfilled.
Different parameters are combined, so a fulfillment has to match all of them.
Example Response (200 OK)
{
"paging_metadata": {},
"result": [
{
"identifier": "{fulfillment-id}",
"equipmentRequestId": "{equipment-request-id}",
"caseId": "1000123",
"description": "Pumps for plant extension",
"requesterBnacBusinessPartnerId": "{partner-business-partner-id}",
"partnerId": "musterchemie",
"authorizationGroupId": "{partner-authorization-group-id}",
"requestStatusCode": "5",
"discoveredAt": "2026-09-28T09:15:02+00:00",
"lastSyncedAt": "2026-09-28T10:15:04+00:00",
"state": "partially-fulfilled",
"items": [
{
"identifier": "{item-id-1}",
"requested": {
"idLink": "https://id.example.com/0815/4711",
"purchaseOrder": "4500012345",
"purchaseOrderLineItem": "00010",
"operatorEquipmentId": "P-101"
},
"state": "equipment-assigned",
"matchedShellId": "https://example.com/shells/pump-4711",
"matchSource": "automatic",
"matchedOn": "id-link",
"assignedEquipmentId": "{equipment-id}",
"warnings": []
},
{
"identifier": "{item-id-2}",
"requested": {
"purchaseOrder": "4500012345",
"purchaseOrderLineItem": "00020"
},
"state": "unmatched",
"warnings": []
}
]
}
]
}
Fields without a value are left out of the response. What your customer asked for on a line item is grouped
under requested; the other fields describe twinsphere's answer.
Syncs
POST /sphere/api/v1/bnac/fulfillments/sync does what the hourly sync does: it picks up requests that have
not been seen yet and queues a sync of every fulfillment that is not finished. The result.summary of the job
tells what it found:
| Field | Meaning |
|---|---|
equipmentRequestsListed |
Equipment requests SAP BNAC listed as waiting for you |
fulfillmentsDiscovered |
Requests seen for the first time and stored as fulfillments |
jobsQueued |
Fulfillment syncs queued |
alreadyQueued |
Fulfillment syncs that were already waiting from an earlier sync |
discoveryFailures |
One message per equipment request that could not be read from SAP BNAC |
POST /sphere/api/v1/bnac/fulfillments/{fulfillmentId}/sync syncs a single fulfillment, for example right
after you created the shells for it, instead of waiting for the next hourly sync.
Note
A sync job succeeds even when single line items could not be delivered. It fails only when the request
itself could not be processed. Check the lastError of the fulfillment and of its line items to see what
did not go through.
Pin a shell
PUT https://{twinsphereTenantURL}/sphere/api/v1/bnac/fulfillments/{fulfillmentId}/items/{itemId}/mapping
{
"shellId": "https://example.com/shells/pump-4711"
}
Sets the shell for the line item, in place of the one matching would choose.
In manual processing, this is the only way to give a line item a shell. The request answers directly with
204 No Content; the shell is delivered by the next delivery or, in automatic
processing, by the next sync.
A line item that was already delivered can be given another shell. It then returns to matched, and the new
shell is delivered in its place. Pinning is refused with 400 Bad Request when:
- the shell does not exist, or it already answers another line item of the same request,
- the shell names another partner with
twinsphere.io/bnac/partner-id, - the line item carries equipment twinsphere did not deliver (
external), - the same shell was already delivered for the line item — deliver the line item again instead,
- the fulfillment is
finalizedorclosed.
Release a shell
DELETE https://{twinsphereTenantURL}/sphere/api/v1/bnac/fulfillments/{fulfillmentId}/items/{itemId}/mapping
Removes the shell from a line item that has not been delivered yet (matched). The line item returns to
unmatched. In automatic processing, the next sync matches it again; in manual processing, it stays
open until you pin a shell.
Deliver a line item
POST https://{twinsphereTenantURL}/sphere/api/v1/bnac/fulfillments/{fulfillmentId}/items/{itemId}/deliver
Queues the delivery of the line item's shell. Use it to deliver a pinned shell in manual processing, and to deliver a line item again after its shell or submodels changed, so that the equipment in SAP BNAC is updated.
Before sending, the delivery checks again that the shell is meant for the partner. If it is not, the line item
carries the reason in its lastError. A shell matched automatically is also released, and the line item returns
to unmatched, as long as nothing was shared yet; a pinned shell stays.
Finalize a request
POST https://{twinsphereTenantURL}/sphere/api/v1/bnac/fulfillments/{fulfillmentId}/finalize
{
"allowIncomplete": false
}
Queues the finalization of the request, which hands it back to your customer for review. The body is optional.
By default, every line item has to carry equipment. Set allowIncomplete to true to finalize a request in
which some line items are still open; at least one line item has to carry equipment either way.
Important
A finalization cannot be undone from your side. Only your customer can send the request back to you.
Jobs
Syncs, deliveries and finalizations run as jobs in the background, because they depend on SAP BNAC. The
endpoints that start them answer 202 Accepted with the job in the body and its address in the Location
header. Get the job from there until its state is succeeded or failed.
Get a job
GET https://{twinsphereTenantURL}/sphere/api/v1/bnac/fulfillments/jobs/{jobId}
Example Response (200 OK)
{
"identifier": "{job-id}",
"kind": "deliver-item",
"trigger": "user-request",
"state": "succeeded",
"queuedAt": "2026-09-28T10:20:00+00:00",
"startedAt": "2026-09-28T10:20:01+00:00",
"completedAt": "2026-09-28T10:20:43+00:00",
"attempts": 1,
"parameters": {
"fulfillmentId": "{fulfillment-id}",
"itemId": "{item-id-1}"
},
"result": {
"delivery": {
"itemState": "equipment-assigned",
"assignedEquipmentId": "{equipment-id}",
"warnings": []
}
}
}
| Field | Values |
|---|---|
kind |
tenant-sync (sync all), sync-fulfillment, deliver-item, finalize |
trigger |
user-request when started through the API, schedule for the hourly sync and the fulfillment syncs it queues |
state |
pending (waiting to start), running, succeeded, failed |
error |
Why the job failed. Only set when state is failed |
result |
summary for tenant-sync, delivery for deliver-item. Only set when state is succeeded |
GET /sphere/api/v1/bnac/fulfillments/jobs lists the jobs, newest first. Filter them by kind, state,
trigger and fulfillmentId, with the same rules and paging as the fulfillment list.
How jobs run
- One at a time per fulfillment. The jobs of one fulfillment run one after another, so a sync, a delivery and a finalization never change the same fulfillment at once. Jobs of different fulfillments run in parallel.
- No duplicates while waiting. A job that is the same as one still
pendingis refused with409 Conflict; the waiting job already covers it. Once that job has started, the same job can be queued again. - Failed jobs are not retried. Start the operation again to retry it. Running a sync or a delivery again is safe: finished work is not repeated, and a delivery updates the same equipment. A finalization that already went through is refused instead of being sent a second time.
- Time limit. A job that runs longer than one hour is stopped and fails.
- Restarts. A job that is interrupted by a twinsphere update returns to
pendingand runs again. Itsattemptscounts every start.
