CLI and CGO API

The functions of the CLI and CGO interfaces are the same, the difference is in the way they are used.

CLI command line API

Data retrieval and operations from the command line locally in shared memory. To access the program remotely from the command line, you can use Curl (HTTP API) or gRPCurl (gRPC API). Program usage:

CLI examples

Create a new customer (Docker container). Result the full customer data:

Update a customer data (Windows PowerShell):

Get a customer data by code (Linux Snap). The customer code and database ID can also be specified.

Query customers by query parameters (Node NPM). Possible filter parameters can be found in the Open API or gRPC documentation.

CGO API

The CGO API a standard shared object binary file (.so or .dll) exposing Nervatura functions as a C-style APIs. It can be called from C, Python, Ruby, Node, Java, Lua, Dart, C#. Supported operating systems: Linux and Windows x64.

• Create(model char/string, options char/string, data char/string) result char/string
• Create a new model data.
  • model: New data type name. Valid values: auth, config, currency, customer, employee, item, link, movement, payment, place, price, product, project, rate, tax, tool, trans
  • options: JSON Object string. Its optional content is the alias field, the value of which is the alias name of the database. If not specified, the value of the NT_DEFAULT_ALIAS environment variable will be used, or an error message will be returned if none is provided. Example: '{"alias":"demo"}'
    The contents of options can be used to override the value of any config setting and its environment variables. For example, not only the alias name of the database, but also its connection can be specified:
    '{"alias": "demo", "NT_ALIAS_DEMO": "sqlite://file:data/demo.db?cache=shared&mode=rwc"}'
  • data: JSON Object string. Specifying the mandatory data of the new data. Optional data will be stored with their default values. The code field is the database independent unique external key. If not specified, it is generated on creation. It cannot be modified after creation. Example: '{"customer_name":"CLI Test"}'
  • result: JSON Object string. The success result is all data of the created data type: Auth, Config, Currency, Customer, Employee, Item, Link, Movement, Payment, Place, Price, Product, Project, Rate, Tax, Tool, Trans. If error occurs, the result is an error code and message.
• Update( model char/string, options char/string, data char/string) result char/string
• Update an existing model data.
  • model: Valid values: auth, config, currency, customer, employee, item, link, movement, payment, place, price, product, project, rate, tax, tool, trans
  • options: JSON Object string. To identify the data, you can specify the database identifier or the code value, but at least one of them is required.
    Its optional content is the alias field, the value of which is the alias name of the database. If not specified, the value of the NT_DEFAULT_ALIAS environment variable will be used, or an error message will be returned if none is provided. The contents of options can be used to override the value of any config setting and its environment variables.
    Example: '{"alias":"demo", "code":"CUS0000000000N2"}'
  • data: JSON Object string. Any field and meta field can be modified individually (for example, customer_name, customer_meta.account), but for complex and custom map data and arrays, the entire data must always be provided (for example, addresses, customer_map). Example: '{"customer_meta":{"account":"1234567890"}}'
  • result: If error occurs, the result is an error code and message, otherwise the success code and message.
• Delete( model char/string, options char/string) result char/string
• Delete an existing model data.
  • model: Valid values: auth, config, currency, customer, employee, item, link, movement, payment, place, price, product, project, rate, tax, tool, trans
  • options: JSON Object string. To identify the data, you can specify the database identifier or the code value, but at least one of them is required.
    Its optional content is the alias field, the value of which is the alias name of the database. If not specified, the value of the NT_DEFAULT_ALIAS environment variable will be used, or an error message will be returned if none is provided. The contents of options can be used to override the value of any config setting and its environment variables.
    Example: '{"alias":"demo", "code":"CUS0000000000N2"}'
  • result: If error occurs, the result is an error code and message, otherwise the success code and message.
• Get( model char/string, options char/string) result char/string
• Get a model data.
  • model: Valid values: auth, config, currency, customer, employee, item, link, log, movement, payment, place, price, product, project, rate, tax, tool, trans
  • options: JSON Object string. To identify the data, you can specify the database identifier or the code value, but at least one of them is required.
    Its optional content is the alias field, the value of which is the alias name of the database. If not specified, the value of the NT_DEFAULT_ALIAS environment variable will be used, or an error message will be returned if none is provided. The contents of options can be used to override the value of any config setting and its environment variables.
    Example: '{"alias":"demo", "code":"CUS0000000000N2"}'
  • result: JSON Object string. The success result is the data of the specified model: Auth, Config, Currency, Customer, Employee, Item, Link, Log, Movement, Payment, Place, Price, Product, Project, Rate, Tax, Tool, Trans. If error occurs, the result is an error code and message.
• Query( model char/string, options char/string) result char/string
• Query data by query parameters.
  • model: Valid values: auth, config, currency, customer, employee, item, link, log, movement, payment, place, price, product, project, rate, tax, tool, trans
  • options: JSON Object string. Possible filter parameters can be found in the Open API or gRPC documentation.
    Its optional content is the alias field, the value of which is the alias name of the database. If not specified, the value of the NT_DEFAULT_ALIAS environment variable will be used, or an error message will be returned if none is provided. The contents of options can be used to override the value of any config setting and its environment variables.
    Example: '{"alias":"demo", "customer_type":"CUSTOMER_COMPANY", "limit":10}'
  • result: JSON Array string. The success result is the array of data of the specified model: Auth, Config, Currency, Customer, Employee, Item, Link, Log, Movement, Payment, Place, Price, Product, Project, Rate, Tax, Tool, Trans. If error occurs, the result is an error code and message.
• View( options char/string) result char/string
• Get the data of a predefined view.
  • options: JSON Object string. Required values ​​are the name of the view. Additionally, you can specify the filter (valid SQL where clause without the where keyword), order by, limit and offset parameters.
    Valid predefined view names are:
    • VIEW_AUTH_MAP, VIEW_AUTH_VIEW
    • VIEW_CONFIG_DATA, VIEW_CONFIG_MAP, VIEW_CONFIG_MESSAGE, VIEW_CONFIG_PATTERN, VIEW_CONFIG_PRINT_QUEUE, VIEW_CONFIG_REPORT, VIEW_CONFIG_SHORTCUT
    • VIEW_CURRENCY_MAP, VIEW_CURRENCY_TAGS, VIEW_CURRENCY_VIEW
    • VIEW_CUSTOMER_ADDRESSES, VIEW_CUSTOMER_CONTACTS, VIEW_CUSTOMER_EVENTS, VIEW_CUSTOMER_MAP, VIEW_CUSTOMER_TAGS, VIEW_CUSTOMER_VIEW
    • VIEW_EMPLOYEE_EVENTS, VIEW_EMPLOYEE_MAP, VIEW_EMPLOYEE_TAGS, VIEW_EMPLOYEE_VIEW
    • VIEW_ITEM_MAP, VIEW_ITEM_TAGS, VIEW_ITEM_VIEW
    • VIEW_LINK_MAP, VIEW_LINK_TAGS, VIEW_LINK_VIEW
    • VIEW_MOVEMENT_MAP, VIEW_MOVEMENT_TAGS, VIEW_MOVEMENT_STOCK, VIEW_MOVEMENT_INVENTORY, VIEW_MOVEMENT_WAYBILL, VIEW_MOVEMENT_FORMULA, VIEW_MOVEMENT_VIEW
    • VIEW_PAYMENT_MAP, VIEW_PAYMENT_INVOICE, VIEW_PAYMENT_TAGS, VIEW_PAYMENT_VIEW
    • VIEW_PLACE_CONTACTS, VIEW_PLACE_EVENTS, VIEW_PLACE_MAP, VIEW_PLACE_TAGS, VIEW_PLACE_VIEW
    • VIEW_PRICE_MAP, VIEW_PRICE_TAGS, VIEW_PRICE_VIEW
    • VIEW_PRODUCT_EVENTS, VIEW_PRODUCT_MAP, VIEW_PRODUCT_TAGS, VIEW_PRODUCT_VIEW, VIEW_PRODUCT_COMPONENTS
    • VIEW_PROJECT_ADDRESSES, VIEW_PROJECT_CONTACTS, VIEW_PROJECT_EVENTS, VIEW_PROJECT_MAP, VIEW_PROJECT_TAGS, VIEW_PROJECT_VIEW
    • VIEW_RATE_MAP, VIEW_RATE_TAGS, VIEW_RATE_VIEW
    • VIEW_TAX_MAP, VIEW_TAX_TAGS, VIEW_TAX_VIEW
    • VIEW_TOOL_EVENTS, VIEW_TOOL_MAP, VIEW_TOOL_TAGS, VIEW_TOOL_VIEW
    • VIEW_TRANS_MAP, VIEW_TRANS_TAGS, VIEW_TRANS_VIEW
    Its optional content is the alias field, the value of which is the alias name of the database. If not specified, the value of the NT_DEFAULT_ALIAS environment variable will be used, or an error message will be returned if none is provided. The contents of options can be used to override the value of any config setting and its environment variables.
    Example: '{"alias":"demo", "name": "VIEW_CUSTOMER_EVENTS", "filter":"subject like '%visit%' and place='City1'", "limit":10}'
  • result: If error occurs, the result is an error code and message, otherwise the success code and result of the view.
• Function( options char/string) result char/string
• Execute a server side function and return the result. For example, get a PDF invoice, send email or get a product price.
  • options: JSON Object string. Required values ​​are the name of the function to be executed and its parameters. Its optional content is the alias field, the value of which is the alias name of the database. If not specified, the value of the NT_DEFAULT_ALIAS environment variable will be used, or an error message will be returned if none is provided. The contents of options can be used to override the value of any config setting and its environment variables.

    Report install example: '{"alias":"demo", "name": "report_install", "values": {"report_key":"ntr_invoice_en"}}'

    PDF report example: '{"alias":"demo", "name": "report_get", "values": {"report_key":"ntr_invoice_en", "code":"INV0000000000N5", "output":"base64", "orientation":"p", "size":"a4"}}'

    CSV report example: '{"alias":"demo", "name": "report_get", "values": {"report_key":"csv_vat_en", "filters":{"date_from":"2025-01-01", "date_to":"2025-01-31", "curr":"EUR"}}}'

    Price example: '{"alias":"demo", "name": "product_price", "values": {"product_code":"PRD0000000000N2", "currency_code":"EUR", "price_type":"PRICE_CUSTOMER"}}'

    Email sending: '{"alias":"demo", "name": "email_send", "values": {"provider":"smtp", "email":{"from":"info@example.com", "recipients":[{"email":"sample@company.com"}], "subject":"Basic email", "text":"Sending a simple text email"}}}'

    Email sending with attached PDF: '{"alias":"demo", "name": "email_send", "values": {"provider":"smtp", "email":{"from":"info@example.com", "recipients":[{"email":"sample@company.com"}], "subject":"Demo Invoice", "text":"Email sending with attached invoice", "attachments":[{"filename":"invoice.pdf", "report_key":"ntr_invoice_en", "code":"INV0000000000N5", "orientation":"p", "size":"a4"}]}}}'

  • result: If error occurs, the result is an error code and message, otherwise the success code and result of the function.

  Valid function names and parameter values:

  • report_install
    • report_key :: string :: required
    • report_dir :: string :: optional
  • report_list
    • report_dir :: string :: optional
    • label :: string :: optional
  • report_get
    • report_key :: string :: optional
    • report_id :: integer :: optional
    • template :: string :: optional
    • code :: string :: optional
    • filters :: JSON Object string :: optional
    • output :: enum[data, pdf, xml, base64] :: optional
    • orientation :: enum[p, l] :: optional
    • size :: enum[a3, a4, a5, letter, legal] :: optional
  • email_send
    • email :: map :: required
      • from :: string :: optional
      • recipients :: JSON Object Array string :: required
        • email :: string :: required
      • subject :: string :: required
      • text :: string :: optional
      • html :: string :: optional
      • attachments :: JSON Object Array string :: optional
        • filename :: string :: optional
        • report_key :: string :: optional
        • report_id :: integer :: optional
        • template :: string :: optional
        • code :: string :: optional
        • orientation :: enum[p, l] :: optional
        • size :: enum[a3, a4, a5, letter, legal] :: optional
    • provider :: enum[smtp] :: optional
  • product_price
    • product_code :: string :: required
    • currency_code :: string :: required
    • price_type :: enum[PRICE_CUSTOMER, PRICE_SUPPLIER] :: required
    • qty :: float :: optional
    • posdate :: string :: optional
    • tag :: string :: optional

• ResetPassword( options char/string) result char/string
• Reset a user password and result a new password
  • options: JSON Object string. Required values ​​are the code of the user to be reset. Its optional content is the alias field, the value of which is the alias name of the database. If not specified, the value of the NT_DEFAULT_ALIAS environment variable will be used, or an error message will be returned if none is provided. The contents of options can be used to override the value of any config setting and its environment variables.
    Example: '{"alias":"demo", "code":"USR0000000000N2"}'
  • result: If error occurs, the result is an error code and message, otherwise the success code and a new password.
• Database( options char/string) result char/string
• Create a new Nervatura database schema.
  • options: JSON Object string. Required values ​​are the alias name of the database to be created and whether it should contain demo data. Example: '{"alias":"demo", "demo":true}'
    The contents of options can be used to override the value of any config setting and its environment variables. For example, not only the alias name of the database, but also its connection can be specified:
    '{"alias": "demo", "demo":true, "NT_ALIAS_DEMO": "sqlite://file:data/demo.db?cache=shared&mode=rwc"}'
  • result: If error occurs, the result is an error code and message, otherwise the success code and message.
• Upgrade( options char/string) result char/string
• Upgrade the Nervatura database schema to the latest version.
  • options: JSON Object string. Required values ​​are the alias name of the database to be upgraded. Example: '{"alias":"demo"}'
    The contents of options can be used to override the value of any config setting and its environment variables. For example, not only the alias name of the database, but also its connection can be specified:
    '{"alias": "demo", "NT_ALIAS_DEMO": "sqlite://file:data/demo.db?cache=shared&mode=rwc"}'
  • result: If error occurs, the result is an error code and message, otherwise the success code and message.

CGO example

Python LoadLibrary example:

import ctypes
import json

ntura = ctypes.cdll.LoadLibrary("path/to/nervatura.so" or "path/to/nervatura.dll")

def encodeOptions(data):
  return json.dumps(data).encode("utf-8")

def checkJson(data):
  try:
    jdata = json.loads(data)
  except ValueError as err:
    return data
  return jdata

def decodeResult(resultStr):
  result = checkJson(resultStr)
  if type(result) == dict:
    if "code" in result:
      if result["code"] not in [200, 201, 204]:
        return [None, result["data"]]
  return [result, None]

def Get(model, options):
  Get = ntura.Get
  Get.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
  Get.restype = ctypes.c_void_p
  result = ctypes.string_at(Get(model.encode("utf-8"), encodeOptions(options))).decode("utf-8")
  return decodeResult(result)

result, err = Get("customer", {"alias":"demo", "code":"CUS0000000000N2"})

if err:
  print("Get error: "+err)
else:
  print(result)
            

Previous

Screenshots and videos

Next

HTTP Open API