openapi: 3.0.0
info:
  version: 1.0.19-oas3
  title: AlayaCare Accounting Accounts Transactions API
  description: '**AlayaCare IDs:**

    The following terms are used to reference IDs that identify resources in AlayaCare:

    - id

    - visit_id

    - premium_id

    - visit_premium_id

    - employee_id

    - cost_centre_id

    - client_id


    **External IDs**

    The following terms are used to reference IDs that identify resources systems external to AlayaCare:

    - employee_external_id

    - client_external_id


    External IDs are required to be unique.

    No other assumptions are made regarding their format they are treated as strings.

    '
servers:
- url: https://example.alayacare.com/ext/api/v2/accounting
security:
- basic_auth: []
tags:
- name: Transactions
paths:
  /transactions:
    get:
      tags:
      - Transactions
      summary: Returns a collection of transactions
      parameters:
      - name: transaction_ids
        description: A list of transaction IDs to filter by
        in: query
        required: false
        schema:
          type: array
          items:
            type: integer
            minimum: 1
      - name: exclude_ids
        description: A list of transaction IDs to exclude from the results
        in: query
        required: false
        schema:
          type: array
          items:
            type: integer
            minimum: 1
      - name: reference_id
        description: The Reference ID of the transaction to find
        in: query
        schema:
          type: integer
      - name: type
        description: The type of transactions to list
        in: query
        required: false
        schema:
          type: string
      - name: reversed
        description: Whether to include reversed transactions or not
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: ar_entry_type
        in: query
        description: The transaction's entry type to filter by.
        schema:
          type: string
          enum:
          - credit
          - debit
      - name: ar_description
        in: query
        description: The transaction's description to filter by.
        required: false
        schema:
          type: string
      - name: invoice_number
        in: query
        description: The invoice number to filter the transactions by
        schema:
          type: string
      - name: search
        description: The Reference ID of the transaction or the Invoice Number to find
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: string
      - name: invoice_id
        description: The invoice ID to filter the transactions by
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: integer
          minimum: 1
      - name: invoice_item_ids
        description: The invoice item IDs to filter the transactions by
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: array
          items:
            type: integer
            minimum: 1
      - name: client_id
        description: The client ID to filter by
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: integer
          minimum: 1
      - name: funder_id
        description: The funder ID to filter by
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: integer
          minimum: 1
      - name: billing_contact_id
        description: The billing contact ID to filter by
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: integer
          minimum: 1
      - name: transaction_date_from
        description: The date after which transactions should be filtered (inclusive) - ex. 2024-01-31
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: string
          format: date
      - name: transaction_date_to
        description: The date before which transactions should be filtered (exclusive) - ex. 2024-01-31
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: string
          format: date
      - name: memo
        description: String for which to search (partial) in the transaction memo
        in: query
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: client_search
        description: The name or the id of the client (partial)
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: string
      - name: date_from
        description: The posting date after which transactions should be filtered (inclusive) - ex. 2024-01-31
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: string
          format: date
      - name: date_to
        description: The posting date before which transactions should be filtered (inclusive) - ex. 2024-01-31
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: string
          format: date
      - name: account_name
        description: The name of the account to filter by
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: string
      - name: account_number
        description: The number of the account to filter by
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: string
      - name: account_ids
        description: The account IDs to filter by
        in: query
        allowEmptyValue: true
        required: false
        schema:
          type: array
          items:
            type: integer
            minimum: 1
      - name: adjusted
        description: Whether or not the transaction has an adjustment allocated to it.
        in: query
        required: false
        allowEmptyValue: false
        schema:
          type: boolean
      - name: include_medicaid
        description: Whether or not to include medicaid funders. Defaults to True
        in: query
        required: false
        schema:
          type: boolean
      - name: include_ccac
        description: Whether or not to include CCAC funders. Defaults to True
        in: query
        required: false
        schema:
          type: boolean
      - name: include_allocated
        in: query
        description: Whether to include allocated transactions or not
        schema:
          type: boolean
          default: true
      - name: include_voided_sales
        in: query
        description: True to included voided sales; False to exclude them. Defaults to true
        schema:
          type: boolean
      - name: only_without_allocations
        in: query
        description: True to select only the transactions that do not have allocations (in this case, note that reverted allocations are considered as non-existent);  False to select the transactions no matter their number of allocations. Defaults to False.
        schema:
          type: boolean
          default: false
      - name: include_canceled_payments
        in: query
        description: True to include canceled payments; False to exclude them. Defaults to true
        schema:
          type: boolean
          default: true
      - name: order
        description: Field on which to sort the results
        in: query
        schema:
          type: string
          enum:
          - posting_date
          - unallocated_amount
          - client_name
          - id
      - name: include_account
        description: Whether to include the account information in the response
        in: query
        schema:
          type: boolean
          default: false
      - name: asc
        description: Whether to sort ascendingly, defaults to false
        in: query
        schema:
          type: boolean
          default: false
      - name: page
        description: Page to retrieve
        in: query
        required: false
        schema:
          type: integer
      - name: count
        description: Number of items per page
        in: query
        required: false
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: List of transactions
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: integer
                    example: 1
                    description: The current page number
                  count:
                    type: integer
                    example: 10
                    description: Number of items in the list
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionSchema'
  /transactions/{id}:
    get:
      tags:
      - Transactions
      summary: Find transaction by ID
      description: Returns a single transaction
      parameters:
      - name: id
        in: path
        description: Reference ID of transaction to return
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: The transaction retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionExtendedSchema'
        '404':
          $ref: '#/components/responses/TransactionNotFound'
components:
  schemas:
    ClientShortSchema:
      type: object
      description: A client
      properties:
        id:
          type: integer
          format: int64
          description: The ID of the client
        name:
          type: string
          description: The name of the client
        alayacare_id:
          type: string
          description: The AlayaCare ID of the client
      example:
        id: 1
        name: Peter Tosh
        alayacare_id: AC000000123
    TransactionExtendedSchema:
      allOf:
      - $ref: '#/components/schemas/TransactionSchema'
      - type: object
        properties:
          entries:
            type: array
            items:
              $ref: '#/components/schemas/TransactionEntrySchema'
          visits:
            type: array
            items:
              $ref: '#/components/schemas/VisitSchema'
    UserShortSchema:
      type: object
      description: A user
      properties:
        id:
          type: integer
          format: int64
          description: The ID of the user
        name:
          type: string
          description: The name of the user
    BillingContactShortSchema:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: The ID of the billing contact
        full_name:
          type: string
          description: The full name of the billing contact
    FunderShortSchema:
      type: object
      description: A funder
      properties:
        id:
          type: integer
          format: int64
          description: The ID of the funder
        code:
          type: string
          description: The code of the funder
        name:
          type: string
          description: The name of the funder
        invoicing_model:
          type: string
          description: The invoicing model of the funder
    NotFound:
      type: object
      properties:
        code:
          type: string
          example: 404
        message:
          type: string
          example: Entity not found
      required:
      - code
      - message
    TransactionAdjustmentSchema:
      type: object
      properties:
        total_credit:
          type: number
          format: float
          description: description
        total_debit:
          type: number
          format: float
          description: description
    TransactionSchema:
      type: object
      description: A representation of an accounting transaction
      readOnly: true
      properties:
        id:
          type: integer
          format: int64
          description: Reference ID
        posting_date:
          type: string
          format: date
          description: Posting date in the `YYYY-MM-DD` format
        type:
          $ref: '#/components/schemas/TransactionType'
        amount:
          type: number
          format: float
          description: The amout of the transaction.
        unallocated_amount:
          type: number
          format: float
          description: The unallocated amount of the transaction.
        allocations_count:
          type: integer
          format: int64
          description: The number of allocations that this transaction has
        invoice_id:
          type: integer
          format: int64
          description: The id of the invoice associated to the transaction; Applicable for transactions of type sale, void and credit/debit notes.
        invoice_number:
          type: integer
          format: int64
          description: The invoice item id of the invoice item associated to the transaction; Applicable for transactions of type sale, void and credit/debit notes.
        invoice_item_id:
          type: integer
          format: int64
          description: The invoice number of the invoice associated to the transaction; Applicable for transactions of type sale, void and credit/debit notes.
        budget_id:
          type: integer
          format: int64
          description: The budget id of the budget associated to the transaction
        memo:
          type: string
          description: A note about the transaction.
        payment_is_canceled:
          type: boolean
          description: whether or not the payment is canceled (currently always false)
          example: true
        is_adjustable:
          type: boolean
          description: whether or not adjustment transaction types exist for this transaction
          example: true
        created_at:
          type: string
          format: date-time
        client:
          $ref: '#/components/schemas/ClientShortSchema'
        funder:
          $ref: '#/components/schemas/FunderShortSchema'
        billing_contact:
          $ref: '#/components/schemas/BillingContactShortSchema'
        create_user:
          $ref: '#/components/schemas/UserShortSchema'
        adjustments:
          $ref: '#/components/schemas/TransactionAdjustmentSchema'
        billing_period_id:
          type: integer
          minimum: 1
          description: The id of the billing period associated to the transaction
    TransactionEntrySchema:
      type: object
      properties:
        account:
          type: object
          properties:
            id:
              type: integer
            account:
              $ref: '#/components/schemas/AccountSchema'
            debit:
              type: number
              format: float
            credit:
              type: number
              format: float
            cost_centre:
              $ref: '#/components/schemas/CostCentreScalarSchema'
    AccountSchema:
      type: object
      description: A representation of a General Ledger account
      properties:
        id:
          type: integer
          description: The ID the GL account
        name:
          type: string
          description: The name of the GL account
        type:
          type: string
          description: The type of the GL account
        is_disabled:
          type: boolean
          description: Whether this GL account is disabled.
        gl_number:
          type: integer
          description: The account number on the General Ledger.
      example:
        id: 2
        name: Revenue - Product A
        type: Revenue
        is_disabled: false
        gl_number: 4002
    TransactionType:
      description: Transaction type
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: The id of the transaction type
        name:
          type: string
          description: The name of transaction type
        AR_entry:
          type: string
          description: The entry type
          enum:
          - credit
          - debit
        is_disabled:
          type: boolean
          description: True if no transaction of that type can be created by the user; False if not
        is_custom:
          type: boolean
          description: True if this type is custom (was created by the user); False if not
    VisitSchema:
      type: object
      properties:
        id:
          type: integer
          minimum: 1
        start_time:
          type: string
          format: date-time
    CostCentreScalarSchema:
      description: A cost centre
      type: object
      properties:
        id:
          type: integer
          example: 1
        number:
          type: string
          example: MTL-032
        description:
          type: string
          example: A cost centre
  responses:
    TransactionNotFound:
      description: Transaction not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFound'
  securitySchemes:
    basic_auth:
      type: http
      description: Basic HTTP auth over https
      scheme: basic