diff --git a/Sponsored Data API - Presentation.pptx b/Sponsored Data API - Presentation.pptx new file mode 100644 index 0000000..26940f3 Binary files /dev/null and b/Sponsored Data API - Presentation.pptx differ diff --git a/documentation/API proposals/API-proposal-Sponsored_Data.v1.md b/documentation/API proposals/API-proposal-Sponsored_Data.v1.md new file mode 100644 index 0000000..ec824b8 --- /dev/null +++ b/documentation/API proposals/API-proposal-Sponsored_Data.v1.md @@ -0,0 +1,12 @@ +| **Field** | Description | +| ---- | ----- | +| API family name | Sponsored Data | +| API family owner | Telecom Argentina S.A. | +| API summary | The Sponsored Data API enables enterprises to sponsor mobile data traffic for specific subscribers, allowing them to access the internet or use applications without consuming their own data allowance.

This first version of the API is designed for ANY-destination sponsorship, meaning all traffic generated by the user during a sponsorship session is zero-rated. This approach ensures simple implementation and broad applicability across diverse use cases.

Sponsorship applies to a predefined volume of traffic and for a determined time period, ensuring controlled usage according to the campaign parameters.

The API may be extended in future iterations to support targeted sponsorship by destination (e.g., domain, IP, service), allowing operators to restrict sponsorship to specific digital services. | +| Technical viability | This initial version of the Sponsored Data API is technically viable in networks that support the provisioning of secondary data offers (Free Units) with zero rating through the Online Charging System (OCS), which is the function responsible for controlling and rating user data consumption.

The implementation assumes a sponsorship model based on ANY Internet destination, meaning no deep packet inspection (DPI) or destination-specific control is required in the operator's core network.

The API only requires that the OCS be able to manage multiple concurrent data balances per subscriber and apply zero rating specifically to the sponsored volume.

The expiration of the sponsored offer — either due to consumption of the allocated volume or the end of its validity period — is typically managed directly by the OCS.

However, the Sponsored Data API also enables the sponsor to revoke a user’s sponsorship on demand. This allows for more dynamic use cases, such as ending the benefit when the user completes a specific action or no longer meets certain conditions. In such cases, the revocation is triggered via a secure interface from an internal component (e.g., an API Gateway or controller) to the control system.

The solution is compatible with 3GPP Release 13 and above, assuming basic support for OCS-based data rating and quota management. +| Commercial viability | The Sponsored Data API enables a wide range of commercially attractive use cases where a third party (e.g., brand, service provider, public institution) **pays for the mobile data consumption of end users** during defined sessions — without requiring destination-specific control.

Example business cases include:

- **Marketing and loyalty campaigns**: Companies can offer sponsored data sessions as a reward or incentive, e.g., "Get 1 hour of free internet with your purchase", improving customer engagement.

- **Onboarding support**: Telcos and digital service providers can offer free data sessions to new users to explore their platform or access help resources, reducing barriers to adoption.

- **Social or public interest programs**: Governments, NGOs or educational institutions can sponsor general-purpose connectivity for specific populations during critical campaigns or events.

The **ANY-destination approach** simplifies implementation and accelerates time to market, allowing sponsors to offer a frictionless “free connectivity” experience without defining or enforcing traffic filters.

From the operator perspective, the API leverages **existing OCS capabilities** and minimal integration, enabling a **fast and low-cost path to revenue** from new B2B segments.

| +| YAML code available? | YES | +| Validated in lab/productive environments? | NO | +| Validated with real customers? | NO | +| Validated with operators? | NO | +| Supporters in API Backlog Working Group | | diff --git a/sponsored_data_api.v1.yaml b/sponsored_data_api.v1.yaml new file mode 100644 index 0000000..737171b --- /dev/null +++ b/sponsored_data_api.v1.yaml @@ -0,0 +1,1289 @@ +openapi: 3.0.0 +info: + title: Sponsored Data API + version: 1.0.0 + description: | + + Sponsored Data API for OpenGateway/CAMARA Project + + The Sponsored Data API allows sponsoring companies (EPs) to cover the cost of mobile data access for end-users on 4G and 5G networks. This API is part of the Open Gateway/CAMARA initiative and provides a set of operations for the dynamic management of mobile data sponsorship. Sponsoring companies can start or revoke sponsorships for users, as well as query the status of both sponsorship sessions and their campaigns. + [TODO: Pensar si vale la pena poner elegibilidad, balance y pausa de campaña] + The API also allows for the verification of user eligibility for sponsorship and the ability to pause and resume active campaigns. With this API, mobile operators can offer differentiated services that enable innovative business models, providing connectivity at no direct cost to the end-user, with funding provided by a sponsoring entity. + + This service is ideal for advertising campaigns, product promotions, or services. + + Objective of This Initial Version + In this initial version of the API, the sponsorship is proposed for all data traffic (ANY) carried by the user's default bearer, for a specified volume and time, without focusing on a specific destination. + + * Onboarding* + Onboarding is the process by which a Sponsoring Company (EP) contracts a Sponsorship Campaign with the API Gateway Platform (OpenGateway) and the specific Mobile Network Operator (MNO). Initially, this event is supported by the signing of an agreement or documentation outlining the general objectives of the campaign and default sponsorship conditions. For example: + + Type of Campaign: Prepaid or postpaid + Total data volume contracted for prepaid campaigns, e.g., 2000 MB + Campaign validity, e.g., (from/to) or (336 total hours consumed since activation) + Default sponsored data volume for users, e.g., 50 MB + Default sponsorship validity per user, e.g., 10 minutes + Additionally, during this onboarding process, the EP is provided with the "sponsorId" and the specific "campaign_Id". + + * campaignId * + Campaign_ID is a unique identifier assigned to each sponsorship campaign contracted by a Sponsoring Company and assigned during the onboarding process. + + * Traceability - sessionId * + All operations associated with a user (UE) sponsorship are grouped under a session identified by a sessionId. This identifier allows tracking and correlating all interactions within the same sponsorship session. + + * Assignment of Identifiers * + Both, campaign_Id and sessionId, are assigned and managed exclusively by the API Gateway Platforms (OpenGateway) and communicated to both the Sponsoring Companies and the MNOs. CampaignId during the onboarding document signing proccess. And sessionId on real time during each sponsorship operation request. + + * Authorization and Authentication * + The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile. + + The specific authorization flows to be used will be determined during the onboarding process, occurring between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, and subject to the prevailing legal framework dictated by local legislation. + + It is important to note that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. + + * Authorization and Consent Approach * + The Sponsored Data API facilitates user-initiated sponsorship of data services, requiring active user engagement at specific moments via the sponsor’s application. Given the nature of this service, where users must explicitly request sponsorship, the "Authorization Code Flow - Frontend Flow" has been chosen as the authorization and consent method. This flow aligns with the need for secure, direct interaction between the user and the service, ensuring that consent is explicitly provided in a manner that complies with data protection regulations such as GDPR. + + * API Functionality * + This API exposes the following endpoints: NOTE: All of these are REQUIRED for minimal and correct operation unless explicitly indicated otherwise [OPTIONAL OPERATION] + + /sponsorship: Initiates sponsorship and includes a webhook for session-related notifications. With HTTP 201, the Gateway Platform returns the sessionId. + /sponsorship/{sponsorId}/{campaignId}/{sessionId}/session-status: Queries the status of a particular session. Returns session-related data. + /sponsorship/{sponsorId}/{campaignId}/{sessionId}/revoke: Revokes an active sponsorship session. If active, it must be terminated. + /campaign/{sponsorId}/{campaignId}/status: Queries the status of the campaign, returning if it is active, paused, or finished, data balance associated with the campaign, consumed data volume and additional information [OPTIONAL OPERATION] + /campaign/{sponsorId}/{campaignId}/active-sponsorship-list: Queries the list of users currently sponsored by the campaign. [OPTIONAL OPERATION] + /campaign/{sponsorId}/{campaignId}/alert-subscription: Requests subscription to events associated with the campaign. Includes a webhook for notifications. In this version of the API, only consumption thresholds and expiration events are available. [OPTIONAL OPERATION] + /campaign/{sponsorId}/{campaignId}/manage: Allows pausing and reactivating a campaign. During onboarding, it should be defined whether paused periods consume campaign validity time. [OPTIONAL OPERATION] + + * Date and Time Formats * + All date and time values in this API are represented using the ISO 8601 format. For example, '2023-11-22T13:37:00Z' represents November 22, 2023 at 1:37 PM UTC. + + * Roles * + Mobile Network Operators (MNOs): Providers of mobile services that manage network infrastructure and data provisioning. + Sponsoring Companies (SCs): Companies that fund the use of mobile data for their clients or specific users, aiming to offer a no-cost data experience. + API Gateway Operator Platform (OpenGateway level): A gateway with various functions based on best business practices established by OpenGateway. In addition to translation functions, it must track and manage campaigns and sessions established during operation. + Sponsored Users (SU): Mobile network users whose mobile data usage is sponsored by the EPs. + +servers: + - url: "{apiRoot}/sponsored-data/v1.0.0" + variables: + apiRoot: + default: http://localhost:9091 + description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` + +paths: + + /sponsorship: + post: + summary: Start Sponsorship Session Request + description: This operation requests the sponsorship for a subscriber in a specific campaign, allowing them to use sponsored data within the limits set by this request or those defined in the campaign onboarding declaration by default. + operationId: startSponsorship + parameters: + - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-accessToken' + requestBody: + description: Parameters for creating the new sponsorship session + required: true + content: + application/json: + schema: + type: object + properties: + sponsorId: + $ref: '#/components/schemas/sponsorId' + campaignId: + $ref: '#/components/schemas/campaignId' + phoneNumber: + $ref: '#/components/schemas/phoneNumber' + dataVolume: + description: Data volume (in MegaBytes) to be sponsored by the sponsor for the mobile user. If not specified, the default data volume defined in the onboarding rules will apply. + type: integer + minimum: 1 + maximum: 1000 + duration: + description: Duration (in minutes) of the requested sponsorship. If not specified, the duration defined in the onboarding rules will apply. + type: integer + minimum: 1 + maximum: 1440 + webhookUrl: + $ref: '#/components/schemas/webhookUrl' + callbackToken: + description: Security token for authenticating notifications sent to the webhook. + type: string + format: "uuid" + pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" # UUID versión 4 regular expression + required: + - sponsorId + - campaignId + - phoneNumber + - webhookUrl + - callbackToken + callbacks: + notifications: + "{$request.body#/webhookUrl}": + post: + tags: + - Sponsorship notifications callback + summary: "Sponsorship notifications callback" + description: | + This endpoint must be implemented by the API consumer. The sponsorship server will send notifications to this URI when a sponsorship ends, providing the reason for termination and session details + operationId: notifySponsorshipEnd + parameters: + - $ref: "#/components/parameters/x-correlator" + - $ref: "#/components/parameters/x-callbackToken" + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/SponsorshipEndNotification" + responses: + "204": + description: Successful notification + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "410": + $ref: "#/components/responses/Generic410" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + responses: + '201': + description: Successful operation. New sponsorship session created. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + type: object + properties: + sponsorId: + $ref: '#/components/schemas/sponsorId' + campaignId: + $ref: '#/components/schemas/campaignId' + sessionId: + $ref: '#/components/schemas/sessionId' + startTime: + $ref: "#/components/schemas/time" + endTime: + $ref: "#/components/schemas/time" + description: | + End date and time of the sponsorship. + Calculated by adding the specified sponsorship duration to the start time (startTime). + If duration is not specified, the default value defined in the onboarding campaign profile is used. + sponsoredDataVolume: + description: The assigned data volume for the user. This value is derived from either the sponsorship request or, if not specified in the request, from the default value defined in the campaign profile during onboarding. + type: integer + minimum: 1 + maximum: 1000 + required: + - sponsorId + - campaignId + - sessionId + - startTime + - endTime + - sponsoredDataVolume + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "405": + $ref: "#/components/responses/Generic405" + "406": + $ref: "#/components/responses/Generic406" + "415": + $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "502": + $ref: "#/components/responses/Generic502" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + + /sponsorship/{sponsorId}/{campaignId}/{sessionId}/session-status: + get: + summary: Sponsorship Session Status Inquiry + description: | + Queries detailed information about a sponsorship session for a specific campaign and sponsor. + NOTES: + The access token for this query must be a 2-legged token, and the sponsor must have been previously authorized with a 3-legged token at the time of session initiation. + The session must have been created by the same API client indicated in the access token. + operationId: getSessionStatus + parameters: + - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-accessToken' + - name: sponsorId + in: path + required: true + schema: + $ref: '#/components/schemas/sponsorId' + - name: campaignId + in: path + required: true + schema: + $ref: '#/components/schemas/campaignId' + - name: sessionId + in: path + required: true + schema: + $ref: '#/components/schemas/sessionId' + responses: + "200": + description: Contains information about the sponsorship session + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + type: object + properties: + sponsorId: + $ref: '#/components/schemas/sponsorId' + campaignId: + $ref: '#/components/schemas/campaignId' + sessionId: + $ref: '#/components/schemas/sessionId' + phoneNumber: + $ref: "#/components/schemas/phoneNumber" + startTime: + $ref: "#/components/schemas/time" + description: Date and time when the sponsorship started. + endTime: + $ref: "#/components/schemas/time" + description: Date and time when the session expires if it is still active, or the end time if the session concluded due to data volume exhaustion. + sessionStatus: + description: Indicates whether the session is active or inactive. + enum: + - active + - inactive + dataVolumeConsumed: + description: Volume of data consumed in the session. (MBytes) + type: integer + dataVolumeAvailable: + description: Volume of remaining available data in the session. (MBytes) + type: integer + endReason: + description: Reason for session termination, if it is no longer active. + enum: + - validity_expired + - data_exhausted + - session_revoked + - not_available + required: + - phoneNumber + - startTime + - endTime + - sessionActive + - dataVolumeConsumed + - dataVolumeAvailable + examples: + session_active: + description: Session still active + value: + sponsorId: "3fa85f64-5717-4562-b3fc-2c963f66afaf@company.com" + campaignId: "3fa85f64-5717-4562-b3fc-2c963f663faf@company.com" + sessionId: "3fa85f64-5717-4562-b3fc-2c963f66afa6@company.com" + phoneNumber: "+541149924576" + startTime: "2024-09-01T12:00:00Z" + endTime: "2024-09-01T14:00:00Z" + sessionStatus: "active" + dataVolumeConsumed: 60 + dataVolumeAvailable: 40 + endReason: not_available + session_inactive: + description: Session still active + value: + sponsorId: "3fa85f64-5717-4562-b3fc-2c963f66afaf@company.com" + campaignId: "3fa85f64-5717-4562-b3fc-2c963f663faf@company.com" + sessionId: "3fa85f64-5717-4562-b3fc-2c963f66afa6@company.com" + phoneNumber: "+541149924576" + startTime: "2024-09-01T12:00:00Z" + endTime: "2024-09-01T13:03:00Z" + sessionStatus: "active" + dataVolumeConsumed: 100 + dataVolumeAvailable: 0 + endReason: data_exhausted + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "405": + $ref: "#/components/responses/Generic405" + "406": + $ref: "#/components/responses/Generic406" + "415": + $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "502": + $ref: "#/components/responses/Generic502" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + + /sponsorship/{sponsorId}/{campaignId}/{sessionId}/revoke: + delete: + summary: Revocation of Sponsorship + description: This operation revokes an active sponsorship, preventing further use of sponsored data for the subscriber. + operationId: revokeSponsorship + parameters: + - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-accessToken' + - name: sponsorId + in: path + required: true + schema: + $ref: '#/components/schemas/sponsorId' + - name: campaignId + in: path + required: true + schema: + $ref: '#/components/schemas/campaignId' + - name: sessionId + in: path + required: true + schema: + $ref: '#/components/schemas/sessionId' + responses: + '200': + description: Session revoked successfully + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + type: object + properties: + sponsorId: + $ref: '#/components/schemas/sponsorId' + campaignId: + $ref: '#/components/schemas/campaignId' + sessionId: + $ref: '#/components/schemas/sessionId' + phoneNumber: + $ref: "#/components/schemas/phoneNumber" + startTime: + $ref: "#/components/schemas/time" + description: Date and time when the sponsorship started. + endTime: + $ref: "#/components/schemas/time" + description: Date and time when the sponsorship finished. + requestResult: + type: string + enum: + - successful_revocation + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "405": + $ref: "#/components/responses/Generic405" + "406": + $ref: "#/components/responses/Generic406" + "415": + $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "502": + $ref: "#/components/responses/Generic502" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + + /campaign/{sponsorId}/{campaignId}/campaign-status: + get: + summary: Campaign Status Inquiry [active, paused, concluded], data volume balance. + operationId: getCampaignStatus + parameters: + - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-accessToken' + - name: sponsorId + in: path + required: true + schema: + $ref: '#/components/schemas/sponsorId' + - name: campaignId + in: path + required: true + schema: + $ref: '#/components/schemas/campaignId' + responses: + '200': + description: Returns the status of the campaign + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + type: object + properties: + sponsorId: + $ref: '#/components/schemas/sponsorId' + campaignId: + $ref: '#/components/schemas/campaignId' + status: + type: string + description: Current status of the campaign (e.g., "active", "paused", "completed"). + enum: + - active # The campaign is currently ongoing. + - paused # The campaign is temporarily halted. Active sponsorships continue until completion, and the campaign's duration does not extend due to this pause. + - completed #The campaign has finished successfully, either because all contracted data has been consumed or the time limit has been reached. This status could be sufficient to indicate that the campaign has ended. + - not_available + startTime: + $ref: "#/components/schemas/time" + description: Date and time when the campaign started. + endTime: + $ref: "#/components/schemas/time" + description: Date and time when the campaign expires if it is still active, or the end time if the campaign concluded due to data volume exhaustion. + campaignType: + description: Indicates whether the campaign is prepaid or postpaid + type: string + enum: + - prepaid + - postpaid + contractedDataVolume: + type: integer + description: Total data volume contracted for the campaign in MegaBytes. + usedDataVolume: + type: integer + description: Total data volume consumed in the campaign, in megabytes (MB), as allocated for sponsorships. + remainingDataVolume: + type: integer + description: Remaining data volume available for the campaign in MegaBytes. + completionReason: + type: string + description: Reason for completion (e.g., "time expired", "data exhausted"). + enum: + - time_expired + - data_exhausted + - not_available # if the campaign is still active or paused + required: + - sponsorId + - campaignId + - status + - startTime + - endTime + - contractedDataVolume + - usedDataVolume + - remainingDataVolume + - completionReason + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "405": + $ref: "#/components/responses/Generic405" + "406": + $ref: "#/components/responses/Generic406" + "415": + $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "502": + $ref: "#/components/responses/Generic502" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + + /campaign/{sponsorId}/{campaignId}/active-sponsorship-list: + get: + summary: Query of Active Sponsorships + operationId: getActiveSponsorships + parameters: + - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-accessToken' + - name: sponsorId + in: path + description: Sponsor ID + required: true + schema: + $ref: '#/components/schemas/sponsorId' + - name: campaignId + in: path + description: ID de la campaña + required: true + schema: + $ref: '#/components/schemas/campaignId' + responses: + '200': + description: List of users currently sponsored by the campaign. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + type: object + properties: + sponsorId: + $ref: '#/components/schemas/sponsorId' + campaignId: + $ref: '#/components/schemas/campaignId' + activeSponsorships: + type: array + items: + type: object + properties: + sessionId: + $ref: '#/components/schemas/sessionId' + phoneNumber: + $ref: "#/components/schemas/phoneNumber" + totalCount: + description: Total number of sponsored subscribers currently. + type: integer + example: 5000 + example: + sponsorId: "3fa85f64-5717-4562-b3fc-2c963f66afaf@company.com" + campaignId: "3fa85f64-5717-4562-b3fc-2c963f663faf@company.com" + activeSponsorships: + - sessionId: "3fa85f64-5717-4562-b3fc-2c963f66afa6@company.com" + phoneNumber: "+541100000001" + - sessionId: "3fa85f64-5717-4562-b3fc-2c967f66afa6@company.com" + phoneNumber: "+541100000002" + - sessionId: "3fa85f64-5717-4562-b3fc-2c953f66afa6@company.com" + phoneNumber: "+541100000003" + totalCount: 3 + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "405": + $ref: "#/components/responses/Generic405" + "406": + $ref: "#/components/responses/Generic406" + "415": + $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "502": + $ref: "#/components/responses/Generic502" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + + /campaign/{sponsorId}/{campaignId}/alert-subscription: + post: + summary: Campaigns - Subscription to Alert y Notifications + description: > + This operation enables Sponsors (EPs) to subscribe to receive notifications related to campaigns. With the subscription, the EP provides a webhook URL and a token, which will be used by the API Gateway to send notifications related to the campaign. + In this API version, only two types of alerts are provided: + - Notification for consuming more than 80% of the contracted data volume. + - Notification for campaign validity expiration. + - Notification for campaign data volume exhausted. + - Alerts for network failures will be addressed in future versions. + operationId: configureAlerts + parameters: + - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-accessToken' + - name: sponsorId + in: path + required: true + schema: + $ref: '#/components/schemas/sponsorId' + - name: campaignId + in: path + required: true + schema: + $ref: '#/components/schemas/campaignId' + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + webhookUrl: + $ref: '#/components/schemas/webhookUrl' + callbackToken: + type: string + description: Security token to authenticate notifications sent to the webhook. + alertDataVolumeThresholds: + type: boolean + description: Indicates whether a notification should be sent when data consumption exceeds 80% of the contracted amount (applicable for prepaid campaigns).. + example: true + campaignExpiryNotification: + type: boolean + description: Indicates whether a notification should be sent when the campaign expires. + example: true + dataVolumeExhausted: + type: boolean + description: Indicates whether a notification should be sent when the campaign data volume is exhausted. + example: true + callbacks: + notifications: + "{$request.body#/webhookUrl}": + post: + tags: + - Campaign notifications callback + summary: "Callback definition for campaign notifications (webhookUrl)" + description: > + This endpoint must be implemented by the API consumer. The server will send notifications to this URL with the token provided in the subscription to authenticate the request. + operationId: notifyCampaignEvent + parameters: + - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-callbackToken' + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CampaignNotification" + responses: + "204": + description: Successful notification + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + type: object + properties: + sponsorId: + $ref: '#/components/schemas/sponsorId' + campaignId: + $ref: '#/components/schemas/campaignId' + notifications: + enum: + - alertDataVolumeThresholds + - campaignExpiryNotification + - dataVolumeExhausted + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "410": + $ref: "#/components/responses/Generic410" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + responses: + '200': + description: Campaign notifications subscription - SUCCESS + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + type: object + properties: + sponsorId: + $ref: '#/components/schemas/sponsorId' + campaignId: + $ref: '#/components/schemas/campaignId' + requestResult: + type: string + example: "Campaign notifications subscription - SUCCESS" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "405": + $ref: "#/components/responses/Generic405" + "406": + $ref: "#/components/responses/Generic406" + "415": + $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "502": + $ref: "#/components/responses/Generic502" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + + /campaign/management: + post: + summary: Campaign Management + description: > + This operation allows pausing or resuming a campaign based on the action parameter provided in the request body. The possible values for action are: + - PAUSE to temporarily halt new sponsorships (ongoing sponsorships will continue until completion). + - RESUME to reactivate the campaign. + If the campaign has already ended, the API will respond with a 400 error, indicating that the campaign is finished and cannot be modified. Pausing a campaign does not extend its end date or overall duration. + operationId: manageCampaign + parameters: + - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-accessToken' + requestBody: + description: Parameters to manage the campaign. + required: true + content: + application/json: + schema: + type: object + properties: + sponsorId: + $ref: '#/components/schemas/sponsorId' + campaignId: + $ref: '#/components/schemas/campaignId' + action: + type: string + enum: + - pause + - resume + description: "The action to be performed on the campaign. It can be 'PAUSE' to pause or 'RESUME' to resume." + responses: + '200': + description: Successful operation + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + type: object + properties: + requestResult: + type: string + example: "CAMPAIGN PAUSED SUCCESSFULLY or CAMPAIGN RESUMED SUCCESSFULLY" + sponsorId: + $ref: '#/components/schemas/sponsorId' + campaignId: + $ref: '#/components/schemas/campaignId' + startTime: + $ref: "#/components/schemas/time" + description: The timestamp indicating when the requested action (PAUSE or RESUME) on the campaign takes effect (in ISO 8601 format). + status: + type: string + description: Current status of the campaign (e.g., "active", "paused", "completed"). + enum: + - paused + - resumed + - completed + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "405": + $ref: "#/components/responses/Generic405" + "406": + $ref: "#/components/responses/Generic406" + "415": + $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "502": + $ref: "#/components/responses/Generic502" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + +components: + + parameters: + x-correlator: + name: x-correlator + in: header + description: Correlation identifier in UUID version 4 format + required: true + schema: + type: string + format: "uuid" + pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" # UUID versión 4 regular expression + x-accessToken: + name: accessToken + in: header + description: Access token for the Sponsor. + required: true + schema: + type: string + x-callbackToken: + name: x-callbackToken + in: header + description: | + Security token for authenticating the notification. It must match the value provided in the callbackToken field of the initial sponsorship request body. + required: true + schema: + type: string + format: uri + example: https://tonys-server.com + headers: + x-correlator: + required: true + schema: + type: string + format: "uuid" + pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" + schemas: + sponsorId: + type: string + description: Unique sponsor identifier, assigned by the API GW Platform operator. Should include a domain associated with the company for easy recognition. + pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" # Excample 'ID@sponsor_domain.com' + campaignId: + type: string + description: "Unique identifier for the campaign, including a UUID and the sponsor's domain." + 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}@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" # Example "UUID@sponsor_domain.com" + phoneNumber: + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: "+123456789" + sessionId: + description: Unique session identifier, assigned by the API GW Platform operator. Should include a domain associated with the company for easy recognition. + type: string + format: uuid + 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}@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" # Example "UUID@sponsor_domain.com" + CampaignNotification: + type: object + properties: + api_version: + description: Data Sponsored API Version (must be 1.0.0) + type: string + enum: + - '1.0.0' + datacontenttype: + description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' + type: string + enum: + - 'application/json' + sponsorId: + $ref: '#/components/schemas/sponsorId' + campaignId: + type: string + description: "Identificador de la campaña." + eventType: + type: string + description: "Tipo de evento que desencadenó la notificación." + enum: + - DATA_VOLUME_THRESHOLD_EXCEEDED (80%) + - DATA_VOLUME_EXHASTED + - CAMPAIGN_EXPIRED + timestamp: + type: string + format: date-time + description: "Fecha y hora en que ocurrió el evento." + ErrorInfo: + description: The error object used for error-cases. + type: object + required: + - status + - code + - message + properties: + status: + type: integer + description: HTTP response status code + code: + type: string + description: Code given to this error + message: + type: string + description: Detailed error description + webhookUrl: + type: string + format: url + description: The URL to which notifications about session status changes will be sent using the HTTP protocol. (e.g., session termination) + example: "https://sponsor.endpoint.example.com/webhook" + SponsorshipEndNotification: + type: object + properties: + api_version: + description: Data Sponsored API Version (must be 1.0.0) + type: string + enum: + - '1.0.0' + datacontenttype: + description: media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs + type: string + enum: + - 'application/json' + sponsorId: + $ref: '#/components/schemas/sponsorId' + campaignId: + $ref: '#/components/schemas/campaignId' + sessionId: + $ref: '#/components/schemas/sessionId' + reason: + type: string + description: Reason for the termination of the sponsorship. + enum: + - EXPIRED + - TERMINATED_BY_SPONSOR + - DATA_EXHAUSTED + - USER_DEREGISTERED + - NOT_AVAILABLE + endTimestamp: + type: string + format: date-time + description: Date and time when the sponsorship session ended. + time: + description: Exact time in ISO 8601 format. + type: string + format: date-time + example: "2024-08-20T14:34:56Z" + responses: + Generic400: + description: Problem with the client request + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + Generic401: + description: Unauthorized + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. + Generic403: + description: | + Client does not have sufficient permission. + In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist: + - Phone number cannot be deducted from access token context.(`{"code": "INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`) + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + examples: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + GENERIC_403_INVALID_TOKEN_CONTEXT: + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: "{{field}} is not consistent with access token." + Generic404: + description: Resource Not Found + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + NOT_FOUND: + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found + DEVICE_IDENTIFIER_NOT_FOUND: + value: + status: 404 + code: DEVICE_NOT_FOUND + message: Some identifier cannot be matched to a device + Generic405: + description: Method Not Allowed + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_405_METHOD_NOT_ALLOWED: + description: Invalid HTTP verb used with a given endpoint + value: + status: 405 + code: METHOD_NOT_ALLOWED + message: The requested method is not allowed/supported on the target resource. + Generic406: + description: Not Acceptable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_406_NOT_ACCEPTABLE: + description: API Server does not accept the media type (`Accept-*` header) indicated by API client + value: + status: 406 + code: NOT_ACCEPTABLE + message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_410_GONE: + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + value: + status: 410 + code: GONE + message: Access to the target resource is no longer available. + Generic415: + description: Unsupported Media Type + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_415_UNSUPPORTED_MEDIA_TYPE: + description: Payload format of the request is in an unsupported format by the Server. Should not happen + value: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: The server refuses to accept the request because the payload format is in an unsupported format. + Generic422: + description: Unprocessable Entity + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + description: Inconsistency between device identifiers not pointing to the same device + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Provided device identifiers are not consistent. + GENERIC_422_DEVICE_NOT_APPLICABLE: + description: Service is not available for the provided device + value: + status: 422 + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. + GENERIC_422_UNABLE_TO_PROVIDE_REACHABILITY_STATUS: + value: + status: 422 + code: UNABLE_TO_PROVIDE_REACHABILITY_STATUS + message: Network issue - Unable to provide reachability status + GENERIC_422_UNSUPPORTED_DEVICE_IDENTIFIERS: + value: + status: 422 + code: UNSUPPORTED_DEVICE_IDENTIFIERS + message: None of the provided device identifiers is supported by the implementation + Generic429: + description: Too Many Requests + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_429_QUOTA_EXCEEDED: + description: Request is rejected due to exceeding a business quota limit + value: + status: 429 + code: QUOTA_EXCEEDED + message: Either out of resource quota or reaching rate limiting. + GENERIC_429_TOO_MANY_REQUESTS: + description: API Server request limit is overpassed + value: + status: 429 + code: TOO_MANY_REQUESTS + message: Either out of resource quota or reaching rate limiting. + Generic500: + description: Internal Server Error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. + Generic501: + description: Not Implemented + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_501_NOT_IMPLEMENTED: + description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations + value: + status: 501 + code: NOT_IMPLEMENTED + message: This functionality is not implemented yet. + Generic502: + description: Bad Gateway + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_502_BAD_GATEWAY: + description: Internal routing problem in the Server side that blocks to manage the service properly + value: + status: 502 + code: BAD_GATEWAY + message: An upstream internal service cannot be reached. + Generic503: + description: Service Unavailable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_503_UNAVAILABLE: + description: Service is not available. Temporary situation usually related to maintenance process in the server side + value: + status: 503 + code: UNAVAILABLE + message: Service Unavailable. + Generic504: + description: Gateway Timeout + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_504_TIMEOUT: + description: API Server Timeout + value: + status: 504 + code: TIMEOUT + message: Request timeout exceeded.