api-spec-template.yml

---
swagger: '2.0'
info:
  description: Refundable External API
  version: APIVERSION
  title: Refundable External API
  contact:
    name: Simon Skinner
    email: ss@refundable.co.uk
host: TEMPLATEHOST.refundable.co.uk
securityDefinitions:
  api_key:
    type: 'apiKey'
    name: 'key'
    in: 'query'
tags:
  - name: Addresses
  - name: Banking
  - name: Charities
  - name: Merchants
  - name: Members
  - name: Offers
  - name: Transactions
  - name: Payments
  - name: Documents
  - name: Communications
  - name: Introducers
  - name: CallRecordings
schemes:
  - https
produces:
  - application/json
paths:
  /call-recordings/{ref}:
    options:
      tags:
        - CallRecordings
      summary: Uploads a call recording
      operationId: optionCallRecording
      parameters:
        - name: ref
          in: path
          required: true
          type: string
      responses:
        '200':
          description: Success
      x-google-backend:
        address: https://call-recordings-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      tags:
        - CallRecordings
      summary: Uploads a call recording
      operationId: postCallRecording
      parameters:
        - name: ref
          in: path
          required: true
          type: string
      responses:
        '200':
          description: Success
      x-google-backend:
        address: https://call-recordings-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /introducers/apikey:
    get:
      tags:
        - Introducers
      summary: Gets the introducer ID for an api key
      operationId: getIntroducerIdForApiKey
      responses:
        '200':
          description: Success
      x-google-backend:
        address: https://api-introducers-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /payments/card:
    options:
      tags:
        - Payments
      summary: Takes a card payment
      operationId: takeCardPaymentOptions
      responses:
        '200':
          description: Success
      x-google-backend:
        address: https://api-payments-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      tags:
        - Payments
      summary: Takes a card payment
      operationId: takeCardPaymentPost
      responses:
        '200':
          description: Success
      x-google-backend:
        address: https://api-payments-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /banking/validate:
    options:
      tags:
        - Banking
      summary: Validates and gets the address from sortcode and account number
      operationId: validateBankOptions
      parameters:
        - name: sortCode
          in: query
          required: true
          type: string
        - name: accountNumber
          in: query
          required: true
          type: string
      responses:
        '200':
          description: Address
      x-google-backend:
        address: https://api-banking-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      tags:
        - Banking
      summary: Validates and gets the address from sortcode and account number
      operationId: validateBankPost
      parameters:
        - name: sortCode
          in: query
          required: true
          type: string
        - name: accountNumber
          in: query
          required: true
          type: string
      responses:
        '200':
          description: Address
      x-google-backend:
        address: https://api-banking-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /addresses/lookup/{postcode}:
    get:
      tags:
        - Addresses
      summary: Gets List of addresses for a postcode
      operationId: lookupPostcode
      parameters:
        - name: postcode
          in: path
          required: true
          type: string
      responses:
        '200':
          description: An array of addresses
      x-google-backend:
        address: https://api-addresses-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /charities:
    get:
      tags:
        - Charities
      summary: Gets List of Charities
      operationId: listCharities
      responses:
        '200':
          description: An array of transactions
          schema:
            $ref: '#/definitions/ArrayOfCharities'
      x-google-backend:
        address: https://api-charities-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /charities/{charityId}:
    get:
      tags:
        - Charities
      summary: Gets details of a single charity
      operationId: getCharity
      parameters:
        - name: charityId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: A single Charity Item
          schema:
            $ref: '#/definitions/Charity'
      x-google-backend:
        address: https://api-charities-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /merchants:
    get:
      tags:
        - Merchants
      summary: Gets List of Merchants
      operationId: listMerchants
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-merchants-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /merchants/nearby:
    get:
      tags:
        - Merchants
      parameters:
        - name: longitude
          in: query
          required: true
          type: number
        - name: latitude
          in: query
          required: true
          type: number
      summary: Gets List of Merchants near to the given logitude and latitude
      operationId: listMerchantsByLocation
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-merchants-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /merchants/{merchantId}:
    get:
      tags:
        - Merchants
      parameters:
        - name: merchantId
          in: path
          required: true
          type: string
      summary: Gets details of a single Merchant
      operationId: getMerchant
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-merchants-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /merchants/{merchantId}/addresses:
    get:
      tags:
        - Merchants
      parameters:
        - name: merchantId
          in: path
          required: true
          type: string
      summary: Gets all addresses for a Merchant
      operationId: listMerchantAddresses
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-merchants-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /members/set-password:
    options:
      tags:
        - Members
      summary: Options sets password
      operationId: setPasswordOptions
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      tags:
        - Members
      summary: Sets password
      operationId: setPasswordPost
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /members/login:
    options:
      tags:
        - Members
      summary: Options for Logs in a User
      operationId: loginUserOptions
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      tags:
        - Members
      summary: Logs in a User
      operationId: loginUser
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /members/{userId}:
    options:
      tags:
        - Members
      summary: Updates a user details
      operationId: updateUserOptions
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      tags:
        - Members
      summary: Updates a user details
      operationId: updateUserPost
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      security:
        - api_key: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /members/create:
    options:
      tags:
        - Members
      summary: Creates a new User Options
      operationId: createUserOptions
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      tags:
        - Members
      summary: Creates a new User
      operationId: createUser
      parameters: []
      security:
        - api_key: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /members/forgot-password:
    options:
      tags:
        - Members
      summary: Sends out an email to allow changing password
      operationId: forgotPasswordOptions
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      tags:
        - Members
      summary: Sends out an email to allow changing password
      operationId: forgotPasswordPost
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /members/validate-voucher:
    options:
      tags:
        - Members
      summary: Validates a voucher code
      operationId: validateVoucherOptions
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      tags:
        - Members
      summary: Validates a voucher code
      operationId: validateVoucherPost
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /members/validate-number:
    options:
      tags:
        - Members
      summary: Validates a number
      operationId: validateNumberOptions
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      tags:
        - Members
      summary: Validates a number
      operationId: validateNumberPost
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /members/cards:
    options:
      tags:
        - Members
      summary: Card options
      operationId: memberCardOptions
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-cards-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    get:
      tags:
        - Members
      summary: Gets a list of cards
      operationId: memberCardList
      parameters: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-cards-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      tags:
        - Members
      summary: Creates a card
      operationId: memberCardCreate
      parameters: []
      security:
        - api_key: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-cards-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /members/is-registered:
    get:
      tags:
        - Members
      summary: Deletes a card options
      operationId: memberIsRegisteredGet
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-members-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /members/cards/{cardId}:
    options:
      tags:
        - Members
      summary: Deletes a card options
      operationId: memberCardDeleteOptions
      parameters:
        - name: cardId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-cards-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    delete:
      tags:
        - Members
      summary: Deletes a card
      operationId: memberCardDelete
      parameters:
        - name: cardId
          in: path
          required: true
          type: string
      security:
        - api_key: []
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-cards-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /offers/categories:
    get:
      tags:
        - Offers
      summary: Gets a List of offer Categories
      operationId: getOfferCategories
      parameters: []
      responses:
        '200':
          description: A list of categories
          schema:
            $ref: '#/definitions/ArrayOfCategories'
      x-google-backend:
        address: https://api-offers-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /offers/categories/{categorySlug}/offers:
    get:
      tags:
        - Offers
      summary: Gets a List of offers for a category
      operationId: getOffers
      parameters:
        - name: categorySlug
          in: path
          required: true
          type: string
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-offers-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /offers/categories/{categorySlug}/offers/{offerSlug}:
    get:
      tags:
        - Offers
      summary: Gets details of an offer from its category
      operationId: getOfferFromCategory
      parameters:
        - name: categorySlug
          in: path
          required: true
          type: string
        - name: offerSlug
          in: path
          required: true
          type: string
      responses:
        '200':
          description: all good
      x-google-backend:
        address: https://api-offers-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /users/{userId}:
    delete:
      summary: Gets a list of transactions ungrouped
      operationId: deleteUser
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      tags:
        - Users
      responses:
        '200':
          description: An array of transactions
          schema:
            $ref: '#/definitions/ArrayOfTransactions'
      x-google-backend:
        address: https://api-users-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    options:
      summary: Gets a list of transactions ungrouped
      operationId: userOption
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      tags:
        - Users
      responses:
        '200':
          description: An array of transactions
          schema:
            $ref: '#/definitions/ArrayOfTransactions'
      x-google-backend:
        address: https://api-users-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS

  /transactions:
    post:
      summary: Gets a list of transactions ungrouped
      operationId: addTransaction
      tags:
        - Transactions
      responses:
        '200':
          description: An array of transactions
          schema:
            $ref: '#/definitions/ArrayOfTransactions'
      x-google-backend:
        address: https://api-transactions-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    options:
      summary: Gets a list of transactions ungrouped
      operationId: optionTransaction
      tags:
        - Transactions
      responses:
        '200':
          description: An array of transactions
          schema:
            $ref: '#/definitions/ArrayOfTransactions'
      x-google-backend:
        address: https://api-transactions-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    get:
      summary: Gets a list of transactions ungrouped
      operationId: listTransactions
      tags:
        - Transactions
      responses:
        '200':
          description: An array of transactions
          schema:
            $ref: '#/definitions/ArrayOfTransactions'
      x-google-backend:
        address: https://api-transactions-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /transactions/grouped:
    get:
      summary: Gets a list of transaction grouped by day
      operationId: listTransactionsGrouped
      tags:
        - Transactions
      responses:
        '200':
          description: An array of transactions
          schema:
            $ref: '#/definitions/ArrayOfTransactionGroups'
      x-google-backend:
        address: https://api-transactions-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /transactions/summary:
    get:
      summary: Gets a summary of transactions
      operationId: transactionSummary
      tags:
        - Transactions
      responses:
        '200':
          description: Transaction Summary
          schema:
            $ref: '#/definitions/ArrayOfTransactionGroups'
      x-google-backend:
        address: https://api-transactions-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /payments:
    get:
      summary: Gets the payment schedule for a member
      operationId: paymentSchedule
      parameters:
        - name: clientId
          in: query
          required: true
          type: string
        - name: memberId
          in: query
          required: true
          type: string
      tags:
        - Payments
      responses:
        '200':
          description: A full payment schedule
          schema:
            $ref: '#/definitions/ArrayOfPayments'
      x-google-backend:
        address: https://api-payments-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /documents:
    get:
      summary: Gets a list of documents for the member
      operationId: documentsList
      parameters:
        - name: clientId
          in: query
          required: true
          type: string
        - name: memberId
          in: query
          required: true
          type: string
      tags:
        - Documents
      responses:
        '200':
          description: A list of documents
          schema:
            $ref: '#/definitions/ArrayOfDocuments'
      x-google-backend:
        address: https://api-documents-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /documents/{documentId}/download:
    get:
      summary: Downloads a given document
      operationId: downloadDocument
      parameters:
        - name: documentId
          in: path
          required: true
          type: string
        - name: clientId
          in: query
          required: true
          type: string
        - name: memberId
          in: query
          required: true
          type: string
      tags:
        - Documents
      responses:
        '200':
          description: A list of documents
          schema:
            $ref: '#/definitions/ArrayOfDocuments'
      x-google-backend:
        address: https://api-documents-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /communications:
    get:
      summary: Gets a list of communication with the client
      operationId: communicationsList
      parameters:
        - name: clientId
          in: query
          required: true
          type: string
        - name: memberId
          in: query
          required: true
          type: string
      tags:
        - Communications
      responses:
        '200':
          description: A list of communications
          schema:
            $ref: '#/definitions/ArrayOfCommunications'
      x-google-backend:
        address: https://api-communications-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    options:
      summary: Creates a message from a user to Refundable (OPTIONS)
      operationId: sendCommunicationOptions
      tags:
        - Communications
      responses:
        '200':
          description: A success result
      x-google-backend:
        address: https://api-communications-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      summary: Creates a message from a user to Refundable
      operationId: sendCommunication
      parameters:
        - name: clientId
          in: query
          required: true
          type: string
        - name: memberId
          in: query
          required: true
          type: string
      tags:
        - Communications
      responses:
        '200':
          description: A success result
      x-google-backend:
        address: https://api-communications-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
  /communications/email-template:
    options:
      summary: Sends an email template to a client
      operationId: sendEmailTemplateOptions
      tags:
        - Communications
      responses:
        '200':
          description: A success result
      x-google-backend:
        address: https://api-communications-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
    post:
      summary: Sends an email template to a client
      operationId: sendEmailTemplatePost
      tags:
        - Communications
      responses:
        '200':
          description: A success result
      x-google-backend:
        address: https://api-communications-TEMPLATEURL-nw.a.run.app
        path_translation: APPEND_PATH_TO_ADDRESS
definitions:
  Communication:
    type: object
    properties:
      id:
        type: string
      direction:
        type: string
      type:
        type: string
      message:
        type: string
      created:
        type: string
  ArrayOfCommunications:
    type: array
    items:
      $ref: '#/definitions/Communication'
  Document:
    type: object
    properties:
      id:
        type: string
      created:
        type: string
      name:
        type: string
  ArrayOfDocuments:
    type: array
    items:
      $ref: '#/definitions/Document'
  Payment:
    type: object
    properties:
      id:
        type: string
      expected:
        type: string
      received:
        type: boolean
      skipped:
        type: boolean
      value:
        type: number
  ArrayOfPayments:
    type: array
    items:
      $ref: '#/definitions/Payment'
  FinancialSummary:
    type: object
    properties:
      totalRefunded:
        type: number
      totalWithdrawn:
        type: number
      totalAvailable:
        type: number
      totalPending:
        type: number
  Transaction:
    type: object
    properties:
      id:
        type: string
      time:
        type: string
      location:
        type: string
      merchantName:
        type: string
      refundValue:
        type: number
      logo:
        type: string
  ArrayOfTransactions:
    type: array
    items:
      $ref: '#/definitions/Transaction'
  TransactionGroup:
    type: object
    properties:
      id:
        type: string
      date:
        type: string
      totalRefunds:
        type: number
      refunds:
        type: array
        items:
          $ref: '#/definitions/Transaction'
  ArrayOfTransactionGroups:
    type: array
    items:
      $ref: '#/definitions/TransactionGroup'
  Category:
    type: object
    properties:
      id:
        type: string
      slug:
        type: string
      name:
        type: string
      imageUrl:
        type: string
      deleted:
        type: boolean
      description:
        type: string
  ArrayOfCategories:
    type: array
    items:
      $ref: '#/definitions/Category'
  Charity:
    type: object
    properties:
      id:
        type: string
      icon:
        type: string
      paymentRef:
        type: string
      telephoneNumber:
        type: string
      sortCode:
        type: string
      deleted:
        type: boolean
      accountNumber:
        type: string
      image:
        type: string
      name:
        type: string
      contactName:
        type: string
      contactEmail:
        type: string
      shortDescription:
        type: string
      miAddress:
        type: string
      description:
        type: string
  ArrayOfCharities:
    type: array
    items:
      $ref: '#/definitions/Charity'