Altoviz Statistics API

openapi: 3.2.0
info:
  title: Altoviz Statistics 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: Statistics
  description: Statistics API
paths:
  /v1/statistics/cashflowbyperiodicity:
    get:
      tags:
      - Statistics
      summary: Settled, outstanding and projected cash flow bucketed over a period
      operationId: GET_Statistics_CashFlowByPeriodicity
      parameters:
      - name: from
        in: query
        description: First day of the period. Combined with to, takes precedence over year.
        schema:
          type: string
          format: date
      - name: to
        in: query
        description: Last day of the period, included
        schema:
          type: string
          format: date
      - name: year
        in: query
        description: Shorthand for a whole calendar year (defaults to the current one). Ignored when a range is given.
        schema:
          type: integer
          format: int32
      - name: periodicity
        in: query
        description: 'Bucket size: Daily, Weekly, Monthly (default), Quarterly or Annually'
        schema:
          $ref: '#/components/schemas/Periodicity'
      - name: cumulative
        in: query
        description: Return running totals instead of per-bucket values
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/CashFlowResult'
            application/json:
              schema:
                $ref: '#/components/schemas/CashFlowResult'
            text/json:
              schema:
                $ref: '#/components/schemas/CashFlowResult'
  /v1/statistics/turnovercomparison:
    get:
      tags:
      - Statistics
      summary: Turnover over a period, compared with the same period one year earlier and with…
      operationId: GET_Statistics_TurnoverComparison
      parameters:
      - name: from
        in: query
        description: First day of the period. Combined with to, takes precedence over year.
        schema:
          type: string
          format: date
      - name: to
        in: query
        description: Last day of the period, included
        schema:
          type: string
          format: date
      - name: year
        in: query
        description: Shorthand for a whole calendar year (defaults to the current one). Ignored when a range is given.
        schema:
          type: integer
          format: int32
      - name: expenses
        in: query
        description: Purchases instead of sales
        schema:
          type: boolean
          default: false
      - name: paid
        in: query
        description: 'Count what was actually settled (encaissements) instead of what was invoiced. Always applied

          for a micro-business, which is taxed on its encaissements — check company.isMicroBusiness in

          the settings before choosing.'
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/TurnoverComparisonResult'
            application/json:
              schema:
                $ref: '#/components/schemas/TurnoverComparisonResult'
            text/json:
              schema:
                $ref: '#/components/schemas/TurnoverComparisonResult'
  /v1/statistics/globalturnover:
    get:
      tags:
      - Statistics
      summary: All-time total turnover
      operationId: GET_Statistics_GlobalTurnover
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/GlobalTurnoverResult'
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalTurnoverResult'
            text/json:
              schema:
                $ref: '#/components/schemas/GlobalTurnoverResult'
  /v1/statistics/turnoverevolution:
    get:
      tags:
      - Statistics
      summary: Turnover over a period, bucketed, optionally compared against the same period…
      operationId: GET_Statistics_TurnoverEvolution
      parameters:
      - name: from
        in: query
        description: First day of the period. Combined with to, takes precedence over year.
        schema:
          type: string
          format: date
      - name: to
        in: query
        description: Last day of the period, included
        schema:
          type: string
          format: date
      - name: year
        in: query
        description: Shorthand for a whole calendar year (defaults to the current one). Ignored when a range is given.
        schema:
          type: integer
          format: int32
      - name: periodicity
        in: query
        description: 'Bucket size: Daily, Weekly, Monthly (default), Quarterly or Annually'
        schema:
          $ref: '#/components/schemas/Periodicity'
      - name: compare
        in: query
        description: Number of previous periods to return alongside, each one calendar year further back (0–2, defaults to 0)
        schema:
          type: integer
          format: int32
      - name: type
        in: query
        description: Dimension to break down by
        schema:
          $ref: '#/components/schemas/TurnoverEvolutionType'
      - name: cumulative
        in: query
        description: Return running totals instead of per-bucket values
        schema:
          type: boolean
          default: false
      - name: customerId
        in: query
        description: Filter by customer ID
        schema:
          type: integer
          format: int32
      - name: supplierId
        in: query
        description: Filter by supplier ID
        schema:
          type: integer
          format: int32
      - name: colleagueId
        in: query
        description: Filter by colleague ID
        schema:
          type: integer
          format: int32
      - name: productId
        in: query
        description: Filter by product ID
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/TurnoverEvolutionResult'
            application/json:
              schema:
                $ref: '#/components/schemas/TurnoverEvolutionResult'
            text/json:
              schema:
                $ref: '#/components/schemas/TurnoverEvolutionResult'
  /v1/statistics/paymentdelay:
    get:
      tags:
      - Statistics
      summary: 'How long payments actually take over a period: average and median days from the…'
      description: 'Answers "do my customers pay me on time, and how late are they?". Read the medians rather than

        the averages — the mean is dragged by a small tail of very late payers, so it can report a

        month''s delay where the typical invoice is paid on time.'
      operationId: GET_Statistics_PaymentDelay
      parameters:
      - name: from
        in: query
        description: First day of the period. Combined with to, takes precedence over year.
        schema:
          type: string
          format: date
      - name: to
        in: query
        description: Last day of the period, included
        schema:
          type: string
          format: date
      - name: year
        in: query
        description: Shorthand for a whole calendar year (defaults to the current one). Ignored when a range is given.
        schema:
          type: integer
          format: int32
      - name: periodicity
        in: query
        description: 'Bucket size: Daily, Weekly, Monthly (default), Quarterly or Annually'
        schema:
          $ref: '#/components/schemas/Periodicity'
      - name: side
        in: query
        description: Customers (default) or suppliers
        schema:
          $ref: '#/components/schemas/PaymentDelaySide'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PaymentDelayResult'
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentDelayResult'
            text/json:
              schema:
                $ref: '#/components/schemas/PaymentDelayResult'
  /v1/statistics/unpaidinvoices:
    get:
      tags:
      - Statistics
      summary: Aged balance of money owed by customers, bucketed by how far each échéance is…
      description: Answers "who owes me money, and how late is it?" as totals per age bucket.
      operationId: GET_Statistics_UnpaidInvoices
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnpaidCommitmentBucket'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnpaidCommitmentBucket'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnpaidCommitmentBucket'
  /v1/statistics/unpaidexpenses:
    get:
      tags:
      - Statistics
      summary: Aged balance of money owed to suppliers, bucketed by how far each échéance is…
      description: The payables mirror of M:Altoviz.Api.Controllers.StatisticsController.UnpaidInvoices(Altoviz.Api.Services.InvoicingClientService); subtract one from the other for a net position.
      operationId: GET_Statistics_UnpaidExpenses
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnpaidCommitmentBucket'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnpaidCommitmentBucket'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UnpaidCommitmentBucket'
  /v1/statistics/topoverduecustomers:
    get:
      tags:
      - Statistics
      summary: Customers with overdue échéances, ranked by outstanding amount
      description: 'Answers "who should I chase first?". Includes the age of each customer''s oldest unpaid

        échéance and when they were last reminded, so "never chased" can be told from "chased and

        still not paying".'
      operationId: GET_Statistics_TopOverdueCustomers
      parameters:
      - name: take
        in: query
        description: How many customers to return (1–20, defaults to 5)
        schema:
          type: integer
          format: int32
          default: 5
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OverdueCustomer'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OverdueCustomer'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OverdueCustomer'
  /v1/statistics/einvoicingready:
    get:
      tags:
      - Statistics
      summary: 'E-invoicing readiness: suppliers and customers configured, and those with issues'
      operationId: GET_Statistics_EinvoicingReady
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/EinvoicingReadyResult'
            application/json:
              schema:
                $ref: '#/components/schemas/EinvoicingReadyResult'
            text/json:
              schema:
                $ref: '#/components/schemas/EinvoicingReadyResult'
components:
  schemas:
    TurnoverComparisonResult:
      type: object
      properties:
        current:
          $ref: '#/components/schemas/TurnoverPeriodValue'
        precedingPeriod:
          $ref: '#/components/schemas/TurnoverPeriodValue'
        previousYear:
          $ref: '#/components/schemas/TurnoverPeriodValue'
      additionalProperties: false
      description: 'A period against the two references that make it readable: the same period one year earlier,

        and the period of equal length immediately before it.'
    PeriodBucketModel:
      type: object
      properties:
        partial:
          type: boolean
          description: 'True when the calendar period was clipped by the requested range, so the bucket holds

            less than a full month/quarter/week of activity and must not be compared at face value.'
        range:
          $ref: '#/components/schemas/DateRangeModel'
        value:
          type: number
          description: Amount (tax excluded)
          format: double
      additionalProperties: false
      description: One point of a series, covering a single bucket of the period
    OverdueCustomer:
      type: object
      properties:
        customerId:
          type: integer
          description: Customer identifier
          format: int32
        customerName:
          type:
          - string
          - 'null'
          description: Customer name at the time of the query
        invoiceCount:
          type: integer
          description: How many échéances make up the amount
          format: int32
        lastReminderOn:
          type:
          - string
          - 'null'
          description: Most recent reminder sent to this customer, or null if never chased
          format: date-time
        oldestOverdueDays:
          type: integer
          description: Age in days of the oldest unpaid échéance
          format: int32
        overdueAmount:
          type: number
          description: Sum still due on échéances past their date
          format: double
      additionalProperties: false
      description: A customer with overdue échéances
    DateRangeModel:
      type: object
      properties:
        from:
          type: string
          description: First day of the period
          format: date
        to:
          type: string
          description: Last day of the period, included
          format: date
      additionalProperties: false
      description: An inclusive date range
    Periodicity:
      enum:
      - Daily
      - Weekly
      - Monthly
      - Quarterly
      - Annually
      type: string
    GlobalTurnoverResult:
      type: object
      properties:
        total:
          type: number
          description: Total turnover (tax excluded)
          format: double
      additionalProperties: false
      description: All-time total turnover
    TurnoverEvolutionType:
      enum:
      - Sales
      - Expenses
      - Customer
      - Supplier
      - Product
      - Colleague
      - Margin
      - Discount
      type: string
      description: Dimension used to break down turnover evolution
    PeriodSeriesModel:
      type: object
      properties:
        buckets:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PeriodBucketModel'
          description: Values, one per bucket
        label:
          type:
          - string
          - 'null'
          description: 'Display label: the year for a whole calendar year, otherwise the bounds'
        offset:
          type: integer
          description: 0 for the requested period, 1 for one calendar year earlier, and so on
          format: int32
        range:
          $ref: '#/components/schemas/DateRangeModel'
      additionalProperties: false
      description: The requested period, or the same period in an earlier year
    PaymentDelayResult:
      type: object
      properties:
        daysLate:
          $ref: '#/components/schemas/TurnoverEvolutionResult'
        daysToPayment:
          $ref: '#/components/schemas/TurnoverEvolutionResult'
        lateShare:
          type: number
          description: Share of the settled amount paid after its due date, 0..1
          format: double
        medianDaysLate:
          type:
          - number
          - 'null'
          description: Median days from due date to payment. Null when nothing settled
          format: double
        medianDaysToPayment:
          type:
          - number
          - 'null'
          description: Median days from document date to payment. Null when nothing settled
          format: double
        settled:
          $ref: '#/components/schemas/TurnoverEvolutionResult'
        settledAmount:
          type: number
          description: Total settled over the period
          format: double
      additionalProperties: false
      description: How long payments actually take over a period.
    TurnoverEvolutionResult:
      type: object
      properties:
        periodicity:
          $ref: '#/components/schemas/Periodicity'
        range:
          $ref: '#/components/schemas/DateRangeModel'
        series:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PeriodSeriesModel'
          description: The requested period first, then any comparison periods
      additionalProperties: false
      description: 'Turnover bucketed over a period. Every series holds the same number of buckets and bucket

        N of each series covers the same period shifted by its `offset` in years, so series can

        be compared index by index.'
    CashFlowResult:
      type: object
      properties:
        expenses:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PeriodBucketModel'
          description: Amounts actually paid out
        periodicity:
          $ref: '#/components/schemas/Periodicity'
        profits:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PeriodBucketModel'
          description: Receipts minus expenses
        projectedExpenses:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PeriodBucketModel'
          description: Paid plus still outstanding
        projectedProfits:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PeriodBucketModel'
          description: Projected receipts minus projected expenses
        projectedReceipts:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PeriodBucketModel'
          description: Received plus still outstanding
        range:
          $ref: '#/components/schemas/DateRangeModel'
        receipts:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PeriodBucketModel'
          description: Amounts actually received
        unpaidExpenses:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PeriodBucketModel'
          description: Payables still outstanding
        unpaidProfits:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PeriodBucketModel'
          description: Outstanding receivables minus outstanding payables
        unpaidReceipts:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PeriodBucketModel'
          description: Receivables still outstanding
      additionalProperties: false
      description: 'Cash flow bucketed over a period: what was settled, what is still outstanding, and the two

        added together. Every list shares the same buckets, so index N is the same period throughout.'
    PaymentDelaySide:
      enum:
      - Customers
      - Suppliers
      type: string
      description: Which side of the ledger a payment delay is measured on
    UnpaidCommitmentBucket:
      type: object
      properties:
        count:
          type: integer
          description: Number of échéances in this bucket
          format: int32
        period:
          type: integer
          description: 'Negative is overdue, 0 is due today, positive is upcoming. -7 is more than 90 days late, 7 more

            than 90 days ahead; the steps in between are 1, 7, 15, 30, 60 and 90 days.'
          format: int32
        total:
          type: number
          description: Amount still due in this bucket
          format: double
      additionalProperties: false
      description: One bucket of an aged balance, keyed by distance from today
    EinvoicingReadyResult:
      type: object
      properties:
        customerIssuesCount:
          type: integer
          description: Number of customers with e-invoicing configuration issues
          format: int32
        customersCount:
          type: integer
          description: Number of customers configured for e-invoicing
          format: int32
        supplierIssuesCount:
          type: integer
          description: Number of suppliers with e-invoicing configuration issues
          format: int32
        suppliersCount:
          type: integer
          description: Number of suppliers configured for e-invoicing
          format: int32
      additionalProperties: false
      description: E-invoicing readiness summary across suppliers and customers
    TurnoverPeriodValue:
      type: object
      properties:
        label:
          type:
          - string
          - 'null'
          description: 'Display label: the year for a whole calendar year, otherwise the bounds'
        range:
          $ref: '#/components/schemas/DateRangeModel'
        value:
          type: number
          description: Total turnover amount (tax excluded)
          format: double
      additionalProperties: false
      description: A turnover total over a period
  securitySchemes:
    ApiKey:
      type: apiKey
      description: 'API KEY generated in application. Example: "X-API-KEY: {apiKey}"'
      name: X-API-KEY
      in: header