###
# BizWebs API
#
# last revision: 2023-09-26
###
schema {
# set of methods and entities for querying the API. To perform updates, @see Mutation
query: Query
# set of methods and entities to create and/or modify entities with this API.
mutation: Mutation
}
""" YYYY-MM-DD format """
scalar Date
""" YYYY-MM-DD HH:II:SS format in system-configured timezone """
# Please note this time may be represented differently if using user-scoped token
scalar DateTime
""" HH:MM 24 hr format """
scalar TimeOfDay
""" EAN code (integer) """
scalar Ean
""" E-mail address """
scalar Email
scalar Phone
""" relative or absolute URL (absolute URL including protocol) """
scalar Url
""" RGB color hexa notation starting with hash char (e.g. #ABCD12) """
scalar Color
""" float in percent points without '%' character (e.g. 62.4 means 62.4%) """
scalar Percentage
""" country code alpha-2 (e.g. cz, sk, pl, de) """
scalar CountryCodeAlpha2
""" currency code - preferrably ISO 4217 (e.g. EUR, CZK, USD) """
# This field may contain user defined custom currency code.
scalar CurrencyCode
""" unique request identificator - prevents duplicate action (e.g. import of an order) """
# The submission ID should be unique string that helps preventing duplication of
# imported data, sending multiple notifications for single action and so on.
# In distributed load-balanced environment this might be caused not just only by you calling API
# multiple times by error, but also by system failover that might occur automatically under
# high load.
# You are responsible for generating it in determinate yet unique way for a single source entity/action.
scalar SubmissionID
scalar WarehouseNumber
""" customer - might be a registered entity or unauthenticated visitor """
# .
If a customer shops without being logged-in, despite of being registered this field holds still reference to UnauthenticatedEmail.
#
# However if a customer makes an order for a company that has been registered before,
# this field holds reference to that Company, whether the customer shopped logged-in or not.
# Resolution of this field may change during time, if the company becomes registered afterwards.
#
# If customer makes an order on behalf of an unregistered company, this field holds a Company object
# having the e-mail address identical to the creator's one or a different one (company specific), depending on data filled into the order form.
union Customer = Company | Person | UnauthenticatedEmail
""" originator of an order, might be null for backend created orders """
# .
#
# If order has been created by logged-in user:
#
- this is reference to the user who created this order,
# - in case the user impersonated a company, this is reference to the user who created this order on behalf of the company.
#
#
# If order has been created by a visitor (unauthenticated user):
#
# - this is an UnauthenticatedEmail object if the visitor shopped privately,
# - this is an UnauthenticatedEmail object if the visitor shopped on behalf of a company - whether registered or not
#
# If a website's representative created the order in the system manually (in administration) the value will be null.
#
union OrderCreator = Person | UnauthenticatedEmail
# Sorting of results in list
enum Direction {
# ascending (A - Z)
ASC
# descending (Z - A)
DESC
}
""" set of string constants representing actions in warehouse """
enum WarehouseAction {
# subtract item from warehouse - item has been removed from warehouse
subtract
# block item - item is temporarily reserved/blocked for specific order
block
# unblock item
unblock
# add item to warehouse
add
}
""" supported weight units """
enum WeightUnit {
kg
}
""" supported dimension units """
enum DimensionUnit {
cm
}
""" list of order element types """
enum PriceElementType {
# shipping fee
# The 'value' field holds Pick-up location ID.
shipping
# payment fee
payment
"gift certificate"
gift
"custom price element, may be positive (custom surcharge) or negative (ad-hoc discount)"
custom
"rounding quantification - system calculated"
autoround
"customer partner card (e.g. ISIC, SPHERE)"
# The 'value' field holds vendor specific card number
partner_card
""" applied percent discount """
# The 'price' field holds negative amount (discount sum).
# The 'value' field holds percentage of applied discount.
percent_discount
""" applied discount """
# The 'price' field holds negative amount (discount).
# the 'value' field holds positive amount (absolute value) of a discount.
discount
}
""" product attribute's type """
enum AttributeType {
# Possible variant of a product (e.g. volume)
variant
"physical variant"
# Probably hard-to-change specification of a product (e.g. color).
# Combination of real variants represents a warehouse item.
real_variant
"description attribute of a product / information"
parameter
"customer's text"
input
"selection of one of the values"
select
"allows selection of multiple values"
checkbox
"custom text value"
textfield
"custom long text"
textarea
"selection of one of the values"
radio
}
""" carrier identificators """
enum CarrierIdent {
ceska_posta
depo
dhl
dpd
geis
gls
intime
ppl
slovenska_posta
sps
ulozenka
ups
wedo
zasilkovna
chameleoon
}
""" orders sorting columns """
enum OrderSorting {
order_id
order_num
# Last change of record. Option available only with partner token!
last_change
pre_inv_id
inv_id
pur_date
}
""" products sorting columns """
enum ProductSorting {
product_id
title
import_code
}
""" payment type identifier """
enum PaymentType {
cash
delivery
card
transfer
cheque
}
""" used in the method getFeedUrl as an argument value """
enum FeedType {
products
availability
}
""" payment identifier type """
enum PaymentReferenceType {
variable_symbol
invoice_num
preinvoice_num
}
""" shipment statuses """
enum ShipmentStatus {
#new_consignment
#ready_consignment
#carrier has data for shipment
carrier_registered
inventory
pickup_order
delivered
not_delivered
returned
unknown
}
interface IStatus {
# Internal ID
id: ID!
# Status name
name: String!
}
""" default dataset specifying a company """
interface ICompany {
# Internal company ID - if registered
id: ID
" legal registration ID "
company_id: String!
" company name incl. legal form "
company_name: String
# company email
email: Email
" VAT ID or tax identification number (TIN)"
# Some countries use one TIN for an entity for both regular tax and VAT identification.
vat_id: String
" VAT ID or tax identification number (TIN) #2 "
# Some countries use specific VAT ID number
vat_id2: String
}
"""
paging info for
SomeobjectLists
"""
interface IPaginationResults {
# pagination page info
pageInfo: PageInfo
}
"""
order filtering, searching and sorting parameters
"""
input OrderParams {
" count of returned results (max) [up to 30] "
limit: Int = 30
" ordinal position of first contained result (list offset) "
cursor: Int
" property name to order the results according to "
order_by: OrderSorting
# sort direction
sort: Direction
" search string "
search: String
}
"""
product filtering, searching and sorting parameters
"""
input ProductParams {
" count of returned results (max) [up to 30] "
limit: Int = 30
" ordinal position of first contained result (list offset) "
cursor: Int
" property name to order the results according to "
order_by: ProductSorting
# sort direction
sort: Direction
" search string "
search: String
}
"""
warehouse item filtering, searching and sorting parameters
"""
input WarehouseItemParams {
" count of returned results (max) [up to 30] "
limit: Int = 30
" ordinal position of first contained result (list offset) "
cursor: Int
}
"""
Information about lists' paging
"""
type PageInfo {
# listing has got next page
hasNextPage: Boolean!
# listing has got a previous page
hasPreviousPage: Boolean!
" Index pointer (ordinal position/offset) of first record on next page of results "
nextCursor: Int
" Index pointer (ordinal position/offset) of first record on previous page of results "
previousCursor: Int
pageIndex: Int
totalPages: Int
}
"""
pageable list of products (cursor)
"""
type ProductList implements IPaginationResults {
data: [Product]
pageInfo: PageInfo
}
"""
pageable list of invoices (cursor)
"""
type InvoiceList implements IPaginationResults {
data: [Invoice]
pageInfo: PageInfo
}
"""
pageable list of orders (cursor)
"""
type OrderList implements IPaginationResults {
data: [Order]
pageInfo: PageInfo
}
"""
pageable list of preinvoices (cursor)
"""
type PreinvoiceList implements IPaginationResults {
data: [Preinvoice]
pageInfo: PageInfo
}
"""
pageable list of warehouse items (cursor)
"""
type WarehouseItemList implements IPaginationResults {
data: [WarehouseItem]
pageInfo: PageInfo
}
"""
Tax-related data
"""
type Taxation {
# tax rate in percent points
tax_rate: Percentage
" tax amount "
amount: Float
" taxed amount (base) "
tax_base: Float
}
""" set of fields defining an address point - publicly recognized location """
interface IAddressPoint {
# street name
street: String
" building ID (descriptive number)"
descriptive_number: String
" street number (orientation number)"
orientation_number: String
# name of city/town/municipality
city: String
# zip code
zip: String
# state
state: String
# country
country: String
}
"""
System-registered postal address.
It may be a an invoicing, delivery or company registered address.
@see
IAddressPoint
"""
# This is an entity associated with some user or company account for repeated usage
type Address implements IAddressPoint {
" internal address ID - if address is one of predefined customer's addressess "
# It allows to reuse one address multiple times. However the same address
# may exist under different IDs, either by different customers registering
# the same address as 'their own' or by a single customer creating duplicates.
id: ID!
# company's name incl. legal form
company_name: String
# person's name
name: String
# person's surname
surname: String
# street name
street: String
" building ID (descriptive number) "
descriptive_number: String
" street number (orientation number) "
orientation_number: String
# name of city/town/municipality
city: String
# zip code
zip: String
# state
state: String
# country
country: String
# contact e-mail
email: Email
# contact phone
phone: Phone
}
"""
Address data snapshot.
"""
# Static address data. It may be a snapshot of system-registered Address or
# ad-hoc address filled into an order by a customer.
type AddressData implements IAddressPoint {
# company's name incl. legal form
company_name: String
# person's name
name: String
# person's surname
surname: String
# street name
street: String
" building ID (descriptive number) "
descriptive_number: String
" street number (orientation number) "
orientation_number: String
# name of city/town/municipality
city: String
# zip code
zip: String
# state
state: String
# country
country: String
# contact e-mail
email: Email
# contact phone
phone: Phone
}
"""
Email address of an unregistered user or registered user's who did not log in
"""
type UnauthenticatedEmail {
# e-mail address
email: Email!
# person's name
name: String
# person's surname
surname: String
# contact phone
phone: Phone
}
"""
Registered person account
"""
type Person {
" internal person ID "
id: ID!
# person's name
name: String
# person's surname
surname: String
# contact phone
phone: Phone
# e-mail address
email: Email!
" set of predefined addresses "
# (for repeated usage)
registered_address: [Address]
}
"""
legal/business entity
"""
type Company implements ICompany {
" Internal company ID - if registered "
id: ID
""" legal registration ID """
company_id: String!
# company's name incl. legal form
company_name: String!
# set of predefined addresses
registered_address: [Address]
# company e-mail
email: Email
# contact person name
name: String
# contact person surnme
surname: String
# contact phone
phone: Phone
# e-mail address
email: Email!
" VAT ID or tax identification number (TIN)"
# Some countries use one TIN for an entity for both regular tax and VAT identification.
vat_id: String
" VAT ID or tax identification number (TIN) #2 "
# Some countries use specific VAT ID number
vat_id2: String
}
"""
Company branch - website's invoicing company.
"""
type InvoicingCompany implements ICompany {
" Internal company ID "
id: ID!
""" legal registration ID """
company_id: String!
# company's name incl. legal form
company_name: String!
""" legal registration address """
address: Address!
# company e-mail
email: Email
# contact phone
phone: Phone
" VAT ID or tax identification number (TIN)"
# Some countries use one TIN for an entity for both regular tax and VAT identification.
vat_id: String
" VAT ID or tax identification number (TIN) #2 "
# Some countries use specific VAT ID number
vat_id2: String
}
"""
Warehouse status definition
"""
type WarehouseStatus implements IStatus {
" Internal warehouse status ID "
id: ID!
# Status name
name: String!
# RGB color in hexa notation (e.g. #A45594)
color: Color
# Status image
image: Url
" text note "
note: String
" allow ordering of item having this WH status "
allow_order: Boolean!
" show product on public e-shop "
show_product: Boolean!
" default delivery in days "
delivery_in_days: Int
" daily deadline for propagated delivery "
# You must place order before the time of day (specific hour) to be entitled for the 'delivery_in_days' expected delivery.
order_deadline: TimeOfDay
}
"""
Order status definition
"""
type OrderStatus implements IStatus {
""" Internal status ID """
id: ID!
# Status name
name: String!
# RGB color in hexa notation (e.g. #A45594)
color: Color
" text description of the meaning of the status "
note: String
" change of order by customer is allowed for this status "
order_change: Boolean!
" system preset to send notification email when setting this status "
statusmail: Boolean!
" system preset to send notification SMS when setting this status"
send_sms: Boolean!
# action in warehouse when setting this status
warehouse_action: WarehouseAction
}
"""
Currency detail
"""
type Currency {
" internal ID "
id: ID!
" 3-letter ISO code "
code: CurrencyCode!
" currency symbol e.g '$' or '€' "
symbol: String!
" custom currency name "
name: String
" rounding precision "
rounding_precision: Int
" number of decimal places "
decimals: Int
}
"""
Amount with currency, possibility to format/locale and indication if it is net or gross
"""
type Price {
" amount with rounding rules "
value: Float!
" raw amount (unrounded) "
raw_value: Float!
# currency reference
currency: Currency!
" includes tax or not - for VAT non-payer this field may carry both values and not to be relied upon "
is_net_price: Boolean
" amount incl. currency symbol and optional formatting/rounding rules "
formatted: String
}
"""
Language version
"""
type LanguageVersion {
" internal ID "
id: ID!
" 2-letter ISO code (country code)"
code: String!
" country name "
name: String!
# default currency used for this language version / country
currency: Currency
# Time zone
timezone: String
# Time format
time_format: String
# Date format
date_format: String
" is visible on eshop "
visible: Boolean!
" 2-letter ISO code of language of system components "
# as supported by BizWebs platform
system_lang: String!
" company assigned to invoice orders from this language version "
company: InvoicingCompany
}
"""
Non-product element in order (possibly affecting a price).
"""
# Order price elements represent most often a shipping or payment fee, applied discount or used gift certificates.
type OrderPriceElement {
" Internal element ID "
id: ID!
# back reference to order
order: Order!
# Element type
type: PriceElementType!
# Element title
title: String
" detailed information about the element (e.g. gift certificate's code, pickup point ID) "
# @see
PriceElementType
value: String
" always net price for the element "
price: Price!
" tax rate for the element "
tax_rate: Percentage
" sum per row (incl. tax) "
sum_with_tax: Price!
}
"""
Product contained within order
"""
type OrderItem {
" Internal order item ID "
id: ID!
" reference to product "
# . Please note that source product may not exist anymore.
product: Product
" item's title "
# . This label might have been changed by admin so it does not have to be identical to soruce product's name.
item_label: String
" import code (identificator from supplier's feed or data source) "
import_code: String
# product's EAN
ean: Ean
# Warehouse number
warehouse_number: WarehouseNumber
" count of ordered pieces "
quantity: Int!
" net price per unit (excl. tax) "
price: Price!
" net sum per row (excl. tax) "
sum: Price!
" recycle fee per unit (1 pc) "
recycle_fee: Price
" weight per unit (1 pc)"
weight: Weight
" tax ratio for given order item "
tax_rate: Percentage
" sum per row (incl. tax) "
sum_with_tax: Price!
}
"""
Order detail
"""
type Order {
" system's internal ID "
id: ID!
" order's evidence number "
order_num: String!
" order's optional external reference "
# This might be a reference to order from marketplace etc.
external_ref: String
" date and time of receiving the order "
pur_date: DateTime!
" variable symbol (payment reference) "
var_symb: Int
" Source of the order (eshop, e-mail, phone etc.). It may contain also custom values. "
source: String
" flag that the order is awaiting administrator's intervention or review "
# Further processing of this order should be avoided until manually reviewed by staff.
# This may happen because of number of various reasons
#
-
# the order number could not be issued due to system misconfiguration,
#
-
# the customer's VAT ID could not have been verified,
#
-
# or other business conditions were met (usage of alternate VAT ID for
# invoicing company, order in the OSS regime etc.)
#
blocked: Boolean!
" customer's note for the order "
note: String
" internal note to order (not visible to customer) "
internal_note: String
" "
customer: Customer!
" reference to person/account creating the order - @see OrderCreator for details "
creator: OrderCreator!
" invoice address "
invoice_address: AddressData!
" delivery address if specified or pickup point's address if applicable "
delivery_address: AddressData
" shipment reports "
shipments: [ShipmentInfo!]
" ordered items (products) "
items: [OrderItem]!
" non-product elements and fees "
price_elements: [OrderPriceElement]!
" total order price - may be net or incl. tax "
# . This object may contain net price for tax-exempted orders. @see
Price for further reference.
sum: Price!
" current order status "
status: OrderStatus
" assigned sales representative "
salesrep: Person
" set of preinvoices (payment requests) related to this order "
preinvoices: [Preinvoice]
" set of invoices (final documents) related to this order "
invoices: [Invoice]
" VAT summary - contains multiple taxation objects corresponding to specific tax rates contained within the order "
vat_summary: [Taxation!]
" order language "
language: LanguageVersion!
" date of last change "
last_change: DateTime!
" this order is in One-Stop-Shop EU VAT regime "
oss: Boolean
" country code for OSS regime "
# VAT taxed on this order follows rates and is dedicated to this EU country "
oss_country: CountryCodeAlpha2
}
"""
Preinvoice - payment request document - not a final invoice
"""
type Preinvoice {
id: ID!
preinvoice_num: Int!
var_symb: Int!
supplier: InvoicingCompany!
customer: Customer!
# Invoice address
invoice_address: AddressData!
created: DateTime!
due_date: DateTime
order: Order!
# List of payments
payments: [Receipt]
invoice: Invoice
# Invoice items
items: [OrderItem]!
# Invoice price elements
price_elements: [OrderPriceElement]!
# Summary price
sum: Price!
# detailed taxing
vat_summary: [Taxation!]
}
"""
Final invoice - serves as an accounting document
"""
type Invoice {
# Invoice internal ID
id: ID!
# Invocing company
supplier: InvoicingCompany!
# Customer
customer: Customer!
# Invoice address
invoice_address: AddressData!
# Buy date
buy_date: Date!
# Due date
due_date: DateTime
# Pay date - the date of payment of the full amount or the last surcharge
pay_date: DateTime
# List of payments
payments: [Receipt]
# Invoice date
created: DateTime!
# The invoice is paid or sum of received relevant payments is higher than the invoiced amount
paid: Boolean!
" regular payment identification - omit starting zeroes "
# Variable symbol
var_symb: Int
# Preinvoice number
preinvoice_num: Int
# Preinvoice
preinvoice: Preinvoice
# Invoice number
invoice_num: String!
# Invoice items
items: [OrderItem]!
# Invoice price elements
price_elements: [OrderPriceElement]!
# Summary price
sum: Price!
# detailed taxing
vat_summary: [Taxation!]
# Original order
order: Order!
# url link for pdf document - downloading this document via API does not mark it as printed in the e-shop
download_pdf: Url!
}
"""
Receipt for order
"""
type Receipt {
# Receipt internal ID
id: ID!
# receipt number
receipt_num: String!
# payment type identificator
payment_type: PaymentType
# Date the receipt was created
created: DateTime
# Date of payment
pay_date: Date
# Total amount of the receipt
sum: Price
# List of items
items: [ReceiptItem]
# Order reference
order: Order
}
"""
Receipt item
"""
type ReceiptItem {
# Item internal ID
id: ID!
# Text description of item
item_label: String
# Item quantity
quantity: Int
# Item price
price: Price
# Tax ratio for given order item
tax_rate: Percentage
}
"""
Producer detail
"""
type Producer {
# Producer internal ID
id: ID!
# Producer name
name: String
# Producer's website
url: Url
}
"""
Category of products
"""
type Category {
" system's internal ID "
id: ID!
" category's main title "
title: String!
" title for menu "
menu_title: String
# Category's description
description: String
" category language "
language: LanguageVersion!
" URL to category's webpage "
link: Url!
" category contains used goods "
used_goods: Boolean!
" whether category may be part of fulltext search result "
search_indexed: Boolean
# Parent category
parent_category: Category
# Children categories
children_categories: [Category]
" products in category "
# please note order of products is independent for each category
products: ProductList
}
"""
Weight of an order or a product
"""
type Weight {
# Weight value
value: Float
# Weight unit (currently only 'kg' unit is supported)
unit: WeightUnit
}
"""
Dimension for length, width or height
"""
type Dimension {
# Dimension value
value: Float
# Dimension unit (currently only 'cm' unit is supported)
unit: DimensionUnit
}
# Product warehouse item
type WarehouseItem {
# Item internal ID
id: ID!
# Quantity on stock
quantity: Float
# Non blocked quantity on stock
available_quantity: Float
# Warehouse identificator
warehouse_number: WarehouseNumber
# Product
product: Product
# EAN
ean: Ean
# Weight
weight: Weight
" warehouse status of this variant "
# this may be NULL if warehouse status is determined by the main product's status
status: WarehouseStatus
# Attributes making up the physical variant of the product
attributes: [Attribute]
# Image path for specific warehouse item variant
image: Url
" product variant's net price (excl. tax) "
# If not set, the product's main price is returned
price: Price!
# Final price of product including tax, discounts and all other price components.
final_price: Price
# Product variant packaging details, dimensions, weight and number of packages
packaging: [Package]
}
"""
Value for a product attribute
"""
#
This object contains user defined content.
type AttributeValue {
# ID
id: ID!
# Text value
value: String
# Image
image: Url
}
"""
specification of product's properties
"""
type Attribute {
" internal attribute ID "
id: ID!
" attribute's name "
# . Please note the value of title may change corresponding to specific language for the same attribute.
title: String
# Type
type: AttributeType
" set of attribute values, for specific attribute types (variants or parameters defined as checkbox) a product may have multiple values "
values: [AttributeValue]
}
# Product
type Product {
# Product internal ID
id: ID!
# Main product title
title: String
# Producer
producer: Producer
# Main product image
image: Url
# Link to the eshop product
link: Url!
# Short description (only plain text)
short: String
# Long description (allowed html format)
long: String
# Main product category
main_category: Category
# Attribute category
attribute_category: Category
# Assigned to categories
assigned_categories: [Category]
# Product EAN
ean: Ean
# Display the product in the store to customers
active: Boolean!
# Product identificator from supplier or data source
import_code: String
# Product net price (excl. tax)
price: Price
# Final price of product including tax, discounts and all other price components.
final_price: Price
# Warehouse item
warehouse_items: [WarehouseItem]
# Attributes
attributes: [Attribute]
# Tax rate for currency price
tax_rate: Percentage
# Product image gallery
alternative_images: [Url]
# Product packaging details, dimensions, weight and number of packages
packaging: [Package]
}
""" shipment detail of carrier"""
type ShipmentInfo {
# carrier identificator
carrier: CarrierIdent
# logistic hub/ pickup point of the carrier
destination_point: LogisticPoint
# parcels of shipment
parcels: [Parcel]
status: ShipmentStatus
# main shipment tracking number
shipment_number: String
# return url of carrier tracking website
tracking_url: Url
}
""" information about the transport hub """
type LogisticPoint {
branch_id: ID!
carrier: CarrierIdent
# address: AddressData
# info: LogisticPointInfo
}
type Parcel {
description: String
weight: Weight
length: Int
width: Int
height: Int
#shipping_wrap: ShippingWrap
}
""" order shipping definition """
type Shipping {
id: ID!
name: String
price: Price
store_pickup: Boolean
carrier: CarrierIdent
}
""" order payment method """
type Payment {
id: ID!
name: String
price: Price
type: PaymentType
}
""" dimension and weight of package for product or his variants """
type Package {
id: ID!
length: Dimension
height: Dimension
width: Dimension
weight: Weight
note: String
}
input PriceInput {
# amount
value: Float!
# currency ISO code
currency_code: CurrencyCode!
" includes tax or not - for VAT non-payer this field may carry both values and not to be relied upon "
is_net_price: Boolean
}
"""
Advanced search of orders.
Usage requires 'partner token'.
"""
input OrderFilter {
" created from "
pur_date_from: Date
" created until "
pur_date_to: Date
# total <
sum_from: Float
# total >
sum_to: Float
# containing item with title
item_title: String
# containing count of items from
items_from: Float
# containing up to count of items
items_to: Float
# order number
order_num: String
# customer name and surname or company name
customer: String
# Address
address: String
# currency
currency: CurrencyCode
# order Status
status: Int
" internal Id "
shipping: Int
" internal Id "
payment: Int
" internal Id of language version "
lang_id: Int
" internal Id of invoicing company "
invoicer_id: Int
" full text search in EAN, Warehouse number and Import code"
# EAN / Warehouse number / Import code
product_identificator: String
# order source
source: String
# internal note
internal_note: String
}
"""
Advanced search of invoices.
Usage requires 'partner token'.
"""
input InvoiceFilter {
# purchased from
buy_date_from: Date
# purchased until
buy_date_to: Date
# due from
due_date_from: Date
# due until
due_date_to: Date
# paid from
pay_date_from: Date
# paid to
pay_date_to: Date
# total <
sum_from: Float
# total >
sum_to: Float
# preinvoiced from
pre_inv_date_from: Date
# preinvoiced until
pre_inv_date_to: Date
# finalized from
inv_date_from: Date
# finalized until
inv_date_to: Date
# overdue
over_due: Boolean
# invoice number
inv_num: String
# preinvoice number
pre_inv_num: String
# customer name and surname or company name
customer: String
" address full text search "
address: String
# currency
currency: CurrencyCode
" original order status internal Id "
status: Int
" internal Id "
shipping: Int
" language version internal Id "
lang_id: Int
" internal Id of invoicing company "
invoicer: String
" original order number "
order_num: String
}
"""
Advanced search of preinvoices.
Usage requires 'partner token'.
"""
input PreinvoiceFilter {
# purchased from
buy_date_from: Date
# purchased until
buy_date_to: Date
# due from
due_date_from: Date
# due until
due_date_to: Date
# paid from
pay_date_from: Date
# paid to
pay_date_to: Date
# total <
sum_from: Float
# total >
sum_to: Float
# preinvoiced from
pre_inv_date_from: Date
# preinvoiced until
pre_inv_date_to: Date
# overdue
over_due: Boolean
# invoice number
inv_num: String
" search for preinvoices with existing/missing final invoices "
invoiced: Boolean
# preinvoice number
pre_inv_num: String
# customer name and surname or company name
customer: String
" address full text search "
address: String
# currency
currency: CurrencyCode
" original order status internal Id "
status: Int
" internal Id "
shipping: Int
" language version internal Id "
lang_id: Int
" internal Id of invoicing company "
invoicer: String
" original order number "
order_num: String
}
"""
Advanced search of products.
Usage requires 'partner token'.
"""
input ProductFilter {
# name
name: String
# EAN
ean: Ean
# import code
import_code: String
# warehouse number
warehouse_number: WarehouseNumber
# producer
producer: String
# is active
active: Boolean
" indicates whether product origins from feed or is native in the system "
import: Boolean
" being assigned to category (internal Id) "
category: Int
" internal Id "
warehouse_status: Int
}
# Querying retrieves data (read access). Batching of multiple queries is not supported with this API.
# To modify data or perform operations @see
Mutation defintion.
#
#
# As of GraphQL nature, for each query you need to specify fields returned. To make this simpler you may use predefined fragments of data (default datasets)
# which honor the _<ObjectName> convention. You may combine predefined fragments with specific field enumeration in your queries.
# @see
fragments.graphql
#
#
# You may need to distinguish between cursors i.e. pageable lists of items (
SomeobjectList objects) returned and simple sets of items
# (array of objects). General rule is that lists are used for 'content generated by public' and are retrieved by
getObjectList queries,
# simple sets are used for 'items created/managed by administrator' and retrieved by
listObjects calls.
#
#
# Please note for cursors you may not request more than 30 items at once (i.e. page size is limited to max. 30 items).
""" Querying retrieves data (read access). """
type Query {
""" Simple greeting method to test request validity, syntax or response processing.
Says Hello to whomever you like. """
hello(
""" whom to greet """
name: String
): String
""" Lists orders. Please note the returned type is pageable list. """
getOrderList(
# language
lang_code: CountryCodeAlpha2
# order status ID
status: Int
# new orders received from
newer_from: DateTime
# orders changed from
changed_from: DateTime
# includes currently blocked orders
include_blocking: Boolean
# pagination and filtering parameters
params: OrderParams
# mass order filter available only with partner token
filter: OrderFilter
): OrderList
""" Retrieve detailed information about specific order. Use '_Order' fragment to retrieve default set of information. """
getOrder(
" order's evidence number "
order_num: String!
): Order
# Preinvoice list
getPreinvoiceList(
company_id: ID
params: OrderParams
" usage of mass preinvoice filter requires 'partner token' "
filter: PreinvoiceFilter
): PreinvoiceList
# Invoice list
getInvoiceList(
company_id: ID
params: OrderParams
" usage of mass invoice filter requires 'partner token' "
filter: InvoiceFilter
): InvoiceList
# Invoice detail
getInvoice(invoice_num: String!): Invoice
# Product list
getProductList(
# Products for language version
lang_code: CountryCodeAlpha2!
# Params
params: ProductParams
# mass product filter available only with partner tokenfilter
filter: ProductFilter
): ProductList
# Product detail
getProduct(
" internal product id "
product_id: ID,
# language code - if omitted, product details of main system language version are provided
lang_code: CountryCodeAlpha2
# import code from supplier or data source
import_code: String
# gets product detail by EAN
ean: Ean
): Product
# Product XML feed url. Contains products and their final prices
getFeedUrl(
# language_code
lang_code: CountryCodeAlpha2!
# feed type product or availability
type: FeedType!
): Url
# Category detail
getCategory(
# internal product id
category_id: ID
# params filter and pagination for products in this category
productListParams: ProductParams
): Category
# List of warehouse items with change of blocking and total quantity in stock
getWarehouseItemsWithRecentStockUpdates(
# search for stock items changed since
changed_from: DateTime!
params: WarehouseItemParams
): WarehouseItemList
# Invoicing company
listMyCompanies(id: ID, name: String, company_id: String): [InvoicingCompany]
# Order statuses list
listOrderStatuses(
" gets order statuses translated for specified language version "
lang_code: CountryCodeAlpha2,
# pass TRUE to ignore statuses managed by inactive paygates
only_active: Boolean
): [OrderStatus]
# Warehouse status list
listWarehouseStatuses(allow_order: Boolean, pickup: Boolean, lang_code: CountryCodeAlpha2): [WarehouseStatus]
# Producer list
listProducers(
# search string for filter
search: String
): [Producer]!
# Shipping list
listShippings(
" shippings belonging to specified language version "
lang_code: CountryCodeAlpha2!,
only_active: Boolean
): [Shipping]!
# Payment list
listPayments(
" payment ways belonging to specified language version "
lang_code: CountryCodeAlpha2!,
only_active: Boolean
): [Payment]!
# Currencies definition
listCurrencies: [Currency]!
# Language version list
listLanguageVersions: [LanguageVersion]!
}
enum NotificationType {
# sends e-mail notification to assigned sales person (if there is some)
EMAIL_SALESPERSON
# sends e-mail notification to website administrator
EMAIL_ADMIN
# sends e-mail notification to customer's e-mail
EMAIL_CUSTOMER
# sends e-mail notification to other e-mail. This must be provided with the 'extra' field of NotificationRequest
EMAIL_OTHER
# calls given URL
WEB_HOOK
# specific system event observed by custom handlers will be fired. @requires Partner-Token
SYSTEM_EVENT
# renders notification to system's notification centre - section of system messages - this is visible to all administrators
APPTRAY_SYSTEM
# renders notification to system's notification centre - section of web-shop messages - this is visible just to specific user (if indicated with the 'extra' field of NotificationRequest)
APPTRAY_SHOP
}
enum NotificationCondition {
# sends notification only if it is the first time ever the entity was created
and_FIRST_CREATE
# sends notification only if the entity was re-created
and_RE_CREATE
# sends notification only if entity was just created or re-created
and_CREATE_OR_EDIT
# sends notification only if it has never been sent before
and_EMAIL_FIRST_SEND
# sends notification only if there has been some change to underlying data
and_CHANGED
# notification is or is not sent corresponding to current system settings
and_SYSTEM_DEFAULT
# force sending of notification
or_ALWAYS
# force silent operation - no notification is sent
NONE
}
input NotificationRequest {
if: [NotificationCondition!]
type: NotificationType!
extra: MessageExtra
}
input MessageExtra {
user_id: ID
text: String
email: Email
url: Url
phone: Phone
}
input WarehouseStatusInput {
id: ID!
}
"""
accepts data for weight
"""
input WeightInput {
value: Float
unit: WeightUnit
}
input DimensionInput {
value: Float
unit: DimensionUnit
}
"""
updates warehouse item - main intended usage is to update its
warehouse status or update quantity in stock
"""
input WarehouseItemInput {
warehouse_number: WarehouseNumber!
ean: Ean
quantity: Float
weight: WeightInput
status: WarehouseStatusInput
price: PriceInput
}
"""
accepts data for an order item
"""
input OrderItemInput {
warehouse_number: WarehouseNumber!
title: String
quantity: Float
tax_rate: Percentage
weight: WeightInput
ean: Ean
price: PriceInput
}
"""
accepts data for customer
"""
input CustomerInput {
name: String
surname: String
email: Email
phone: Phone
" legal registration ID "
company_id: String
# company's name incl. legal form
company_name: String
vat_id: String
vat_id2: String
}
input OrderPriceElementInput {
type: PriceElementType!
title: String
tax_rate: Percentage
price: PriceInput
reference_id: ID
}
input AddressDataInput {
# company's name incl. legal form
company_name: String
# person's name
name: String
# person's surname
surname: String
# street name
street: String
" building ID (descriptive number)"
descriptive_number: String
" street number (orientation number)"
orientation_number: String
# name of city/town/municipality
city: String
# zip code
zip: String
# state
state: String
# country
country: CountryCodeAlpha2
}
input TaxationInput {
# tax rate in percent points
tax_rate: Percentage!
" tax amount "
amount: Float!
" taxed amount (base) "
tax_base: Float!
currency_code: CurrencyCode
}
input ShipmentInfoInput {
# carrier identificator
carrier: CarrierIdent!
# logistic hub / pickup point
destination_point: LogisticPointInput
# main shipment tracking number
shipment_number: String
# currency chshipment status
status: ShipmentStatus
#parcels: [ParcelInput]
# total weight of shipment
#weight: Weight
}
input LogisticPointInput {
branch_id: ID!
}
"""
set of data needed to create a new order
"""
input OrderInput {
# external order number. Used for matching records
ext_order_id: String
# customer data
customer: CustomerInput!
# invoice address
invoice_address: AddressDataInput!
# delivery address
delivery_address: AddressDataInput
" datetime when the order has been created in source environment "
# This does not impact the internal 'pur_date' (creation timestamp), but
# is recorded to order's history for reference
external_pur_date: DateTime
# list of ordered items
items: [OrderItemInput!]!
# delivery, payment and other order elements
price_elements: [OrderPriceElementInput]
" initial order status - internal Id "
status: Int!
note: String
" order source e.g. market place identificator - defaults to 'api' "
source: String
" array of taxation inputs (base, rate, tax amount) "
vat_summary: [TaxationInput]
" language version iinternal Id "
lang_id: Int!
" currency internal Id (not currency code) "
currency_id: Int!
" final price of order - subject to verification "
# If omitted, it is calculated based on 'vat_summary' taxation and/or
# sum of ordered items and price elements.
# Inconsistencies may result into failed validation (reporting errors and not accepting the input).
sum: PriceInput
" additional information for shipping e.g. pickup point branch ID "
shipments: [ShipmentInfoInput!]
# order in One Stop Shop (OSS) mode - defaults to FALSE
oss: Boolean
# code for country in OSS - defaults to NULL
oss_country: CountryCodeAlpha2
# order tax excluded - defaults to FALSE
tax_excl: Boolean
" reason for tax exemption "
# You may use one of predefined constants
#
- eu-deal - intracommunitary delivery of goods
#
- export - export of goods outside of EU
#
- eu-service - intracommunitary provision of service
#
- export-service - provision of service outside of EU
#
# By using one of these constants the tax exemption reason will be replaced with system's default tax sentence
# translated to language of order's target language version.
# Also, you may provide any other custom text. This text will be used in invoice.
tax_excl_reason: String
" unique entity identificator - @see SubmissionID "
order_submission_id: SubmissionID!
}
input PackageInput {
id: ID
length: DimensionInput
width: DimensionInput
height: DimensionInput
weight: WeightInput
note: String
}
""" set of methods and entities to create and/or modify entities with this API. """
type Mutation {
" creates a preinvoice (payment request) for an order "
preinvoiceOrder(
" order's evidence number for which to create preinvoice "
order_num: String!
" possibility to tweak default system behavior or send multiple notifications "
send_notification: [NotificationRequest!]
): Preinvoice
" creates final invoice for preinvoice "
finalizeInvoice(
# preinvoice (payment request's) evidence number
preinvoice_num: String!
" possibility to tweak default system behavior or send multiple notifications "
send_notification: [NotificationRequest!]
): Invoice
" sets order status "
changeOrderStatus(
" order's evidence number for which to change the status "
order_num: String!
" system's internal status' id "
status_id: Int!
" possibility to tweak default system behavior or send multiple notifications "
send_notification: [NotificationRequest!]
): Order
" change status, quantity of warehouse item "
updateWarehouseItem(
warehouse_item: WarehouseItemInput!
# required if there are multiple language versions in the system with a currency containing the same currency ISO code
lang_id: Int
send_notification: [NotificationRequest!]
): WarehouseItem
" create new order "
newOrder (
data: OrderInput!
): Order
" payment of the invoice/preinvoice and creation of a receipt "
recordPayment(
" payment reference identificator "
payment_reference: String!
" reference type e.g. preinvoice number, invoice number or variable_symbol "
reference_type: PaymentReferenceType!
" payment type identificator "
payment_type: PaymentType!
" total amount of payment "
amount: PriceInput!
" payment date "
pay_date: Date!
): Receipt
" product packaging information "
addPackage(
product_id: ID!
warehouse_number: ID,
package: PackageInput
): Package
" delete product package "
deletePackage(package_id: ID!): Boolean
" edit product package information "
updatePackage(
package_id: ID!
package: PackageInput
): Package
}