### Get Network Balance (HTTP Request Example) Source: https://catenax-ev.github.io/docs/Io/standards/CX-0105-AssetTrackingUseCase This example shows how to make an HTTP GET request to retrieve the available balances in a specific network. It includes the necessary Authorization header and path parameters for the request. The response provides details about the network, balance, and user information. ```http GET https://{baseURL}/{apiVersion}/administration/balance/{network} Authorization: Bearer ``` -------------------------------- ### DID Document Example (JSON) Source: https://catenax-ev.github.io/docs/next/standards/CX-0049-DIDDocumentSchema This is an illustrative example of a valid Catena-X Decentralized Identifier (DID) document. It demonstrates the structure and content expected for a DID document, including context, ID, service endpoints, verification methods, and authentication/capability invocation details. This example serves as a practical guide for implementing DID documents. ```json { "@context": [ "https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/jws-2020/v1", "https://w3id.org/dspace-dcp/v1.0/dcp.jsonld", "https://w3id.org/dspace/2025/1/context.jsonld" ], "id": "did:web:example.com/sub/path", "service": [ { "type": "CredentialService", "serviceEndpoint": "https://credential-service-example.com", "id": "did:web:example.com#CredentialService" }, { "type": "DataService", "serviceEndpoint": "https://subdomain.provider-domain.com/subpath/.well-known/dspace-version", "id": "did:web:provider-domain.com#dsp-agent-1" } ], "verificationMethod": [ { "id": "did:web:example.com#keys-82of94hf-j20f-8fn4-9fj3-93hjv0384nfl", "type": "JsonWebKey2020", "controller": "did:web:example.com", "publicKeyJwk": { "kty": "EC", "crv": "secp256k1", "x": "9jnfg6e4fK97rfvJo975ojkdxsy6qmcvk69Djkdf56e", "y": "8bdtb734civgR49tiDS4ax9klbZ45dsh832nchfhRv2" } }, { "id": "did:web:example.com#keys-93uwifie-9x33-9fn4-cv93-89f19bmnqxod", "type": "JsonWebKey2020", "controller": "did:web:example.com", "publicKeyJwk": { "kty": "EC", "crv": "secp256k1", "x": "9c29fn9823mxdufw349mxfj49cjtr89mxjr349fxnjf", "y": "0ymei1920yks129x0mk2390ucm849cfmnj489mxdkew" } } ], "authentication": [ "did:web:example.com#keys-02v9209fmxjfw93c0mjfw30mxf3490fmcx34" ], "capabilityInvocation": [ "did:web:example.com#keys-0xm10di23fuc9834fumx89fwjxm9342j02hj" ] } ``` -------------------------------- ### JSON Example: Digital Twin with Child Items Source: https://catenax-ev.github.io/docs/Io/standards/CX-0045-AspectModelDataChainTemplate This JSON example demonstrates a minimal setup for a digital twin that includes child items. It shows the structure for defining a 'catenaXId' for the parent and an array of 'childItems', each with its own 'catenaXId' and 'businessPartner'. This is used to establish a parent-child relationship between digital twins. ```json { "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d", "childItems": [ { "catenaXId": "urn:uuid:7BeA9fAE-A1ca-D164-3BDF-0E5bac5E5b7d", "businessPartner" : "BPNL50096894aXYZ" } ] } ``` -------------------------------- ### Example Parameter Key Usage Source: https://catenax-ev.github.io/docs/Io/standards/CX-0129-RequestforQuotationExchange Demonstrates the usage of the 'parameterKey' enumeration, specifically showing an example where a parameter has no value. ```json { "parameterKey": "HasNoValue" } ``` -------------------------------- ### JSON Example: Digital Twin with Parent Items Source: https://catenax-ev.github.io/docs/Io/standards/CX-0045-AspectModelDataChainTemplate This JSON example illustrates a minimal setup for a digital twin that includes parent items. It defines the 'catenaXId' for the digital twin and an array of 'parentItems', where each parent item has a 'catenaXId' and 'businessPartner'. This structure is used to link a digital twin to its parent entities. ```json { "catenaXId": "urn:uuid:055c1128-0375-47c8-98de-7cf802c3241d", "parentItems": [ { "catenaXId": "urn:uuid:7BeA9fAE-A1ca-D164-3BDF-0E5bac5E5b7d", "businessPartner" : "BPNL50096894aXYZ" } ] } ``` -------------------------------- ### Data Asset Structure and Example Source: https://catenax-ev.github.io/docs/Io/standards/CX-0074-BusinessPartnerGateAPI Details the structure of data assets required for BPDM Gate access and provides an example payload. ```APIDOC ### Data Asset Structure The data asset must contain the following properties: - **_dct:type** (string, @id reference) - The type of the data asset (e.g., `cx-taxo:BPDMGate`). - **_dct:subject** (string, @id reference) - The subject of the data asset (e.g., `cx-taxo:FullAccessGateInputForSharingMember`). - **_dct:description** (string) - A description of the data asset. - **cx-common:version** (string) - The version of the data asset (e.g., `6.3`). ### Request Example ```json { "@context": { "dct": "http://purl.org/dc/terms/", "cx-taxo": "https://w3id.org/catenax/taxonomy#", "cx-common": "https://w3id.org/catenax/ontology/common#" }, "@type": "Asset", "@id": "a8f15946-2347-47a8-a67f-846e7303fd94", "properties": { "dct:type": { "@id": "cx-taxo:BPDMGate" }, "dct:subject": { "@id": "cx-taxo:FullAccessGateInputForSharingMember" }, "dct:description": "Grants the Sharing Member full access to the input persistence. This can be used to read business partner data in the input persistence, and create / update business partner data in the input persistence from data sources of the Sharing Member. To that end, it also grants read access to the input changelog entries.", "cx-common:version": "6.3" }, "dataAddress": { "@type": "DataAddress", "type": "HttpData", "baseUrl": "https:///companies//api/v6/", "oauth2:tokenUrl": "https:///auth/realms//protocol/openid-connect/token", "oauth2:clientId": "", "oauth2:clientSecretKey": "", "proxyMethod": true, "proxyPath": true, "proxyQueryParams": true, "proxyBody": true } } ``` ``` -------------------------------- ### Get Production Tracking Data Request (HTTP GET) Source: https://catenax-ev.github.io/docs/standards/CX-0142-ShopFloorInformationService This snippet demonstrates the HTTP GET request structure for the GetProductionTrackingData endpoint. It requires specific path parameters and includes a JSON payload with details about the product and manufacturing steps for which tracking data is requested. The request is sent to the Modular Production system via a connector. ```http GET /get-production-tracking HTTP/1.1 Host: localhost:3000 Content-Type: application/json Content-Length: 1007 ``` ```json { "request" : { "identifierNumber" : "box-12345678", "stepIdentifierList" : [ { "processStepId" : "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01", "processParameterList" : [ { "processParameterSemanticId" : "0173-1#02-ABK233#001", "processParameterName" : "Drehmoment_Max" } ] } ], "customerId" : "550e8400-e29b-41d4-a716-446655440000", "identifierType" : "partInstanceId", "billOfProcessId" : "box-with-lid-12345678-bill-of-process", "version" : "1.0.0", "processReferenceType" : "processStep" }, "header" : { "senderBpn" : "BPNL7588787849VQ", "relatedMessageId" : "d9452f24-3bf3-4134-b3eb-68858f1b2362", "expectedResponseBy" : "2023-06-19T21:24:00+07:00", "context" : "urn:samm:io.catenax.shopfloor_information.get_production_tracking:1.0.0", "messageId" : "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", "receiverBpn" : "BPNL6666787765VQ", "sentDateTime" : "2023-06-19T21:24:00+07:00", "version" : "2.0.0" } } ``` -------------------------------- ### Example Usage Policy Definition (JSON) Source: https://catenax-ev.github.io/docs/standards/CX-0142-ShopFloorInformationService This JSON object defines a usage policy for a Data Asset in Catenax, specifying conditions for data exchange. It enforces that the Framework Agreement must be 'DataExchangeGovernance:1.0' and the Usage Purpose must be 'cx.core.industrycore:1'. ```json { "@context": [ "http://www.w3.org/ns/odrl.jsonld", "https://w3id.org/catenax/2025/9/policy/context.jsonld", ], "@type": "Set", "@id": "sis-unsubscribe-production-forecast-02-policy", "permission": [ { "action": "use", "constraint": [ { "and": [ { "leftOperand": "FrameworkAgreement", "operator": "eq", "rightOperand": "DataExchangeGovernance:1.0" }, { "leftOperand": "UsagePurpose", "operator": "isAnyOf", "rightOperand": "cx.core.industrycore:1" } ] } ] } ] } ``` -------------------------------- ### Example Contract Definition (JSON) Source: https://catenax-ev.github.io/docs/standards/CX-0142-ShopFloorInformationService This JSON object defines a contract for a Data Asset in Catenax. It links the asset to its access and contract policies using their respective IDs and specifies an assetsSelector to identify the target asset by its ID. ```json { "@context": {}, "@id": "sis-unsubscribe-production-forecast-01-contract", "@type": "ContractDefinition", "accessPolicyId": "sis-unsubscribe-production-forecast-01-policy", "contractPolicyId": "sis-unsubscribe-production-forecast-02-policy", "assetsSelector" : { "@type" : "CriterionDto", "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", "operator": "=", "operandRight": "sis-unsubscribe-production-forecast-01" } } ``` -------------------------------- ### Usage Policy Definition Source: https://catenax-ev.github.io/docs/standards/CX-0142-ShopFloorInformationService Example of a Usage Policy definition for a Data Asset, specifying the permitted usage purposes and governance frameworks. ```APIDOC ## Usage Policy Definition ### Description A Usage Policy defines the constraints on how a Data Asset can be used after access has been granted. It specifies requirements like framework agreements and usage purposes. ### Method N/A (Policy Definition) ### Endpoint N/A (Policy Definition) ### Parameters - **action** (string) - Required - Typically "use". - **constraint.and.leftOperand** (string) - Required - The attribute to check (e.g., "FrameworkAgreement", "UsagePurpose"). - **constraint.and.operator** (string) - Required - The comparison operator (e.g., "eq", "isAnyOf"). - **constraint.and.rightOperand** (string) - Required - The value(s) to compare against (e.g., "DataExchangeGovernance:1.0", "cx.core.industrycore:1"). ### Request Example ```json { "@context": [ "http://www.w3.org/ns/odrl.jsonld", "https://w3id.org/catenax/2025/9/policy/context.jsonld", ], "@type": "Set", "@id": "sis-provide-production-forecast-02-policy", "permission": [ { "action": "use", "constraint": [ { "and": [ { "leftOperand": "FrameworkAgreement", "operator": "eq", "rightOperand": "DataExchangeGovernance:1.0" }, { "leftOperand": "UsagePurpose", "operator": "isAnyOf", "rightOperand": "cx.core.industrycore:1" } ] } ] } ] } ``` ### Response N/A (Policy Definition) ``` -------------------------------- ### Unsubscribe API Request Example Source: https://catenax-ev.github.io/docs/standards/CX-0142-ShopFloorInformationService Demonstrates an HTTP DELETE request for the Unsubscribe functionality, used to opt out of receiving information. This request is sent from the consumer to the producer via a connector like Tractus-X EDC. The endpoint URL includes a message ID as a path parameter. ```HTTP DELETE /relatedMessageId/00000000-0000-0000-C000-000000000042 HTTP/1.1 Host: {{internal-server}} ``` -------------------------------- ### Contract Definition Source: https://catenax-ev.github.io/docs/standards/CX-0142-ShopFloorInformationService Example of a Contract Definition that links a Data Asset with its Access and Usage Policies. ```APIDOC ## Contract Definition ### Description A Contract Definition links a Data Asset to its corresponding Access Policy and Usage Policy. It also includes a selector to identify the specific asset the contract applies to. ### Method N/A (Contract Definition) ### Endpoint N/A (Contract Definition) ### Parameters - **accessPolicyId** (string) - Required - The ID of the Access Policy to be used. - **contractPolicyId** (string) - Required - The ID of the Usage Policy to be used. - **assetsSelector.@type** (string) - Required - Type of the selector, typically "CriterionDto". - **assetsSelector.operandLeft** (string) - Required - The property to match for asset selection (e.g., "https://w3id.org/edc/v0.0.1/ns/id"). - **assetsSelector.operator** (string) - Required - The comparison operator (e.g., "="). - **assetsSelector.operandRight** (string) - Required - The value to match (e.g., the asset ID). ### Request Example ```json { "@context": {}, "@id": "sis-provide-production-forecast-01-contract", "@type": "ContractDefinition", "accessPolicyId": "sis-provide-production-forecast-01-policy", "contractPolicyId": "sis-provide-production-forecast-02-policy", "assetsSelector" : { "@type" : "CriterionDto", "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", "operator": "=", "operandRight": "sis-provide-production-forecast-01" } } ``` ### Response N/A (Contract Definition) ``` -------------------------------- ### Deprecated PCF Exchange API GET Endpoint Example Source: https://catenax-ev.github.io/docs/next/standards/CX-0136-UseCasePCF Example of a deprecated GET request to the PCF exchange API. This endpoint is maintained for backward compatibility but is scheduled for removal. ```http GET https://\{someURL\}/productIds/mat345?requestId=123&message=... ``` -------------------------------- ### PCF Exchange API GET Endpoint Example Source: https://catenax-ev.github.io/docs/next/standards/CX-0136-UseCasePCF Example of a GET request to the PCF exchange API for asynchronous data exchange. This endpoint is used to request PCF data. It requires manufacturerPartId or customerPartId and a requestId. ```http GET https://\{someURL\}/footprintExchange/123?manufacturerPartId=456&customerPartId=789&message=... ``` -------------------------------- ### POST /catenax-onboarding Source: https://catenax-ev.github.io/docs/standards/CX-0105-AssetTrackingUseCase Creates a Digital Twin for an IoT device by registering it in the Catena-X network. This process involves retrieving device information, creating entries in the DeviceRegistry, setting up submodels, and configuring EDC assets and policies. ```APIDOC ## POST /catenax-onboarding ### Description Create a Digital Twin of the devices with the specified identifier. In this case the identifier represents the identfier of the device which it has in its own network. When requesting the creation of a device, the following steps are made: 1 - Get the neccessary information for the device from its network 2 - Create an entry in the DeviceRegistry which contains information of the device in its network and its information in the Catena-X network 3 - Create and save the submodel of the device and its data list (which is at this point empty) at the submodel server 4 - Create a Data Asset in the EDC for the device submodel and data submodel 5 - Create a Policy 6 - Creating a Contract for the device EDC Asset 7 - Creating a Contract for the device data EDC Asset (if registerTwin is true) 8 - Create a Shell Descriptor/Digital Twin in the dDTR instance 9 - Create a Data Asset for the Shell Descriptor in the EDC Devices that shall be created as a Digital Twin must be registered in the IoT network before! ### Method POST ### Endpoint `https://{baseURL}/catenax-onboarding` ### Parameters #### Request Headers - **Authorization** (string) - Required - Bearer Token ("Bearer ") - **Content-Type** (string) - Required - application/json #### Request Body - **id** (string) - Required - UUID of the device in the IoT network - **network** (string) - Required - Network in which the device is registered in - **registerTwin** (boolean) - Required - Boolean/Flag which indicates if the EDC data asset for the device shall be registered as a AAS Descriptor in the (d)DTR instance - **ownerID** (string) - Required - BPNL of the data owner ### Request Example ```json { "id": "fb212345-5bc9-4c43-8acc-699062cb0419", "network": "helium", "registerTwin": true, "ownerID": "BPN0000000001" } ``` ### Response #### Success Response (200) - **result** (string) - Result of the onboarding task (DEVICE_TWIN_CREATED, DEVICE_TWIN_CREATION_ERROR) - **deviceCxId** (string) - Identiier of the device submodel, also resembles the Catena-X Identifier (null on DEVICE_TWIN_CREATION_ERROR) - **deviceDataCxId** (string) - Identifier of the device data submodel #### Response Example ```json { "result": "DEVICE_TWIN_CREATED", "deviceCxId": "dff4dc9b-1234-4d25-ab66-7780c7e25730", "deviceDataCxId": "a720e3f6-ab28-498c-1234-f860d3899326" } ``` ``` -------------------------------- ### POST /catenax-onboarding Source: https://catenax-ev.github.io/docs/Io/standards/CX-0105-AssetTrackingUseCase Creates a Digital Twin for an IoT device by registering it in the Catena-X network. This process involves retrieving device information, creating entries in the DeviceRegistry, setting up submodels and data assets, and optionally registering the device as an AAS Descriptor in the dDTR instance. ```APIDOC ## POST /catenax-onboarding ### Description Create a Digital Twin of the devices with the specified identifier. In this case the identifier represents the identfier of the device which it has in its own network. When requesting the creation of a device, the following steps are made: 1 - Get the neccessary information for the device from its network 2 - Create an entry in the DeviceRegistry which contains information of the device in its network and its information in the Catena-X network 3 - Create and save the submodel of the device and its data list (which is at this point empty) at the submodel server 4 - Create a Data Asset in the EDC for the device submodel and data submodel 5 - Create a Policy 6 - Creating a Contract for the device EDC Asset 7 - Creating a Contract for the device data EDC Asset (if registerTwin is true) 8 - Create a Shell Descriptor/Digital Twin in the dDTR instance 9 - Create a Data Asset for the Shell Descriptor in the EDC Devices that shall be created as a Digital Twin must be registered in the IoT network before! ### Method POST ### Endpoint `https://{baseURL}/catenax-onboarding` ### Parameters #### Request Headers - **Authorization** (string) - Required - Bearer Token ("Bearer ") - **Content-Type** (string) - Required - application/json #### Request Body - **id** (string) - Required - UUID of the device in the IoT network - **network** (string) - Required - Network in which the device is registered in - **registerTwin** (boolean) - Required - Boolean/Flag which indicates if the EDC data asset for the device shall be registered as a AAS Descriptor in the (d)DTR instance - **ownerID** (string) - Required - BPNL of the data owner ### Request Example ```json { "id": "fb212345-5bc9-4c43-8acc-699062cb0419", "network": "helium", "registerTwin": true, "ownerID": "BPN0000000001" } ``` ### Response #### Success Response (200) - **result** (string) - Result of the onboarding task (DEVICE_TWIN_CREATED, DEVICE_TWIN_CREATION_ERROR) - **deviceCxId** (string) - Identifier of the device submodel, also resembles the Catena-X Identifier (null on DEVICE_TWIN_CREATION_ERROR) - **deviceDataCxId** (string) - Identifier of the device data submodel #### Response Example ```json { "result": "DEVICE_TWIN_CREATED", "deviceCxId": "dff4dc9b-1234-4d25-ab66-7780c7e25730", "deviceDataCxId": "a720e3f6-ab28-498c-1234-f860d3899326" } ``` ``` -------------------------------- ### Provide Production Tracking Response Example Source: https://catenax-ev.github.io/docs/Io/standards/CX-0142-ShopFloorInformationService This JSON dataset shows an example response for the ProvideProductionTracking endpoint. The response structure is consistent regardless of the request type and includes details about the product, identifier, and process step values. ```json { "header": { "senderBpn": "BPNL7588787849VQ", "relatedMessageId": "d9452f24-3bf3-4134-b3eb-68858f1b2362", "expectedResponseBy": "2023-06-19T21:24:00+07:00", "context": "urn:samm:io.catenax.shopfloor_information.provide_production_tracking:1.0.0", "messageId": "3b4edc05-e214-47a1-b0c2-1d831cdd9ba9", "receiverBpn": "BPNL6666787765VQ", "sentDateTime": "2023-06-19T21:24:00+07:00", "version": "2.0.0" }, "response": { "identifierNumber": "box-12345678", "catenaXId": "urn:uuid:580d3adf-1981-44a0-a214-13d6ceed9379", "identifierType": "partInstanceId", "version": "1.0.0", "processStepIdentifierList": [ { "processStepId": "Fuegen.Anpressen_Einpressen.Schrauben.Deckelverschrauben_01", "processParameterValueList": [ { "processParameterName": "Drehmoment_Max", "semanticId": "0173-1#02-ABK233#001", "processParameterQuality": "ok", "processParameterValue": "10" } ] } ] } } ```