PremierApi

Ruby wrapper gem for Premier API.

Features:

• HTTP POST client for /api/comm with Basic Auth + ID-UJ header
• Partner management (PARTNERI, PARTNERI_ADD)
• Issued invoices (FA_OUT, FA_OUT_ADD, FA_OUT_UHR)
• Structured error handling with Premier error code mapping

Installation

# Gemfile
gem "premier_api"

Configuration

PremierApi.configure do |config|
  config.base_url = "https://your-server:5000"   # URL where ApiComPrem is running
  config.username = "api_user"                     # User defined in Premier
  config.password = "secret"                       # Password
  config.id_uj    = "1"                            # Accounting unit ID
  config.timeout  = 120                            # Timeout in seconds (max 2 min)
  config.logger   = Rails.logger                   # Optional logging
end

Usage

Basic client

client = PremierApi::Client.new

# Read-only connection check
client.ping # => true

# Generic command
response = client.execute("SAZBY_DPH")
response.success?  # => true
response.data      # => [{"kod_dph" => "01", "text" => "...", ...}]

# With automatic raise on error
response = client.execute!("PARTNERI", parameters: { part_typ: "OD" })

Partners

client = PremierApi::Client.new

# List / search partners
response = client.partners.list(part_ico: "12345678")
response = client.partners.list(part_typ: "OD", part_adr: 1)

# Create a partner
response = client.partners.create(
  "ODBERATEL" => true,
  "CISLO"     => "WEB001",
  "NAZEV"     => "Firma s.r.o.",
  "ICO"       => "12345678",
  "DIC"       => "CZ12345678",
  "ULICE"     => "Hlavní 42",
  "PSC"       => "11000",
  "MESTO"     => "Praha",
  "E_MAIL"    => "info@firma.cz"
)
partner_id = response.first["id"]

# Update a partner
client.partners.update(partner_id, "E_MAIL" => "new@firma.cz")

# Invoice/order counts
client.partners.counts(partner_id)

Issued invoices

client = PremierApi::Client.new

# List invoices
response = client.invoices_out.list(id_part: partner_id)
response = client.invoices_out.list(dat_od: "2025-01-01", dat_do: "2025-01-31")

# With field selection
response = client.invoices_out.list(
  id_part: partner_id,
  query_fields: [
    { "tableName" => "FA_OUT", "tableFields" => "INTER,DOKLAD,CISLO,DATUM_VYS,CELKEM" },
    { "tableName" => "POLOZKY", "tableFields" => "FAKTURA,TEXT,MNOZSTVI,CENA" }
  ]
)

# Create an invoice
response = client.invoices_out.create(
  "ID_PAR"    => partner_id,
  "DATUM_VYS" => "2025-01-15",
  "DATUM_SPL" => "2025-01-29",
  "DATUM_USK" => "2025-01-15",
  "CELKEM"    => 1210.0,
  "FORMA"     => "Převodním příkazem",
  "OBJEDNAVKA" => "OBJ-2025-0042",
  "VARIABL"   => "20250042",
  "DOKLAD"    => "VF",
  "FA_POL"    => [
    {
      "TEXT"      => "Product ABC",
      "MNOZSTVI"  => 2,
      "CENA_MJ"   => 500.0,
      "CENA"      => 1000.0,
      "SAZBA_DPH" => 21.0,
      "KOD_DPH"   => "15",
      "CENA_DPH"  => 210.0,
      "MJ"        => "pcs"
    }
  ]
)

invoice_number = response.first["cislo_fa"]
invoice_id     = response.first["id_fa"]

# Allow duplicate variable symbol
client.invoices_out.create(data, parameters: { variabl_force: 1 })

# Record a payment
client.invoices_out.record_payment(invoice_id, amount: 1210.0, date: "2025-01-20")

Querying with queryCondition

response = client.execute("FA_OUT",
  parameters: { typ_fa: "FA" },
  query_condition: {
    "tableName"  => "FA_OUT",
    "conditions" => [
      { "fieldName" => "INTER", "relationalOperator" => ">", "value" => "100" },
      { "logicalOperator" => "AND", "fieldName" => "INTER", "relationalOperator" => "<", "value" => "200" }
    ]
  }
)

Error handling

begin
  response = client.execute!("PARTNERI_ADD", parameters: { typCmd: "ADD" }, data: { ... })
rescue PremierApi::DuplicatePartnerError => e
  # Error 3006: partner name already exists
  puts "Partner already exists: #{e.message}"
rescue PremierApi::ApiError => e
  puts "Premier error ##{e.error_number}: #{e.message}"
rescue PremierApi::HttpError => e
  puts "HTTP error #{e.status}: #{e.message}"
rescue PremierApi::ConnectionError => e
  puts "Network error: #{e.message}"
end

INFO command (discovering structure)

# Show structure of the FA_OUT command
response = client.execute("INFO", parameters: { prikaz: "FA_OUT" })
puts response.data

# Show table structure
response = client.execute("INFO", parameters: { table_name: "PARTNERY" })

Requirements

• Ruby >= 3.0
• Premier Enterprise (SQL edition, MSSQL 2016+)
• Running ApiComPrem service with a configured port and accounting unit

License

MIT