schema.graphql

### # BizWebs API # # last revision: 2023-09-12 ### schema { query: Query 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. sk, pl, de) """ scalar CountryCodeAlpha2 """ 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: # # # If order has been created by a visitor (unauthenticated user): # # # 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 } """ 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 } """ 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 } 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 } """ 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 } """ 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 ID" 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! # Status color 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! # Status color color: Color " text note " 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 """ type Currency { " internal ID " id: ID! " 3-letter ISO code " code: String! " currency symbol e.g '$' or '€' " symbol: String! } """ 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 " 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 } """ Product contained within order """ type OrderItem { " Internal order item ID " id: ID! " back Reference to order " order: Order! " reference to product " # . Please note that source product possibly does 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: String " 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 } # Order type Order { " system's internal ID " id: ID! " order's evidence number " order_num: 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.). Might contain also custom values. " source: String " flag that the order is awaiting administrator's intervention or review " 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! oss: Boolean oss_country: CountryCodeAlpha2 } 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 #@receipt: [Receipt] invoice: Invoice # Invoice items items: [OrderItem]! # Invoice price elements price_elements: [OrderPriceElement]! # Summary price sum: Price! # detailed taxing vat_summary: [Taxation] } # Invoice 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 # Payment list #@payments: [Receipt] # Invoice date created: DateTime! # The invoice is paid paid: Boolean # 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 download_pdf: Url } # Producer 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 # Show category in eshop menu #visibility: Boolean " 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 } # Product warehouse item type WarehouseItem { # Item internal ID id: ID! # Quantity on stock quantity: Float # Warehouse identificator warehouse_number: String # Product product: Product # EAN ean: Ean # Weight weight: Weight # Status status: WarehouseStatus # Attributes making up the physical variant of the product attributes: [Attribute] # Image path warehouse item variant image: Url # Variant price price: Price } """ 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 price price: Price # Warehouse item warehouse_items: [WarehouseItem] # Attributes attributes: [Attribute] # Tax rate for currency price tax_rate: Percentage # Product image gallery alternative_images: [Url] } type ShipmentInfo { carrier: CarrierIdent destination_point: LogisticPoint } type LogisticPoint { branch_id: ID! carrier: CarrierIdent # address: AddressData # info: LogisticPointInfo } input OrderFilter { # created from pur_date_from: Date # created until pur_date_to: Date # total < sum_from: Float # total > sum_to: Float # item title item_title: String # items price from items_from: Float # items price to items_to: Float # order number order_num: String, # customer name and surname or company name customer: String # Address address: String # currency currency: String # order Status status: Int # shipping shipping: String # payment payment: String # language lang_id: String # Invoicing company invoicer_id: String # EAN / Warehouse number / Import code product_identificator: String # order source source: String # internal note internal_note: String } """ Advanced invoices search. Only available with 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 # not invoices invoiced: Boolean, # finalized finalized: Boolean # overdue over_due: Boolean # invoice number inv_num: String, # preinvoice number pre_inv_num: String # curomer name and surname or company name customer: String # address address: String # currency currency: String # status status: Int # shipping shipping: String, # language lang_id: String # invoiced by invoicer: String # order number order_num: String } """ Advanced preinvoices search. Only available with 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, # preinvoice number pre_inv_num: String # curomer name and surname or company name customer: String # address address: String # currency currency: String # status status: Int # shipping shipping: String, # language lang_id: String # invoiced by invoicer: String } """ Advanced products search. Only available with partner token """ input ProductFilter { # name name: String # EAN ean: Ean # import code import_code: String # warehouse number warehouse_number: String # producer producer: String # indicator indicators: String # dicounts discounts: String # is active active: Boolean # product origin import: Boolean # category category: String cached_warehouse_status: String # product feed provider importer: String } # 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. # @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). 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: String # 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 # mass preinvoice filter available only with partner tokenfilter filter: PreinvoiceFilter ): PreinvoiceList # Invoice list getInvoiceList( company_id: ID params: OrderParams # mass invoice filter available only with partner tokenfilter filter: InvoiceFilter ): InvoiceList # Invoice detail getInvoice(invoice_num: String!): Invoice # Product list getProductList( # Products for language version lang_code: String! # 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 lang_code: String # import code from supplier or data source import_code: String # EAN ean: Ean ): Product # Category detail getCategory( # internal product id category_id: ID # params filter and pagination for products in this category productListParams: ProductParams ): Category # Invoicing company listMyCompanies(id: ID, name: String, company_id: String): [InvoicingCompany] # Order statuses list listOrderStatuses( # if true ignore statuses for inactive paygates only_active: Boolean, lang_code: String ): [OrderStatus] # Warehouse status list listWarehouseStatuses(allow_order: Boolean, pickup: Boolean, lang_code: String): [WarehouseStatus] #@ Producer list #@listProducers( #@ search string for filter #@ search: String #@): [Producer] #@ Producer detail #@getProducer( #@ Producer id #@ id: ID, #@ Producer name #@ name: String #@): Producer } 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! } input WeightInput { value: Float unit: WeightUnit } input WarehouseItemInput { warehouse_number: String! ean: Ean quantity: Float weight: WeightInput status: WarehouseStatusInput } 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 send_notification: [NotificationRequest!] ): WarehouseItem }