K-φ (K-Phi) Excel Import API

openapi: 3.2.0
info:
  title: K-φ Excel Import API
  version: 1.0.0
  description: 'Read your K-φ data (statements, cash, forecasts, scenarios) and save scenarios. The tenant always comes from the credential. Every response is { data, meta }; every error { error: { code, message } }.'
tags:
- name: Excel Import
paths:
  /api/v1/excel_import:
    post:
      operationId: post_excel_import
      summary: 'Import a spreadsheet: preview, then commit'
      x-audience: data
      description: 'WRITE — import rows into K-φ from a spreadsheet the person gave you, in the fixed format (kphi_excel_template): cash forecasts, a GL version, or a bank statement. Read the person''s file yourself, whatever its layout, and send the rows with the template''s column names. Call it WITHOUT commit first: the answer is a preview (what was recognised, the rows refused and why, totals for a GL) and nothing is written; show it to the person. Call it with commit: true only when they confirm. All or nothing: one bad row saves nothing. Up to 2000 rows per call for cash forecasts, 200000 for a GL. Cash forecasts remember their batch (the upload they came from: batch, defaulting to the file name). A sheet sent again: ask the person whether to ADD on top, REPLACE the batch (mode: "replace" removes that batch''s previous lines first) or SYNC it (mode: "sync": line by line, what is new is added, what left the sheet is removed, the rest is kept with its id). Hand-typed lines and other batches always stay. The preview says how many lines the batch holds today and, for sync, the counts it would add, remove and keep.'
      x-scope: write:data
      x-extension-only: false
      security:
      - bearer: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                  meta:
                    type: object
                    properties:
                      api:
                        type: string
                      capability:
                        type: string
                      at:
                        type: string
        '401':
          description: No or invalid credential
        '403':
          description: Scope, extension or Builder Mode refused
        '422':
          description: The capability refused the input
        '429':
          description: Rate or daily quota reached
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                kind:
                  type: string
                  enum:
                  - cash-forecasts
                  - gl
                  - bank-statement
                  description: cash-forecasts (CASH > Cash forecasts), gl (a GL version, K-φ layout), bank-statement (movements of one bank account)
                rows:
                  type: array
                  description: The rows, keyed by the template's column names (any order; missing optional columns left out)
                  items:
                    type: object
                    additionalProperties: true
                text:
                  type: string
                  description: 'Instead of rows: the sheet as tab- or comma-separated text with its header row'
                commit:
                  type: boolean
                  description: 'false (default): preview only. true: save.'
                filename:
                  type: string
                  description: The person's file name, for the audit trail (and the GL version name by default)
                batch:
                  type: string
                  description: 'cash-forecasts: the upload these lines belong to (default: the file name without extension)'
                mode:
                  type: string
                  enum:
                  - add
                  - append
                  - replace
                  - sync
                  description: 'cash-forecasts: add on top (default), replace the batch''s previous lines, or sync line by line (add what is new, remove what left the sheet, keep the rest; the preview says the counts). gl: append (default) or replace the version.'
                vdate:
                  type: string
                  description: 'gl: the version date, yyyy-mm-dd'
                account_id:
                  type: string
                  description: 'bank-statement: the account the movements belong to (from kphi_bank_position)'
                iban:
                  type: string
                  description: 'bank-statement: the account''s IBAN, instead of account_id'
                currency:
                  type: string
                force:
                  type: boolean
                  description: 'bank-statement: import even when the file''s opening + movements do not equal its closing balance'
              required:
              - kind
              additionalProperties: false
      tags:
      - Excel Import
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key, OAuth access token, extension key (kphix_…) or extension session token (kxs1.…)
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key with the gl:ingest scope (ERP connectors)
x-scopes:
  gl:ingest: Push GL data from an ERP (/api/gl/mappings, /api/gl/schema, /api/gl/ingest)
  mcp:tools: All read scopes (read:gl read:cash read:forecast read:sheets read:data)
  mcp:write: All MCP write scopes (write:scenarios write:config write:data write:sheets)
  read:gl: Read statements, KPIs, ratios, GL lines, versions, dimensions, variance, data lake, FX rates and FP&A settings
  read:cash: Read bank positions, transactions, balance history, cash forecast, AR/AP
  read:forecast: Read forecasts, budgets, scenarios (levers, list, run) and valuations
  read:sheets: Read the Google Sheets registered as inputs of the account, each tab as JSON (/api/v1/sheets/…), and their webhooks' deliveries (2026-11-02)
  write:sheets: 'Register and remove the Google Sheets the account serves as JSON (read only: K-φ never writes to a sheet), and the webhooks told when one changes'
  read:data: 'Read the Data library (/api/v1/data/…): market, macro and public series with their source and licence (2026-11-03)'
  write:vars: 'Define, load and remove the account''s own variables (var.<CODE>) of the Data library, and nothing else: never the books (2026-11-05)'
  write:scenarios: Save scenarios (Simulation page)
  write:config: 'Change tenant configuration: flow rules, classification overrides, budget versions and templates, valuation refresh'
  write:data: 'Import rows from a spreadsheet Claude read (Excel in, 2026-10-29): cash forecasts, a GL version, a bank statement; preview first, then commit'
  run:build: 'Call the BUILD''s functions that only read (POST /api/v1/fn/<name>): the logic the account built, served as an API (2026-10-29)'
  run:build:write: 'Also call the BUILD''s functions that change data (declared "writes": true in its kphi.json)'
x-limits:
  per_ip_per_min: 200
  extension_per_min: 120
  extension_per_day: 20000