# NISA API REST API for POHODA accounting data of companies connected to NISA. ## Base URL All endpoints are under `http://0.0.0.0:1409/v1/`. Requests and responses use UTF-8. ## API key NISA issues an API key for each integration. Request it at `info@nisa.digital`. Keep the key on your server and never put it into browser or mobile app code. NISA enables API access for each company separately. Requests for a company without API access return 404. ## Authorization Send the API key in the `Authorization` header of every request. An unknown key returns 401. Requests without the `Authorization` header read only the demo company. The examples on this page use it. ``` Authorization: Bearer ``` ## Company and accounting unit A company has a company id (`cid`), which NISA sends together with the API key. Each accounting year of the company is a separate accounting unit with its own id (`uid`). `GET /v1/info/:cid` lists the accounting units of the company with `uid`, `year`, `id_number` (IČO), `valid_from` and `valid_to`. Most endpoints take the `uid` as a path parameter. ``` curl -H "Authorization: Bearer " http://0.0.0.0:1409/v1/info/ curl -H "Authorization: Bearer " http://0.0.0.0:1409/v1/accounts_chart/ ``` ## Requests and responses Each endpoint lists its method, path and query parameters, request body with the required `Content-Type`, and response. Responses are JSON unless the endpoint states otherwise. Errors return one of the HTTP status codes below. The body is usually a short text message; some endpoints return an empty body or the POHODA XML response instead. ``` 400 Bad Request: Your request doesn't meet the required input format 401 Not Authorized: Your request doesn't meet authorization requirements 404 Not Found: The entity you're looking for is missing 460 Request Error: Requested operation wasn't performed, or XML import failed 500 Internal Error: We encountered an internal server error 503 Not Available: Requested entity is offline and cannot be reached, try again later ``` ## Digitálny poštár Endpoints under `/v1/epostar/` use a separate API key (`Authorization: Bearer ep_...`), return errors as JSON and limit the number of requests per minute. The section `/v1/epostar/` describes the details. ## Documentation for language models The complete documentation as one text file, for a language model (LLM) or a coding assistant: `http://0.0.0.0:1409/guide`, also available as `http://0.0.0.0:1409/llms.txt`. # Endpoints ## /v1/slovensko/ ### /v1/slovensko/tax/:search Lookup companies in the tax register. Example: http://0.0.0.0:1409/v1/slovensko/tax/etlab Parameters: ``` :search - partial company name or ICO ``` Request: ``` GET ``` Response: ``` 200 text/json { cin: string, company id (ICO) tin: string, tax id (DIC) vatin: string, VAT id (ICDPH) name: string street: string municipality: string postal_code: string country: string effective_to: string, YYYY-MM-DD }[] ``` ### /v1/slovensko/vat/:search Lookup companies in the VAT register. Example: http://0.0.0.0:1409/v1/slovensko/vat/etlab Parameters: ``` :search - partial company name or ICO ``` Request: ``` GET ``` Response: ``` 200 text/json { cin: string, company id (ICO) vatin: string, VAT id (ICDPH) name: string street: string municipality: string postal_code: string country: string effective_to: string, YYYY-MM-DD registered_on: string, YYYY-MM-DD registration_kind: string }[] ``` ## /v1/info/ ### /v1/info/:cid List accounting units (years) for a company id prefix. Example: http://0.0.0.0:1409/v1/info/88899460-4d0b-421b8d67 Request: ``` GET ``` Response: ``` 200 text/json ``` ## /v1/costcenter/ ### /v1/costcenter/:uid List cost centers for a unit. Example: http://0.0.0.0:1409/v1/costcenter/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { ID: number, database id IDS: string, cost center id SText: string, cost center name }[] ``` ## /v1/activity/ ### /v1/activity/:uid List activities for a unit. Example: http://0.0.0.0:1409/v1/activity/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { ID: number, database id IDS: string, activity id SText: string, activity name }[] ``` ## /v1/custom_order/ ### /v1/custom_order/:uid List custom orders for a unit. Example: http://0.0.0.0:1409/v1/custom_order/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { ID: number, database id IDS: string, activity id SText: string, activity name }[] ``` ## /v1/vat/ ### /v1/vat/:uid List VAT mappings: pre-accounting, VAT breakdown, and KV DPH groups. Example: http://0.0.0.0:1409/v1/vat/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { available: ( 'issued_invoices'| 'issued_credit_notes'| 'issued_advance_invoices'| 'issued_receivables'| 'received_invoices'| 'received_credit_notes'| 'received_advance_invoices'| 'received_payables' )[], incoming: ( 'issued_invoices'| 'issued_credit_notes'| 'issued_advance_invoices'| 'issued_receivables' )[], outgoing: ( 'received_invoices'| 'received_credit_notes'| 'received_advance_invoices'| 'received_payables' )[], pre_accounting: { issued_invoices: { ID: number, IDS: string, SText: string }[], issued_credit_notes: { ID: number, IDS: string, SText: string }[], issued_advance_invoices: { ID: number, IDS: string, SText: string }[], issued_receivables: { ID: number, IDS: string, SText: string }[], received_invoices: { ID: number, IDS: string, SText: string }[], received_credit_notes: { ID: number, IDS: string, SText: string }[], received_advance_invoices: { ID: number, IDS: string, SText: string }[], received_payables: { ID: number, IDS: string, SText: string }[], }, vat_breakdown: { issued_invoices: { ID: number, IDS: string, SText: string }[], issued_credit_notes: { ID: number, IDS: string, SText: string }[], issued_advance_invoices: { ID: number, IDS: string, SText: string }[], issued_receivables: { ID: number, IDS: string, SText: string }[], received_invoices: { ID: number, IDS: string, SText: string }[], received_credit_notes: { ID: number, IDS: string, SText: string }[], received_advance_invoices: { ID: number, IDS: string, SText: string }[], received_payables: { ID: number, IDS: string, SText: string }[], }, vat_split: { issued_invoices: { ID: number, IDS: string, SText: string }[], issued_credit_notes: { ID: number, IDS: string, SText: string }[], issued_advance_invoices: { ID: number, IDS: string, SText: string }[], issued_receivables: { ID: number, IDS: string, SText: string }[], received_invoices: { ID: number, IDS: string, SText: string }[], received_credit_notes: { ID: number, IDS: string, SText: string }[], received_advance_invoices: { ID: number, IDS: string, SText: string }[], received_payables: { ID: number, IDS: string, SText: string }[], }, } ``` ## /v1/accounts_chart/ ### /v1/accounts_chart/:uid List chart of accounts for a unit. Example: http://0.0.0.0:1409/v1/accounts_chart/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { ID: number, database id IDS: string, account number SText: string, account name }[] ``` ## /v1/accounting_journal/ ### /v1/accounting_journal/:uid List accounting journal entries for a unit. Example: http://0.0.0.0:1409/v1/accounting_journal/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { Datum: date, date DatZdPln: date, date of taxable supply Cislo: string, number SText: string, text UMD: string, umd UD: string, ud Kc: number, amount Mena: string, currency CmKurs: number, exchange rate in foreign currency Cm: number, amount in foreign currency Stredisko: string, cost center CisloZAK: string, order number Cinnost: string, activity ParSym: string, pairing symbol ParSym2: string, pairing symobol Firma: string, company Jmeno: string, name ParICO: string, company id Pozn: string, note DatCreate: date, creation date DatSave: date, date of modification }[] ``` ## /v1/invoice/ ### /v1/invoice/numbering/:uid List invoice numberings for a unit. Example: http://0.0.0.0:1409/v1/invoice/numbering/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { type: 'pohoda_sk'|'pohoda_cz' available: ( 'issued_invoice'| 'issued_credit_note'| 'issued_advance_invoice'| 'issued_receivables'| 'received_invoice'| 'received_credit_note'| 'received_advance_invoice'| 'received_payables' )[] numbering: { ID: number, database id Rok: number, numbering year IDS: string, numbering prefix Cislo: string, next number SText: string, naming type: one of 'available' values }[] } Usually, number is IDS + Cislo, e.g. "PF2300001" ``` ### /v1/invoice/export/pdf/:uid/:invoice_number Export invoice PDF by number. Example: http://0.0.0.0:1409/v1/invoice/export/pdf/88899460-4d0b-421b8d67-2023/VD00000001 Parameters: ``` :uid - accounting unit identifier :invoice_number - invoice number ``` Request: ``` GET ``` Response: ``` 200 application/pdf Buffer PDF ``` ### /v1/invoice/companies/:uid List companies referenced by unit invoices. Example: http://0.0.0.0:1409/v1/invoice/companies/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { Firma: string, company name Jmeno: string|null, contact person Ulice: string|null, street PSC: string|null, postal code Obec: string|null, city Email: string|null, email Tel: string|null, phone ICO: string|null, company id DIC: string|null, tax id ICDPH: string|null, vat id }[] ``` ### /v1/invoice/list/:uid List invoices with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/invoice/list/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/json { from?: number, // default 0 size?: number, // default 30 ids?: number[], // optional restrict to IDs asc?: string, // optional sort asc e.g. "Datum;ID" desc?: string, // optional sort desc e.g. "Datum;ID" on?: string[] // optional filters: tokens "Field;search;from;to" } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ### /v1/invoice/by-number/:uid/:invoice_number Get invoice detail by number. Example: http://0.0.0.0:1409/v1/invoice/by-number/88899460-4d0b-421b8d67-2023/VFA2300034 Parameters: ``` :uid - accounting unit identifier :invoice_number - invoice number ``` Request: ``` GET ``` Response: ``` 200 text/json // TInvoice shape (key fields) { ID: number, internal id Cislo: string, invoice number RelTpFak: number, invoice type Firma: string, partner name ICO?: string|null, partner id Datum: string, issue date YYYY-MM-DD DatSplat?: string|null, due date YYYY-MM-DD KcCelkem: number, total amount KcLikv: number, outstanding amount, 0 = fully paid status: "none" | "partially" | "left", payment state items: TInvoiceItem[], line items } ``` ### /v1/invoice/import/xml/:uid Import invoice XML and return vendor response. Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/xml text/xml // body: XML conforming to Stormware invoice.xsd (SK/CZ) // either a single or a wrapper Schema: SK (https://www.stormware.sk/xml/schema/version_2/invoice.xsd), CZ (https://www.stormware.cz/xml/schema/version_2/invoice.xsd) ... ``` Response: ``` 200 text/xml XML response according to SK (https://www.stormware.sk/xml/schema/version_2/response.xsd) or CZ (https://www.stormware.cz/xml/schema/version_2/response.xsd) xml schema. ``` ### /v1/invoice/file/add/:uid Attach a file to an invoice. Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/json { invoice: string, // invoice number name: string, // file name including extension content: string, // base64-encoded file content type?: string, // MIME type, inferred from extension if omitted size?: number // optional; normalized by API from base64 content // API also sends originalSize to Pohoda agent, derived from decoded bytes } ``` Response: ``` 200 text/plain internal directory path for invoice ``` ### /v1/invoice/import/isdoc/:uid Import ISDOC/ISDOCX from PDF and return vendor response. Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/json { name: string, // original file name (e.g., my.pdf) content: string // base64-encoded PDF content } ``` Response: ``` 200 text/xml XML response according to SK (https://www.stormware.sk/xml/schema/version_2/response.xsd) or CZ (https://www.stormware.cz/xml/schema/version_2/response.xsd) xml schema. ``` ### /v1/invoice/facility/:uid Update invoice or line facility (centre, activity, order). Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/json { invoice_id: number, // required invoice ID invoice_item_id?: number, // optional: update single line if provided refStr?: number, // optional: centre ID (stredisko) refCin?: number, // optional: activity ID (cinnost) cisloZAK?: string // optional: order number } ``` Response: ``` 200 text/plain OK ``` ## /v1/bank/ ### /v1/bank/accounts/:uid List bank accounts for a unit. Example: http://0.0.0.0:1409/v1/bank/accounts/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { ID: number, database id IDS: string, account identifiers IBAN: string, international bank account number Swift: string, swift code SText: string, account name KodBanky: string, bank code Banka: string, bank name Mena: string, currency Zrusen: date, cancelation date }[] ``` ### /v1/bank/balance/:uid Get bank account balance as of date. Example: http://0.0.0.0:1409/v1/bank/balance/88899460-4d0b-421b8d67-2023?account_id=1&date=2024-12-31 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET account_id (query), date (query, optional) ``` Response: ``` 200 text/json { balance: number, running balance before end of date } ``` ### /v1/bank/balances/:uid List bank balances as of date. Example: http://0.0.0.0:1409/v1/bank/balances/88899460-4d0b-421b8d67-2023?date=2024-12-31 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET date (query, optional) ``` Response: ``` 200 text/json { id: number, account id IDS: string, account code Banka: string, bank name IBAN: string, international account number balance: number, running balance before end of date }[] ``` ### /v1/bank/account/:uid/:id Get bank account detail by ID. Example: http://0.0.0.0:1409/v1/bank/account/88899460-4d0b-421b8d67-2023/1 Parameters: ``` :uid - accounting unit identifier :id - bank account ID ``` Request: ``` GET ``` Response: ``` 200 text/json { ID: number, database id IDS: string, account identifiers IBAN: string, international bank account number Swift: string, swift code SText: string, account name KodBanky: string, bank code Banka: string, bank name Mena: string, currency Zrusen: date|null, cancelation date } ``` ### /v1/bank/list/:uid List bank movements with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/bank/list/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET POST text/json { from?: number, // default 0 size?: number, // default 30 ids?: number[], // optional restrict to IDs asc?: string, // optional sort asc e.g. "Datum;ID" desc?: string, // optional sort desc e.g. "Datum;ID" on?: string[] // optional filters: tokens "Field;search;from;to" } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ### /v1/bank/import/xml/:uid Import bank movement XML and return vendor response. Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/xml text/xml // body: conforming to Stormware data.xsd and bank.xsd (SK/CZ) // every must contain one Schema: SK (https://www.stormware.sk/xml/schema/version_2/bank.xsd), CZ (https://www.stormware.cz/xml/schema/version_2/bank.xsd) ... ``` Response: ``` 200 text/xml XML response according to SK (https://www.stormware.sk/xml/schema/version_2/response.xsd) or CZ (https://www.stormware.cz/xml/schema/version_2/response.xsd) xml schema. 400 body is not a dataPack with bank items only ``` ## /v1/storage/ ### /v1/storage/:uid List storages with total inventory value. Example: http://0.0.0.0:1409/v1/storage/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { ID: number, storage id IDS: string, storage code SText: string, storage name suma: number, total inventory value }[] ``` ### /v1/storage/:uid/:id/items List items for a specific storage. Example: http://0.0.0.0:1409/v1/storage/88899460-4d0b-421b8d67-2023/1/items Parameters: ``` :uid - accounting unit identifier :id - storage ID ``` Request: ``` GET ``` Response: ``` 200 text/json { ID: number, item id IDS: string, item code EAN: string|null, barcode RefSklad: number, storage id Nazev: string, item name SText: string, description StavZ: number, stock quantity MJ: string, unit NakupC: number, purchase price }[] ``` ## /v1/cash/ ### /v1/cash/accounts/:uid List cash accounts for a unit. Example: http://0.0.0.0:1409/v1/cash/accounts/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { ID: number, database id IDS: string, account identifiers SText: string, account name Zrusen: date, cancelation date }[] ``` ### /v1/cash/list/:uid List cash movements with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/cash/list/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/json { from?: number, // default 0 size?: number, // default 30 ids?: number[], // optional restrict to IDs asc?: string, // optional sort asc e.g. "Datum;ID" desc?: string, // optional sort desc e.g. "Datum;ID" on?: string[] // optional filters: tokens "Field;search;from;to" } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ### /v1/cash/balance/:uid/:id Get cash register balance as of date. Example: http://0.0.0.0:1409/v1/cash/balance/88899460-4d0b-421b8d67-2023/1?date=2024-12-31 Parameters: ``` :uid - accounting unit identifier :id - cash register ID ``` Request: ``` GET date (query param) optional ``` Response: ``` 200 text/json { balance: number } ``` ### /v1/cash/balances/:uid List cash register balances as of date. Example: http://0.0.0.0:1409/v1/cash/balances/88899460-4d0b-421b8d67-2023?date=2024-12-31 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET date (query param) optional ``` Response: ``` 200 text/json { id, IDS, SText, balance }[] ``` ### /v1/cash/list/:uid List cash movements with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/cash/list/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ### /v1/cash/numbering/:uid List cash numberings for a unit. Example: http://0.0.0.0:1409/v1/cash/numbering/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { type: string, // pohoda_sk, pohoda_cz available: string[], // incoming, outgoing numbering: { ID: number, database id Rok: number, numbering year IDS: string, numbering prefix Cislo: string, next number SText: string, naming type: string, numbering type, see types above }[] } Ussualy, number is combination of IDS an Cislo, like "HP2300001" ``` ### /v1/cash/import/xml/:uid Import cash voucher XML and return vendor response. Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/xml text/xml // body: XML conforming to Stormware voucher.xsd (SK/CZ) // either a single or a wrapper Schema: SK (https://www.stormware.sk/xml/schema/version_2/voucher.xsd), CZ (https://www.stormware.cz/xml/schema/version_2/voucher.xsd) ... ``` Response: ``` 200 text/xml XML response according to SK (https://www.stormware.sk/xml/schema/version_2/response.xsd) or CZ (https://www.stormware.cz/xml/schema/version_2/response.xsd) xml schema. ``` ## /v1/personal/ ### /v1/personal/employees/:uid List employees for a unit. Example: http://0.0.0.0:1409/v1/personal/employees/88899460-4d0b-421b8d67-2023 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { employee_number: string, employee number employee_name: string, employee name employee_surname: string, employee surname employee_prefix: string, employee prefix employee_birth_number: string, employee birth number employment_enter_date: date, employment start date in "yyyy-mm-dd" format employment_leave_date: date, employment end date in "yyyy-mm-dd" format employment_active: boolean, employment active employment_number: string, employment number employment_position: string, employment position employment_name: string, employment name employment_place: string, employment place department_name: string, department name working_hour_start: string, working hour start working_hour_end: string, working hour end working_schedule: string, working schedule working_daily: string, working daily working_weekly: string, working weekly working_monthly: string, working monthly }[] ``` ### /v1/personal/employments/list/:uid List employments with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/personal/employments/list/88899460-4d0b-421b8d67-2023 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET POST text/json { from?: number, // default 0 size?: number, // default 30 fields?: DField[] // optional filters and sort; see DField in Response below } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ### /v1/personal/employments/:uid/:employee_id List employments for one employee. Example: http://0.0.0.0:1409/v1/personal/employments/88899460-4d0b-421b8d67-2023/123 Parameters: ``` uid - accounting unit identifier employee_id - employee ID uid - accounting unit identifier pomer_id - employment relationship ID ``` Request: ``` GET ``` Response: ``` 200 text/json { Cislo: string, employment number status: 'yes'|'no', employment active flag DatNast?: string, start date YYYY-MM-DD DatOdch?: string, end date YYYY-MM-DD Zarazeni: string, position text Str?: string, cost centre code RefZAM: number, employee internal id ZAM: { ID: number, Jmeno: string, Prijmeni: string, OsCislo: string, Email: string } }[] ``` ### /v1/personal/attendance/excel/:uid Download the same Attendance Excel report as the HR Attendance page. Example: http://0.0.0.0:1409/v1/personal/attendance/excel/88899460-4d0b-421b8d67-2023?from=2024-01-01&to=2024-01-31 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET from (YYYY-MM-DD), to (YYYY-MM-DD), employee_ids (comma list, optional) ``` Response: ``` 200 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet ``` ### /v1/personal/absence/excel/:uid Download the same Absences Excel report as the HR Absences page. Example: http://0.0.0.0:1409/v1/personal/absence/excel/88899460-4d0b-421b8d67-2023?from=2024-01-01&to=2024-12-31 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET from (YYYY-MM-DD), to (YYYY-MM-DD), employee_ids (comma list, optional) ``` Response: ``` 200 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet ``` ### /v1/personal/attendance/:uid Attendance report as JSON, same data as the HR Attendance Excel report. Example: http://0.0.0.0:1409/v1/personal/attendance/88899460-4d0b-421b8d67-2023?from=2024-01-01&to=2024-01-31 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET from (YYYY-MM-DD), to (YYYY-MM-DD), employee_ids (comma list, optional) ``` Response: ``` 200 text/json { year: number, report year month: number, report month 1-12 employees: { employee_number: string employee_surname: string employee_name: string department_name: string days: { date: string, "YYYY-MM-DD" day: number, day of month day_name: string, weekday name is_public_holiday: boolean worked: number, worked hours overtime: number, overtime hours night: number, night hours absence: number, absence hours scheduled: number, scheduled hours absences: { code: number, text: string }[] }[] summary: { work_days: number, worked hours on working days saturdays: number, worked hours on Saturdays sundays: number, worked hours on Sundays holidays: number, worked hours on public holidays total_worked: number, total worked hours overtime: number, total overtime hours night: number, total night hours absences: number, total absence hours monthly_total: number, worked + absence hours scheduled: number, scheduled hours difference: number, monthly total - scheduled } }[] }[] ``` ### /v1/personal/absence/report/:uid Absence report as JSON, same data as the HR Absences Excel report. Example: http://0.0.0.0:1409/v1/personal/absence/report/88899460-4d0b-421b8d67-2023?from=2024-01-01&to=2024-12-31 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET from (YYYY-MM-DD), to (YYYY-MM-DD), employee_ids (comma list, optional) ``` Response: ``` 200 text/json { employee_number: string title: string name: string surname: string title_after: string position: string cost_center: string absence_type: string, type label, includes subtype when present absence_type_code: number, RelDrDov code subtype: string|null, request subtype code date_from: string, "YYYY-MM-DD" date_to: string, "YYYY-MM-DD" duration: number, absence duration unit: "d"|"h", duration unit }[] ``` ### /v1/personal/absence/:uid List absences in a date range for optional employees. Example: http://0.0.0.0:1409/v1/personal/absence/88899460-4d0b-421b8d67-2023?from=2024-01-01&to=2024-12-31&employee_ids=1,2 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET from (YYYY-MM-DD), to (YYYY-MM-DD), employee_ids (comma list, optional) ``` Response: ``` 200 text/json { ID: number, absence id RefAg: number, employment id (pomer_id) DatZac: string, start date YYYY-MM-DD DatKon: string, end date YYYY-MM-DD DnyPrac: number, working days DnyKal: number, calendar days Dnu: number, business days RelDrDov: number, absence type code ZacPrac?: number|null, start time value RelZacJ?: number, start time unit KonPrac?: number|null, end time value RelKonJ?: number, end time unit locked: boolean }[] ``` ### /v1/personal/absence/remove/:uid Remove absences by IDs and return removed rows. Parameters: ``` uid - accounting unit identifier ``` Request: ``` POST text/json { ids: number[] } ``` Response: ``` 200 text/json { ID: number, removed absence id RefAg: number, employment id (pomer_id) DatZac: string, start date YYYY-MM-DD DatKon: string, end date YYYY-MM-DD DnyPrac: number, working days DnyKal: number, calendar days Dnu: number, business days RelDrDov: number, absence type code ZacPrac?: number|null, start time value RelZacJ?: number, start time unit KonPrac?: number|null, end time value RelKonJ?: number, end time unit locked: boolean }[] ``` ### /v1/personal/employee/:uid/:id Get employee by ID. Example: http://0.0.0.0:1409/v1/personal/employee/88899460-4d0b-421b8d67-2023/42 Parameters: ``` uid - accounting unit identifier employee_id - employee ID ``` Request: ``` GET ``` Response: ``` 200 text/json { ID?: number OsCislo: string, personal number Jmeno: string, first name Prijmeni: string, last name Email?: string Tel?: string Ucet?: string, bank account RelStav?: number, marital status Titul?: string TitulZa?: string Ulice?: string, street Obec?: string, city PSC?: string, ZIP Stat?: string, country RodCisl?: string, birth number DatNar?: string, birth date YYYY-MM-DD } ``` ### /v1/personal/employment/person/:uid/:pomer_id Get employee by employment relationship ID. Example: http://0.0.0.0:1409/v1/personal/employment/person/88899460-4d0b-421b8d67-2023/777 Parameters: ``` uid - accounting unit identifier pomer_id - employment relationship ID ``` Request: ``` GET ``` Response: ``` 200 text/json { Jmeno: string Prijmeni: string Email?: string Tel?: string Ucet?: string, bank account NazevPomer?: string, employment name NazevPracMist?: string, position name } ``` ### /v1/personal/info/:uid/:employee_id Get employee info with employments. Example: http://0.0.0.0:1409/v1/personal/info/88899460-4d0b-421b8d67-2023/42 Parameters: ``` uid - accounting unit identifier employee_id - employee ID ``` Request: ``` GET ``` Response: ``` 200 text/json { employee: TEmployeeMix company: { Soubor: string, Firma: string, ICO: string, Rok: number } pomery: TEmployeePomer[] } ``` ### /v1/personal/employee/by-email/:uid/:email Get employee by email. Example: http://0.0.0.0:1409/v1/personal/employee/by-email/88899460-4d0b-421b8d67-2023/user%40acme.com Parameters: ``` uid - accounting unit identifier email - URL-encoded ``` Request: ``` GET ``` Response: ``` 200 text/json { ID?: number OsCislo: string, personal number Jmeno: string, first name Prijmeni: string, last name Email?: string Tel?: string Ucet?: string, bank account RelStav?: number, marital status Titul?: string TitulZa?: string Ulice?: string, street Obec?: string, city PSC?: string, ZIP Stat?: string, country RodCisl?: string, birth number DatNar?: string, birth date YYYY-MM-DD } // returns {} when not found ``` ### /v1/personal/password_update/:uid Update employee password and optionally email. Parameters: ``` uid - accounting unit identifier ``` Request: ``` POST text/json { id: number, pwd: string, email: string } ``` Response: ``` 200 text/plain OK ``` ### /v1/personal/contact_update/:uid Update employee contact fields (password, email, phone). Parameters: ``` uid - accounting unit identifier ``` Request: ``` POST text/json { id: number, pwd?: string, email?: string, number?: string } ``` Response: ``` 200 text/plain OK ``` ### /v1/personal/profile/:uid/:employee_id Get employee profile with children and additional info. Example: http://0.0.0.0:1409/v1/personal/profile/88899460-4d0b-421b8d67-2023/42 Parameters: ``` uid - accounting unit identifier employee_id - employee ID ``` Request: ``` GET ``` Response: ``` 200 text/json { basic: { ID: number OsCislo?: string, personal number Jmeno: string, first name Prijmeni: string, last name Titul?: string TitulZa?: string Email?: string Tel?: string Ucet?: string, bank account RelStav?: number|string, marital status RodCisl?: string, birth number DatNar?: string, birth date YYYY-MM-DD Ulice?: string, street CP?: string, street no. Obec?: string, city PSC?: string, ZIP Stat?: string, country KonUlice?: string, contact street KonCP?: string, contact street no. KonObec?: string, contact city KonPSC?: string, contact ZIP KonStat?: string, contact country } children: [ { RefAg: number, // employment id DatOd: string, // YYYY-MM-DD DatDo: string|null, // YYYY-MM-DD or null SText: string, // child name RodCisl: string // child birth number } ] aditional: { RefAg: number, DatOd: string|null, DatDo: string|null, SText?: string, RodCisl?: string, KcOdec?: number } | null files: any[] } ``` ### /v1/personal/salary/:uid/:salary_id Get a salary with items and deductions. Example: http://0.0.0.0:1409/v1/personal/salary/88899460-4d0b-421b8d67-2023/555 Parameters: ``` uid - accounting unit identifier salary_id - salary ID ``` Request: ``` GET ``` Response: ``` 200 text/json { salary: TEmployeeSalary slozky: TEmployeeSlozky[] srazky: TEmployeeSrazky[] employee: TEmployeeDetail & { ID: number } } ``` ### /v1/personal/benefit/types/:uid List benefit item types. Example: http://0.0.0.0:1409/v1/personal/benefit/types/88899460-4d0b-421b8d67-2023 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { id: number, item type id name: string, name/label Proc?: number, percentage Sazba?: number, rate RelDruhSlozky?: number, category code SText?: string, description }[] ``` ### /v1/personal/benefits/:uid List benefits for optional employees. Example: http://0.0.0.0:1409/v1/personal/benefits/88899460-4d0b-421b8d67-2023 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET POST text/json { employee_ids?: number[] } ``` Response: ``` 200 text/json { ID?: number RefAg: number, employment id SText?: string, description DatOd?: string, valid from YYYY-MM-DD DatDo?: string, valid to YYYY-MM-DD RefSlozky?: number, benefit type id RelDruhSlozky?: number, category code Hod?: number, hours Proc?: number, percentage Sazba?: number, rate Kc?: number, amount Ucet?: string, bank account KodBanky?: string VarSym?: string SpecSym?: string KonstSym?: string }[] ``` ### /v1/personal/benefit/:uid/:id Remove a benefit item by ID. Parameters: ``` uid - accounting unit identifier id - benefit ID ``` Request: ``` POST ``` Response: ``` 200 text/json { ID: number, removed benefit id RefAg: number, employment id DatOd?: string, valid from YYYY-MM-DD DatDo?: string, valid to YYYY-MM-DD SText?: string, description RefSlozky?: number, benefit type id RelDruhSlozky?: number, category code Hod?: number, hours Proc?: number, percentage Sazba?: number, rate Kc?: number, amount Ucet?: string, bank account KodBanky?: string VarSym?: string SpecSym?: string KonstSym?: string } // returns {} when not found ``` ### /v1/personal/benefit/:uid/:id/update Update a benefit item. Parameters: ``` uid - accounting unit identifier id - benefit ID ``` Request: ``` POST text/json { DatOd?: string, // YYYY-MM-DD DatDo?: string, // YYYY-MM-DD RefAg?: number, // employment id RefSlozky?: number, // benefit type id (sMZslozky.ID) RelDruhSlozky?: number, // category code Hod?: number, Kc?: number, Proc?: number, Sazba?: number, SText?: string, Ucet?: string, KodBanky?: string, VarSym?: string, SpecSym?: string, KonstSym?: string } ``` Response: ``` 200 text/plain OK ``` ### /v1/personal/benefit/add/:uid Add a benefit item. Parameters: ``` uid - accounting unit identifier ``` Request: ``` POST text/json { RefAg: number, // required employment id RefSlozky: number, // required benefit type id (sMZslozky.ID) DatOd: string, // YYYY-MM-DD DatDo: string, // YYYY-MM-DD Hod?: number, Kc?: number, Proc?: number, Sazba?: number, SText?: string, RelDruhSlozky?: number, Ucet?: string, KodBanky?: string, VarSym?: string, SpecSym?: string, KonstSym?: string } ``` Response: ``` 200 text/plain OK ``` ### /v1/personal/deductions/:uid List deductions for optional employees. Example: http://0.0.0.0:1409/v1/personal/deductions/88899460-4d0b-421b8d67-2023 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET POST text/json { employee_ids?: number[] } ``` Response: ``` 200 text/json { ID?: number RefAg: number, employment id SText: string, description DatOd: string, valid from YYYY-MM-DD DatDo: string, valid to YYYY-MM-DD Cela?: number Kc?: number, amount Rozhod?: string RelDrSra?: number, deduction type RelPk?: number Ucet?: string, bank account KodBanky?: string SpecSym?: string KonstSym?: string VarSym?: string RelFond?: number, fund type RelZivPj?: number, life insurance }[] ``` ### /v1/personal/deductions/previous_month/:uid List previous month deduction summary. Example: http://0.0.0.0:1409/v1/personal/deductions/previous_month/88899460-4d0b-421b8d67-2023 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { 'employee number': string 'Name': string 'Cost center': string|null 'Basic Wage': number 'Gross wage - used holiday': number 'Doctor visit - Gross wage': number 'Travel contribution': number 'Overtimes during week': number 'Overtimes during bank holiday': number 'Overtimes during weekends': number 'Night work compensation': number 'Tax base Employee': number 'Medical insurance - Employee': number 'Old age insurance - Employee': number 'Health insurance - Employee': number 'Deduction - injunction': number 'Deduction Others': number 'Health Insurance - Employer': number 'Unemployment insurance - Employer': number 'Guarantee fund - Employer': number 'Annual tax calculation': number 'Supplement pension saving': number ... more summary columns ... }[] ``` ### /v1/personal/payslips/:uid List payslips with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/personal/payslips/88899460-4d0b-421b8d67-2023 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET POST text/json { from?: number, // default 0 size?: number, // default 30 fields?: DField[] // optional filters and sort // default sort: { name: 'FilterDatum', sort: 'desc' } } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ### /v1/personal/employees_status/:uid List employment status in a date range. Example: http://0.0.0.0:1409/v1/personal/employees_status/88899460-4d0b-421b8d67-2023?from=2024-01-01&to=2024-12-31&employee_ids=1,2 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET from (YYYY-MM-DD), to (YYYY-MM-DD), employee_ids (comma list, optional) ``` Response: ``` 200 text/json [ { // employment rows ID: number, employment id Cislo?: string, employment number DatNast?: string, start date YYYY-MM-DD DatOdch?: string, end date YYYY-MM-DD|null JeAktiv?: boolean RefZAM: number, employee id Jmeno: string Prijmeni: string ZdrPostih?: boolean ZdrPostihT?: boolean }, { // demographic rows Jmeno: string Prijmeni: string RelPohl?: number, gender code ZdrPostih?: boolean ZdrPostihT?: boolean } ] ``` ### /v1/personal/access_list/:uid List employees with basic contact for access control. Example: http://0.0.0.0:1409/v1/personal/access_list/88899460-4d0b-421b8d67-2023?dateTo=2024-12-31 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET dateTo (YYYY-MM-DD, optional) ``` Response: ``` 200 text/json { user_id, company_id, party_id, company_name, name, email, phone, type, search, leave_date }[] ``` ### /v1/personal/recruit/:uid Create a new employee (recruit). Parameters: ``` uid - accounting unit identifier ``` Request: ``` POST text/json { // Required basics created_at: string, // ISO datetime updated_at: string, // ISO datetime company_ico: string, party_id: string, pracovny_stav: number, titul_pred: string, // max 14 meno: string, priezvisko: string, titul_za: string, // max 14 email: string, id_pracovna_pozicia: string, pracovna_pozicia: string, klasifikacia: string, // max 7 (SK ISCO) popis_prace: string, note?: string, // Employment details (optional) druh_pracovneho_pomeru?: number, zaciatok_pracovneho_pomeru?: string, // ISO date miesto_prace?: string, miesto_prace_kod?: string, // max 6 (LAU/LSUJ) stredisko?: string, hruba_mzda?: number, hruba_mzda_slovom?: string, reldruhm?: number, pracovny_fond?: number, pracovny_fond_den?: number, praca_na_dobu_urcitu?: string, // ISO date date_sent?: string, // ISO date pohlavie?: number, // Personal data datum_narodenia?: string, // ISO date rodne_priezvisko: string, rodne_cislo: string, // d{6}/d{3,4} miesto_narodenia: string, narodnost: string, statna_prislusnost: string, cislo_op: string, rodinny_stav?: number, // Foreign national cudzinec: boolean, krajina_narodenia: string, // 2-letter cudzinec_op?: string, cudzinec_adresa?: string, cudzinec_doklad?: string, cudzinec_poistovna?: string, cudzinec_cssz?: string, // Address adresa_ulica: string, adresa_cislo: string, adresa_psc: string, adresa_mesto: string, adresa_stat: string, // 2-letter kontakt_adresa_ulica: string, kontakt_adresa_cislo: string, kontakt_adresa_psc: string, kontakt_adresa_mesto: string, kontakt_adresa_stat: string, // 2-letter kontakt_telefon?: string, // Payments iban: string, swift_bic: string, var_sym?: string, zdravotna_poistovna?: number, // Benefits/flags ztp: boolean, starobny_dochodok: boolean, invalidny_dochodok: boolean, vysluhovy_dochodok: boolean, dochodca: boolean, invalidita: string, trvala_starostlivost_dieta: boolean, nezdanitelna_cast: boolean, dan_bonus: boolean, // Children deti: { meno: string, rodne_cislo: string }[], // Attachments files: ({ name: string, type: string, size: number, content: string }| { id: number, name: string, type: string, size: number, content?: string })[], // Consent + token gdpr: boolean, token?: string } ``` Response: ``` 200 text/plain OK ``` ### /v1/personal/health_insurance/:uid List health insurance companies for a unit. Example: http://0.0.0.0:1409/v1/personal/health_insurance/88899460-4d0b-421b8d67-2023 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { ID: number, internal id IDS: string, code Ucet: string, bank account KodBanky: string, bank code VarSym: string, variable symbol KonstSym: string, constant symbol }[] ``` ### /v1/personal/pension_funds/:uid List pension funds for a unit. Example: http://0.0.0.0:1409/v1/personal/pension_funds/88899460-4d0b-421b8d67-2023 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { id: number, internal id name: string, company name Ucet: string, bank account KodBanky: string, bank code VarSym?: string, variable symbol SpecSym?: string, specific symbol KonstSym?: string, constant symbol }[] ``` ### /v1/personal/insurers/:uid List life insurers for a unit. Example: http://0.0.0.0:1409/v1/personal/insurers/88899460-4d0b-421b8d67-2023 Parameters: ``` uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { id: number, internal id name: string, company name Ucet: string, bank account KodBanky: string, bank code VarSym: string, variable symbol SpecSym: string, specific symbol KonstSym: string, constant symbol }[] ``` ## /v1/property/ ### /v1/property/assets/:uid List investment assets with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/property/assets/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET POST text/json { from?: number, // default 0 size?: number, // default 30 ids?: number[], // optional restrict to IDs asc?: string, // optional sort asc desc?: string, // optional sort desc on?: string[] // optional filters: tokens "Field;search;from;to" } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ### /v1/property/small_assets/:uid List small assets with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/property/small_assets/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET POST text/json { from?: number, // default 0 size?: number, // default 30 ids?: number[], // optional restrict to IDs asc?: string, // optional sort asc desc?: string, // optional sort desc on?: string[] // optional filters: tokens "Field;search;from;to" } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ### /v1/property/depreciations/:uid List asset depreciations with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/property/depreciations/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET POST text/json { from?: number, // default 0 size?: number, // default 30 ids?: number[], // optional restrict to IDs asc?: string, // optional sort asc desc?: string, // optional sort desc on?: string[] // optional filters: tokens "Field;search;from;to" } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ### /v1/property/tax_depreciation/:uid/:id List tax depreciations for an asset. Example: http://0.0.0.0:1409/v1/property/tax_depreciation/88899460-4d0b-421b8d67-2023/100 Parameters: ``` :uid - accounting unit identifier :id - asset ID ``` Request: ``` GET ``` Response: ``` 200 text/json { ID: number RefAg: number, asset id Rok: string, year RelTpOdp: number, depreciation method RelSkOdp: number, depreciation group KcVstup: number|null, entry value Procento: number, percent KcOdpis: number, depreciation KcKorekce: number, correction Zcelku: number KcOdpisCalc: number, calculated depreciation KcZust: number, remaining }[] ``` ### /v1/property/book_depreciation/:uid/:id List book depreciations for an asset. Example: http://0.0.0.0:1409/v1/property/book_depreciation/88899460-4d0b-421b8d67-2023/100 Parameters: ``` :uid - accounting unit identifier :id - asset ID ``` Request: ``` GET ``` Response: ``` 200 text/json { ID: number Mesic: string, ISO date (month) RefIMO: number, book category id Zivotnost: number, lifetime KcVstup: number, entry value Procento: number, percent KcOdpis: number|null, depreciation KcKorekce: number, correction KcOdpisCalc: number, calculated depreciation KcZustatek: number, remaining IDS: string, book category code }[] ``` ### /v1/property/vehicles/:uid List motor vehicles with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/property/vehicles/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET POST text/json { from?: number, // default 0 size?: number, // default 30 ids?: number[], // optional restrict to IDs asc?: string, // optional sort asc desc?: string, // optional sort desc on?: string[] // optional filters: tokens "Field;search;from;to" } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ## /v1/orders/ ### /v1/orders/list/:uid List orders with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/orders/list/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET POST text/json { from?: number, // default 0 size?: number, // default 30 ids?: number[], // optional restrict to IDs asc?: string, // optional sort asc desc?: string, // optional sort desc on?: string[] // optional filters: tokens "Field;search;from;to" } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ### /v1/commissions/list/:uid List commissions with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/commissions/list/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET POST text/json { from?: number, // default 0 size?: number, // default 30 ids?: number[], // optional restrict to IDs asc?: string, // optional sort asc desc?: string, // optional sort desc on?: string[] // optional filters: tokens "Field;search;from;to" } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ## /v1/contracts/ ### /v1/contracts/list/:uid List contracts with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/contracts/list/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET POST text/json { from?: number, // default 0 size?: number, // default 30 ids?: number[], // optional restrict to IDs asc?: string, // optional sort asc desc?: string, // optional sort desc on?: string[] // optional filters: tokens "Field;search;from;to" } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ## /v1/reports/ ### /v1/reports/general_ledger/:uid List general ledger summary. Example: http://0.0.0.0:1409/v1/reports/general_ledger/88899460-4d0b-421b8d67-2023?from=2024-01-01&to=2024-12-31 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { Ucet: string, account number Nazev: string, account name typ: number zmd: number, opening debit zdal: number, opening credit md: number, debit dal: number, credit kmd: number, closing debit kdal: number, closing credit Datum: string, YYYY-MM-DD }[] ``` ### /v1/reports/general_ledger/:uid/:account List general ledger entries for an account. Example: http://0.0.0.0:1409/v1/reports/general_ledger/88899460-4d0b-421b8d67-2023/311?from=2024-01-01&to=2024-12-31 Parameters: ``` :uid - accounting unit identifier :account - account number ``` Request: ``` GET ``` Response: ``` 200 text/json { Datum?: string, YYYY-MM-DD Cislo: string, document number PDoklad?: number|null, internal id Firma?: string, company SText?: string, description UD: string, debit account UMD: string, credit account Kc: number, amount Dir?: string, direction }[] ``` ### /v1/reports/journal/:uid List journal entries with server-side filtering and pagination. Example: http://0.0.0.0:1409/v1/reports/journal/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/json { from?: number, // default 0 size?: number, // default 30 ids?: number[], // optional: restrict to IDs asc?: string, // optional: sort asc, e.g. "Datum;ID" desc?: string, // optional: sort desc, e.g. "Datum;ID" on?: string[] // optional filters, tokens "Field;search;from;to" } ``` Response: ``` 200 text/json { total: number, filtered: number, fields: DField[], data: any[], summary: { [key: string]: number }, query: DQuery } DField = { name: string, text?: string, sort?: 'asc'|'desc'|'', // simple values (one of these may be present) string?: string|null, number?: number|null, numbers?: number[], date?: string|null, // ISO YYYY-MM-DD checkbox?: boolean|null, select?: { // select-like inputs type: 'number'|'date'|'string', value?: any|null, options: { value: any, text: string }[] }, checkbuttons?: { // select-like inputs type: 'number'|'string', value?: any|null, options: { value: any, text: string }[] }, checkboxes?: { // select-like inputs type: 'number'|'date'|'string'|'number[]'|'string[]', values?: any[], options: { value: any, text: string }[], classInput?: string }, range?: { // ranges and validity type: 'number'|'date', nullable?: boolean, from?: number|string|Date|null, to?: number|string|Date|null }, valid_until?: { type: 'date', nullable?: boolean, value?: string|Date|null } } DQuery = { from: number, size: number, init?: number, fields: DField[] } ``` ### /v1/reports/costs_revenues_by_account/:uid List costs and revenues by account. Example: http://0.0.0.0:1409/v1/reports/costs_revenues_by_account/88899460-4d0b-421b8d67-2023?account=5&from=2024-01-01&to=2024-12-31 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { Datum: string, YYYY-MM-DD RelTpFak?: number, invoice type PDoklad?: number, internal id Cislo?: string, document number SKPP_Cislo?: string SKPP_SText?: string SKPV_Cislo?: string SKPV_SText?: string Firma?: string Jmeno?: string SText?: string UD: string UMD: string Kc: number RelUdAg: number Dir?: string }[] ``` ### /v1/reports/monthly_statement/:uid Compute monthly statement for selected accounts. Example: http://0.0.0.0:1409/v1/reports/monthly_statement/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/json { from?: string, // ISO date YYYY-MM-DD to?: string, // ISO date YYYY-MM-DD ucty: string[], // required: account numbers/prefixes stredisko?: number, // optional: centre ID cinnost?: number, // optional: activity ID zakazka?: string // optional: order number } ``` Response: ``` 200 text/json { Datum: string, YYYY-MM-DD UD: string UMD: string Kc: number }[] ``` ### /v1/reports/highest_bank/:uid Get bank summary for current and previous month. Example: http://0.0.0.0:1409/v1/reports/highest_bank/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { Bank: string, bank name Bank_ID: number|string, bank id CurrentMonthTotal: number PreviousMonthTotal: number period_to: string, YYYY-MM-DD } ``` ### /v1/reports/highest_cash/:uid Get cash summary for current and previous month. Example: http://0.0.0.0:1409/v1/reports/highest_cash/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { Cash: string, cash name Cash_ID: number|string, cash id CurrentMonthTotal: number PreviousMonthTotal: number period_to: string, YYYY-MM-DD } ``` ### /v1/reports/statistics/:uid Get company statistics. Example: http://0.0.0.0:1409/v1/reports/statistics/88899460-4d0b-421b8d67-2023?current_year_db=true Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { PayablesTotal: number PayablesIn3Days: number PayablesOverduted30Days: number ReceivablesTotal: number ReceivablesIn3Days: number ReceivablesOverduted30Days: number danNaVystupe: number danNaVstupe: number predbeznaDPH: number bank_name: string bank_id: string|number bank_current_total: number bank_previous_total: number bank_period_to: string, YYYY-MM-DD cash_name: string cash_id: string|number cash_current_total: number cash_previous_total: number cash_period_to: string, YYYY-MM-DD period_to: string, YYYY-MM-DD is_current_year_or_newer: 'True'|'False' } ``` ### /v1/reports/income_tax/:uid List corporate income tax inputs. Example: http://0.0.0.0:1409/v1/reports/income_tax/88899460-4d0b-421b8d67-2023?from=2024-01-01&to=2024-12-31 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` GET ``` Response: ``` 200 text/json { revenues: { ID: number, account: string, name: string }[] expenses: { ID: number, account: string, name: string }[] revenues_ud: { ID: number, sum: number, UD: string }[] revenues_umd: { ID: number, sum: number, UMD: string }[] cost_ud: { ID: number, sum: number, UD: string }[] cost_umd: { ID: number, sum: number, UMD: string }[] } ``` ### /v1/reports/income_tax/:uid/:account List corporate income tax entries for an account. Example: http://0.0.0.0:1409/v1/reports/income_tax/88899460-4d0b-421b8d67-2023/518?from=2024-01-01&to=2024-12-31 Parameters: ``` :uid - accounting unit identifier :account - account number ``` Request: ``` GET ``` Response: ``` 200 text/json { Datum: string, YYYY-MM-DD Firma: string SText: string UD: string UMD: string Cislo: string Kc: number Dir?: string }[] ``` ### /v1/reports/overview/:uid Compute profitability overview. Example: http://0.0.0.0:1409/v1/reports/overview/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/json { centre?: number, // optional: centre ID cinnost?: number, // optional: activity ID cislo_zak?: string, // optional: order number RelTpFak?: number[], // optional: invoice types [1,2,3,4,5,6,11,12,13,14,15,16] InvoiceType?: number, // optional: one of RelTpFak (affects sign) dateTo?: string, // optional: ISO date YYYY-MM-DD dateFrom?: string, // optional: ISO date YYYY-MM-DD from?: number, // optional: days lower bound, default 0 to?: number // optional: days upper bound, default 100 } ``` Response: ``` 200 text/json { sum: number, count: number } ``` ### /v1/reports/overview/:uid/items List items contributing to profitability overview. Example: http://0.0.0.0:1409/v1/reports/overview/88899460-4d0b-421b8d67-2023/items Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/json { centre?: number, cinnost?: number, cislo_zak?: string, RelTpFak?: number[], InvoiceType?: number, dateTo?: string, // ISO date YYYY-MM-DD dateFrom?: string, // ISO date YYYY-MM-DD percentage: string // one of: '30','360','720','1080' } ``` Response: ``` 200 text/json { Cislo: string, document number PDoklad: string, internal id Datum: string, YYYY-MM-DD DatSplat: string, due date YYYY-MM-DD Days: number, overdue days Firma: string SText: string KcCelkem: number, total KcLikv: number, paid Taxable: number }[] ``` ### /v1/reports/selected_services/:uid Compute KPIs for selected services. Example: http://0.0.0.0:1409/v1/reports/selected_services/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/json { centre?: number, cinnost?: number, cislo_zak?: string, RelTpFak?: number[], // invoice types [1,2,3,4,5,6,11,12,13,14,15,16] InvoiceType?: number, dateTo?: string, // ISO date YYYY-MM-DD dateFrom?: string, // ISO date YYYY-MM-DD type: 'N'|'P'|'S'|'C'|'l' // required: service code } ``` Response: ``` 200 text/json { sum: number } ``` ### /v1/reports/selected_services/:uid/items List items for selected services KPIs. Example: http://0.0.0.0:1409/v1/reports/selected_services/88899460-4d0b-421b8d67-2023/items Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/json { centre?: number, cinnost?: number, cislo_zak?: string, RelTpFak?: number[], InvoiceType?: number, dateTo?: string, // ISO date YYYY-MM-DD dateFrom?: string, // ISO date YYYY-MM-DD type: 'N'|'P'|'S'|'C'|'l' // required: service code } ``` Response: ``` 200 text/json { Cislo: string, document number PDoklad: string, internal id Datum: string, YYYY-MM-DD DatSplat: string, due date YYYY-MM-DD Firma: string SText: string KcCelkem: number, total KcLikv: number, paid Taxable: number }[] ``` ## /v1/sql/ ### /v1/sql/:uid Run a read-only SQL SELECT for a unit and return rows. Example: http://0.0.0.0:1409/v1/sql/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/plain Request body is sql in plain text. Only SELECT allowed. Use :db placeholder for current unit DB. POST text/base64 Request body is base64 encoded sql. Only SELECT allowed. Use :db placeholder for current unit DB. ``` Response: ``` 200 text/json { json object }[] ``` ### /v1/sql/one/:uid Run a read-only SQL SELECT for a unit and return a single row. Example: http://0.0.0.0:1409/v1/sql/one/88899460-4d0b-421b8d67-2023 Parameters: ``` :uid - accounting unit identifier ``` Request: ``` POST text/plain Request body is sql in plain text. POST text/base64 Request body is base64 encoded sql. ``` Response: ``` 200 text/json { json object } || null ``` ## /v1/epostar/ ### /v1/epostar/companies Digitálny poštár: Peppol e-invoicing without NISA. Every call needs the API key we gave you. List the companies (DIČ) you work for. Parameters: ``` Authorization: Bearer ep_... ``` Request: ``` GET ``` Response: ``` 200 application/json { dic: string, 10-digit DIČ legal_name: string contact_email: string | null contact_phone: string | null direction: 'SEND' | 'RECEIVE' | 'BOTH' status: 'requested' | 'active' | 'rejected' status_reason: string | null created_at, updated_at: ISO time } [] Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies Add a company. We activate it after we check your mandate to act for it; until then it is "requested". Adding the same DIČ again returns it unchanged. A company that receives through another provider today moves to us with a migration code from that provider: see participants and activate. contact_email and contact_phone are optional and are written to the company's business card in the central Peppol SMP, where they can be publicly visible. They need not belong to the company, an accounting office address works too. Neither we nor Compacer send any messages to them. Parameters: ``` Authorization: Bearer ep_... ``` Request: ``` POST application/json { dic: string, 10-digit DIČ legal_name: string contact_email?: string contact_phone?: string direction?: 'SEND' | 'RECEIVE' | 'BOTH', default BOTH } ``` Response: ``` 200 201 application/json { dic: string, 10-digit DIČ legal_name: string contact_email: string | null contact_phone: string | null direction: 'SEND' | 'RECEIVE' | 'BOTH' status: 'requested' | 'active' | 'rejected' status_reason: string | null created_at, updated_at: ISO time } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic One company with its live Compacer state. Parameters: ``` Authorization: Bearer ep_... :dic - DIČ of the company ``` Request: ``` GET ``` Response: ``` 200 application/json company, plus compacer: { registered, can_receive, status, note, valid_until } | { error } | null Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/participants/:dic Check a company before you add it: is it reachable in Peppol, and who receives for it? served_by_compacer is true also for a company another Compacer partner registered; registered_with_us only for ours. The register is updated once a day and does not show test companies. state UNKNOWN means the register could not be read, never that the company is not registered. Parameters: ``` Authorization: Bearer ep_... :dic - 10-digit DIČ ``` Request: ``` GET ``` Response: ``` 200 application/json { dic: string, state: 'REGISTERED' | 'NOT_REGISTERED' | 'UNKNOWN', served_by_compacer: boolean, registered_with_us: boolean, registered_on: string | null, note: string | null } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/activate Move a company that receives through another provider to us without a gap. Ask that provider for a migration code and send it here after we activate the company; such a company is active with status_reason saying it waits for the code. We send the code to the central SMP at once and do not keep it. Follow the move in GET company and the events. A company that only sends needs no code (409 not_needed); a company already registered with us answers 409 already_registered, and one registered with us for another direction 409 direction_conflict. We never deregister a company to move it: that would stop its receiving. Parameters: ``` Authorization: Bearer ep_... :dic - DIČ of the company ``` Request: ``` POST application/json { migration_code: string, 1–24 printable characters without spaces } ``` Response: ``` 202 application/json { dic: string state: string, e.g. REVOKE_PENDING, ACTIVE, QUEUED state_reason: string | null revoke_due_at: ISO time | null, legal deadline for the removal } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/deregister/cancel Call off a pending deregistration, possible until the company is removed. Only we deregister a company, on its request; moving to another provider goes through migration-code, so receiving never stops. Parameters: ``` Authorization: Bearer ep_... :dic - DIČ of the company ``` Request: ``` POST ``` Response: ``` 202 application/json { dic: string state: string, e.g. REVOKE_PENDING, ACTIVE, QUEUED state_reason: string | null revoke_due_at: ISO time | null, legal deadline for the removal } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/migration-code The only way to move a company that receives through us to another provider: no gap in receiving. Call it only when the company asks to leave; checking that is on you, and we record which client asked and when. Hand the code to the new provider; the company keeps receiving through us until the code is used. Calling again gives a new code. Not for a company that only sends. 409 company_shared: someone else also uses this company, contact us. We do not keep the code. Parameters: ``` Authorization: Bearer ep_... :dic - DIČ of the company ``` Request: ``` POST ``` Response: ``` 200 application/json { dic: string, state: string, migration_code: string } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/validate Check a UBL invoice or credit note (Peppol BIS 3). Nothing is sent. The supplier EndpointID must be the company DIČ (scheme 0245). Parameters: ``` Authorization: Bearer ep_... :dic - DIČ of the sending company ``` Request: ``` POST application/xml UBL Invoice or CreditNote XML, at most 10 MB ``` Response: ``` 200 application/json { valid: boolean, would_accept: boolean, already_submitted: boolean, error: string | null, note: string | null, findings: { id, flag, location, text }[] } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/outbound Send a UBL invoice or credit note. Repeat a request with the same Idempotency-Key and XML to get the same result, never a second invoice. 201 sent, 202 outcome not known yet (we resolve it, follow the events), 422 refused with reasons, 200 repeated request. Parameters: ``` Authorization: Bearer ep_... Idempotency-Key: your unique id of this document, 1–200 characters :dic - DIČ of the sending company ``` Request: ``` POST application/xml UBL Invoice or CreditNote XML, at most 10 MB ``` Response: ``` 200 201 202 422 application/json { id: number idempotency_key: string invoice_number: string, cbc:ID document_type: 'Invoice' | 'CreditNote' recipient_dic: string | null submission_status: 'submitting' | 'submitted' | 'failed' | 'unknown' submission_error: string | null, reasons when failed compacer_invoice_id: string | null dispatch_status: string | null, e.g. PENDING_DISPATCH, DISPATCHED mls_state, mls_response_code (AB/AP/RE), mls_status_reason, mls_description: string | null tdd_status: VALID | INVALID | NOT_REQUIRED | NOT_GENERATED | null, tax document tdd_c5_status: PENDING | ACCEPTED | REJECTED | null, tax office answer tdd_c5_description: string | null created_at, updated_at: ISO time } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/outbound Sent documents of a company. Parameters: ``` Authorization: Bearer ep_... :dic - DIČ ?after - id of the last item you already have, default 0 ?limit - 1–200, default 100 ?status - submitting | submitted | failed | unknown ``` Request: ``` GET ``` Response: ``` 200 application/json { items: outbound[], oldest first next_after: number, pass as ?after for the next page } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/outbound/:id One sent document with delivery and tax office status. Parameters: ``` Authorization: Bearer ep_... :dic - DIČ :id - document id ``` Request: ``` GET ``` Response: ``` 200 application/json { id: number idempotency_key: string invoice_number: string, cbc:ID document_type: 'Invoice' | 'CreditNote' recipient_dic: string | null submission_status: 'submitting' | 'submitted' | 'failed' | 'unknown' submission_error: string | null, reasons when failed compacer_invoice_id: string | null dispatch_status: string | null, e.g. PENDING_DISPATCH, DISPATCHED mls_state, mls_response_code (AB/AP/RE), mls_status_reason, mls_description: string | null tdd_status: VALID | INVALID | NOT_REQUIRED | NOT_GENERATED | null, tax document tdd_c5_status: PENDING | ACCEPTED | REJECTED | null, tax office answer tdd_c5_description: string | null created_at, updated_at: ISO time } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/outbound/:id/xml The XML exactly as you sent it. Parameters: ``` Authorization: Bearer ep_... :dic - DIČ :id - document id ``` Request: ``` GET ``` Response: ``` 200 application/xml Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/inbound Received documents of a company. Attachments are embedded in the XML. Parameters: ``` Authorization: Bearer ep_... :dic - DIČ ?after - id of the last item you already have, default 0 ?limit - 1–200, default 100 ?response_status - not_requested | pending | sending | succeeded | failed | refused ``` Request: ``` GET ``` Response: ``` 200 application/json { items: inbound[], oldest first next_after: number, pass as ?after for the next page } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/inbound/:id One received document. Parameters: ``` Authorization: Bearer ep_... :dic - DIČ :id - document id ``` Request: ``` GET ``` Response: ``` 200 application/json { id: number instance_id: string invoice_number: string document_type: 'Invoice' | 'CreditNote' sender_dic, sender_name: string | null issue_date: string | null received_at: ISO time response_type: 'acknowledge' | 'reject' | null response_reason: string | null response_status: 'not_requested' | 'pending' | 'sending' | 'succeeded' | 'failed' | 'refused' response_error: string | null responded_at: ISO time | null created_at, updated_at: ISO time } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/inbound/:id/xml The received UBL XML. Parameters: ``` Authorization: Bearer ep_... :dic - DIČ :id - document id ``` Request: ``` GET ``` Response: ``` 200 application/xml Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/inbound/:id/ack Accept a received invoice. One answer per invoice; repeating the same answer is safe. We retry delivery to the sender until response_status is succeeded or refused. Parameters: ``` Authorization: Bearer ep_... :dic - DIČ :id - document id ``` Request: ``` POST ``` Response: ``` 200 application/json { id: number instance_id: string invoice_number: string document_type: 'Invoice' | 'CreditNote' sender_dic, sender_name: string | null issue_date: string | null received_at: ISO time response_type: 'acknowledge' | 'reject' | null response_reason: string | null response_status: 'not_requested' | 'pending' | 'sending' | 'succeeded' | 'failed' | 'refused' response_error: string | null responded_at: ISO time | null created_at, updated_at: ISO time } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/companies/:dic/inbound/:id/reject Reject a received invoice with a reason. Parameters: ``` Authorization: Bearer ep_... :dic - DIČ :id - document id ``` Request: ``` POST application/json { reason: string, 3–500 characters } ``` Response: ``` 200 application/json { id: number instance_id: string invoice_number: string document_type: 'Invoice' | 'CreditNote' sender_dic, sender_name: string | null issue_date: string | null received_at: ISO time response_type: 'acknowledge' | 'reject' | null response_reason: string | null response_status: 'not_requested' | 'pending' | 'sending' | 'succeeded' | 'failed' | 'refused' response_error: string | null responded_at: ISO time | null created_at, updated_at: ISO time } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/events Every change for all your companies, oldest first. Keep the last id and ask with ?after=id; you never miss an event, even after downtime. The same event can come twice, so skip ids you already handled. Parameters: ``` Authorization: Bearer ep_... ?after - id of the last item you already have, default 0 ?limit - 1–200, default 100 ``` Request: ``` GET ``` Response: ``` 200 application/json { items: event[], oldest first next_after: number, pass as ?after for the next page } event = { id: number created_at: ISO time type: 'company.status_changed' | 'outbound.status_changed' | 'inbound.received' | 'inbound.response_changed' dic: string document_id: number | null, id of the outbound or inbound document data: object, the changed fields } Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ``` ### /v1/epostar/usage Billable counts per company for one month: invoices accepted for sending and invoices received. Parameters: ``` Authorization: Bearer ep_... ?month - YYYY-MM ``` Request: ``` GET ``` Response: ``` 200 application/json { dic: string, outbound: number, inbound: number }[] Errors: { error: string code, message: string, findings?: object[] } 401 bad key, 403 company not active, 404 not found, 409 conflict, 413 too large, 415 not XML, 422 invalid or refused document, 503 try again 429 too many requests, wait Retry-After seconds. Per key and minute: 120 GET, 60 POST ```