{
  "swagger": "2.0",
  "info": {
    "title": "Bonus Offer Catalog",
    "description": "API for managing bonus offers within the Gamanza Engage platform. This service allows operators to synchronize their bonus catalogs and link offers to gamification mechanics and CRM campaigns.",
    "version": "1.0"
  },
  "tags": [
    {
      "name": "PlatformAPIBonusCatalogController"
    }
  ],
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/rx-api/bonus-offer/v1/offer/{bonusOfferId}": {
      "delete": {
        "summary": "Deletes a bonus offer from the Gamanza Engage platform",
        "description": "This endpoint allows operators to remove a bonus offer from the Gamanza Engage catalog using the operator's unique identifier (bonusOfferId).\n\nOnce deleted, the bonus offer will no longer be available for linking to gamification mechanics (e.g., mission rewards, tournament prizes, or loyalty shop items) or CRM campaigns.\n\n**Important:** Deleting a bonus offer does not affect bonuses that have already been awarded to players. This operation only removes the offer from the catalog, preventing future usages in other mechanics.\n\n**Soft Delete Mechanism:** This operation performs a soft delete. The bonus offer is marked as deleted in the database but remains physically present for 30 days. After this retention period, the record is automatically purged from the database using MongoDB's TTL (Time-To-Live) index mechanism.",
        "operationId": "PlatformAPIBonusCatalogController_deleteBonusOffer",
        "responses": {
          "204": {
            "description": "No Content",
            "schema": {}
          },
          "400": {
            "description": "400 (BAD REQUEST) error with some field in the request",
            "schema": {
              "$ref": "#/definitions/ResponseHttpErrorResponse"
            }
          },
          "401": {
            "description": "401 Unauthorized",
            "schema": {}
          },
          "500": {
            "description": "500 (Error) Internal server Error",
            "schema": {}
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "bonusOfferId",
            "description": "The unique identifier for the bonus offer as defined in the operator's external system (source of truth). This is used as the primary reference for delete operation.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "timestamp": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The ISO-8601 timestamp indicating when this bonus offer was deleted in the operator's system."
                }
              },
              "required": [
                "timestamp"
              ]
            }
          },
          {
            "name": "x-authorization",
            "description": "The client needs to authenticate themselves for this request. The auth request return a valid JWT access token",
            "in": "header",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "PlatformAPIBonusCatalogController"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      },
      "put": {
        "summary": "Creates a new bonus offer or updates an existing one within the Gamanza Engage platform (Upsert)",
        "description": "This endpoint allows operators to seamlessly synchronize their catalog of bonus offers with Gamanza Engage. It is designed to act as an idempotent `upsert` (update or insert) operation, relying on the operator's own unique identifier (bonusOfferId) as the source of truth.\n\n - Create (Insert): If the {bonusOfferId} does not currently exist within the Gamanza Engage database, the system will ingest the payload and create a brand-new bonus offer.\n - Update: If a bonus offer associated with the {bonusOfferId} already exists, the system will overwrite the existing configuration with the new data provided in the request body.\n\nBy maintaining an up-to-date catalog of the operator's available bonuses via this endpoint, Gamanza Engage can effectively link these external bonus offers to internal platform features, such as gamification mechanics (e.g., mission rewards, tournament prizes, or loyalty shop items) and targeted CRM campaigns.",
        "operationId": "PlatformAPIBonusCatalogController_upsertBonusOffer",
        "responses": {
          "202": {
            "description": "Accepted",
            "schema": {}
          },
          "400": {
            "description": "400 (BAD REQUEST) error with some field in the request",
            "schema": {
              "$ref": "#/definitions/ResponseHttpErrorResponse"
            }
          },
          "401": {
            "description": "401 Unauthorized",
            "schema": {}
          },
          "500": {
            "description": "500 (Error) Internal server Error",
            "schema": {}
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "bonusOfferId",
            "description": "The unique identifier for the bonus offer as defined in the operator's external system (source of truth). This is used as the primary reference for upsert operations.",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "The human-readable name of the bonus offer (e.g., 'Welcome Deposit Match', 'Summer Free Spins'). Used for display purposes in CRM and gamification UIs."
                },
                "status": {
                  "$ref": "#/definitions/BonusOfferCatalogBonusOfferStatus",
                  "description": "The current operational state of the bonus offer. ACTIVE indicates the offer can currently be awarded or interacted with. INACTIVE indicates the offer is disabled, expired, or archived."
                },
                "category": {
                  "$ref": "#/definitions/BonusOfferCatalogBonusOfferCategory",
                  "description": "The category object assigned to this bonus offer. Crucial for enforcing regulatory limits and calculating thresholds."
                },
                "bonusOfferType": {
                  "type": "string",
                  "description": "An optional classification of the bonus mechanics (e.g., 'bonus_money', 'deposit_match', 'free_spins', 'cashback'). Helps the Gamanza Engage system determine how the bonus should be tracked and analytics."
                },
                "currency": {
                  "type": "string",
                  "description": "The 3-letter ISO 4217 currency code (e.g., 'EUR', 'CHF', 'USD') associated with the valueInCurrency field. This specifies the base currency of the bonus offer, which is essential for accurate cross-currency conversions when enforcing regulatory thresholds or awarding gamification mechanics. If no defined the platform sets the Default currency configured in the Gamanza Engage Platform."
                },
                "valueInCurrency": {
                  "type": "string",
                  "description": "Defines the absolute monetary value of the bonus in the referenced currency. This field is represented as a string to guarantee exact precision over the network and avoid floating-point calculation errors. The value must be a valid numeric string using a dot ('.') strictly as the decimal separator. Thousands separators are not allowed (e.g., send '1500.50' instead of '1,500.50' or '1.500,50')."
                },
                "timestamp": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The ISO-8601 timestamp indicating when this bonus offer was created or last updated in the operator's system."
                },
                "keywords": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "A list of tags or keywords associated with the bonus (e.g., ['VIP', 'sportsbook', 'retention']). Useful for filtering, searching, or targeting specific CRM campaigns within Gamanza Engage."
                }
              },
              "description": "Represents a standardized bonus campaign or offer ingested from an operator's external system to be linked with Gamanza Engage gamification and CRM mechanics.",
              "required": [
                "name",
                "status",
                "timestamp"
              ]
            }
          },
          {
            "name": "x-authorization",
            "description": "In order to provide a proper API integration, the Gamanza Engage support the following authentication methods that should be implemented by the Operators platform: API Key (API Key value) or Client Credentials (accessToken)",
            "in": "header",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "PlatformAPIBonusCatalogController"
        ],
        "security": [
          {
            "OAuth2": []
          }
        ]
      }
    }
  },
  "definitions": {
    "BonusOfferCatalogBonusOfferCategory": {
      "type": "object",
      "properties": {
        "categoryId": {
          "type": "string",
          "description": "The unique identifier for the regulatory category. This ID must link directly to the system settings where the actual monetary limits and timeframes (e.g., yearly limits) are defined."
        },
        "name": {
          "type": "string",
          "description": "The optional human-readable name of the category (e.g., 'Regular Bonus', 'Discount Bonus')."
        }
      },
      "description": "Defines the category of the bonus offer. This is a critical component for system scalability and regulatory compliance, allowing the platform to support and enforce multiple configurable thresholds based on the category type (e.g., limiting 'Regular Bonus' to 100 EUR/year and 'Discount Bonus' to 50 EUR/year).",
      "required": [
        "categoryId"
      ]
    },
    "BonusOfferCatalogBonusOfferStatus": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "INACTIVE"
      ],
      "default": "ACTIVE"
    },
    "HttpResponseDetails": {
      "type": "object",
      "properties": {
        "faultCode": {
          "type": "integer",
          "format": "int32"
        },
        "fields": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/ResponseField"
          }
        }
      }
    },
    "ResponseField": {
      "type": "object",
      "properties": {
        "field": {
          "type": "string"
        },
        "error": {
          "type": "string"
        }
      }
    },
    "ResponseHttpErrorResponse": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        },
        "request": {
          "$ref": "#/definitions/ResponseRequest"
        },
        "details": {
          "$ref": "#/definitions/HttpResponseDetails"
        },
        "timestamp": {
          "type": "string"
        }
      }
    },
    "ResponseRequest": {
      "type": "object",
      "properties": {
        "xRequestId": {
          "type": "string"
        },
        "sourceIp": {
          "type": "string"
        },
        "method": {
          "type": "string"
        },
        "uri": {
          "type": "string"
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        }
      }
    },
    "protobufAny": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    },
    "rpcStatus": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/protobufAny"
          }
        }
      }
    }
  },
  "securityDefinitions": {
    "OAuth2": {
      "type": "oauth2",
      "description": "The client needs to authenticate themselves for this request. The auth request return a valid JWT access token",
      "flow": "application",
      "tokenUrl": "https://platform-api-{customer-instance-id}.gamanzaengage.com/api/oauth/v1/token"
    }
  }
}