Altoviz Bank Accounts API

openapi: 3.2.0
info:
  title: Altoviz Bank Accounts API
  description: 'RESTful APIs for the Altoviz services


    ## Deprecations


    ### Product prices


    A product now stores its sale price both excluding and including tax, so both are

    returned, along with the margin figures derived from them: `taxExcludedPrice`,

    `taxIncludedPrice`, `margin`, `markupRate` (margin over cost, FR « taux de marge ») and

    `marginRate` (margin over sale price, FR « taux de marque »).


    Two fields are deprecated as a result:


    | Deprecated | Use instead |

    | --- | --- |

    | `unitPrice` | `taxExcludedPrice` |

    | `isUnitPriceTaxIncluded` | `taxIncludedPrice`, to send a tax-included price |


    **`unitPrice` is now always the tax-excluded price.** It previously held whichever half

    the product was priced in, which `isUnitPriceTaxIncluded` told you. For a product priced

    tax-included, `unitPrice` therefore returns a different number than it used to, and

    `isUnitPriceTaxIncluded` is now always `false`. If you read the flag before using the

    price, your result is unchanged. If you assumed the price was tax-included, read

    `taxIncludedPrice`.


    Writing is unaffected. Both fields are still accepted and behave exactly as before:

    `unitPrice` alone is read as tax-excluded, and setting `isUnitPriceTaxIncluded` to `true`

    still means the price you are sending includes tax. `margin`, `markupRate` and

    `marginRate` are derived by the server and ignored if sent.'
  contact:
    name: Altoviz
    email: contact@altoviz.com
  license:
    name: Altoviz license
    url: https://altoviz.com/license
  version: v1
  x-logo:
    url: https://altoviz.com/altoviz-logo-ext-violet-262x72.png
    altText: Altoviz logo
servers:
- url: https://api.altoviz.com
  description: Altoviz
security:
- {}
tags:
- name: Bank Accounts
  description: Bank accounts API
paths:
  /v1/bankaccounts/providers:
    get:
      tags:
      - Bank Accounts
      summary: List of supported bank account providers
      operationId: GET_BankAccounts_Providers
      parameters:
      - name: query
        in: query
        description: query (full text search)
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankProvider'
  /v1/bankaccounts:
    get:
      tags:
      - Bank Accounts
      summary: List bank accounts
      operationId: GET_BankAccounts_List
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankAccount'
    post:
      tags:
      - Bank Accounts
      summary: Create a bank account
      description: 'Creates an account kept by hand. An account synchronized from a provider cannot be created

        here — the connection is established in the Altoviz application, and the provider fields are

        read-only throughout this API.'
      operationId: POST_BankAccounts_Post
      requestBody:
        description: Bank account to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountCreate'
          text/json:
            schema:
              $ref: '#/components/schemas/BankAccountCreate'
          application/*+json:
            schema:
              $ref: '#/components/schemas/BankAccountCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/bankaccounts/{id}:
    get:
      tags:
      - Bank Accounts
      summary: Get a bank account by ID
      operationId: GET_BankAccounts_Get
      parameters:
      - name: id
        in: path
        description: Bank account ID
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - Bank Accounts
      summary: Update a bank account
      description: Refused with 400 on a connected account, whose contents Altoviz mirrors rather than owns.
      operationId: PUT_BankAccounts_Update
      parameters:
      - name: id
        in: path
        description: Bank account ID
        required: true
        schema:
          type: integer
          format: int32
      requestBody:
        description: Bank account
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountCreate'
          text/json:
            schema:
              $ref: '#/components/schemas/BankAccountCreate'
          application/*+json:
            schema:
              $ref: '#/components/schemas/BankAccountCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Bank Accounts
      summary: Delete a bank account
      description: 'Deleting a bank account is irreversible and reaches past the account itself. It removes

        every transaction the account holds, and — unless another account shares it — the accounting

        journal attached to it together with every accounting entry written in that journal. There is

        no undo, and no export is taken first.


        Three cases are refused rather than deleted, so the destructive path is narrow:

        — 409 when the account holds transactions already reconciled with a receipt, a supplier

        or colleague payment, or a miscellaneous operation. This API never overrides that check, so an

        account with any bookkeeping against it cannot be deleted here at all: detach or delete those

        settlements in the Altoviz application first, and consider whether you meant to.

        — 400 when the account is connected to a provider, i.e. its `provider` is set.

        — 400 when the account is the company''s main one.

        What survives the 409 gate is an account with no reconciled transactions, so in practice this

        deletes an account that was created by mistake or never used. If you only want it out of the

        way of day-to-day work, there is nothing to delete: leave it in place.'
      operationId: DELETE_BankAccounts_Delete
      parameters:
      - name: id
        in: path
        description: Bank account ID
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/bankaccounts/setasmain/{id}:
    post:
      tags:
      - Bank Accounts
      summary: Make a bank account the main one
      description: 'Exactly one account is the company''s main account, so this moves the designation rather than

        adding it: whichever account held it loses it in the same operation. Setting the account that

        already holds it changes nothing and still succeeds.


        Allowed on a connected account, unlike `PUT` and `DELETE`. Being the main account is

        Altoviz''s own designation, not something the provider owns.

        400 when the account''s type cannot be the main one: only an account kept by hand and a

        Linxo-synchronized account qualify. A Stripe, GoCardless, PayPal or SumUp account is a payment

        balance rather than a bank account, and is refused.

        The main account is what the application offers first when a settlement needs a bank account.

        It is unrelated to `defaultPaymentMethod`, which is per-account.'
      operationId: POST_BankAccounts_SetAsMain
      parameters:
      - name: id
        in: path
        description: Bank account ID
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /v1/bankaccounts/{id}/transactions:
    get:
      tags:
      - Bank Accounts
      summary: List a bank account's transactions
      operationId: GET_BankAccounts_Transactions
      parameters:
      - name: id
        in: path
        description: Bank account ID
        required: true
        schema:
          type: integer
          format: int32
      - name: PageIndex
        in: query
        schema:
          type: integer
          format: int32
      - name: PageSize
        in: query
        schema:
          type: integer
          format: int32
      - name: OrderBy
        in: query
        schema:
          type: string
      - name: From
        in: query
        description: From (inclusive)
        schema:
          type: string
          format: date
      - name: To
        in: query
        description: To (inclusive)
        schema:
          type: string
          format: date
      - name: SearchTerm
        in: query
        description: Full-text search over the label and the amount
        schema:
          type: string
      - name: HideExcluded
        in: query
        description: Leave out the transactions that have been set aside. Off by default, so they are returned.
        schema:
          type: boolean
      - name: HideReconciliated
        in: query
        description: 'Leave out the transactions already matched to a settlement. Off by default, so they are

          returned.'
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          headers:
            x-page-prev:
              description: Relative URL of previous page when available
              schema:
                type: string
            x-page-next:
              description: Relative URL of next page when available
              schema:
                type: string
            x-page-count:
              description: Total number of pages
              schema:
                type: integer
                format: int32
            x-record-count:
              description: Total number of matching records
              schema:
                type: integer
                format: int32
            x-page-index:
              description: Current page index
              schema:
                type: integer
                format: int32
            x-page-size:
              description: Current page size
              schema:
                type: integer
                format: int32
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankTransaction'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    BankTransaction:
      type: object
      properties:
        bankAccountId:
          type: integer
          description: Bank account ID
          format: int32
          readOnly: true
        category:
          type:
          - string
          - 'null'
          description: Category as the provider classifies it
          readOnly: true
        coming:
          type: boolean
          description: Whether the transaction is announced but not yet settled by the bank
          readOnly: true
        date:
          type: string
          description: Date the transaction counts under
          format: date-time
          readOnly: true
        fullLabel:
          type:
          - string
          - 'null'
          description: Full label as the bank sends it
          readOnly: true
        id:
          type: integer
          description: Bank transaction ID
          format: int32
          readOnly: true
        includedExternalFeesAmount:
          type: number
          description: Fees already included in Altoviz.Api.Models.BankTransaction.Value
          format: double
          readOnly: true
        isExcluded:
          type: boolean
          description: 'Whether the transaction has been set aside, so it is not offered for reconciliation and does

            not count towards the account''s pending total. Toggled by `Exclude` and `Include`.'
          readOnly: true
        isImported:
          type: boolean
          description: Whether the transaction came from a file import rather than a provider
          readOnly: true
        isReconciliated:
          type: boolean
          description: Whether the transaction is already matched to a settlement
          readOnly: true
        label:
          type:
          - string
          - 'null'
          description: Short label
          readOnly: true
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            type:
            - string
            - 'null'
          description: Metadata carried with the transaction
          readOnly: true
        nature:
          $ref: '#/components/schemas/BankTransactionNature'
        notes:
          type:
          - string
          - 'null'
          description: Notes
          readOnly: true
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        transactionId:
          type:
          - string
          - 'null'
          description: The transaction's identifier at the provider it was synchronized from
          readOnly: true
        value:
          type: number
          description: Amount. Negative for money leaving the account.
          format: double
          readOnly: true
        valueDate:
          type:
          - string
          - 'null'
          description: Value date
          format: date-time
          readOnly: true
      additionalProperties: false
      description: Bank transaction.
    BankAccount:
      type: object
      properties:
        accountNumber:
          type:
          - string
          - 'null'
          description: Accounting account number
          readOnly: true
        balance:
          type: number
          description: Current balance, derived from the initial balance and every transaction since
          format: double
          readOnly: true
        bankName:
          type:
          - string
          - 'null'
          description: Bank name
        bic:
          type:
          - string
          - 'null'
          description: BIC
        connected:
          type: boolean
          description: 'Whether this account is synchronized from a provider, which is exactly whether

            Altoviz.Api.Models.BankAccount.Provider is set.


            A connected account is read-only: `PUT` and `DELETE` on it are refused. Disconnect

            it in the Altoviz application first if you mean to take it over by hand.'
          readOnly: true
        currency:
          type:
          - string
          - 'null'
          description: ISO currency code. Defaults to EUR.
        defaultPaymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        iban:
          type:
          - string
          - 'null'
          description: IBAN
        id:
          type: integer
          description: Bank account ID
          format: int32
          readOnly: true
        initialBalance:
          type: number
          description: 'Balance the account held before the first transaction Altoviz knows about. The running

            `balance` is derived from it, so changing it moves every balance after it.'
          format: double
        isMain:
          type: boolean
          description: Whether this is the company's main account
          readOnly: true
        journalCode:
          type:
          - string
          - 'null'
          description: Accounting journal code
          readOnly: true
        lastUpdatedAt:
          type:
          - string
          - 'null'
          description: When the account was last synchronized with its provider
          format: date-time
          readOnly: true
        logoUri:
          type:
          - string
          - 'null'
          description: Bank logo URL
          readOnly: true
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            type:
            - string
            - 'null'
          description: 'Metadata: free-form key/value pairs carried with the bank account, for an integration to keep

            its own identifiers and flags against it.


            Sent as a PATCH, not a replacement: keys you send are added or updated, keys you leave out

            keep whatever they held, and a key is removed only when you send it as `null`. Omitting

            the property entirely leaves the whole bag untouched, and `""` stores an empty value

            rather than removing the key.'
        name:
          type:
          - string
          - 'null'
          description: Name
        pendingTransactions:
          type: integer
          description: Transactions not yet reconciled with a document
          format: int32
          readOnly: true
        pendingTransactionsTotal:
          type: number
          description: Total value of the transactions not yet reconciled
          format: double
          readOnly: true
        provider:
          $ref: '#/components/schemas/BankAccountProvider'
        synchronizing:
          type: boolean
          description: Whether a synchronization is running
          readOnly: true
      additionalProperties: false
      description: Bank account
    BankAccountProvider:
      type: object
      properties:
        accountId:
          type:
          - string
          - 'null'
          description: The account's identifier at the provider
          readOnly: true
        accountStatus:
          type:
          - string
          - 'null'
          description: The connection's status as the provider last reported it
          readOnly: true
        bankName:
          type:
          - string
          - 'null'
          description: The bank name the provider reports, which may differ from the account's own
          readOnly: true
        type:
          $ref: '#/components/schemas/BankAccountType'
      additionalProperties: false
      description: 'The provider a bank account is synchronized from. Read-only throughout: a connection is

        established in the Altoviz application, never through this API.'
    Error:
      type: object
      properties:
        errors:
          type:
          - array
          - 'null'
          items:
            type: string
          description: List of error messages
        message:
          type:
          - string
          - 'null'
          description: Error message
      additionalProperties: false
      description: Error
    BankAccountCreate:
      type: object
      properties:
        bankName:
          type:
          - string
          - 'null'
          description: Bank name
        bic:
          type:
          - string
          - 'null'
          description: BIC
        currency:
          type:
          - string
          - 'null'
          description: ISO currency code. Defaults to EUR.
        defaultPaymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        iban:
          type:
          - string
          - 'null'
          description: IBAN
        initialBalance:
          type: number
          description: 'Balance the account held before the first transaction Altoviz knows about. The running

            `balance` is derived from it, so changing it moves every balance after it.'
          format: double
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            type:
            - string
            - 'null'
          description: 'Metadata: free-form key/value pairs carried with the bank account, for an integration to keep

            its own identifiers and flags against it.


            Sent as a PATCH, not a replacement: keys you send are added or updated, keys you leave out

            keep whatever they held, and a key is removed only when you send it as `null`. Omitting

            the property entirely leaves the whole bag untouched, and `""` stores an empty value

            rather than removing the key.'
        name:
          type:
          - string
          - 'null'
          description: Name
      additionalProperties: false
      description: Bank account
    BankProvider:
      type: object
      properties:
        beta:
          type:
          - boolean
          - 'null'
          description: Beta
        branchName:
          type:
          - string
          - 'null'
          description: Bank provider branch name
        countryCodes:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Bank provider country codes
        id:
          type:
          - string
          - 'null'
          description: Bank provider Id
        logoUri:
          type:
          - string
          - 'null'
          description: Bank provider logo URI
        markets:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Bank provider markets
        name:
          type:
          - string
          - 'null'
          description: Bank provider name
      additionalProperties: false
      description: Bank provider
    BankAccountType:
      enum:
      - Standard
      - Stripe
      - GoCardless
      - Paypal
      - SumUp
      - Linxo
      - Other
      type: string
    ProblemDetails:
      type: object
      properties:
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        title:
          type:
          - string
          - 'null'
        type:
          type:
          - string
          - 'null'
      additionalProperties: {}
    BankTransactionNature:
      enum:
      - Transfer
      - Order
      - Check
      - CashDeposit
      - Payback
      - Withdrawal
      - Loan
      - BankFees
      - Card
      - CardSummary
      - Interest
      - Dividend
      - Other
      type: string
    PaymentMethod:
      enum:
      - Transfer
      - Order
      - Check
      - Cash
      - Card
      - Bill
      - Usec
      - Other
      type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      description: 'API KEY generated in application. Example: "X-API-KEY: {apiKey}"'
      name: X-API-KEY
      in: header