openapi: 3.0.1
info:
  title: Push Notification Channel Service API Specification
  description: |
    This page describes how to integrate with the **Push Notification Channel Service** on a technical level.

    This service is a specialized downstream service, typically called by the central Notification Service. Its sole
    responsibility is to handle the formatting and dispatching of push notifications to mobile and web clients (e.g., via
    FCM).

    -----

    ## REST Resources

    The Push Notification Channel Service provides a single resource for sending a **push notification**.

    ### The Push Notification Resource

    A **push notification** request defines the content to be "pushed" to a user's device. It consists of:
    * **`reference`**: A unique ID for tracking this specific send request.
    * **`token`**: The device-specific push token (e.g., an FCM registration token).
    * **`title`**: The title of the notification.
    * **`body`**: The main message content of the notification.
    * **`appName`**: The target application (e.g., "Banqup").
    * **`data`**: An optional key-value map for sending custom data payloads.

    An example of a **push notification request** in JSON format:

    ```json
    {
      "reference": "push_ref_778899_def",
      "token": "eEd-LqO...8d1sF-j",
      "title": "New Invoice Received",
      "body": "You have received a new invoice (INV-2025-0043) from Acme Corp.",
      "appName": "Banqup",
      "deviceType": "PHONE",
      "data": {
        "documentId": "b1a4c2a0-4f5c-4b3d-811c-9e2b6a4a1f2c",
        "action": "view_invoice"
      }
    }
    ```

    When this push notification is successfully queued for sending, the service returns a unique **notificationId**:

    ```json
    {
      "notificationId": "f4b3c2a1-9e8d-4f6c-8a7b-1d2e3c4b5a6d"
    }
    ```

    -----

    ## Sending a Push Notification

    To send a new push notification, you'll perform a **POST** request to the [**/core/pushnotification/v1/pushnotifications
    **](../../../docs/communication/push_notification/send-push-notification) endpoint, providing the full push
    notification object in the request body.

    ```http
    POST /v1/pushnotifications
    Content-Type: application/json

    {
      "reference": "push_ref_778899_def",
      "token": "eEd-LqO...8d1sF-j",
      "title": "New Invoice Received",
      "body": "You have received a new invoice (INV-2025-0043) from Acme Corp.",
      "appName": "Banqup",
      "deviceType": "PHONE"
    }
    ```

    A successful response (HTTP `202 Accepted`) will return the `notificationId` confirming the push notification has
    been accepted for delivery.

    -----

    ## Security

    Access to send push notifications is controlled by the **`push_notification_send`** security scope. All requests to
    the Push Notification Channel API must be authenticated using an OAuth security scheme and include a token with the
    required scope.
  version: 2.1.22
servers:
- description: ''
  url: https://api.btx.fr.banqup.com/platform/pushnotification
- description: ''
  url: https://api.btx.eu.banqup.com/platform/pushnotification
paths: {}
components:
  schemas:
    Notification:
      required:
      - body
      - title
      type: object
      properties:
        title:
          minLength: 1
          type: string
          description: The title of the notification
        body:
          minLength: 1
          type: string
          description: The body content of the notification
      description: Object containing notification details
    Option:
      required:
      - collapse
      - priority
      - ttl
      type: object
      properties:
        ttl:
          type: integer
          description: Time to live in seconds
          format: int32
        collapse:
          maxLength: 64
          minLength: 0
          type: string
          description: Collapse key for message deduplication
        priority:
          $ref: '#/components/schemas/Priority'
      description: Object containing additional data
    Priority:
      type: string
      description: Delivery priority
      example: NORMAL
      enum:
      - NORMAL
      - HIGH
    PushNotification:
      required:
      - reference
      type: object
      properties:
        reference:
          minLength: 1
          type: string
        recipient:
          $ref: '#/components/schemas/Recipient'
        notification:
          $ref: '#/components/schemas/Notification'
        data:
          type: object
          additionalProperties:
            type: object
            description: Object containing additional data
          description: Object containing additional data
        option:
          $ref: '#/components/schemas/Option'
    Recipient:
      required:
      - fcmToken
      type: object
      properties:
        fcmToken:
          minLength: 1
          type: string
          description: FCM Token
    PushNotificationResponse:
      required:
      - notificationId
      type: object
      properties:
        notificationId:
          minLength: 1
          type: string
          format: uuid
    ApiErrorProblemDetail:
      required:
      - error
      - requestId
      - timestamp
      type: object
      properties:
        status:
          type: integer
          format: int32
        error:
          type: string
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          format: uri
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
          format: uri
        problems:
          type: array
          items:
            $ref: '#/components/schemas/NestedProblem'
        properties:
          type: object
          additionalProperties:
            type: object
    NestedProblem:
      required:
      - detail
      - error
      - title
      type: object
      properties:
        error:
          type: string
        title:
          type: string
        detail:
          type: string
        type:
          type: string
          format: uri
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.btx.fr.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.btx.fr.banqup.com/oauth2/auth
          tokenUrl: https://api.btx.fr.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
