openapi: 3.0.0
info:
  title: premiumpay API for data
  version: 1.0.0
  description: >-
    API to obtain data about sales and channel performance All POST endpoints
    require a valid JWT token to be included in the Authorization header and a
    header X-client-id with the client_id provided by premiumpay.
servers:
  - url: https://dev.premiumpay.pro/datosapi/{basePath}
    variables:
      basePath:
        default: v1
    description: Developing server
  - url: https://api.premiumpay.pro/datosapi/{basePath}
    variables:
      basePath:
        default: v1
    description: Production server
tags:
  - name: version
    description: Version of the API
  - name: server
    description: Server status
  - name: data
    description: Data endpoints
  - name: bots
    description: Bots endpoints
paths:
  /version:
    get:
      tags:
        - version
      operationId: api.getVersion
      summary: api version
      description: Return the current version of the API
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                properties:
                  status:
                    type: string
                    enum:
                      - ok
                      - ko
                  version:
                    $ref: '#/components/schemas/Version'
                additionalProperties: false
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /status:
    post:
      tags:
        - server
      operationId: api.status
      summary: status of api server
      description: Return the status of the server and the rate limit of the user
      security:
        - jwt: []
      parameters:
        - in: header
          name: X-client-id
          schema:
            type: string
            maxLength: 50
          required: true
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/BadJson'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /sales:
    post:
      tags:
        - data
      summary: sales data
      description: >-
        Retrieve sales data for a period. The request must include the
        start_date_time and end_date_time parameters and the pasarela_id
        parameter (gateway id). The service_id parameter is optional. If the
        service_id parameter is included, the request will return the sales of
        the service. If the service_id parameter is not included, the request
        will return the sales of all the services belonging the gateway.
      security:
        - jwt: []
      parameters:
        - in: header
          name: X-client-id
          schema:
            type: string
            maxLength: 50
          required: true
      requestBody:
        content:
          application/json:
            schema:
              required:
                - start_date_time
                - end_date_time
              type: object
              properties:
                start_date_time:
                  type: string
                  format: date-time
                end_date_time:
                  type: string
                  format: date-time
                pasarela_id:
                  type: integer
                service_id:
                  type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/BadJson'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /gateways:
    post:
      tags:
        - data
      summary: gateways list
      description: >-
        Retrieve list of gateways. The request must include the include_services
        parameter. If the include_services parameter is 'yes', the request will
        return the services of the gateway. If the include_services parameter is
        not included or have another value, the request will return the gateways
        without services list.
      security:
        - jwt: []
      parameters:
        - in: header
          name: X-client-id
          schema:
            type: string
            maxLength: 50
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                include_services:
                  type: string
                  enum:
                    - 'yes'
                    - 'no'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Gateway'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/BadJson'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /aggregatesales:
    post:
      tags:
        - data
      summary: aggregated sales for a period
      description: >-
        Retrieve aggregated sales data for a period. The request must include
        the start_date_time and end_date_time parameters and the aggregate_field
        parameter. The aggregate_field parameter can be 'country',
        'payment_method' or 'service'.
      security:
        - jwt: []
      parameters:
        - in: header
          name: X-client-id
          schema:
            type: string
            maxLength: 50
          required: true
      requestBody:
        content:
          application/json:
            schema:
              required:
                - start_date_time
                - end_date_time
              type: object
              properties:
                start_date_time:
                  type: string
                  format: date-time
                end_date_time:
                  type: string
                  format: date-time
                aggregate_field:
                  type: string
                  enum:
                    - country
                    - payment_method
                    - service
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - $ref: '#/components/schemas/Sale'
                    - $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/BadJson'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /channels:
    post:
      tags:
        - bots
      summary: channel list
      description: >-
        Retrieve list of channels. The request can include the include_links
        parameter to return channel links. Additionally, you can filter channels
        by specific link names or exclude channels that have the specified link
        names. If include_links is 'yes', the response will include channel
        links. If exclude_link_names is 'yes' and link_names is provided, it
        will return channels that do NOT have the specified link names. You can
        also specify which fields to include in the response for both channels
        and links using channel_fields and link_fields. The consolidate_links
        parameter allows you to consolidate link data in the response.
      security:
        - jwt: []
      parameters:
        - in: header
          name: X-client-id
          schema:
            type: string
            maxLength: 50
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                include_links:
                  type: string
                  enum:
                    - 'yes'
                    - 'no'
                  default: 'no'
                  description: Whether to include links in the response. Defaults to "no".
                link_names:
                  type: array
                  items:
                    type: string
                  description: Optional array of link names to filter channels by.
                exclude_link_names:
                  type: string
                  enum:
                    - 'yes'
                    - 'no'
                  default: 'no'
                  description: >-
                    Optional parameter. When set to "yes" and link_names is
                    provided, returns channels that do NOT have the specified
                    link names. Only used if link_names has values.
                channel_fields:
                  type: array
                  items:
                    type: string
                  description: >-
                    Optional array of channel field names to include in the
                    response. If not specified, all channel fields are returned.
                  example:
                    - nombre
                    - is_default_bot
                    - num_enlaces
                link_fields:
                  type: array
                  items:
                    type: string
                  description: >-
                    Optional array of link field names to include in the
                    response when include_links is "yes". If not specified, all
                    link fields are returned.
                  example:
                    - telegram_namecanal
                    - nombre
                    - entradas_unicas
                    - entradas_total
                    - pagos_importe
                    - safecode
                    - pagos_num
                    - aprobacion_automatica
                consolidate_links:
                  type: string
                  enum:
                    - 'yes'
                    - 'no'
                  default: 'no'
                  description: >-
                    Optional parameter. When set to "yes", consolidates link
                    data in the response. Defaults to "no".
        required: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Channel'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/BadJson'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /channel_results:
    post:
      tags:
        - bots
      summary: List of channel results
      description: >-
        Retrieve list of channel results. The request must include the
        start_date_time and end_date_time parameters and the channel_id
        parameter. The invitation_link parameter is optional. If the
        invitation_link parameter is included, the request will return the
        results of the invitation link. If the invitation_link parameter is not
        included, the request will return the results of the channel.
      security:
        - jwt: []
      parameters:
        - in: header
          name: X-client-id
          schema:
            type: string
            maxLength: 50
          required: true
      requestBody:
        content:
          application/json:
            schema:
              required:
                - start_date_time
                - end_date_time
              type: object
              properties:
                start_date_time:
                  type: string
                  format: date-time
                end_date_time:
                  type: string
                  format: date-time
                channel_id:
                  type: integer
                invitation_link:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Enlace'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/BadJson'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /channel_sales:
    post:
      tags:
        - bots
      summary: sales of a channel
      description: >-
        Retrieve sales data of a channel. The request must include the
        start_date_time and end_date_time parameters and the channel_id
        parameter. The invitation_link parameter is optional. If the
        invitation_link parameter is included, the request will return the sales
        of the invitation link. If the invitation_link parameter is not
        included, the request will return the sales of all the invitation links
        of the channel.
      security:
        - jwt: []
      parameters:
        - in: header
          name: X-client-id
          schema:
            type: string
            maxLength: 50
          required: true
      requestBody:
        content:
          application/json:
            schema:
              required:
                - start_date_time
                - end_date_time
              type: object
              properties:
                start_date_time:
                  type: string
                  format: date-time
                end_date_time:
                  type: string
                  format: date-time
                channel_id:
                  type: integer
                invitation_link:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CanalVentaTelegram'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/BadJson'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /create_public_link:
    post:
      tags:
        - bots
      summary: create public link for a channel
      description: >-
        Create a public link for a channel. The request must include the
        channel_id parameter and  optionally the duration_hours,
        requires_approval and auto_approval parameters. The request will return
        the public link created.
      security:
        - jwt: []
      parameters:
        - in: header
          name: X-client-id
          schema:
            type: string
            maxLength: 50
          required: true
      requestBody:
        content:
          application/json:
            schema:
              required:
                - channel_id
                - name
              type: object
              properties:
                channel_id:
                  type: integer
                  description: Internal premiumpay channel ID
                name:
                  type: string
                  description: Name of the link
                duration_hours:
                  type: integer
                  description: Duration in hours (0 unlimited)
                requires_approval:
                  type: string
                  enum:
                    - 'yes'
                    - 'no'
                  description: Indicates if approval is required
                auto_approval:
                  type: string
                  enum:
                    - 'yes'
                    - 'no'
                  description: Indicates if approval is automatic
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Link'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/BadJson'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /personal_welcome_message:
    post:
      tags:
        - bots
      summary: personal welcome message
      description: >-
        Create a personal welcome message for a channel. The request must
        include the channel_id and message parameters  and optionally the
        invite_link, button, welcome_url and button_callback parameters.
      security:
        - jwt: []
      parameters:
        - in: header
          name: X-client-id
          schema:
            type: string
            maxLength: 50
          required: true
      requestBody:
        content:
          application/json:
            schema:
              required:
                - channel_id
                - message
              type: object
              properties:
                channel_id:
                  type: integer
                  description: Internal premiumpay channel ID
                message:
                  type: string
                  description: Welcome message
                invite_link:
                  type: string
                  description: Invitation link (optional)
                button:
                  type: string
                  description: Text of the button (optional)
                button_callback:
                  type: string
                  description: url of the button (optional)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/BadJson'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    BadJson:
      description: Invalid JSON received
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Response'
    Unauthorized:
      description: If the token is not valid or the device/group does no belong to user.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Response'
    NotFound:
      description: File not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Response'
    TooManyRequests:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Response'
    AuthError:
      description: JWT token or user credentials are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Response'
  schemas:
    Response:
      properties:
        error:
          type: string
        status:
          type: string
          enum:
            - ok
            - ko
      required:
        - status
      additionalProperties: false
      example:
        status: ko
        error: No data
    Status:
      properties:
        ratelimit:
          type: object
          properties:
            rateLimit:
              type: integer
              description: Maximum number of requests in the current period
            rateLimitPeriod:
              type: integer
              description: Period duration in seconds
            rateLimitRemaining:
              type: integer
              description: Remaining requests in the current period
            rateLimitReset:
              type: integer
              description: Unix timestamp when rate will reset
        status:
          type: string
          enum:
            - ok
            - ko
      required:
        - status
      additionalProperties: false
      example:
        status: ko
        ratelimit:
          rateLimit: 100
          rateLimitPeriod: 3600
          rateLimitRemaining: 0
          rateLimitReset: 1616425200
    Version:
      type: string
      description: Current API version
      example: 1.0.0
    Channel:
      type: object
      properties:
        id:
          type: integer
          example: 40
        nombre:
          type: string
          example: test bienvenida
        activo:
          type: boolean
          example: true
        telegramToken:
          type: string
          example: 1710246670_cbef
        telegramIdcanal:
          type: string
          example: '-1002087167666'
        telegramNamecanal:
          type: string
          example: bienvenida
        tsRegistered:
          type: integer
          example: 1710246670
        tsInit:
          type: integer
          example: null
        lastfijadoBoton:
          type: string
          example: null
        lastfijadoUrl:
          type: string
          example: null
        lastfijadoMensaje:
          type: string
          example: null
        welcomeBoton:
          type: string
          example: null
        welcomeUrl:
          type: string
          example: null
        welcomeMensaje:
          type: string
          example: null
        telegramBotIdtelegramBot:
          type: string
          example: Banner Bot
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    Link:
      type: object
      properties:
        idtelegram_publicidad_acceso:
          type: integer
          example: 136
        nombre:
          type: string
          example: test manual
        duracion_horas:
          type: integer
          example: 0
        numero_usuarios:
          type: integer
          example: 0
        requiere_aprobacion:
          type: boolean
          example: true
        aprobacion_automatica:
          type: boolean
          example: false
        fecha_creacion:
          type: object
          properties:
            date:
              type: string
              example: '2024-03-12 13:32:14.000000'
            timezone_type:
              type: integer
              example: 3
            timezone:
              type: string
              example: UTC
        safecode:
          type: string
          example: https://t.me/+YbxJOf0nXgBiY2Nk
        telegram_token:
          type: string
          example: null
        telegram_idcanal:
          type: string
          example: '-1002087167666'
        telegram_namecanal:
          type: string
          example: bienvenida
        telegram_bot_idtelegram_bot:
          type: string
          example: Banner Bot
        login_business_id:
          type: integer
          example: 6112
        activo:
          type: boolean
          example: true
        fecha_inicio:
          type: string
          example: null
        telegram_channel_idtelegram_channel:
          type: integer
          example: 40
    Gateway:
      type: object
      properties:
        id:
          type: integer
          example: 1
        idpasarela:
          type: string
          example: '6112'
          description: ID of the user that owns the pasarela
        nombre:
          type: string
          example: angel gateway
        activo:
          type: boolean
          example: true
        emailremitente:
          type: string
          format: email
        emailrecibir:
          type: string
          format: email
        logo:
          type: string
          example: pasarela_574_dc09d6295abb0408.png
        nombreTipster:
          type: string
          example: Tipsterguay
        servicios:
          type: array
          items:
            $ref: '#/components/schemas/Service'
    Service:
      type: object
      properties:
        idproducto:
          type: integer
        idpasarela:
          type: integer
        descripcion:
          type: string
        precio:
          type: string
        precioCop:
          type: integer
        moneda:
          type: string
        enlace:
          type: string
        tipster:
          type: string
        emailtipster:
          type: string
        emailcomprador:
          type: string
        activo:
          type: boolean
        devoluciones:
          type: boolean
        imagen_filename:
          type: string
        essubscripcion:
          type: boolean
        periodoDias:
          type: integer
        periodo_intervalo:
          type: string
        periodo_intervalo_cantidad:
          type: integer
        telegram_token:
          type: string
        telegram_idcanal:
          type: string
        telegram_namecanal:
          type: string
        stripe_productid:
          type: string
        stripe_priceid:
          type: string
        canal_gestionado:
          type: boolean
        apikey:
          type: string
        telegram_bot_idtelegram_bot:
          type: integer
        contenido:
          type: string
        telegram_bot_name:
          type: string
      required:
        - idproducto
        - idpasarela
        - descripcion
        - precio
        - moneda
        - enlace
        - tipster
        - emailtipster
        - activo
    Enlace:
      type: object
      properties:
        idtelegram_publicidad_acceso:
          type: integer
          description: invitation link ID
        nombre:
          type: string
          description: Name of the link
        duracion_horas:
          type: integer
          description: Duration in hours
        numero_usuarios:
          type: integer
          description: Maximum number of users
        requiere_aprobacion:
          type: boolean
          description: Indicates if approval is required
        aprobacion_automatica:
          type: boolean
          description: Indicates if approval is automatic
        fecha_creacion:
          type: object
          properties:
            date:
              type: string
              format: date-time
              description: Creation date in 'YYYY-MM-DD HH:MM:SS' format
            timezone_type:
              type: integer
              description: Timezone type
            timezone:
              type: string
              description: Timezone
        safecode:
          type: string
          description: Service code
        telegram_token:
          type: string
          description: Telegram token
        telegram_idcanal:
          type: string
          description: Telegram channel ID
        telegram_namecanal:
          type: string
          description: Telegram channel name
        telegram_bot_idtelegram_bot:
          type: string
          description: Telegram bot ID
        login_business_id:
          type: integer
          description: User ID
        activo:
          type: boolean
          description: Indicates if active
        fecha_inicio:
          type: string
          format: date-time
          description: Start date in 'YYYY-MM-DD HH:MM:SS' format
        telegram_channel_idtelegram_channel:
          type: integer
          description: Telegram channel ID
        solicitudes:
          type: integer
          description: Number of requests
        entradas_unicas:
          type: integer
          description: Number of unique entries
        entradas_total:
          type: integer
          description: Total number of entries
        salidas_unicas:
          type: integer
          description: Number of unique exits
        salidas_total:
          type: integer
          description: Total number of exits
        pagos_num:
          type: integer
          description: Number of payments
        pagos_importe:
          type: string
          description: Payment amount
        welcome_boton:
          type: string
          description: Welcome button
        welcome_url:
          type: string
          description: Welcome URL
        welcome_mensaje:
          type: string
          description: Welcome message
        solicitudesPendientes:
          type: string
          description: Pending requests
        entradasUnicas:
          type: string
          description: Unique entries
        entradasSinSalida:
          type: string
          description: Entries without exit
        numPagos:
          type: integer
          description: Number of payments
        importePagos:
          type: integer
          description: Payment amount
    Sale:
      type: object
      properties:
        n_transacciones:
          type: integer
          description: Number of transactions
        pais:
          type: string
          description: Country code
        pais_nice:
          type: string
          description: Country name
        payment:
          type: string
          description: Payment method
        quantity:
          type: number
          description: Quantity of item sold
      required:
        - n_transacciones
        - quantity
    Transaction:
      type: object
      properties:
        product:
          type: string
          description: Product description
        cantidad:
          type: string
          description: Quantity
        dinero:
          type: string
          description: Amount of money (comma as decimal separator)
        comision:
          type: string
          description: Commission (comma as decimal separator)
        moneda:
          type: string
          description: Currency
          example: EUR
      required:
        - product
        - cantidad
        - dinero
        - comision
        - moneda
    VentaTelegram:
      type: object
      properties:
        telegram_userid:
          type: string
          description: User ID on Telegram
        telegram_username:
          type: string
          description: Username on Telegram
        fecha_solicitud:
          type: string
          format: date-time
          description: Date and time of the request in 'YYYY-MM-DD HH:MM:SS' format
        fecha_entrada:
          type: string
          format: date-time
          description: Date and time of entry in 'YYYY-MM-DD HH:MM:SS' format
        fecha_salida:
          type: string
          format: date-time
          description: Date and time of exit in 'YYYY-MM-DD HH:MM:SS' format
        num_pagos:
          type: string
          description: Number of payments
        importe_pagos:
          type: string
          description: Payment amount in EUR
    CanalVentaTelegram:
      type: object
      properties:
        idtelegram_publicidad_acceso:
          type: integer
          description: internal channel ID
        nombre:
          type: string
          description: Name of the channel
        duracion_horas:
          type: integer
          description: Duration in hours
        numero_usuarios:
          type: integer
          description: Number of users
        requiere_aprobacion:
          type: boolean
          description: Indicates if approval is required
        aprobacion_automatica:
          type: boolean
          description: Indicates if approval is automatic
        fecha_creacion:
          type: object
          properties:
            date:
              type: string
              format: date-time
              description: Creation date in 'YYYY-MM-DD HH:MM:SS' format
            timezone_type:
              type: integer
              description: Timezone type
            timezone:
              type: string
              description: Timezone
        safecode:
          type: string
          description: Safe code
        telegram_token:
          type: string
          description: Telegram token
        telegram_idcanal:
          type: string
          description: ID of the Telegram channel
        telegram_namecanal:
          type: string
          description: Name of the Telegram channel
        telegram_bot_idtelegram_bot:
          type: string
          description: ID of the Telegram bot
        login_business_id:
          type: integer
          description: ID of the associated business
        activo:
          type: boolean
          description: Indicates if active
        fecha_inicio:
          type: string
          format: date-time
          description: Start date in 'YYYY-MM-DD HH:MM:SS' format
        telegram_channel_idtelegram_channel:
          type: integer
          description: ID of the Telegram channel
        solicitudes:
          type: integer
          description: Number of requests
        entradas_unicas:
          type: integer
          description: Number of unique entries
        entradas_total:
          type: integer
          description: Total number of entries
        salidas_unicas:
          type: integer
          description: Number of unique exits
        salidas_total:
          type: integer
          description: Total number of exits
        pagos_num:
          type: integer
          description: Number of payments
        pagos_importe:
          type: string
          description: Payment amount
        welcome_boton:
          type: string
          description: Welcome button
        welcome_url:
          type: string
          description: Welcome URL
        welcome_mensaje:
          type: string
          description: Welcome message
        ventas:
          type: array
          items:
            $ref: '#/components/schemas/VentaTelegram'
          description: List of sales of users while in this channel
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      x-bearerInfoFunc: api.decode_token
      description: >-
        JWT token to authenticate requests. The token must be included in the
        Authorization header as a bearer token the JWT must use the HS256
        algorithm and the secret key is the client_secret provided by
        premiumpay.
