{"contract":"kphi-ingest","version":"1","status":"draft","notes":"One shape per kind of financial record, whatever system it comes from. A connection (recipe) maps its source fields to these; a file, an API call or a sync all land the same way. Draft until the owner validates it: field names may still change.","conventions":{"dates":"YYYY-MM-DD (FX also accepts YYYY-MM, a monthly rate)","currencies":"ISO 4217, three upper-case letters","amounts":"numbers, not strings; a dot for decimals; no thousands separator","signs":"TRA: positive = money in, negative = money out. INV: positive, a credit note is negative. PAY and LOAN principal: positive.","ids":"the source system's own id, stable across syncs: a re-sync with the same id updates, it never duplicates","unknown_fields":"refused, so a typo is caught instead of silently dropped; put extra source fields in raw (an object, kept as is)"},"objects":{"GL":{"name":"General ledger entries","description":"Journal lines, one per account and side. Actuals land in one ledger version per month (named YYYY-MM), a budget or a forecast in the version you name. The source's own line id makes a re-send update the line, never add it twice (owner, 2026-11-13).","lands_in":"the ledger (gl_entries, versions)","ingest":"B5","key":["version","id"],"fields":{"id":{"type":"string","required":true,"max":128,"desc":"The source system's own id for the line"},"date":{"type":"date","required":true,"desc":"Posting date"},"entity":{"type":"string","required":true,"max":40,"desc":"Company code, as in K-φ"},"acct":{"type":"string","required":true,"max":40,"desc":"Ledger account"},"desc":{"type":"string","max":300},"dr":{"type":"number","desc":"Debit, 0 or more"},"cr":{"type":"number","desc":"Credit, 0 or more"},"ccy":{"type":"currency","required":true},"bu":{"type":"string","max":40,"desc":"Business unit (optional axis)"},"tp":{"type":"string","max":80,"desc":"Third party (optional axis)"},"version_type":{"type":"enum","values":["ACTUALS","BUDGET","FORECAST"],"default":"ACTUALS"},"version":{"type":"string","max":60,"desc":"Required for a budget or a forecast (e.g. Budget 2026); actuals go to their month"}}},"BAL":{"name":"Bank balances","description":"One closing balance per bank account per day. The account is created on first sight.","lands_in":"bank_accounts, bank_balances","ingest":"B5","key":["account_ref","date"],"fields":{"account_ref":{"type":"string","required":true,"max":64,"compact":true,"desc":"IBAN, the account number as the bank gives it, or the account's code in K-φ (Accounts & mapping)"},"account_name":{"type":"string","max":120,"desc":"Name shown in K-φ"},"bank_name":{"type":"string","max":120},"currency":{"type":"currency","required":true},"date":{"type":"date","required":true,"desc":"Balance date (end of day)"},"balance":{"type":"number","required":true,"desc":"Closing booked balance"},"available":{"type":"number","desc":"Available balance, when the bank gives one"},"kind":{"type":"enum","values":["reported","statement"],"default":"reported","desc":"statement = from a bank statement (never overwritten); reported = from an API"},"entity":{"type":"string","max":40,"desc":"K-φ entity code the account belongs to"},"bu":{"type":"string","max":40},"gl_account":{"type":"string","max":40,"desc":"Ledger account the bank account posts to"},"raw":{"type":"object"}}},"TRA":{"name":"Bank transactions","lands_in":"bank_transactions","ingest":"B5","key":["id"],"fields":{"id":{"type":"string","required":true,"max":128,"desc":"The bank's own reference for the movement"},"account_ref":{"type":"string","required":true,"max":64,"compact":true,"desc":"Same value as BAL.account_ref: IBAN, number or K-φ account code"},"date":{"type":"date","required":true,"desc":"Value date"},"booking_date":{"type":"date"},"amount":{"type":"number","required":true,"nonzero":true,"desc":"Signed: positive = money in"},"currency":{"type":"currency","required":true},"description":{"type":"string","max":500},"counterparty":{"type":"string","max":200},"bank_code":{"type":"string","max":40,"desc":"Bank transaction code (BTC, BAI...)"},"status":{"type":"enum","values":["posted","pending"],"default":"posted"},"raw":{"type":"object"}}},"INV":{"name":"Invoices (receivables and payables)","description":"Open and settled AR and AP items. A re-sync with the same id updates the item.","lands_in":"invoices, invoice_settlements","ingest":"B5","key":["id"],"fields":{"id":{"type":"string","required":true,"max":128,"desc":"The source system's invoice id"},"direction":{"type":"enum","values":["AR","AP"],"required":true,"desc":"AR = a customer owes us, AP = we owe a supplier"},"number":{"type":"string","max":64,"desc":"Invoice number as printed"},"counterparty_code":{"type":"string","max":64},"counterparty_name":{"type":"string","max":200},"entity":{"type":"string","max":40},"bu":{"type":"string","max":40},"gl_account":{"type":"string","max":40},"currency":{"type":"currency","required":true},"amount":{"type":"number","required":true,"nonzero":true,"desc":"Total incl. tax; a credit note is negative"},"open_amount":{"type":"number","desc":"Still to be paid; defaults to amount. 0 = paid"},"issue_date":{"type":"date"},"due_date":{"type":"date","required":true},"paid_date":{"type":"date","desc":"When fully paid"},"raw":{"type":"object"}},"rules":["one_of:counterparty_code,counterparty_name","abs_le:open_amount,amount","same_sign:open_amount,amount","date_order:issue_date,due_date"]},"MAP":{"name":"Mappings","description":"How the source's codes map to K-φ: a ledger account to a category, a bank account to an entity and ledger account, a source entity code to a K-φ entity.","lands_in":"chart of accounts (config cfg), bank_accounts, datalake_entity_map","ingest":"B5","key":["kind","source_code"],"fields":{"kind":{"type":"enum","values":["ledger_account","bank_account","entity"],"required":true},"source_code":{"type":"string","required":true,"max":64,"desc":"Ledger account number, bank account ref, or the source's entity code"},"name":{"type":"string","max":200},"category":{"type":"string","max":40,"desc":"ledger_account: K-φ category (asset, liability, equity, revenue, cogs, opex, tax...)"},"subcategory":{"type":"string","max":80},"entity":{"type":"string","max":40,"desc":"bank_account and entity: the K-φ entity code"},"bu":{"type":"string","max":40},"gl_account":{"type":"string","max":40,"desc":"bank_account: the ledger account it posts to"}},"rules":["when:kind=ledger_account:required:category","when:kind=bank_account:required:entity","when:kind=entity:required:entity"]},"FX":{"name":"FX rates","description":"1 unit of from = rate units of to. Monthly: closing (end of month), average (the month), historical.","lands_in":"config fx_rates (monthly closing / average / historical)","ingest":"B5","key":["date","from","to","rate_type"],"fields":{"date":{"type":"month_or_date","required":true,"desc":"YYYY-MM, or a YYYY-MM-DD date (its month is used)"},"from":{"type":"currency","required":true},"to":{"type":"currency","required":true},"rate":{"type":"number","required":true,"positive":true},"rate_type":{"type":"enum","values":["closing","average","historical"],"required":true}},"rules":["differ:from,to"]},"LOAN":{"name":"Loans and facilities","description":"Debt facilities for covenants and the cash forecast, with their repayment schedule when known.","lands_in":"none yet: K-φ has no loan storage today (covenants hold a facility label only). Validated now; stored when the loan store is built.","ingest":"not yet","key":["id"],"fields":{"id":{"type":"string","required":true,"max":128},"name":{"type":"string","required":true,"max":200},"lender":{"type":"string","max":200},"entity":{"type":"string","max":40},"currency":{"type":"currency","required":true},"principal":{"type":"number","required":true,"positive":true,"desc":"Amount drawn or committed at start"},"outstanding":{"type":"number","desc":"Principal still owed today"},"start_date":{"type":"date","required":true},"maturity_date":{"type":"date","required":true},"rate_kind":{"type":"enum","values":["fixed","floating"],"required":true},"rate":{"type":"number","desc":"Annual rate in %, fixed (or the current all-in floating rate)"},"index":{"type":"string","max":40,"desc":"Floating: SOFR, EURIBOR 3M, SONIA..."},"margin":{"type":"number","desc":"Floating: margin over the index, in %"},"repayment":{"type":"enum","values":["bullet","amortising","custom"],"required":true},"frequency":{"type":"enum","values":["monthly","quarterly","semiannual","annual"]},"gl_account":{"type":"string","max":40},"schedule":{"type":"array","max":600,"items":{"date":{"type":"date","required":true},"principal":{"type":"number","required":true},"interest":{"type":"number"}},"desc":"Repayments; required when repayment is custom"},"raw":{"type":"object"}},"rules":["date_order:start_date,maturity_date","abs_le:outstanding,principal","when:rate_kind=fixed:required:rate","when:rate_kind=floating:required:index","when:repayment=custom:required:schedule","when:repayment=amortising:required:frequency"]},"PAY":{"name":"Payment instructions","description":"Payments to make, prepared in another system. In K-φ they go through the same approval and signature as any payment run.","lands_in":"payments_beneficiaries, payments_runs (as a draft run)","ingest":"not yet","key":["id"],"fields":{"id":{"type":"string","required":true,"max":128},"entity":{"type":"string","max":40},"debit_account_ref":{"type":"string","required":true,"max":64,"compact":true,"desc":"The paying account (BAL.account_ref)"},"beneficiary_name":{"type":"string","required":true,"max":140},"beneficiary_iban":{"type":"iban"},"beneficiary_account_number":{"type":"string","max":34},"beneficiary_routing_code":{"type":"string","max":20,"desc":"US routing number or UK sort code"},"beneficiary_country":{"type":"string","pattern":"^[A-Z]{2}$","desc":"ISO 3166 two letters"},"currency":{"type":"currency","required":true},"amount":{"type":"number","required":true,"positive":true},"execution_date":{"type":"date","required":true},"reference":{"type":"string","max":140,"desc":"Remittance text the beneficiary sees"},"invoice_ref":{"type":"string","max":128,"desc":"INV.id of the AP invoice this pays, when there is one"},"raw":{"type":"object"}},"rules":["one_of:beneficiary_iban,beneficiary_account_number","when:beneficiary_account_number:required:beneficiary_routing_code"]},"VAR":{"name":"Variables","description":"Any reference series the account defines: a price, a curve, an index, a margin rate, a volume. One value per variable, date and key; key empty for a single value a day, a tenor (3M, 10Y) or any label for a curve or a set. A variable named for the first time is created. A sheet tab VAR holds these columns; a tab \"VAR - BRENT\" may instead have date, value (or date, 3M, 1Y, 10Y: one column per key).","lands_in":"variables, variable_points (the account's own: Data library series var.<CODE>)","ingest":"B5","key":["variable","date","key"],"fields":{"variable":{"type":"string","required":true,"max":40,"desc":"The variable's code: letters, digits, _ . or - (BRENT, EUR_SWAP, MARGIN.ICE); upper-cased"},"date":{"type":"date","required":true},"key":{"type":"string","max":20,"desc":"Empty for a single value a day; a tenor (3M, 10Y), a contract month (2026-12) or any label for a curve or a set"},"value":{"type":"number","required":true},"unit":{"type":"string","max":30,"desc":"Kept when the variable is created or has no unit yet (USD/bbl, %, index)"},"name":{"type":"string","max":120,"desc":"Kept when the variable is created"}}}}}