openapi: '3.0.3' info: title: Block Notification API version: '1.0.0' description: "The blocking process is a process in the automotive industry to segregate or quarantine nonconforming parts in the supply chain to prevent using them in the production process. Therefore, the supplier must send all relevant information to the customer, so that he is able to identify the affected parts for example at the assembly line or in logistics. \n\n This API is to be used to transfer this information in a standardized manner and to trace the individual parts back to see whether they have been blocked and sorted out on the customer side in order to prevent subsequent damage or major product recalls. In addition, the notification is intended to improve the quality and speed of the block information provided." license: name: Apache License v2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://example.com/api/v1 variables: api-version: default: '1.0.0' paths: # Path to send and receive block notifications /block-notification/receive: post: tags: - Block Notification requestBody: $ref: '#/components/requestBodies/BlockNotificationReceive' responses: "201": $ref: '#/components/responses/Successful' "400": $ref: '#/components/responses/Malformed' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFoundError' "405": $ref: '#/components/responses/Duplication' "422": $ref: '#/components/responses/SemanticError' # Path to send and receive a status update of a existing block notifications /block-notification/update: post: tags: - Block Notification requestBody: $ref: '#/components/requestBodies/BlockNotificationUpdate' responses: "201": $ref: '#/components/responses/Successful' "400": $ref: '#/components/responses/Malformed' "401": $ref: '#/components/responses/Unauthorized' "403": $ref: '#/components/responses/Forbidden' "404": $ref: '#/components/responses/NotFoundError' "405": $ref: '#/components/responses/Duplication' "422": $ref: '#/components/responses/SemanticError' components: # Schemas to build up the request body and the reponses schemas: BlockNotificationReceive: type: object description: "Request schema to send block notifications." properties: header: $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic' content: $ref: '#/components/schemas/NotificationContentReceive' required: - header - content BlockNotificationUpdate: type: object description: "Request body schema to send a status update for an existing block notification." properties: header: $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic' content: $ref: '#/components/schemas/NotificationContentUpdate' required: - header - content # Schemas to build up the header urn_samm_io.catenax.shared.message_header_3.0.0_HeaderCharacteristic: description: Characteristic describing the common shared aspect Message Header type: object properties: messageId: description: "Unique ID identifying the message. The purpose of the ID is\ \ to uniquely identify a single message, therefore it MUST not be reused." $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' context: $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_ContextCharacteristic' sentDateTime: description: Time zone aware timestamp holding the date and the time the message was sent by the sending party. The value MUST be formatted according to the ISO 8601 standard $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp' senderBpn: description: The Business Partner Number of the sending party. The value MUST be a valid BPN. BPNA and BPNS are not allowed. Applicable constraints are defined in the corresponding standard $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnlTrait' receiverBpn: description: The Business Partner Number of the receiving party. The value MUST be a valid BPN. BPNA and BPNS are not allowed. Applicable constraints are defined in the corresponding standard. $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnlTrait' expectedResponseBy: description: Time zone aware timestamp holding the date and time by which the sending party expects a certain type of response from the receiving party. The meaning and interpretation of the fields's value are context-bound and MUST therefore be defined by any business domain or platform capability making use of it. The value MUST be formatted according to the ISO 8601 standard $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp' relatedMessageId: description: Unique ID identifying a message somehow related to the current one $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' version: description: The unique identifier of the aspect model defining the structure and the semantics of the message's header. The version number should reflect the versioning schema of aspect models in Catena-X. $ref: '#/components/schemas/urn_samm_io.catenax.shared.message_header_3.0.0_SemanticVersioningTrait' required: - messageId - context - sentDateTime - senderBpn - receiverBpn - version urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait: type: string description: "The fully anonymous Catena-X ID of the serialized part or\ \ batch, valid for the Catena-X dataspace. \n\nThe provided regular expression ensures that the UUID is composed\ \ of five groups of characters separated by hyphens, in the form 8-4-4-4-12\ \ for a total of 36 characters (32 hexadecimal characters and 4 hyphens),\ \ optionally prefixed by \"urn:uuid:\" to make it an IRI." pattern: "(^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)|(^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)" urn_samm_io.catenax.shared.message_header_3.0.0_ContextCharacteristic: type: string description: |- Information about the context the message should be considered in. The value MUST consist of two parts: an identifier of the context (e.g. business domain, etc.) followed by a version number. Both the identifier and the version number MUST correspond to the content of the message. If the content of a message is described by an aspect model available in the Catena-X Semantic Hub, then the unique identifier of this semantic model (e.g. urn:samm:io.catenax.:1.x.x) MUST be used as a value of the context field. This is considered the default case. In all other cases the value of the context field MUST follow the pattern --:<[major] version> (e.g. TRACE-QM-Alert:1.x.x). Versioning only refers to major versions in both default and fallback cases. Note: The version of the message's header is specified in the version field. example: 'Traceability-BlockNotification:1.0.0' urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp: type: string pattern: "-?([1-9][0-9]{3,}|0[0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T(([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\\ .[0-9]+)?|(24:00:00(\\.0+)?))(Z|(\\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))?" description: Describes a Property which contains the date and time with an optional timezone. example: '2024-10-07T10:15+00:00' urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnlTrait: type: string description: "The provided regular expression ensures that the BPNL is composed\ \ of prefix 'BPNL', 10 digits and two alphanumeric letters." pattern: "^BPNL[a-zA-Z0-9]{12}$" urn_samm_io.catenax.shared.message_header_3.0.0_SemanticVersioningTrait: type: string description: Constraint for defining a SemVer version. pattern: "^(0|[1-9][0-9]*).(0|[1-9][0-9]*).(0|[1-9][0-9]*)(-(0|[1-9A-Za-z-][0-9A-Za-z-]*)(.[0-9A-Za-z-]+)*)?([0-9A-Za-z-]+(.[0-9A-Za-z-]+)*)?$" example: '3.0.0' # Schemas to build up the content (default notification) urn_samm_io.catenax.block_notification_receive_1.0.0_PartBlockingInformationSet: description: The characteristic of the part blocking information defined as an Array Set. type: array items: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_PartBlockingInformationEntity' uniqueItems: true urn_samm_io.catenax.block_notification_data_1.0.0_PartBlockingInformationEntity: description: The entitiy of the part blocking information Array Set. type: object properties: catenaXId: description: "The fully anonymous Catena-X ID of the serialized part or\ \ batch, valid for the Catena-X dataspace." $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' blockStatus: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_1.0.0_BlockStatus' componentLevelContainment: description: Section with blocking information at component level. $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_ComponentLevelContainmentCharacteristic' periodAndVolumeLevelContainment: description: Section with blocking information at period and volume level. $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_PeriodAndVolumeLevelContainmentCharacteristic' locationInTheContainer: description: 'Object which contain information regarding the locality of the part within a small load carrier. ' $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_LocationInTheContainerCharacteristic' required: - catenaXId - blockStatus - componentLevelContainment - periodAndVolumeLevelContainment urn_samm_io.catenax.block_notification_1.0.0_BlockStatus: type: string description: "Child-element of the partBlockingInformation array.\n\nProvides\ \ information about the status of the individual part within a blocking\ \ notification that must be blocked for security reasons. \n\nACTIVE means\ \ that the part has been identified as a damaged and safety-critical part\ \ and must therefore be blocked on the customer side.\n\nPART_BLOCKED\ \ Status when the receiver has accepted the block and has actually blocked\ \ the part (Note: sender must be informed!).\n\nCANCELED serves as the\ \ update status of the component originally identified to be blocked if\ \ the manufacturer subsequently determines that the original part does\ \ meet safety requirements, is not damaged or that the information was\ \ sent by mistake. " enum: - ACTIVE - PART_BLOCKED - CANCELED urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnaCharacteristic: type: string description: "Identifies the respective address of the supplier's location from which the corresponding components are delivered. \n\n The provided regular expression ensures that the BPNA is composed\ \ of prefix 'BPNA', 10 digits and two alphanumeric letters." pattern: "^BPNA[a-zA-Z0-9]{12}$" urn_samm_io.catenax.block_notification_data_1.0.0_IntegrationLevelCharacteristic: type: string description: "(E/E component generation (hardware and software) with defined\ \ functional content and coordinated system communication) [Vehicle electrics/electronics]\t" example: 'S18A-19-03-400' urn_samm_io.catenax.serial_part_3.0.0_PartIdCharacteristic: type: string description: |- An ID that consists of two different pieces of information but at least always contains a part number: Part Number identifier of a particular part design (or material used) which unambiguously identifies a part design within a single corporation, sometimes across several corporations Change Index (optional) The change index corresponds to the identification of a version of a technical object (also in the technical drawing). This provides easy-to-understand version management, which allows older variants to be clearly addressed. The first version usually has an index of 0. When changes are made, this is usually increased by 1. The current edition therefore has the highest change index. Alternatively, it is possible to represent the index in ascending order with letters, i.e. A, B, C,... Z, AA, AB, etc. example: '884267902' urn_samm_io.catenax.serial_part_3.0.0_KeyTrait: type: string description: Constraint that ensures that the standard keys and custom key prefixes can be used. pattern: ^(manufacturerId|partInstanceId|batchId|van|customKey:\w+)$ urn_samm_io.catenax.serial_part_3.0.0_ValueCharacteristic: type: string description: The value of an identifier. urn_samm_io.catenax.serial_part_3.0.0_KeyValueList: description: "A list of key value pairs for local identifiers, which are composed\ \ of a key and a corresponding value." type: object properties: key: description: 'The key of a local identifier. ' $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_KeyTrait' value: description: The value of an identifier. $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_ValueCharacteristic' required: - key - value urn_samm_io.catenax.serial_part_3.0.0_LocalIdentifierCharacteristic: description: "A local identifier enables identification of a part in a specific\ \ dataspace, but is not unique in Catena-X dataspace. Multiple local identifiers\ \ may exist. \n\n A single serialized part may have multiple attributes, that uniquely\ \ identify a that part in a specific dataspace (e.g. the manufacturer`s dataspace)" type: array items: $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_KeyValueList' uniqueItems: true example: - key: 'manufacturerId' value: 'BPNL0123456789ZZ' - key: 'partInstanceId' value: 'SN12345678' - key: 'customKey:ecuSerialNumber' value: '220115001384267902201978150063581180' urn_samm_io.catenax.block_notification_data_1.0.0_ComponentLevelContainmentCharacteristic: description: 'The characteristic of the component level containment defined as a Object. ' type: object properties: manufacturingLocationId: $ref: '#/components/schemas/urn_samm_io.catenax.shared.business_partner_number_2.0.0_BpnaCharacteristic' integrationLevel: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_IntegrationLevelCharacteristic' customerPartId: $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_PartIdCharacteristic' localIdentifiers: $ref: '#/components/schemas/urn_samm_io.catenax.serial_part_3.0.0_LocalIdentifierCharacteristic' required: - manufacturingLocationId - customerPartId - localIdentifiers urn_samm_io.catenax.shared.quantity_2.0.0_ItemUnitEnumeration: type: string pattern: "[a-zA-Z]*:[a-zA-Z]+" description: Enumeration for common item units. enum: - unit:piece - unit:set - unit:pair - unit:page - unit:cycle - unit:kilowattHour - unit:gram - unit:kilogram - unit:tonneMetricTon - unit:tonUsOrShortTonUkorus - unit:ounceAvoirdupois - unit:pound - unit:metre - unit:centimetre - unit:kilometre - unit:inch - unit:foot - unit:yard - unit:squareCentimetre - unit:squareMetre - unit:squareInch - unit:squareFoot - unit:squareYard - unit:cubicCentimetre - unit:cubicMetre - unit:cubicInch - unit:cubicFoot - unit:cubicYard - unit:litre - unit:millilitre - unit:hectolitre - unit:secondUnitOfTime - unit:minuteUnitOfTime - unit:hourUnitOfTime - unit:day urn_samm_io.catenax.shared.quantity_2.0.0_QuantityValueCharacteristic: type: number description: The quantity value associated with the unit expressed as float. example: 20.0 urn_samm_io.catenax.block_notification_data_1.0.0_QuantityCharacteristic: description: 'The characteristic to define the quantity an value of a property. ' type: object properties: itemUnit: description: "The unit of an item. Common units may be related to mass,\ \ count, linear, area, volume or misc." $ref: '#/components/schemas/urn_samm_io.catenax.shared.quantity_2.0.0_ItemUnitEnumeration' quantityValue: description: The quantity value associated with the unit. $ref: '#/components/schemas/urn_samm_io.catenax.shared.quantity_2.0.0_QuantityValueCharacteristic' required: - itemUnit - quantityValue urn_samm_io.catenax.block_notification_data_1.0.0_DeliveryPlaceCharacteristic: type: string description: "The identification number of the unloading point. An unloading\ \ point is an important part of logistics, as it describes the location\ \ where goods can be loaded or unloaded using a means of transport. In\ \ addition to the address itself, the spatial conditions at the unloading\ \ point are also important. Each warehouse has its own type of unloading\ \ point, such as a ramp that is specifically designed for loading and\ \ unloading goods. These specific conditions are crucial for the efficient\ \ and secure processing of deliveries.\t" example: '22610' urn_samm_io.catenax.block_notification_data_1.0.0_DeliveryNoteNumberCharacteristic: type: string description: "The number of the delivery note that accompanies the delivery\ \ and shows the description, unit and quantity of goods included in the\ \ delivery, etc..\t" example: '68988545' urn_samm_io.catenax.block_notification_data_1.0.0_PackageNumberCharacteristic: type: string description: "Identififcation number of the package, the unit of goods and\ \ packaging material. These can be boxes, pallets, mesh boxes, roll containers\ \ and other loading equipment." example: '12295140916130' urn_samm_io.catenax.block_notification_data_1.0.0_OrderNumberCharacteristic: type: string description: The order number (only for production synchronization requests (JIS)) example: '7334663' urn_samm_io.catenax.block_notification_data_1.0.0_PeriodAndVolumeLevelContainmentCharacteristic: description: 'The characteristic of the period and volume level containment defined as Object. ' type: object properties: sizeOfProductionLot: description: "A production lot is the combined number of products or manufactured\ \ parts that are produced in a work process without interruption. There\ \ is no need to convert production facilities. \t" $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_QuantityCharacteristic' deliveryNoteNumber: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_DeliveryNoteNumberCharacteristic' packageNumber: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_PackageNumberCharacteristic' deliveryPlace: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_DeliveryPlaceCharacteristic' deliveryDate: description: "The date, on which the supplier handed over the shipment \ \ to the carrier. Shiiping date of the manufacturer." $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp' numberOfPartsPerDeliveryNote: description: The quanity of delivered parts per delivery note. $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_QuantityCharacteristic' productionDate: $ref: '#/components/schemas/urn_samm_org.eclipse.esmf.samm_characteristic_2.1.0_Timestamp' numberOfPartsPerPackage: description: Number of parts, which are stored in a package. $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_QuantityCharacteristic' orderNumber: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_OrderNumberCharacteristic' required: - sizeOfProductionLot - deliveryNoteNumber - packageNumber - deliveryPlace - deliveryDate - numberOfPartsPerDeliveryNote - productionDate - numberOfPartsPerPackage urn_samm_io.catenax.block_notification_data_1.0.0_XPositionCharacteristic: type: string description: "Position along the X coordinate where the faulty component\ \ (cell) is located within the small charge carrier.\t" example: 'F' urn_samm_io.catenax.block_notification_data_1.0.0_YPositionCharacteristic: type: string description: Position along the Y coordinate where the faulty component (cell) is located within the small charge carrier. example: '10' urn_samm_io.catenax.block_notification_data_1.0.0_SmallLoadCarrierLayerCharacteristic: type: string description: |- The layer within the small load carrier in which the faulty part is located. (Ideally if available: UCID = Unique Container ID - ID of the small load carrier in which the faulty part is located) Packaging specific for high-voltage battery cells. Other components (e.g. penthouse are not packaged in small load carriers). example: '53BUN6555599345283155+000000008' urn_samm_io.catenax.block_notification_data_1.0.0_LocationInTheContainerCharacteristic: description: The characteristic to define the location in the container defined as entity. type: object properties: xPosition: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_XPositionCharacteristic' yPosition: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_YPositionCharacteristic' smallLoadCarrierLayer: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_data_1.0.0_SmallLoadCarrierLayerCharacteristic' # Schemas to build up the content (status udpate notification) urn_samm_io.catenax.block_notification_status_update_1.0.0_PartBlockingInformationSet: description: The characteristic of the part blocking information defined as an Array Set. type: array items: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_status_update_1.0.0_PartBlockingInformationEntity' uniqueItems: true example: - catenaXId: '580d3adf-1981-44a0-a214-13d6ceed9379' blockStatus: 'PART_BLOCKED' - catenaXId: '6a3cA7E1-1682-5F25-FE1d-cF112433C2f4' blockStatus: 'PART_BLOCKED' - catenaXId: '550d3swf-1845-55sw-a2s8-13d6ceed4265' blockStatus: 'PART_BLOCKED' urn_samm_io.catenax.block_notification_status_update_1.0.0_PartBlockingInformationEntity: description: The entitiy of the part blocking information Array Set. type: object properties: catenaXId: $ref: '#/components/schemas/urn_samm_io.catenax.shared.uuid_2.0.0_UuidV4Trait' blockStatus: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_1.0.0_BlockStatus' required: - catenaXId - blockStatus NotificationContentReceive: type: object properties: notificationStatus: $ref: '#/components/schemas/NotificationStatus' problemDescription: type: string maxLength: 1000 example: "Gear boxes lose oil while driving." description: A free text field which provides information why the parts from the provided list must be blocked or sorted out. blockInformations: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_receive_1.0.0_PartBlockingInformationSet' required: - notificationStatus - blockInformations NotificationContentUpdate: type: object properties: notificationStatus: $ref: '#/components/schemas/NotificationStatus' updateReason: type: string maxLength: 1000 example: "Defect gear boxes were sorted out to prevent major damage." description: A free text field that informs why a previously provided list of damaged parts needs to be updated. For example, because the order to block the parts must be canceled due to a user error or because the damaged parts were sorted out by the customer and thus blocked. blockInformations: $ref: '#/components/schemas/urn_samm_io.catenax.block_notification_status_update_1.0.0_PartBlockingInformationSet' required: - notificationStatus - blockInformations NotificationStatus: type: string enum: - CREATED - SENT - RECEIVED - ACKNOWLEDGED - CLOSED example: 'SENT' description: The status of the block notification. The following entries are supported and allowed - CREATED This status is an internal status and is used after the initial creation of a notification. It is not communicated to an other CX/business partner. - SENT This status means that the notification has been sent out. This status is shown on the sender side (and not on the receiver side). - RECEIVED This status means that the notification has been received by the receiver. The status is shown on sender and receiver side. It is not communicated to another CX/business partner. - ACKNOWLEDGED Defines that a user has confirmed that the notification has been received. - CLOSED This status is set by the initiator of the notification either to regularly close the notification (i.e., after the receiver has set the status to ACKNOWLEDGED). # Response Content responses: Successful: description: Block notification was sent successfully. Malformed: description: Request body was malformed. Unauthorized: description: The requesting user or client is not authenticated. Forbidden: description: The requesting user or client is not authorized to access.resources. NotFoundError: description: Method not allowed. Duplication: description: Could not accept the sent block notification, because a block notification with that same notification ID already exists. SemanticError: description: Could not accept the sent block notification even though it is syntactically correct. The block notification is not accepted, because of semantic reasons (e.g., an affected item is not known by the receiver). # Request Body Content requestBodies: BlockNotificationReceive: content: application/json: schema: $ref: '#/components/schemas/BlockNotificationReceive' BlockNotificationUpdate: content: application/json: schema: $ref: '#/components/schemas/BlockNotificationUpdate'