swagger: '2.0' info: title: API ServiceOrdering description: |- ## TMF API Reference : TMF 641 - Service Ordering Management Version 4.1 ### TMF641 performs the following operations on service order resource : - Retrieval of a service order or a collection of service orders by id - Creation of a service order - Deletion of service order Copyright © TM Forum 2020. All Rights Reserved version: 4.1.0 host: serverRoot basePath: /tmf-api/serviceOrdering/v4 schemes: - https securityDefinitions: OAuth2: type: oauth2 flow: application tokenUrl: "https://api.mtn.com/v1/oauth/access_token/accesstoken?grant_type=client_credentials" security: - OAuth2: [] consumes: - application/json;charset=utf-8 produces: - application/json;charset=utf-8 tags: - name: serviceOrder paths: /serviceOrder: post: operationId: createServiceOrder summary: Creates a ServiceOrder description: This operation creates a ServiceOrder entity. tags: - serviceOrder parameters: - name: serviceOrder description: The ServiceOrder to be created required: true schema: $ref: '#/definitions/ServiceOrder_Create' in: body - name: sourceIdentifier in: query description: source identifier toidentify the customer like 'MNS_Portal' required: true type: string - name: transactionId in: header description: >- Transaction ID for tracing purposes. If not passed by API client, this value is generated internally required: false type: string responses: '200': description: Created schema: $ref: '#/definitions/CreateServiceOrder_SuccessResponse' '400': description: Bad Request schema: $ref: '#/definitions/Error400' '401': description: Unauthorized schema: $ref: '#/definitions/Error401' '403': description: Forbidden schema: $ref: '#/definitions/Error403' '404': description: Not Found schema: $ref: '#/definitions/Error404' '405': description: Method Not allowed schema: $ref: '#/definitions/Error405' '500': description: Internal Server Error schema: $ref: '#/definitions/Error500' /serviceOrder/{id}: get: operationId: retrieveServiceOrder summary: Retrieves a ServiceOrder by ID description: This operation retrieves a ServiceOrder entity. Attribute selection is enabled for all first level attributes. tags: - serviceOrder parameters: - name: id description: Identifier of the ServiceOrder. This could be Partner ID or MSISDN. required: true type: string in: path - name: sourceIdentifier in: query description: This field denotes the channel that is initiating request to SOA., ex-'Experian,TransUnion' required: false type: string - name: idType in: query description: This field denotes whether the provided Id is Partner ID or MSISDN. required: false type: string enum: - PartnerId - MSISDN - name: transactionId in: header description: >- Transaction ID for tracing purposes. If not passed by API client, this value is generated internally required: false type: string responses: '200': description: Success schema: $ref: '#/definitions/GetServiceOrderResponse' '400': description: Bad Request schema: $ref: '#/definitions/Error400' '401': description: Unauthorized schema: $ref: '#/definitions/Error401' '404': description: Not Found schema: $ref: '#/definitions/Error404' '500': description: Internal Server Error schema: $ref: '#/definitions/Error500' definitions: GetServiceOrderResponse: type: object properties: statusCode: type: string description: HTTP error code extension example: '0000' statusMessage: type: string description: Message. example: Successful transactionId: type: string description: transactionId from the backend or MADAPI generated during request. example: '1f73e9a3-39fa-596a-a030-e03d8cb01a2c' supportMessage: type: string example: 'API Executed Successfully' description: Short description apnDetails: type: array items: properties: apnId: type: string description: APN Id associated with Partner example: '34345' apnName: type: string description: APN name associated with Partner example: 'apn_34345.co.za' ServiceOrder_Create: type: object required: - externalId - operatorId - serviceOrderItem - sourceIdentifier - sourceSystem properties: accessId: type: string example: PROVIDENT description: Access Id as part of IBF RA externalId: type: string example: '320055544792213' description: Requestor reference number consumer uses for identifiy the order operatorId: type: string example: Operator1 description: Operator Id is used to identify the user operates on the order otn: type: string example: 20231209212028-320055544792213 description: OTN value as part of IBF RA requestedStartDate: type: string example: 2019-09-16+02:00 description: Effective date is the date when will be order is provision from serviceOrderItem: type: array description: Lis of service order items items: $ref: '#/definitions/ServiceOrderItem' sourceSystem: type: string example: MADAPI description: System where the SORB order was initiated enum: - MADAPI - PROVIDENT ServiceOrderItem: type: object required: - orderType - packges properties: action: type: string example: add description: Action of the oder item enum: - add - remove orderType: type: string example: Modify description: Order type of oder item enum: - Create - Modify - Migrate - SIM Swap - MSISDN Swap packages: description: Packages details $ref: '#/definitions/Package' Package: type: object required: - id properties: action: type: string example: add description: Acton --optional parameter is used to identify the action of the package such as add/remove enum: - add - remove - modify - softSuspendOut - hpbxSuspend - hpbxUnsuspend - softUnsuspendOut - softSuspendIn - softUnsuspendIn - softSuspendOutOfBundle - softUnsuspendOutOfBundle - suspend - groupSuspend - unsuspend - groupUnsuspend - smsOnlyRoamingSuspend - smsOnlyRoamingUnsuspend - smsOOUnbar - smsOOBar - RICASuspend - RICAUnsuspend - Reserve - Unreserve - changePassword - paymentHolidaySuspend - paymentHolidayUnsuspend - replace - serviceDeactivate - bindDeactivate - productDeactivate - updateCampaignDetail - modifyRateChange - rateChange - productMigrationWithinSamePartner - serviceMigrationFromActiveInstance - serviceMigrationFromCancelledInstance - serviceMigrationUSSDActiveInstance - serviceMigrationUSSDCancelledInstance features: type: array description: A List of features items: $ref: '#/definitions/Feature' id: type: string example: ANCHOR description: Used to identify the catalogue code of the package product: type: array description: List of products which will be added or removed from the subscription items: $ref: '#/definitions/Product' service: type: array description: List of service which includes equipment details such as MSISDN and SIM items: $ref: '#/definitions/Service' Feature: type: object required: - name - value properties: name: type: string example: ID description: Name is used identify the name of the parameter value: type: string example: '01575' description: Value is used to get the incoming parameter value in the request Service: type: object properties: itemAction: type: string example: add description: Item Action to determine the action of the equipment such add/remove enum: - add - remove type: type: string example: MSISDN description: Service Type defines the equipment type such as MSISDN/SIM Card enum: - MSISDN - SIM Card - APN - IP Address value: type: string example: 27xxxxxxxxx description: Service Value contains the value of the given equipment Product: type: object required: - action - id properties: action: type: string example: add description: Product Action to determine the action of the product will be added or removed enum: - add - remove features: type: array description: List of feature items: $ref: '#/definitions/Feature' id: type: string example: APN description: Product offering code is used to identify the product title: Product CreateServiceOrder_SuccessResponse: type: object properties: statusCode: type: string description: HTTP error code extension example: '0000' statusMessage: type: string description: status of Message. example: Successful transactionId: type: string description: transactionId from the backend or MADAPI generated during request. example: '1f73e9a3-39fa-596a-a030-e03d8cb01a2c' supportMessage: type: string example: Order has been modified description: Short description requestorRefNum: type: string example: '320055544792213' description: Requester reference number consumer uses for identify the order sorbRefNum: type: string example: 1700037701915-n-0 description: Sorb reference number is the Id used to identify the SORB Order Request Error400: properties: statusCode: type: "integer" description: Status code from target system to indicate transaction status statusMessage: type: "string" description: Status message from target system to indicate transaction status. supportMessage: type: "string" description: detail message from target system to indicate transaction status. transactionId: type: string description: This is the same transactionId that is sent in the request example: "0d1e1b18-1b6d-4792-8417-72d337f42a1c" links: type: array items: properties: rel: type: string href: type: string Error401: properties: statusCode: type: "integer" description: Status code from target system to indicate transaction status example: 4000 statusMessage: type: "string" description: Status message from target system to indicate transaction status. example: Unauthorised supportMessage: type: "string" description: detail message from target system to indicate transaction status. example: Please verify token environment and key faultMessage1: type: "string" description: "" faultMessage2: type: "string" description: fault message Error404: properties: timestamp: type: string format: date-time description: Timestamp that the error occurred example: '2021-07-21T17:32:28Z' status: type: "integer" description: Status code from target system to indicate transaction status example: 404 error: type: "string" description: error message example: Not found message: type: string description: details path: type: string description: The path that caused the error Error405: properties: timestamp: type: string format: date-time description: Timestamp that the error occurred example: '2021-07-21T17:32:28Z' status: type: "integer" description: Status code from target system to indicate transaction status example: 405 error: type: "string" description: error message example: Method Not Allowed message: type: string description: details path: type: string description: The path that caused the error Error415: properties: timestamp: type: string format: date-time description: Timestamp that the error occurred example: '2021-07-21T17:32:28Z' status: type: "integer" description: Status code from target system to indicate transaction status example: 415 error: type: "string" description: error message example: Unsupported Media Type message: type: string description: details path: type: string description: The path that caused the error Error500: properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '3001' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client example: 'Internal Server Error' transactionId: type: string description: This is the same transactionId that is sent in the request example: "0d1e1b18-1b6d-4792-8417-72d337f42a1c" timestamp: type: string format: date-time description: Timestamp that the error occurred example: '2021-07-21T17:32:28Z' path: type: string description: The path that caused the error method: type: string description: method used by MADAPI to get the response Error403: type: object properties: statusCode: type: string description: HTTP error code extension example: "6000" statusMessage: type: string description: "Short description of the error" example: "Forbidden" supportMessage: type: string description: "Longer description of the error" example: "Please verify token environment or access token or API key" transactionId: type: string description: "Id for tracing." example: "fg545f-cf4gg4fd55-fdg85hg6"