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 DocumentVersion per 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.

SAP BNAC settings in the Manage UI

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:

  1. The shell and the submodels SAP BNAC imports are uploaded to BNAC as equipment, see Data requirements.
  2. The equipment is published and shared into the partner's authorization group.
  3. 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-assigned and 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:

  1. ID Link: a shell whose globalAssetId is 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.
  2. Purchase order: otherwise, a shell answers when both the purchase order and the line match exactly. They are compared as text, so 00010 and 10 are 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:

  1. 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.
  2. 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-id cannot be pinned.
  3. Pin the shell to the line item, see Pin a shell.
  4. Deliver the line item, see Deliver a line item, and follow the job until it has succeeded or failed.
  5. 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 DocumentVersion is delivered, together with its files, when one of its languages matches a configured code exactly, ignoring case. A DocumentVersion in several languages is delivered whole.
  • A DocumentVersion that 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 finalized or closed.

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 pending is refused with 409 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 pending and runs again. Its attempts counts every start.