Each call is fully transactional. If any part fails — a bad cast, a missing required field, a check-constraint violation — the whole document and all of its items roll back together. A call either creates everything or nothing.

Both functions share the same set of resolver helpers (see Field resolution), so the object format for a company, a contact, a currency or a VAT rate is identical across the two.

Calling convention

Both functions are reached over HTTP with POST form-encoded parameters. Append ?mode=json to receive a structured JSON response instead of raw text.

Endpoints

Request parameters

Example request

curl -X POST 'https://<INSTANCE>.obs2go.com/functions/create_expense?mode=json' \
  --data-urlencode 'token=<TOKEN>' \
  --data-urlencode 'data={"document_no":"0000001234", ... }'

Response format

With ?mode=json the response is an envelope with three fields: ExitCode, Error and Data.

Success — ExitCode 0

The new document id is returned inside Data.data, a two-element array: the first element holds the returned value (the id), the second holds the function name.

{
  "ExitCode": 0,
  "Error": "",
  "Data": {
    "data": [
      [ 18 ],            // returned id (new expenses.id / invoices.id)
      [ "create_expense" ]  // function name
    ]
  }
}

Error — ExitCode 1

On failure Data is null and Error carries the message raised by the function (for example the RAISE EXCEPTION texts documented under each function below).

{
  "ExitCode": 1,
  "Error": "create_invoice: \"issuer_id\" (our_companies) is required",
  "Data": null
}

Field resolution

Foreign-key fields are not passed as raw ids. Instead the payload describes the target row, and a resolver finds the matching id — creating the row when it does not yet exist. Every resolver also accepts a plain integer, in which case it is used as-is and no lookup happens. Omitted or null attributes resolve to null.

Companies — recipient_companies_id, company_id

Target table companies. Upserted on the unique eik constraint.

{ "eik": "123123123", "name": "Acme Inc", "vat_number": "BG123123123" }

• When eik is present it is the conflict key — an existing company is reused, a new one is inserted.
• When eik is absent the resolver falls back to an exact name match, and inserts a new company if none is found.
• vat_number and abbreviation are optional.

Our companies — paid_by_company_id, issuer_id

Target table our_companies. Same { eik, name } object as above; upserted on eik, with a name fallback.

Contacts — recipient_contacts_id, contact_id

Target table contacts. Upserted on the composite unique key (name, surname, family_name, email).

{ "name": "Ivan", "surname": "Petrov", "family_name": "Ivanov", "email": "[email protected]" }

Currency — currency

Target table currency, looked up by name (BGN, EUR, USD, …). Accepts a plain string, an id, or an object.

"EUR"                  // string — matched on currency.name
{ "name": "EUR" }       // object form
2                      // plain id — used as-is

An unknown currency raises Unknown currency: <value>.

VAT rate — vat_rate_id

Target table vat_rates, whose name column is the numeric rate (0.00, 9.00, 20.00, …). The object carries the rate value under rate or name; a plain integer is treated as an existing id.

{ "rate": 20 }        // looked up where vat_rates.name = 20
{ "name": 20 }        // same thing
3                    // plain id — used as-is

If the rate value is not found it is inserted as a new vat_rates row. Note that both 20.00 and -20.00 exist — pass a signed value for credit-note rates.

Master items — material_id, product_id, service_id, machinery_id

Targets materials, products, services, machinery. The resolver looks for an existing row by code then by name, and inserts a new row by name when neither matches.

{ "name": "Widget A" }                  // or { "code": "...", "name": "..." }

Bank account — our_companies_bank_account_id

Target table our_companies_bank_accounts. The iban is mandatory and acts as the de-duplication key (lookup-then-insert).

{ "iban": "BG80BNBG96611020345678", "bank": "First Investment Bank", "bic_code": "FINVBGSF" }

• When the IBAN is not found a new account is created under the invoice issuer_id (its our_company_id).
• name is required by the table; when the object omits it, it inherits the IBAN value.
• An object without iban raises ... must contain "iban".

create_expense

Creates one expenses row plus the expense_items lines listed under expense_items.

Header attributes

Line item attributes — expense_items[]

Example call

{
  "paid_by_company_id":     { "eik": "111111111", "name": "My Company Ltd" },
  "recipient_companies_id": { "eik": "222222222", "name": "Acme Inc", "vat_number": "BG222222222" },
  "recipient_contacts_id":  { "name": "Ivan", "surname": "Petrov",
                              "family_name": "Ivanov", "email": "[email protected]" },
  "currency":              "EUR",
  "tax_option_id":         1,
  "vat_rate_id":           { "rate": 20 },
  "vat_purchases_type_id": 2,
  "expense_categories_id": 6,
  "document_date":         "2026-05-14",
  "document_no":           "0000001234",
  "document_type_id":      1,
  "due_date":              "2026-06-13",
  "purchase_order_id":     null,
  "comment":               "Imported from supplier portal",
  "status_id":             1,
  "expense_items": [
    {
      "qty": 2, "unit_id": 1, "price_per_unit": 100.00,
      "discount": 0,
      "line_base_amount": 200.00, "line_tax_amount": 40.00,
      "line_total_amount": 240.00, "line_total": 240.00,
      "product_id": { "name": "Widget A" },
      "vat_rate_id": { "rate": 20 },
      "tax_option_id": 1,
      "line_expense_categories_id": 6,
      "line_cost_location_id": 1
    }
  ]
}

curl -X POST 'https://<INSTANCE>.obs2go.com/functions/create_expense?mode=json' \
  --data-urlencode 'token=<TOKEN>' \
  --data-urlencode "[email protected]"

# => { "ExitCode": 0, "Error": "", "Data": { "data": [ [18], ["create_expense"] ] } }

create_invoice

Creates one invoices row plus the invoice_items lines listed under invoice_items.

Header attributes

Line item attributes — invoice_items[]

Example call

{
  "company_id":  { "eik": "222222222", "name": "Acme Inc", "vat_number": "BG222222222" },
  "issuer_id":   { "eik": "111111111", "name": "My Company Ltd" },
  "contact_id":  { "name": "Ivan", "surname": "Petrov",
                  "family_name": "Ivanov", "email": "[email protected]" },
  "invoice_no":  1000000123,
  "currency":    "EUR",
  "issue_date":  "2026-05-14",
  "due_date":    "2026-06-13",
  "month":       "2026-05-01",
  "payment_method_id": 1,
  "status_id":   1,
  "category_id": 1,
  "our_companies_bank_account_id": {
    "iban": "BG80BNBG96611020345678",
    "bank": "First Investment Bank",
    "bic_code": "FINVBGSF"
  },
  "tax_option_id": 1,
  "vat_rate_id": { "rate": 20 },
  "income_category_id": 1,
  "invoice_items": [
    {
      "product_id": { "name": "Widget A" },
      "qty": 2, "unit_id": 1, "price_per_unit": 100.00,
      "invoices_income_category_id": 1,
      "discount": 0,
      "line_cost_location_id": 1,
      "tax_option_id": 1,
      "vat_rate_id": { "rate": 20 }
    }
  ]
}

curl -X POST 'https://<INSTANCE>.obs2go.com/functions/create_invoice?mode=json' \
  --data-urlencode 'token=<TOKEN>' \
  --data-urlencode "[email protected]"

# => { "ExitCode": 0, "Error": "", "Data": { "data": [ [4072], ["create_invoice"] ] } }

Reference values

Integer ids accepted by the plain fields. These are the seed values at the time of writing — query the source tables for the authoritative list.

Errors

All of the messages below arrive in the Error field with ExitCode: 1. The function is transactional, so when any of these fire nothing is written.