{"openapi":"3.1.0","info":{"title":"Bokflinken suggestor API","version":"1","description":"Read an organization's books and suggest entries for a human to review.\n\nAn API key belongs to one organization. With it you can read everything listed here, and write one thing: entry suggestions. A suggestion is never booked by itself. A member of the organization approves it (it becomes a draft and is booked like any other draft), edits it, or rejects it.\n\nAmounts are whole numbers of öre. Dates are YYYY-MM-DD. Accounts are BAS account numbers.\n\nBefore suggesting, check /entries, /drafts and /suggestions/entries for the same transaction, and send an externalRef (for example the bank transaction id) so that a retry does not create a duplicate."},"servers":[{"url":"http://app.bokflinken.se/api/v1"}],"security":[{"apiKey":[]}],"paths":{"/organization":{"get":{"summary":"The organization this key belongs to","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Suggestor API access is not enabled for the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscal-years":{"get":{"summary":"Fiscal years, with their dates and status","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Suggestor API access is not enabled for the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/accounts":{"get":{"summary":"Chart of accounts","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Suggestor API access is not enabled for the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts":{"get":{"summary":"Customers and suppliers","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Suggestor API access is not enabled for the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices":{"get":{"summary":"Invoices","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Suggestor API access is not enabled for the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entries":{"get":{"summary":"Booked ledger entries with rows, for one fiscal year","parameters":[{"name":"fiscalYear","in":"query","required":true,"description":"A fiscal year name from /fiscal-years","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Suggestor API access is not enabled for the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entries/{entryId}":{"get":{"summary":"One ledger entry with its row history","parameters":[{"name":"entryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Suggestor API access is not enabled for the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts":{"get":{"summary":"Pending drafts: entries waiting to be booked (from invoices, entered manually, or approved suggestions)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Suggestor API access is not enabled for the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/suggestions/entries":{"get":{"summary":"Suggestions made with API keys, newest first","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["suggested","approved","booked","rejected"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EntrySuggestion"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Suggestor API access is not enabled for the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Suggest an entry","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntrySuggestionBody"}}}},"responses":{"200":{"description":"A suggestion with this externalRef already exists; it is returned unchanged","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EntrySuggestion"}}}}}},"201":{"description":"The suggestion was created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EntrySuggestion"}}}}}},"400":{"description":"The body does not match the schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Suggestor API access is not enabled for the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The entry cannot be suggested: unknown or closed account, no open fiscal year for the date, or rows that do not balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/suggestions/entries/{suggestionId}":{"get":{"summary":"One suggestion, to see what became of it","parameters":[{"name":"suggestionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EntrySuggestion"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Suggestor API access is not enabled for the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such suggestion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key created under Settings > API keys: Authorization: Bearer bf_..."}},"schemas":{"EntrySuggestionBody":{"type":"object","properties":{"date":{"type":"string","description":"Transaction date, YYYY-MM-DD. Decides the fiscal year."},"description":{"type":"string","description":"The entry text, as it will appear in the journal"},"rows":{"type":"array","items":{"type":"object","properties":{"accountNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"BAS account number, e.g. 1930"},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Amount in öre, a positive whole number"},"isDebit":{"type":"boolean","description":"true for a debit row, false for a credit row"},"description":{"type":"string"}},"required":["accountNumber","amount","isDebit"],"additionalProperties":true},"description":"At least two rows; debits must equal credits"},"note":{"type":"string","description":"Note to the human reviewer: which document this came from, why these accounts"},"externalRef":{"type":"string","description":"Your own reference for the transaction. Posting the same reference again returns the first suggestion instead of creating a duplicate."}},"required":["date","description","rows"],"additionalProperties":true},"EntrySuggestion":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["suggested","approved","booked","rejected"]},"date":{"type":"string"},"fiscalYear":{"type":"string"},"description":{"type":"string"},"totalAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Sum of debits in öre"},"externalRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"suggestedBy":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Name of the API key that made the suggestion"},"entryId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The ledger entry, once the suggestion is booked"},"createdAt":{"type":"string"},"rows":{"type":"array","items":{"type":"object","properties":{"rowNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"accountNumber":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"accountName":{"type":"string"},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"isDebit":{"type":"boolean"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["rowNumber","accountNumber","accountName","amount","isDebit","description"],"additionalProperties":true}}},"required":["id","status","date","fiscalYear","description","totalAmount","externalRef","note","suggestedBy","entryId","createdAt","rows"],"additionalProperties":true},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","method_not_allowed","invalid_request","unprocessable","internal_error"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}},"required":["error"],"additionalProperties":true}}}}