K-φ (K-Phi) Gl API

openapi: 3.2.0
info:
  title: K-φ Gl 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: Gl
paths:
  /api/gl/schema:
    get:
      operationId: gl_schema
      summary: 'The GL ingest contract: request fields, target fields a mapping can fill…'
      x-scope: gl:ingest
      security:
      - apiKeyHeader: []
      responses:
        '200':
          description: The contract (same content as this description)
        '401':
          description: X-API-Key missing or unknown
        '403':
          description: The key lacks gl:ingest
      tags:
      - Gl
  /api/gl/mappings:
    get:
      operationId: gl_mappings
      summary: 'The mapping templates of this account: the mapping_id to send with an ingest'
      x-scope: gl:ingest
      security:
      - apiKeyHeader: []
      responses:
        '200':
          description: Array of mapping templates
        '401':
          description: X-API-Key missing or unknown
        '403':
          description: The key lacks gl:ingest
      tags:
      - Gl
  /api/gl/ingest:
    post:
      operationId: gl_ingest
      summary: Push raw ERP ledger rows; the mapping template turns them into GL entries, one…
      description: 'A version is one fiscal period. Sending multiple periods with fiscal_year+period_num set is rejected. Locked or approved versions cannot be overwritten (409). Entries posting to a closed period are rejected (409) until reopened in Financial Close. mode: "append" (increment — adds rows) or "replace" (re-snapshots this version, idempotent). Omit to use the connector default. Accounting close stays monthly and is independent of this. append is idempotent by entry_id within a version: re-sending a row with the same source entry_id upserts it rather than double-counting. Send a stable entry_id (or control totals) to be safe against re-sends. Optional control totals — control_dr, control_cr, control_count — are checked against the mapped Actual rows before any write; a mismatch rejects the whole push (422) and ingests nothing.'
      x-scope: gl:ingest
      security:
      - apiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mapping_id
              - data
              properties:
                mapping_id:
                  type: string
                  description: string (required) — mapping template id; list via GET /api/gl/mappings
                data:
                  type: array
                  description: array (required) — raw ERP rows as objects keyed by source column name
                  items:
                    type: object
                    description: one raw ERP row, keyed by source column name
                ver:
                  type: string
                  description: string (optional) — version label; default "ERP_YYYYMMDD"
                vdate:
                  type: string
                  description: string (optional) — version date YYYY-MM-DD; default today
                mode:
                  type: string
                  description: string (optional) — "append" (default) or "replace"
                fiscal_year:
                  type: integer
                  description: integer (optional) — when set with period_num, enforces 1 version = 1 period
                period_num:
                  type: integer
                  description: integer (optional) — 1..12; pair with fiscal_year for period versioning
                version_type:
                  type: string
                  description: string (optional) — default "ACTUALS"
                control_dr:
                  type: number
                  description: optional control total of debits; a mismatch rejects the whole push (422)
                control_cr:
                  type: number
                  description: optional control total of credits
                control_count:
                  type: integer
                  description: optional row count
      responses:
        '200':
          description: Rows ingested
        '400':
          description: mapping_id or data missing, or several periods with fiscal_year+period_num
        '401':
          description: X-API-Key missing or unknown
        '403':
          description: The key lacks gl:ingest
        '404':
          description: Unknown mapping_id
        '409':
          description: Version locked or approved, or period closed
        '422':
          description: 'Control totals do not match: nothing ingested'
        '429':
          description: Entry limit of the plan reached
      tags:
      - Gl
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