Record types

Introduction

All data within the Sharespine Integration Platform revolves around records and these records have different properties depending on their type. These records can also have different relationships to each other.

In this section we will go through all these and highlight important information for you to understand how to work with them in the best way possible.

Connection

A tenant can have multiple connections to external systems. The Connection record gives information about existing connections and their state. The Connection interface is currently READ-ONLY via API.

LatestTransferStatus

The connection record stores data about the status of transfers per Plug. This information can be used to confirm that a transaction has been executed, when it occurred, and if it was successful. Each Plug has its own purpose; for example, OrderImport imports orders to The Integration Platform, and OrderExport exports orders to an external system.

lastTransfer

The status record stores data about the most recent transfer and the most recent successful transfer. Both use the following format:

startTime

The timestamp for when the transfer was started.

endTime

The timestamp for when the transfer ended.

transferReportId

The localId for the transfer report that contains more information.

numConsidered

Number of records that was considered for the import or export. Note that records can also be ignored; this means that numFailed=0 does not necessarily indicate that all records succeeded. The transfer report contains the full information.

numFailed

Number of records that failed the import or export.

sessionErrors

Contains a list of any errors that occurred during the transfer.

Log event

All import/export transactions within the Integration Platform generates a trace in the form of logs. These logs are accessible through log events which contain information about general transaction details as well as all related records affected by the transaction.

Each record has auxiliary log message with more detailed information about the status message of that particular record.

Add a log event

External error events can be added through the API endpoint /log/event. It is intended to be used to inform the user about errors that have occurred in the remote system during an import/export through the API. The events will be shown in user interface for the integration platform under event history.

Example:

  [
    {
        "severity": "Error",
        "relatedRecordType": "order",
        "direction": "export",
        "summary": "Product missing in remote system",
        "body": [
            "The order could not be created",
            "An order row contained an unknown product SKU"
        ],
        "relatedIdMsgs": [
            {
                "id": "3fb2568eb7e165e34dd311af5550002b",
                "displayId": "1001",
                "message": "Order could not be created"
            }
        ],
        "time": "2015-01-02T03:04:05Z"
    }
  ]

Product

A Product is a central record type in the Integration Platform. The product refers to the entity sold to the end customer and should have a unique sku (Stock Keeping Unit). The Integration Platform collects and saves information about the product in a unified format. The data is stored as product properties and references to other record types.

Complete or partial product information can be added and updated through the available API-endpoints. The complete aggregated product information can always be accessed through the API.

Variant group

A Variant Group is used to group products that have a logical connection to each other. The variant group can contain information that is common for the products that belong to it. Pictures that are common for all products can be saved in the product variant group while pictures that are unique for the product should be saved in that individual product record.

Category

A category is used to logically connect products that belong to the same segment. The category can contain child categories and products can refer to both main categories and child categories. The products are not saved within the category instead the product contains a reference to the category.

Example of a category structure:

Price list

The Integration Platform is using the concept of price lists to logically structure prices between systems. The price list itself mainly contains name, default currency and optionally some custom data. The actual price values are saved directly in the product record with a reference to the price list.

The product price contains an array of qtyPrice which allows setting price levels based on the purchase quantity.

Product prices

To add a price you need to connect a price list and to specify the price per quantity (purchaseQty).

prices

This field exists on the product record and contains an array of prices. Note that all prices need to be sent when updating the prices field.

pricelist

The integration platform supports multiple price list. To add a price it is mandatory to have at least one price list.

qtyPrices

The integration platform supports prices based on the purchase qty e.g. 1 for SEK 20 each or if you buy at least 5 it is SEK 12 each. See example below.

purchaseQty

The limit for when the price is valid e.g 5 means that quantity of at least 5 will qualify

originalPriceExclVat

This field contains the price in the format Money

Example: The following example will add two price levels to one price list and one price level to another price list

{
    "prices": [
        {
            "pricelist": {
                "localId": "3fb2568eb7e165e34dd311af5550002b",
            },
            "qtyPrices": [
                {
                    "purchaseQty": "1",
                    "originalPriceExclVat": {
                        "currency": "SEK",
                        "amount": "20.00",
                        "decimals": 2
                    }
                },
                {
                    "purchaseQty": "5",
                    "originalPriceExclVat": {
                        "currency": "SEK",
                        "amount": "12.00",
                        "decimals": 2
                    }
                }
            ]
        },
        {
            "pricelist": {
                "localId": "3fb2568eb7e165e34dd311af5550002c",
            },
            "qtyPrices": [
                {
                    "purchaseQty": "1",
                    "originalPriceExclVat": {
                        "currency": "SEK",
                        "amount": "50.00",
                        "decimals": 2
                    }
                }
            ]
        }
    ]
}

Content Group

A content group is used to structure alternate content for products or variant groups. The content group contains some settings that specify how specific fields should be modified.

The content group provides the opportunity to send different texts depending on the receiving system. A common use case is to create a content group for a marketplace to enable custom product titles and descriptions for that marketplace.

The actual text is saved in the product record in the alternateContent field which is connected to a content group by localId.

Example of content group

Request

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/product/{localId}

Response

Full response omitted for brevity.

{
    "alternateContent": {
        "3fb2568eb7e165e34dd311af5550002b": {
            "contentGroupId": "3fb2568eb7e165e34dd311af5550002b",
            "title": "string",
            "title_lang": {
                "swe": "Exempeltext",
                "eng": "Example text"
            },
            "shortDescription": "string",
            "shortDescription_lang": {
                "swe": "Exempeltext",
                "eng": "Example text"
            },
            "description": "string",
            "description_lang": {
                "swe": "Exempeltext",
                "eng": "Example text"
            }
        }
    },
    ...
}

More information in the Swagger API reference.

Attribute

The attribute mainly consists of a name. It is possible to add attribute values to a product or a variant group and to connect these values to the attribute e.g. the attribute named Size can be connected to a product and the attribute value XL is added to the product. The attribute itself does not contain any attribute values.

The customData field is used to configure attributes in the Integration Platform to match attributes for remote systems. See CustomData

File

The Integration Platform has a file storage system that handles uploaded files. Upload a file through the API and then connect the file to a Product or Variant group. Read more in the endpoints for POST /product/{localId}/picture or POST /product/variantgroup/{localId}/picture.

Order

The Order is a central record type in the Integration Platform. The order contains information about a sale that has taken place and it includes rows, addresses and can have shipment(s) and payment transaction(s). A complete set of order information is recommended to leverage the full potential of the Integration Platform.

The Integration Platform can use an Order;

• as a source when creating an invoice.
• to fulfill shipments.
• to reconcile payments.
• and more…

Order type

An order can be a sales order or a return order. A sales order is a document generated by the seller specifying the details about the product or services ordered by the customer. A return order is a document specifying the items returned by the customer, it might be all or a subset of the original order.

Order status fields

The Integration Platform supports three different status fields to represent the current status of an order. All fields have a fixed set of status options which can be used e.g. in conditions for a connection. It is recommended to use all relevant fields even if the original system has a different status representation.

Order status

The Integration Platform has a fixed set of order status options that is used to describe the current order status.

pending

The order is in a pending state, ready to begin being processed.

processing

The order is in a processing state, undergoing fulfillment.

completed

The order is in a completed state, dispatched to customer.

cancelled

The order has been cancelled.

Order shipping status

The Integration Platform has a fixed set of shipping status options that is used to describe the current shipping status. Information about the actual shipment is saved as a Shipment and the payment information is saved as Payment Transaction Events.

not-shipped

The shipment status of the order is pending.

fully-shipped

The shipment status of the order is fulfilled.

part-shipped

The shipment status of the order is partly fulfilled.

returned

The shipment status of the order is returned.

Order payment status

The Integration Platform has a fixed set of payment status options that is used to describe the current payment status.

unpaid

No money has been paid at all yet.

fully-paid

All money paid.

partially-paid

Some money paid.

cancelled

The payment has been cancelled. Probably due to order being cancelled.

Order row

The order row should contain all information needed to deliver and bookkeep the sale e.g. title, qty, pricePerUnit and Tax.

Order row type

The Integration Platform supports multiple rowType’s. It is important that the correct rowType is used for each order row. The Integration Platform can use the row type as a part of a condition when sending the order information to an ERP or Accounting system.

The current valid options are:

product

This is a physical product or a service.

paymentfee

A payment fee.

shippingfee

A shipping fee.

handlingfee

A handling fee.

discount

Row discount, a discount bound to this specific row item.

voucher

A gift card, coupon or similar. Important to have side ordered in order being bookkept later in the chain.

comment

A human-readable free text comment attached to the row.

rounding

Tip amount, since it is important to bookkeep correct later in the chain.

gratuity

Tip amount, since it is important to bookkeep correct later in the chain.

customamount

A custom amount that can be used for separate cost or compensation that does not fit any of the other row types. Expected, but not mandatory, content for this row type is:

• qty = 1
• title = describe the amount
• sku = empty or a relevant id or code
• weight, volume and unit is irrelevant and can be null.

Order row prices & discounts

Outline on how to interpret and utilize row prices and discounts. Let’s first discuss the purpose of following important fields;

qty

How many items of something (where something is indicated by rowType) this row accounts for.

pricePerUnitExclTax

The amount for each item. Net. That is, per unit, excluding of all tax(es) and discounts.

perUnitTaxes

The tax for each item.

rowDiscountExclTax

Information about possible total discount amount for all items on this row. Already deducted in above perUnitExclTax and can be used as information when you want to communicate if discount has been applied.

perDiscountTaxes

Information about possible total tax amount for all item on this row. Also behaves just like rowDiscountExclTax

Invoice

The Invoice is a central record type in the Integration Platform. The invoice is the receipt of a sale that has taken place and it includes rows, addresses and payment transaction(s). A complete set of order information is recommended to leverage the full potential of the Integration Platform.

Invoice type

An invoice can be of type invoice or credit. An invoice is a document generated by the seller specifying the details about the product or services bought by the customer. A credit invoice is a document specifying the items returned by the customer.

Invoice status fields

The Integration Platform supports two different status fields to represent the current status of an invoice. All fields have a fixed set of status options which can be used e.g in conditions for native Connectors. It is recommended to use all relevant fields even if the original system has a different status representation.

Invoice status

The Integration Platform has a fixed set of order status options that is used to describe the current order status.

draft

The invoice is currently being edited, not yet ready and subject to change.

sent

The invoice has been sent to customer, should not be edited from now on.

credited

The invoice has been credited.

cancelled

The invoice has been cancelled, can be used if the invoice has nt yet been sent to the customer. If it has, credited is used instead.

Invoice payment status

The Integration Platform has a fixed set of payment status options that is used to describe the current payment status.

unpaid

The invoice has not yet been fully paid. Might be totally unpaid or partially paid.

fully-paid

The invoice has been fully paid and no more money left to pay by customer.

partially-paid

The invoice is party paid, awaiting full payment.

cancelled

The invoice payment has been cancelled, probably due to the invoice being cancelled.

Invoice row

The invoice row should contain all information needed to deliver and bookkeep the sale e.g description, quantity, sales price and tax/vat.

Invoice row type

Same as Order row type. Read that section for more information.

Invoice row prices & discounts

Same as Order row prices & discounts. Read that section for more information.

Supplier Invoice

The supplier invoice is a document that is issued by a supplier to a merchant. The supplier invoice includes rows, addresses, posting and more. A complete set of information is recommended to leverage the full potential of the Integration Platform.

Supplier Invoice type

An supplier invoice can be of type invoice or credit. An supplier invoice is a document generated by the seller specifying the details about the product or services bought by the merchant. A credit invoice is a document specifying the items returned by the merchant.

Supplier Invoice status fields

The Integration Platform supports two different status fields to represent the current status of a supplier invoice. All fields have a fixed set of status options which can be used e.g in conditions for native Connectors. It is recommended to use all relevant fields even if the original system has a different status representation.

Supplier Invoice payment status

The Integration Platform has a fixed set of payment status options that is used to describe the current payment status.

unpaid

The supplier invoice has not yet been fully paid. Might be totally unpaid or partially paid.

fully-paid

The supplier invoice has been fully paid and no more money left to pay by customer.

partially-paid

The supplier invoice is party paid, awaiting full payment.

cancelled

The supplier invoice payment has been cancelled, probably due to the supplier invoice being cancelled.

Supplier Invoice row

The supplier invoice row should contain all information needed to bookkeep the sale e.g description, quantity, sales price, tax/vat and detailed posting information.

Supplier Invoice row type

The Integration Platform supports multiple rowType’s. It is important that the correct rowType is used for each order row. The Integration Platform can use the row type as a part of a condition when sending the order information to an ERP or Accounting system.

The current valid options are:

postingonly

Used when only posting information is available. There is no reference to a product or a fee.

product

This is a physical product or a service.

handlingfee

A handling fee

paymentfee

A payment fee.

shippingfee

A shipping fee.

Shipment

A shipment is not its own record type but rather a part of the record type Order. An order can have multiple shipments and each shipment contains information about the forwarder that deliveries the parcel and tracking information. Add as much relevant shipment information as possible.

trackingCode

Used if the whole shipment have its own tracking code

trackingUri

Used when the shipment have a specific uri for the shipment

forwarder

The service/company that deliveries the shipment.

• code - unique code that identifies the forwarder
• name - a human readable name for the forwarder

parcels

The parcels contains a list of parcels that belong to the shipment. A shipment usually have at least one parcel and each parcel has its unique trackingCode.

• parcelType - add type if the information is available. Use the forwarders parcel type when possible e.g EVENLOPE1, BOX1, ..
• weight - weight of the parcel as shipped
• volume - volume of the parcel as shipped

Payment Method

A payment method is required when adding a payment transaction to an order. The payment method in the platform represents a specific type of payment e.g gift card, invoice, credit card and so on. The external payment methods can be mapped to the platform’s payment methods from the settings in a connector. The mapping does not need to be one-to-one.

Payment Transaction

An order can have one or more payment transactions. The payment transactions and their events are used to represent each payment state, which later can be used in automatic accounting. A scenario with multiple transactions is when an order is paid using a Gift card and the Gift card does not cover the full order amount, remaining amount is paid with Credit card.

A payment transaction is always started with a prepare event in the integration platform. A prepare event is usually created when a payment is reserved by the payment provider. A prepare event is added to an order and it also contains a payment method, see API-endpoint POST /order/{localid}/payment. Following events is added directly to the payment transaction, see API-endpoint POST /payment/transaction/{localid}/event

Events

prepare

Payment initiated/reserved in external system, meaning a sale has taken place.

cancel

The payment was cancelled/aborted before the payment was captured/finalized.

payment

Payment captured/finalized in an external system, meaning it is now paid by the customer.

deposit

A payout has been issued by the Payment System Provider (PSP), meaning the merchant now has the money.

refund

The customer has been refunded a partial or full amount due to, for example, a return for some reason.

credit

A credit has been issued by the PSP, meaning the merchant will be deducted money on the next payout.

A common transaction event sequence is:

1. prepare - Payment initiated/reserved in external system, meaning a sale has taken place.
2. payment - Payment captured/finalized in an external system, meaning it is now paid by the customer.
3. deposit - A payout has been issued by the Payment System Provider (PSP), meaning the merchant now has the money.

Another possible transaction sequence is:

1. prepare - Payment initiated/reserved in external system, meaning a sale has taken place.
2. payment - Payment captured/finalized in an external system, meaning it is now paid by the customer.
3. deposit - A payout has been issued by the Payment System Provider (PSP), meaning the merchant now has the money.
4. credit - The customer has been credited a partial or full amount due to, for example, a return for some reason.
5. refund - A refund has been issued by the PSP, meaning the merchant will be deducted money on the next payout.

Another possible transaction sequence is:

1. prepare - Payment initiated/reserved in external system, meaning a sale has taken place.
2. cancel - Payment canceled in the external system (possible since the payment was never paid by the customer). As opposed to the above scenario where the payment event existed and thus not possible to simply cancel.

Example of creating a simple Payment Transaction

The first step is to start the transaction with a prepare event. The event is created from an order endpoint.

The example below represents that a payment have been authorized and 100 SEK has been reserved. The PSP deducts a fee of 4 SEK and the VAT for the fee is 1 SEK.

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/order/{localId}/payment \
    -XPOST \
    -d \
    '{
        "type": "prepare",
        "eventTime": "2015-01-02T03:04:05Z",
        "paymentMethodId": "3fb2568eb7e165e34dd311af5550002b",
        "correlationId": "{Unique id for the transaction (created by the payment service provider)}",
        "correlationOrderNo": "string",
        "comment": "string",
        "amount": {
            "currency": "SEK",
            "amount": "100.00"
        },
        "feeExclTax": {
            "currency": "SEK",
            "amount": "4.00"
        },
        "feeTaxes": [
            {
                "taxType": "vat",
                "label": "string",
                "percentage": "25.00",
                "taxableAmount": {
                    "currency": "SEK",
                    "amount": "4.00"
                },
                "tax": {
                    "currency": "SEK",
                    "amount": "1.00"
                }
            }
        ]
    }'

All transaction events thereafter are added through the POST /payment/transaction/{localId}/event/ endpoint. More details can be found in the Swagger API reference.

Example of adding a customer payment event to a Payment Transaction

All subsequent events are added directly to the payment transaction. The example below represents that a payment have been captured and 100 SEK has been reserved. The PSP deducts a fee of 4 SEK and the VAT for the fee is 1 SEK. Note that the total fee for payment transaction now is 8 SEK (4 SEK in prepare + 4 SEK in payment).

$ curl
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.{HOSTNAME}/api/payment/transaction/{localId}/event/ \
    -XPOST \
    -d \
    '{
        "type": "payment",
        "eventTime": "2015-01-02T03:04:05Z",
        "amount": {
            "currency": "SEK",
            "amount": "100.00"
        },
        "feeExclTax": {
            "currency": "SEK",
            "amount": "4.00"
        },
        "feeTaxes": [
            {
                "taxType": "vat",
                "label": "string",
                "percentage": "25.00",
                "taxableAmount": {
                    "currency": "SEK",
                    "amount": "4.00"
                },
                "tax": {
                    "currency": "SEK",
                    "amount": "1.00"
                }
            }
        ]
    }'

More details can be found in the Swagger API reference.

Cash Register

The cash register represents a single unique physical cash register and is primarily used for grouping Z Reports since at least one cash register is needed to be able to transport Z Report’s within the platform.

Z Report

A Z Report is a detailed history of the transactions for one day, a.k.a. Daily taking. All sales, returns, gratuity, gift cards and information about payment methods used are possible to use within the Z Report.

It is primarily used to transfer the aggregated set of transactions (receipts) for one single day.

Important concepts within the settlement report are the usage of;

• sales Aggregated customer receipts for all sales events.
• returns Aggregated customer receipts for all sales events.
• coupon Aggregated sold gift cards.
• gratuity Aggregated gratuity/tipping.
• rounding Possible occurrence of difference between physically received money and money accounted for within the Z Report.
• paymentmethod Aggregated information per distinct payment method.

Settlement Report

A Settlement report represents reconciliation information and is primarily used to transfer the aggregated set of transactions within a timeframe on an external liquid account.

Settlements are usually used in conjunction with Z Reports where Z Reports holds information about cash register events and the Settlement Reports reconciliation information from PSP affected by these sales events.

Important concepts within the settlement report are the usage of;

• paid Money transferred from Customer to PSP.
• deposited Money transferred from PSP to Merchant.
• refunded Money transferred from PSP to Customer.
• credited Money transferred from Merchant to PSP.

Ledger account

A ledger account can hold a name, number and description. The integration platform has the possibility to create ledger entries based on transactions, where each entry will be connected to an account. The account in the integration platform is mapped to an account in the external system before ledger entries are exported.

Ledger entry

A ledger entry contains:

seriesId

The series to where the entry should be added.

entryDate

The date when the transaction occurred and the date for when the transaction is added to the ledger.

currency

The currency of the ledger entry.

comment

A descriptive text of the ledger entry.

entrySource

The system that created the ledger entry e.g a connector in the integration platform.

rows

The ledger entry rows with information about ledger account, debit amount and credit amount.