Trade API v2.0
The Publit Trade API offers the methods and resources necessary to programatically implement a Publishing functionality in the Publit system.
The API is a RESTful based API with methods accessible through HTTP-requests. As a RESTful service it supports the common HTTP verbs, and lists resources defined per URL.
Terminology
-
Account - A Publit account of type Retailer or Publisher
-
Client - A customer or an account
-
Customer - An end consumer
-
Publisher - The publisher that owns the right for the product
-
Retailer - The retailer account that uses the API
-
User - A user of an account that can authenticate against the API
-
Contributor - A person that has contributed to a work, for example an author or translator
-
Manifestation - An edition of a work in a specific type (Book/Ebook/Audiobook) and format. Identified by the Publit manifestation_id or it’s unique ISBN
-
Product - An article that can be sold
-
Work - A literary work that has the characteristics that are common to all it’s manifestations
-
Catalogue - A catalogue of products
Authentication
All requests to the API need to be authenticated via basic authentication. The authentication is similar to any other basic authentication but can be used to login to specific accounts if a user has more than one.
The Publit authentication string is made up of three parts and should be compiled as follows: user_name;account_id:password
Note the semicolon between user_name and account_id, this separates the user from the account and is specific for the Publit APIs. If the account_id is omitted the user will automatically be logged in the the first available account the system can find for the user.
Credentials will be received by Publit upon agreement to use the API.
The API can also be accessed through tokens, see the Token resource for more information.
Environments
The API has two different environments:
-
Production - Live environment
-
Staging - Test environment for development
The staging should be used for testing only. The staging environment is re-migrated on a regular basis and any changes (for example test orders) made on it from testing will then be lost, and as such it should be viewed as a non-persistant environment. No communication prior to a re-migration of the staging environment will be made.
Time
All timestamps conveyed through the APIs are in UTC.
Custom headers
These custom headers will be returned in every authenticated request to the Publit APIs:
-
Token - Token hash
-
account_id - The authenticated account_id
-
user_id - The authenticated user_id
-
locale - The active locale of the request
General GET interface
Most GET resources have the same interface for the query string parameters. These parameters allows for filtering the data and loading relations.
If no other parameters are listed in the GET resources the following query string parameters apply.
INDEX
The index method is a basic method that lists all available resources on a specific endpoint.
The index list can be filtered and manipulated using the following parameters:
-
limit (number, optional) - Limit and offset. Usage:
limit=offset,limitorlimit=limit -
with (string, optional) - With querystring parameter. Use for loading relations if any. Usage:
with=relation. add relations with comma (,)with=relation,other_relation. See under the Response section of each of the resource methods for more information about which relations are available. -
scope (string, optional) - Scope querystring parameter. Use for filtering through pre defined scopes, if any. Usage:
scope=scope_methodorscope=method;qualifier -
has (string, optional) - Has querystring parameter. Allows for filtering through relations. Usage:
has=relation(attribute;operator;value);combinator. Has is only applicable for direct relations, it is not possible to use it on sub-relations. -
attribute (string, optional) - Allows for filtering directly on model attributes. Usage:
created_at=2017-01-01%2000:00:00 -
attribute_args (string, optional) - Allows for enhancing filtering on attributes. Set filtering attribute +
_argsin the querystring. Usage:created_at=2017-01-01%2000:00:00&created_at_args=GREATER_EQUAL -
auxiliary_attribute (string, optional) -
auxiliary_attributequerystring parameter. Use for loading attributes defined by the resource but not part of the model, if any. Usage:auxiliary_attribute=some_pre_defined_attribute -
order_by (string, optional) -
order_byquerystring parameter. Use for ordering responses. Usage:order_by=attribute -
order_dir (string, optional) - Order direction parameter, use together with
order_by. Usage:order_dir=<enum[ASC|DESC]>(default is ASC)
Large data sets and pagination
When calling the Index methods consideration must be taken for response times. Loading a data set that is too large will be memory intensive and slow to parse, and can ultimately result in timeout errors from the APIs.
To make the request faster, more consistent and less error-prone make sure to limit the data set and use pagination to iterate through the data. Also remember that loading additional relations to a resource (with) can make the data set grow exponentially, which should be considered when evaluating how many items to recover in each request.
Any limited data set will return pagination data nodes which can be parsed and used for subsequent calls.
Publit recommends by practice to limit the response using the limit query parameter and page results if needed, and enforces a maximum limit of 200 items per request on each index method call if not stated otherwise.
Example
Query for loading a maximum 20 (limit) products that has been created after 2017-01-01 00:00:00 (created_at and created_at_args) together with the related publisher and the related work and its thema categories (with).
GET ../trade/v2.0/products?with=publisher,work.thema_categories&created_at=2017-01-01%2000:00:00&created_at_args=GREATER_EQUAL;AND&limit=20Query for loading a maximum of 10 campaigns with an offset of 5 (limit=5,10), scoped by ongoing (scope=ongoing) together with its campaign products (with=campaign_products). The results are ordered descending by id (order_by=id and order_dir=DESC).
GET ../trade/v2.0/campaigns?scope=ongoing&with=campaign_products&order_by=id&order_dir=DESC&limit=5,10SHOW
The Show method is a method that shows one specific resource on a specific endpoint. Since it allways lists only one resource no additional filtering can be made. But the returned resource can be modified by loading additional relations. The following query parameters apply for the Show methods:
-
with (string, optional) - With querystring parameter. Use for loading relations if any. Usage:
with=relation. add relations with comma (,)with=relation,other_relation -
auxiliary_attribute (string, optional) -
auxiliary_attributequerystring parameter. Use for loading attributes defined by the resource but not part of the model, if any. Usage:auxiliary_attribute=some_pre_defined_attribute
Example
Query for loading an order together with a relation to it’s order_rows.
GET ../trade/v2.0/orders/1?with=order_rows
Token ¶
The Token resource creates an authentication token that can be used for subsequent calls against the API.
Any resource that is accessed via credentials and basic auth will return an authentication token that can be used for subsequent calls.
Using token for authentication
When successfully authenticated a return token attribute will be present in the headers. This can be used instead of the password when making further authentication attempts. This is useful as it permits the password to be omitted when making requests.
When authorising using token the authentication string should be compiled as follows: user_name;account_id (note that the password is omitted). And the token should be sent in the header as an attribute called token.
Every time an authentication request to any resource is made without a token, the token will be reset.
Example Headers:
Basic <base64 encoded string (for example myuser)>
Token <token hash>Token ¶
Creates authorisation token.
Create tokenPOST/<api>/v2.0/token
Example URI
POST //v2.0/token
Request
Headers
Basic: <base64 encoded hash>Response
200Returned if status is ok.
Headers
Content-Type: application/json
Token: <token hash>
user_id: <user_id>
account_id: <account_id>Body
{
"data": "OK"
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
404Returned if the service is down.
Product listing ¶
The API has two different product listing resources; the older Products resource and the newer Catalogue resource. The Catalogue resource is the preferred resource to use for ingesting products from Publit.
The Products resource is deprecated in favor of the Catalogue resource.
Catalogue ¶
The Catalogue resource is the main resource for fetching new, updated and upcoming products from Publit.
The Catalogue resource contains information about products (see the response section of the SHOW endpoint for more details) but has several relations which can be loaded into them.
Each resource in the response from the catalogue is a product which is either commercially available, upcoming or removed.
Available relations
The relations available for loading in the catalogue resource (with the with keyword in the query string) are:
-
publisher - The publisher of the product
-
publisher.retailer_publisher_details - Specific retailer-publisher details. (See the Retailer publisher details resource for more information).
-
work - The related work of the product. Most of it’s data is already available in the product, but is useful as a “bridge” to other data
-
work.description_works - The description of the literary work (and product)
-
work.thema_categories - The Thema categorisation of the literary work. (see http://www.editeur.org/151/thema for more information)
-
product_work_contributors - The contributors of the literary work connected to the product
-
product_work_contributors.contributor_biography - The biography of the connected contributor
-
product_manifestation_contributors - The contributors of the manifestation connected to the product. These are manifestation-specific contributors, such as readers for audiobook manifestations.
-
product_manifestation_contributors.contributor_biography - The biography of the connected contributor
-
product_measurement - Loads additional measurement data about the product, such as width, height and page amount
-
product_campaigns - List of related product_campaigns, which is a struct containing information about both a campaign (see the campaigns section) and the campaign_product which holds information about a products specific price during a campaign
-
ongoing_product_campaigns - Same as the product_campaigns relation but scoped to only load ongoing campaigns
-
upcoming_product_campaigns - Same as the product_campaigns relation but scoped to only load upcoming campaigns
-
ended_product_campaigns - Same as the product_campaigns relation but scoped to only load ended campaigns
-
series - Related series object of the product if applicable (if the title belongs to a series)
-
keywords - Related keyword objects for the product (empty if no keywords are set)
-
currency_instance - The currency object related to the product (relevant information can be obtained directly from the currency-attribute, the relation is only available because of legacy reasons)
-
language_instance - The language object the product relates to (relevant information can be obtained directly from the language-attribute, the relation is only available because of legacy reasons)
-
epub_information - Object containing information about the associated EPUB-files (will be empty if the product is not an Ebook)
For retailers with special permission to host files the following relation is available on top of the list above:
- files - The related files of the product
Usage:
?with=<relation>The structure of the related objects can be viewed under the response section for the INDEX-resource.
Available auxiliary attributes
A product can also be loaded with the auxiliary attribute thumbnails. If used the thumbnails attribute will be loaded displaying a list of thumbnails available for representing the product.
Usage:
?auxiliary=thumbnails
Available scopes
The scopes available for filtering products (with the scope keyword in the query string, see the general GET-interface) are:
-
productAvailability;availability code - A general scope that lets the user scope the returned data on an availability code
-
available - The available scope only lists products that are commercially available for sale
-
notYetAvailable - The notYetAvailable scope only lists products that are upcoming
-
notAvailable - The notAvailable scope only lists products that are not available
Usage:
?scope=productAvailability;21
?scope=available
?scope=notYetAvailable
?scope=notAvailableProduct Availability
Each listed product has an availability-id as defined by the ONIX standard (see Codelist 65 for more information). Publit supports three availability codes:
-
10 Not Yet Available. Will be set in the product if the product has an availability date set in the future.
-
21 In Stock. Will be set if the product is eligible for sale.
-
40 Not Available. Will be set if the product is not available (either redrawn from sales or not ready for sales for unspecified reasons).
The retailer must follow these availability codes when implementing ingestion from Publit. Only if the code is 21 is the product commercially available and eligible for sales.
Not Yet Available Products
Any product that is upcoming (not yet available) may not have all meta data and/or files in place.
But as soon as any data is changed or added for a product it will trigger the updated_at-timestamp which will allow additional data to be ingested continously.
Product ingestion example
This is a basic example on how to ingest products.
Limit enforcing
The maximum limit of the catalogue resource is set to 300. If no limit is provided this will be set automatically.
Best practice
We recommend that the listing should be filtered with a timestamp from the last time any products from Publit was ingested. This enables you to update the delta only without having to fetch every single product for each ingestion.
It also makes for smaller and quicker responses and thus easier parsing and error handling.
Example
The query in this example lists 50 products (limit=50) that has been created or updated after or equal to a certain timestamp, in this case 2017-08-01 12:00:00 (updated_at=2017-08-01%2012:00:00&updated_at_args=GREATER_EQUAL;AND).
GET .../trade/v2.0/catalogue?updated_at=2017-08-01%2012:00:00&updated_at_args=GREATER_EQUAL;AND&auxiliary=thumbnails&with=publisher,product_work_contributors.contributor_biography,product_work_contributors.contributor_biography,product_manifestation_contributors.contributor_biography,product_measurement,work.thema_categories,work.description_works&limit=50The above request would list 50 products with related information about:
-
publisher
-
contributors (with biographies)
-
description
-
category
-
measurements
-
thumbnails
If more than 50 products exist that match the filters, the response’s next attribute could be used for pagination through more result pages.
Switching to the Catalogue resource from the Products resource
The Catalogue resource is the new preferred way of fetching content from the API. Previously the Products resource was the preferred way. If you have an ingestion in place that is based on the Products resource this section lists caveats and gotchas between the Products and the Catalogue resources.
In order to make the switch from the Products resource to the Catalogue resource easier the Catalogue resource has been made structurally as similar as possible to the Products resource.
Some differences do however exist, partly to make the Catalogue resource simpler and more usable (some attributes has been modified so loading of additional relations are no longer necessary), but the largest difference is that the Catalogue resource also lists upcoming (and not yet released) titles that the ingestor must take into account when implementing this resource. Read more about availability under the Availability section of this resource.
Fetching and loading relations should be pretty much the same for the Catalogue resource as for the Products resource. Some relations have been renamed (see the lists below), but the main ingestion flow should be considered the same (see the Best Practice section above).
Differences in data structure
The following attributes in the data structure, in comparison to the Products resource, have been altered:
-
currency_id- has been replaced bycurrencyand shows the ISO currency (ISO4217) code instead of the propriatary Publit currency ID -
language_id- has been replaced bylanguageand shows the ISO language (ISO639-2) code instead of the propriatary Publit language ID -
active- has been replaced byproduct_availability_idto be able to convey the Product availability in a more granular fashion using ONIX standard codes.
Renamed relations
The following relations in the Products resource have been renamed in the Catalogue resource:
-
currency- has been renamed tocurrency_instance -
language- has been renamed tolanguage_instance
Since the ISO-codes are used directly in the Catalogue resource the loading of these resources should no longer be necessary.
IndexGET/trade/v2.0/catalogue
Example URI
GET /trade/v2.0/catalogue
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1_1",
"retailer_id": "1",
"price": "10.0000",
"currency": "SEK",
"business_model_id": "1",
"available_at": "2017-01-01 00:00:00",
"product_id": "1",
"publisher_id": "1",
"manifestation_id": "1",
"manifestation_type": "Ebook",
"work_id": "1",
"title": "My title",
"subtitle": "My subtitle",
"language": "swe",
"isbn": "9781234567891",
"formatted_isbn": "978-12-34567-89-1",
"current_price": "10.0000",
"product_availability_id": "10",
"updated_at": "2017-01-01 00:00:00",
"publisher": {
"id": "1",
"company_name": "Publisher AB",
"imprint": "Publab",
"retailer_publisher_identifier": "1",
"retailer_publisher_identification_format": "R-ID",
"retailer_publisher_details": {
"id": "1",
"retailer_account_id": "1",
"publisher_account_id": "1",
"retailer_publisher_identifier": "ABC-123",
"retailer_publisher_identification_format": "retailerA-ID",
"publit_handles_export": "True",
"publisher_name": "Publisher AB",
"retailer_name": "Retailer AB",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
},
"work": {
"id": "1",
"title": "My title",
"subtitle": "My subtitle",
"istc": "Hello, world!",
"language_id": "1",
"original_publication_year": "2017-01-01 00:00:00",
"description_works": [
{
"id": "1",
"description": "Some descriptive text...",
"updated_at": "2017-01-01 00:00:00",
"pivot": {
"connected_id": "1",
"description_work_id": "1",
"connected_type": "Work",
"id": "1"
}
}
],
"thema_categories": [
{
"id": "1",
"code": "FBA",
"description": "Modern & contemporary fiction",
"parent_code": "FB",
"pivot": {
"id": "1",
"work_id": "1",
"connected_id": "1",
"type": "Panthema"
}
}
]
},
"product_work_contributors": [
{
"contributor_id": "1",
"name": "August",
"lastname": "Strindberg",
"sort_name": "Strindberg",
"prefix": "Hello, world!",
"birth_date": "1849-01-28 00:00:00",
"contributor_biography_id": "1",
"sort_order": "1",
"product_id": "1",
"role": "Author",
"role_onix_code": "A01",
"work_id": "1",
"contributor_biograhpy": {
"id": "1",
"biography": "Some biographical text about the contributor...",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
}
],
"product_manifestation_contributors": [
{
"contributor_id": "1",
"name": "August",
"lastname": "Strindberg",
"sort_name": "Strindberg",
"prefix": "Hello, world!",
"birth_date": "1849-01-28 00:00:00",
"contributor_biography_id": "1",
"sort_order": "1",
"product_id": "1",
"role": "Author",
"role_onix_code": "A01",
"manifestation_id": "1",
"contributor_biograhpy": {
"id": "1",
"biography": "Some biographical text about the contributor...",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
}
],
"product_measurement": {
"product_id": "1",
"pages": "100",
"length_unit": "mm",
"width": "210",
"height": "297",
"duration": "3600"
},
"product_campaigns": [
{
"outlet_reference_id": "1_1",
"outlet_type": "RetailerAccount",
"campaign_name": "My summer campaign",
"start_date": "2017-07-01 00:00:00",
"end_date": "2017-07-30 23:59:59",
"price": "10.0000",
"price_tier_id": "1",
"currency": "SEK"
}
],
"ongoing_product_campaigns": [
{
"outlet_reference_id": "1_1",
"outlet_type": "RetailerAccount",
"campaign_name": "My summer campaign",
"start_date": "2017-07-01 00:00:00",
"end_date": "2017-07-30 23:59:59",
"price": "10.0000",
"price_tier_id": "1",
"currency": "SEK"
}
],
"upcoming_product_campaigns": [
{
"outlet_reference_id": "1_1",
"outlet_type": "RetailerAccount",
"campaign_name": "My summer campaign",
"start_date": "2017-07-01 00:00:00",
"end_date": "2017-07-30 23:59:59",
"price": "10.0000",
"price_tier_id": "1",
"currency": "SEK"
}
],
"ended_product_campaigns": [
{
"outlet_reference_id": "1_1",
"outlet_type": "RetailerAccount",
"campaign_name": "My summer campaign",
"start_date": "2017-07-01 00:00:00",
"end_date": "2017-07-30 23:59:59",
"price": "10.0000",
"price_tier_id": "1",
"currency": "SEK"
}
],
"currency_instance": {
"id": "1",
"name": "Swedish Krona",
"iso3": "SEK",
"isonum": "752"
},
"language_instance": {
"id": "1",
"iso3": "swe",
"iso2": "se",
"native_name": "Svenska",
"name": "Swedish"
},
"series": [
{
"id": "1",
"name": "Series name",
"account_id": "1234",
"content_amount": "3",
"description": "Some descrptive text",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"pivot": {
"work_id": "1",
"series_id": "1",
"id": "1",
"order": "1"
}
}
],
"keywords": [
{
"name": "CustomKeyword",
"pivot": {
"work_id": "1",
"keyword_id": "1",
"sort_order": "0"
}
}
],
"files": [
{
"id": "1",
"type": "Ebook",
"original_name": "some_file_name.ext",
"size": "1234567",
"extension": "epub",
"mime_type": "application/epub+zip",
"checkusm": "<md5 file hash>",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"pivot": {
"connected_id": "1",
"file_id": "1"
}
}
],
"thumbnails": [
{
"id": "1",
"type": "Ebook",
"original_name": "some_file_name.ext",
"size": "1234567",
"extension": "epub",
"mime_type": "application/epub+zip",
"checkusm": "<md5 file hash>",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"url": "https://url/to/thumbnail.jpg"
}
],
"´epub_information´": {
"manifestation_id": "1",
"file_id": "1",
"pages": "123",
"fxl": "True",
"version": "2"
}
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array",
"description": "List of products"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/catalogue/{id}
Example URI
GET /trade/v2.0/catalogue/1_1
URI Parameters
- id
string(required) Example: 1_1Id of product resource
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1_1",
"retailer_id": "1",
"price": "10.0000",
"currency": "SEK",
"business_model_id": "1",
"available_at": "2017-01-01 00:00:00",
"product_id": "1",
"publisher_id": "1",
"manifestation_id": "1",
"manifestation_type": "Ebook",
"work_id": "1",
"title": "My title",
"subtitle": "My subtitle",
"language": "swe",
"isbn": "9781234567891",
"formatted_isbn": "978-12-34567-89-1",
"current_price": "10.0000",
"product_availability_id": "10",
"updated_at": "2017-01-01 00:00:00"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"retailer_id": {
"type": "string",
"description": "The retailer id"
},
"price": {
"type": "string",
"description": "The _normal_ price of the product"
},
"currency": {
"type": "string",
"description": "Currency ISO-code"
},
"business_model_id": {
"type": "string",
"description": "Proprietary business model id"
},
"available_at": {
"type": "string",
"description": "Available date of product. Indicates the date when the product should be (or was) available for sale."
},
"product_id": {
"type": "string",
"description": "Proprietary product id"
},
"publisher_id": {
"type": "string",
"description": "Proprietary publisher id"
},
"manifestation_id": {
"type": "string",
"description": "Proprietary manifestation id"
},
"manifestation_type": {
"type": "string",
"enum": [
"Ebook",
"Audiobook",
"Pod"
],
"description": "Type of manifestation"
},
"work_id": {
"type": "string",
"description": "Proprietary work id"
},
"title": {
"type": "string",
"description": "Title of the literary work"
},
"subtitle": {
"type": "string",
"description": "Subtitle of the literary work"
},
"language": {
"type": "string",
"description": "Language ISO-code"
},
"isbn": {
"type": "string",
"description": "ISBN of the product"
},
"formatted_isbn": {
"type": "string",
"description": "Formatted ISBN of the product"
},
"current_price": {
"type": "string",
"description": "The current price of the product. Best practice is to always use this field for storing price of the product"
},
"product_availability_id": {
"type": "string",
"enum": [
"10",
"21",
"40"
],
"description": "The availability_id of the product. The availability IDs used is a subset of the ONIX standard codelist 65 (https://onix-codelists.io/codelist/65)."
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
}
}
}Response
404Returned if account retailer product id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Products ¶
The Products resource can be used for fetching commersially available products from Publit.
The Product resource contains basic information about the product (see the response section of each endpoint for more details) but has several relations which can be loaded into it.
This resource is deprecated in favor of the Catalogue resource.
Available relations
The relations available for loading into products (with the with keyword in the query string) are:
-
publisher - The publisher of the product
-
publisher.retailer_publisher_details - Specific retailer-publisher details. (See the Retailer publisher details resource for more information).
-
currency - The currency of the price of the product (all prices are always conveyed in the same currency for a specific retailer)
-
work - The related work of the product. Most of it’s data is already available in the product, but is useful as a “bridge” to other data
-
work.description_works - The description of the literary work (and product)
-
work.thema_categories - The Thema categorisation of the literary work. (see http://www.editeur.org/151/thema for more information)
-
language - The language of the product
-
product_work_contributors - The contributors of the literary work connected to the product
-
product_work_contributors.contributor_biography - The biography of the connected contributor
-
product_manifestation_contributors - The contributors of the manifestation connected to the product. These are manifestation-specific contributors, such as readers for audiobook manifestations.
-
product_manifestation_contributors.contributor_biography - The biography of the connected contributor
-
product_measurement - Loads additional measurement data about the product, such as width, height and page amount
-
product_campaigns - List of related product_campaigns, which is a struct containing information about both a campaign (see the campaigns section) and the campaign_product which holds information about a products specific price during a campaign
-
ongoing_product_campaigns - Same as the product_campaigns relation but scoped to only load ongoing campaigns
-
upcoming_product_campaigns - Same as the product_campaigns relation but scoped to only load upcoming campaigns
-
ended_product_campaigns - Same as the product_campaigns relation but scoped to only load ended campaigns
For retailers with special permission to host files the following relation is available on top of the list above:
- files - The related files of the product
Usage:
?with=<relation>Available auxiliary attributes
A product can also be loaded with the auxiliary attribute thumbnails. If used the thumbnails attribute will be loaded displaying a list of thumbnails available for representing the product.
Usage:
?auxiliary=thumbnails
Product ingestion example
This is a basic example on how to ingest products.
Best practice
We recommend that the listing should be filtered with a timestamp from the last time any products from Publit was ingested. This enables you to update the delta only without having to fetch every single product for each ingestion.
It also makes for smaller and quicker responses and thus easier parsing and error handling.
Example
The query in this example lists 50 products (limit=50) that has been created or updated after or equal to a certain timestamp, in this case 2017-08-01 12:00:00 (updated_at=2017-08-01%2012:00:00&updated_at_args=GREATER_EQUAL;AND).
GET .../trade/v2.0/products?updated_at=2017-08-01%2012:00:00&updated_at_args=GREATER_EQUAL;AND&auxiliary=thumbnails&with=publisher,product_work_contributors.contributor_biography,product_work_contributors.contributor_biography,product_manifestation_contributors.contributor_biography,product_measurements,work.thema_categories,work.description_works&limit=50The above request would list 50 products with related information about:
-
publisher
-
contributors (with biographies)
-
description
-
category
-
measurements
-
thumbnails
If more than 50 products exists that matches the filters, the response’s next attribute could be used for pagination through more result pages.
IndexGET/trade/v2.0/products
Example URI
GET /trade/v2.0/products
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1_1",
"retailer_id": "1",
"price": "10.0000",
"currency_id": "1",
"business_model_id": "1",
"active": "True",
"available_at": "2017-01-01 00:00:00",
"product_id": "1",
"publisher_id": "1",
"manifestation_id": "1",
"manifestation_type": "Ebook",
"work_id": "1",
"title": "My title",
"subtitle": "My subtitle",
"language_id": "1",
"isbn": "9781234567891",
"formatted_isbn": "978-12-34567-89-1",
"updated_at": "2017-01-01 00:00:00",
"current_price": "10.0000",
"publisher": {
"id": "1",
"company_name": "Publisher AB",
"imprint": "Publab",
"retailer_publisher_identifier": "1",
"retailer_publisher_identification_format": "R-ID",
"retailer_publisher_details": {
"id": "1",
"retailer_account_id": "1",
"publisher_account_id": "1",
"retailer_publisher_identifier": "ABC-123",
"retailer_publisher_identification_format": "retailerA-ID",
"publit_handles_export": "True",
"publisher_name": "Publisher AB",
"retailer_name": "Retailer AB",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
},
"currency": {
"id": "1",
"name": "Swedish Krona",
"iso3": "SEK",
"isonum": "752"
},
"work": {
"id": "1",
"title": "My title",
"subtitle": "My subtitle",
"istc": "Hello, world!",
"language_id": "1",
"original_publication_year": "2017-01-01 00:00:00",
"description_works": [
{
"id": "1",
"description": "Some descriptive text...",
"updated_at": "2017-01-01 00:00:00",
"pivot": {
"connected_id": "1",
"description_work_id": "1",
"connected_type": "Work",
"id": "1"
}
}
],
"thema_categories": [
{
"id": "1",
"code": "FBA",
"description": "Modern & contemporary fiction",
"parent_code": "FB",
"pivot": {
"id": "1",
"work_id": "1",
"connected_id": "1",
"type": "Panthema"
}
}
]
},
"language": {
"id": "1",
"iso3": "swe",
"iso2": "se",
"native_name": "Svenska",
"name": "Swedish"
},
"product_work_contributors": [
{
"contributor_id": "1",
"name": "August",
"lastname": "Strindberg",
"sort_name": "Strindberg",
"prefix": "Hello, world!",
"birth_date": "1849-01-28 00:00:00",
"contributor_biography_id": "1",
"sort_order": "1",
"product_id": "1",
"role": "Author",
"role_onix_code": "A01",
"work_id": "1",
"contributor_biograhpy": {
"id": "1",
"biography": "Some biographical text about the contributor...",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
}
],
"product_manifestation_contributors": [
{
"contributor_id": "1",
"name": "August",
"lastname": "Strindberg",
"sort_name": "Strindberg",
"prefix": "Hello, world!",
"birth_date": "1849-01-28 00:00:00",
"contributor_biography_id": "1",
"sort_order": "1",
"product_id": "1",
"role": "Author",
"role_onix_code": "A01",
"manifestation_id": "1",
"contributor_biograhpy": {
"id": "1",
"biography": "Some biographical text about the contributor...",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
}
],
"product_measurement": {
"product_id": "1",
"pages": "100",
"length_unit": "mm",
"width": "210",
"height": "297",
"duration": "3600"
},
"product_campaigns": [
{
"outlet_reference_id": "1_1",
"outlet_type": "RetailerAccount",
"campaign_name": "My summer campaign",
"start_date": "2017-07-01 00:00:00",
"end_date": "2017-07-30 23:59:59",
"price": "10.0000",
"price_tier_id": "1",
"currency": "SEK"
}
],
"ongoing_product_campaigns": [
{
"outlet_reference_id": "1_1",
"outlet_type": "RetailerAccount",
"campaign_name": "My summer campaign",
"start_date": "2017-07-01 00:00:00",
"end_date": "2017-07-30 23:59:59",
"price": "10.0000",
"price_tier_id": "1",
"currency": "SEK"
}
],
"upcoming_product_campaigns": [
{
"outlet_reference_id": "1_1",
"outlet_type": "RetailerAccount",
"campaign_name": "My summer campaign",
"start_date": "2017-07-01 00:00:00",
"end_date": "2017-07-30 23:59:59",
"price": "10.0000",
"price_tier_id": "1",
"currency": "SEK"
}
],
"ended_product_campaigns": [
{
"outlet_reference_id": "1_1",
"outlet_type": "RetailerAccount",
"campaign_name": "My summer campaign",
"start_date": "2017-07-01 00:00:00",
"end_date": "2017-07-30 23:59:59",
"price": "10.0000",
"price_tier_id": "1",
"currency": "SEK"
}
],
"files": [
{
"id": "1",
"type": "Ebook",
"original_name": "some_file_name.ext",
"size": "1234567",
"extension": "epub",
"mime_type": "application/epub+zip",
"checkusm": "<md5 file hash>",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"pivot": {
"connected_id": "1",
"file_id": "1"
}
}
],
"thumbnails": [
{
"id": "1",
"type": "Ebook",
"original_name": "some_file_name.ext",
"size": "1234567",
"extension": "epub",
"mime_type": "application/epub+zip",
"checkusm": "<md5 file hash>",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
]
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array",
"description": "List of products"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/products/{id}
Example URI
GET /trade/v2.0/products/1_1
URI Parameters
- id
string(required) Example: 1_1Id of product resource
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1_1",
"retailer_id": "1",
"price": "10.0000",
"currency_id": "1",
"business_model_id": "1",
"active": "True",
"available_at": "2017-01-01 00:00:00",
"product_id": "1",
"publisher_id": "1",
"manifestation_id": "1",
"manifestation_type": "Ebook",
"work_id": "1",
"title": "My title",
"subtitle": "My subtitle",
"language_id": "1",
"isbn": "9781234567891",
"formatted_isbn": "978-12-34567-89-1",
"updated_at": "2017-01-01 00:00:00",
"current_price": "10.0000",
"publisher": {
"id": "1",
"company_name": "Publisher AB",
"imprint": "Publab",
"retailer_publisher_identifier": "1",
"retailer_publisher_identification_format": "R-ID",
"retailer_publisher_details": {
"id": "1",
"retailer_account_id": "1",
"publisher_account_id": "1",
"retailer_publisher_identifier": "ABC-123",
"retailer_publisher_identification_format": "retailerA-ID",
"publit_handles_export": "True",
"publisher_name": "Publisher AB",
"retailer_name": "Retailer AB",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
},
"currency": {
"id": "1",
"name": "Swedish Krona",
"iso3": "SEK",
"isonum": "752"
},
"work": {
"id": "1",
"title": "My title",
"subtitle": "My subtitle",
"istc": "Hello, world!",
"language_id": "1",
"original_publication_year": "2017-01-01 00:00:00",
"description_works": [
{
"id": "1",
"description": "Some descriptive text...",
"updated_at": "2017-01-01 00:00:00",
"pivot": {
"connected_id": "1",
"description_work_id": "1",
"connected_type": "Work",
"id": "1"
}
}
],
"thema_categories": [
{
"id": "1",
"code": "FBA",
"description": "Modern & contemporary fiction",
"parent_code": "FB",
"pivot": {
"id": "1",
"work_id": "1",
"connected_id": "1",
"type": "Panthema"
}
}
]
},
"language": {
"id": "1",
"iso3": "swe",
"iso2": "se",
"native_name": "Svenska",
"name": "Swedish"
},
"product_work_contributors": [
{
"contributor_id": "1",
"name": "August",
"lastname": "Strindberg",
"sort_name": "Strindberg",
"prefix": "Hello, world!",
"birth_date": "1849-01-28 00:00:00",
"contributor_biography_id": "1",
"sort_order": "1",
"product_id": "1",
"role": "Author",
"role_onix_code": "A01",
"work_id": "1",
"contributor_biograhpy": {
"id": "1",
"biography": "Some biographical text about the contributor...",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
}
],
"product_manifestation_contributors": [
{
"contributor_id": "1",
"name": "August",
"lastname": "Strindberg",
"sort_name": "Strindberg",
"prefix": "Hello, world!",
"birth_date": "1849-01-28 00:00:00",
"contributor_biography_id": "1",
"sort_order": "1",
"product_id": "1",
"role": "Author",
"role_onix_code": "A01",
"manifestation_id": "1",
"contributor_biograhpy": {
"id": "1",
"biography": "Some biographical text about the contributor...",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
}
],
"product_measurement": {
"product_id": "1",
"pages": "100",
"length_unit": "mm",
"width": "210",
"height": "297",
"duration": "3600"
},
"product_campaigns": [
{
"outlet_reference_id": "1_1",
"outlet_type": "RetailerAccount",
"campaign_name": "My summer campaign",
"start_date": "2017-07-01 00:00:00",
"end_date": "2017-07-30 23:59:59",
"price": "10.0000",
"price_tier_id": "1",
"currency": "SEK"
}
],
"ongoing_product_campaigns": [
{
"outlet_reference_id": "1_1",
"outlet_type": "RetailerAccount",
"campaign_name": "My summer campaign",
"start_date": "2017-07-01 00:00:00",
"end_date": "2017-07-30 23:59:59",
"price": "10.0000",
"price_tier_id": "1",
"currency": "SEK"
}
],
"upcoming_product_campaigns": [
{
"outlet_reference_id": "1_1",
"outlet_type": "RetailerAccount",
"campaign_name": "My summer campaign",
"start_date": "2017-07-01 00:00:00",
"end_date": "2017-07-30 23:59:59",
"price": "10.0000",
"price_tier_id": "1",
"currency": "SEK"
}
],
"ended_product_campaigns": [
{
"outlet_reference_id": "1_1",
"outlet_type": "RetailerAccount",
"campaign_name": "My summer campaign",
"start_date": "2017-07-01 00:00:00",
"end_date": "2017-07-30 23:59:59",
"price": "10.0000",
"price_tier_id": "1",
"currency": "SEK"
}
],
"files": [
{
"id": "1",
"type": "Ebook",
"original_name": "some_file_name.ext",
"size": "1234567",
"extension": "epub",
"mime_type": "application/epub+zip",
"checkusm": "<md5 file hash>",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"pivot": {
"connected_id": "1",
"file_id": "1"
}
}
],
"thumbnails": [
{
"id": "1",
"type": "Ebook",
"original_name": "some_file_name.ext",
"size": "1234567",
"extension": "epub",
"mime_type": "application/epub+zip",
"checkusm": "<md5 file hash>",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"retailer_id": {
"type": "string",
"description": "The retailer id"
},
"price": {
"type": "string",
"description": "The _normal_ price of the product"
},
"currency_id": {
"type": "string",
"description": "Proprietary currency id"
},
"business_model_id": {
"type": "string",
"description": "Proprietary business model id"
},
"active": {
"type": "string",
"enum": [
"True",
"False"
],
"description": "Active flag, indicates if the product is commercially available for sale. If `True` the product is avaiable for purchase"
},
"available_at": {
"type": "string",
"description": "Available date of product. Indicates the date when the product is made available for sale. Only when this time has passed and the `active` flag is true will the product be available for sale"
},
"product_id": {
"type": "string",
"description": "Proprietary product id"
},
"publisher_id": {
"type": "string",
"description": "Proprietary publisher id"
},
"manifestation_id": {
"type": "string",
"description": "Proprietary manifestation id"
},
"manifestation_type": {
"type": "string",
"enum": [
"Ebook",
"Audiobook",
"Pod"
],
"description": "Type of manifestation"
},
"work_id": {
"type": "string",
"description": "Proprietary work id"
},
"title": {
"type": "string",
"description": "Title of the literary work"
},
"subtitle": {
"type": "string",
"description": "Subtitle of the literary work"
},
"language_id": {
"type": "string",
"description": "Proprietary language id"
},
"isbn": {
"type": "string",
"description": "ISBN of the product"
},
"formatted_isbn": {
"type": "string",
"description": "Formatted ISBN of the product"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
},
"current_price": {
"type": "string",
"description": "The current price of the product. Best practice is to always use this field for storing price of the product"
},
"publisher": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"company_name": {
"type": "string",
"description": "Name of the publishing company"
},
"imprint": {
"type": "string",
"description": "Imprint of the publisher"
},
"retailer_publisher_identifier": {
"type": "string",
"description": "Retailer publisher identifier, if any"
},
"retailer_publisher_identification_format": {
"type": "string",
"description": "Retailer publisher identification format, if any"
},
"retailer_publisher_details": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"retailer_account_id": {
"type": "string",
"description": "Proprietary retailer id"
},
"publisher_account_id": {
"type": "string",
"description": "Proprietary publisher id"
},
"retailer_publisher_identifier": {
"type": "string",
"description": "The retailers publisher ID"
},
"retailer_publisher_identification_format": {
"type": "string",
"description": "The type of identification format"
},
"publit_handles_export": {
"type": "string",
"enum": [
"True"
],
"description": "This flag indicates if distribution of the product is handled from Publit. (If _False_ the distribution (including order handling) is supposed to be handled elsewhere)."
},
"publisher_name": {
"type": "string",
"description": "Name of publisher"
},
"retailer_name": {
"type": "string",
"description": "Name of retailer"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
}
},
"description": "The related retailer publisher details"
}
},
"description": "The related publisher"
},
"currency": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"name": {
"type": "string",
"description": "Name of the currency in english"
},
"iso3": {
"type": "string",
"description": "ISO-4217 standard format of the currency"
},
"isonum": {
"type": "string",
"description": "ISO-4217 standard numeric format of the currency"
}
},
"description": "The related currency"
},
"work": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"title": {
"type": "string",
"description": "Title of the work"
},
"subtitle": {
"type": "string",
"description": "Subtitle of the work"
},
"istc": {
"type": "string",
"description": "istc code of work, if any"
},
"language_id": {
"type": "string",
"description": "proprietary language id of the work"
},
"original_publication_year": {
"type": "string",
"description": "Original year of publication in timestamp format."
},
"description_works": {
"type": "array",
"description": "Related descriptions of the work"
},
"thema_categories": {
"type": "array",
"description": "Related Thema categories of the work"
}
},
"description": "The related work"
},
"language": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"iso3": {
"type": "string",
"description": "ISO three letter code of the language"
},
"iso2": {
"type": "string",
"description": "ISO two letter code of the language"
},
"native_name": {
"type": "string",
"description": "Name of the language in the native tongue"
},
"name": {
"type": "string",
"description": "Name of the language in english"
}
},
"description": "Related language of the product"
},
"product_work_contributors": {
"type": "array",
"description": "List of related contributors connected to the work"
},
"product_manifestation_contributors": {
"type": "array",
"description": "List of related contributors connected to the manifestation"
},
"product_measurement": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "Id of the related product"
},
"pages": {
"type": "string",
"description": "Number of pages (Note for digital free flowing formats this is approximated)"
},
"length_unit": {
"type": "string",
"description": "Length unit of the the width and height attributes"
},
"width": {
"type": "string",
"description": "Width of the product (only applicable to physical formats)"
},
"height": {
"type": "string",
"description": "Height of the product (only applicable to physical formats)"
},
"duration": {
"type": "string",
"description": "Duration of the product (only applicable to audiobook formats)"
}
},
"description": "Related product measurement"
},
"product_campaigns": {
"type": "array",
"description": "Related campaigns"
},
"ongoing_product_campaigns": {
"type": "array",
"description": "Related ongoing campaigns"
},
"upcoming_product_campaigns": {
"type": "array",
"description": "Related upcoming campaigns"
},
"ended_product_campaigns": {
"type": "array",
"description": "Related ended campaigns"
},
"files": {
"type": "array",
"description": "Related files (only available for retailers with special permissions to host files)"
},
"thumbnails": {
"type": "array",
"description": "Auxiliary thumbnails attribute"
}
}
}Response
404Returned if account retailer product id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Campaigns ¶
Campaigns ¶
The campaigns resource lists campaigns and campaign general campaign information such as name, start_date and end_date.
A campaign starts automatically when the start_date is passed. From that point on the current_price attribute in the products resource will change, for the affected products, to the price set in the campaign. Likewise the campaign automatically ends once the end_date has passed - and the current_price will be updated accordingly.
The campaign does also have an active attribute. This attribute is indicates if a created campaign should be regarded as live - this is not the same as an ongoing campaign which is solely defined by the start- and end-dates. As an example an existing campaign can be inactivated by the publisher if they wish to discontinue a campaign (or remove it) - it should then no longer be regarded as live.
Available relations
A campaign can be loaded with the following relations:
- campaign_products - The related mapping to specific products. Includes references to productID and campaign prices
Available Scopes
The campaign Index resource can be filtered with the following scopes (load by using the scope query string parameter):
-
ongoing - Lists only currently ongoing campaigns
-
upcoming - Lists only campaigns that are to come
-
ended - Lists campaigns that has ended
IndexGET/trade/v2.0/campaigns
Example URI
GET /trade/v2.0/campaigns
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1",
"name": "My campaign",
"active": "True",
"start_date": "2017-09-01 00:00:00",
"end_date": "2017-09-30 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"campaign_products": [
{
"id": "1",
"campaign_id": "1",
"product_id": "1",
"price": "10.0000",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
]
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array",
"description": "List of campaigns"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/campaigns/{campaign_id}
Example URI
GET /trade/v2.0/campaigns/1
URI Parameters
- campaign_id
number(required) Example: 1Id of requested campaign resource
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"name": "My campaign",
"active": "True",
"start_date": "2017-09-01 00:00:00",
"end_date": "2017-09-30 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"campaign_products": [
{
"id": "1",
"campaign_id": "1",
"product_id": "1",
"price": "10.0000",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"name": {
"type": "string",
"description": "Name of the campaign. As named by the Publisher"
},
"active": {
"type": "string",
"enum": [
"True",
"False"
],
"description": "Active flag, indicates if the Campaign is deactivated/cancelled or not"
},
"start_date": {
"type": "string",
"description": "Timestamp indicating the start of the campaign"
},
"end_date": {
"type": "string",
"description": "Timestamp indicating the end of the campaign"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
},
"campaign_products": {
"type": "array",
"description": "List of related `campaign_products`"
}
}
}Response
404Returned if campaign id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}File ¶
Retailers that host files on own servers can use these resources to fetch and list available files.
The file resources are only available for retailers that are set up to host their own files. To enable an account to be eligible for hosting of files a special agreement must be signed with Publit.
Files ¶
Available auxiliary attributes
The file resource can be loaded with the following auxiliary attributes (using auxiliary query string parameter):
- presigned_url - A presigned download URL.
Best practice
Using presigned_url is recommended best practice. The presigned URL makes downloading more stable and does not enforce a timeout, which the download resource do, making it better for downoading larger files.
Downloading examples
Using the download resource (via curl)
curl -u "username;account_id:password" -o file.extension https://api.publit.com/trade/v2.0/files/1/downloadUsing presigned_url (via curl)
curl -o file.extension <presigned_url>IndexGET/trade/v2.0/files
Example URI
GET /trade/v2.0/files
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1",
"type": "Ebook",
"original_name": "some_file_name.ext",
"size": "1234567",
"extension": "epub",
"mime_type": "application/epub+zip",
"checkusm": "<md5 file hash>",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"presigned_url": "https://some/presigned/url.to.file"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array",
"description": "File list"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/files/{file_id}
Example URI
GET /trade/v2.0/files/1234
URI Parameters
- file_id
number(required) Example: 1234Id of the requested file
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"type": "Ebook",
"original_name": "some_file_name.ext",
"size": "1234567",
"extension": "epub",
"mime_type": "application/epub+zip",
"checkusm": "<md5 file hash>",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"presigned_url": "https://some/presigned/url.to.file"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"type": {
"type": "string",
"enum": [
"Ebook",
"EbookCover",
"EbookThumbnail",
"EbookSmallThumbnail",
"Audiobook",
"AudiobookCover",
"AudiobookThumbnail",
"AudiobookSmallThumbnail"
],
"description": "Type of file"
},
"original_name": {
"type": "string",
"description": "The original name of the file"
},
"size": {
"type": "string",
"description": "The size of the file in bytes"
},
"extension": {
"type": "string",
"description": "The file extensions of the fie"
},
"mime_type": {
"type": "string",
"description": "The mime type of the file"
},
"checkusm": {
"type": "string",
"description": "The md5 file hash of the file"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
},
"presigned_url": {
"type": "string",
"description": "Presigned (pre-authenticated) URL to file for downloading. The URL will be valid to use for 5 minutes after creation"
}
}
}Response
404Returned if file id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}DownloadGET/trade/v2.0/files/{file_id}/download
Example URI
GET /trade/v2.0/files/1234/download
URI Parameters
- file_id
number(required) Example: 1234Id of the requested file
Response
200Body
Returned if the request was succesful together with the binary file. The mime-type will be set to the most appropriate for the file.Order handling ¶
Orders ¶
The orders resource handles listing and creation of orders.
The orders resource is one of the very few resources where the input parameters for creating an order differs from hte actual order data stored. This is to simplify the order creation process.
This resource is not available for proxy retailers.
Available relations
The order resource can be loaded with the following relations:
-
order_statuses - The statuses of the order
-
order_rows - The order rows the order consist of
-
order_rows.order_row_digital_content_key - Content keys for downloading items purchased that is in digital formats
-
order_rows.order_row_digital_content_key.drm_type - DRM type of the downloadable content
-
invoice - The invoice the order is bound to
-
print_orders - The related print orders (for purchases of printed type books only)
Order references
When creating orders different reference numbers can be added, even though they are not required:
-
client_order_reference -
intermediator_order_reference
Depending on if a retailer acts as an intermediator or not the different fields has different meaning. An easy rule of thumb is this:
If the retailer acts as an intermediator the intermediator_order_reference should be used for sending the retailer order identifier.
In all other cases the retailers order identifier should be sent in the client_order_reference field (the client in this case refers to the client of Publit - which is the retailer).
These references helps greately to match orders from one system to Publit, and makes any support issues regarding orders much quicker and easier to handle.
As best practice it is always recommended to add a reference number to the order so it can be tracked between different systems.
Examples for creating orders
These are some exmples no how to create orders through the TradeAPI and what to expect in response.
Note that the response and request data is fictional and the example only aims to give an understanding about the data structures.
Simple Ebook purchase order
Simple purchase of ebook. The response for ebook purchases include the placed order, the related order_rows and the related order_row_digital_content_keys from where it is possible to discern information about how to download the purchased contents.
The provided client_id points to the authenticated retailer account placing the order and the item_id points to an Ebook product.
Request:
POST ../trade/v2.0/orders
The request could also be sent to: POST ../trade/v2.0/order_preview
Payload data structure
{
"client_id":1,
"client_type":"RetailerAccount",
"client_order_reference":"ref:12345",
"items":[
{
//Assuming that the id 1 points to an Ebook
"item_id":1,
"amount":"1",
"item_type":"Product"
}
]
}Response
[
{
"contractor_id": "1",
"client_type": "RetailerAccount",
"client_id": "1",
"territory_class_id": "30",
"client_order_reference": "ref:12345",
"intermediator_id": null,
"intermediator_order_reference": null,
"delivery_message": null,
"order_currency_id": "131",
"status": "Accepted",
"invoice_id": "1",
"updated_at": "2017-10-14 15:46:03",
"created_at": "2017-10-14 15:46:03",
"id": "1",
"order_rows": [
{
"order_row_type_id": "2",
"item_id": "1",
"amount": "1",
"price_per_unit_ex_vat": "100.000000",
"vat_per_unit": "25.000000",
"total_inc_vat": "125.000000",
"vat_rate": "0.2500",
"currency_id": "131",
"order_row_description": "The Book title : subtitle : 978xxxxxxxxxx",
"raw_unit_price": "100.000000",
"publisher_retailer_discount": "0.00",
"order_row_message": null,
"order_id": "1",
"updated_at": "2017-10-14 15:46:03",
"created_at": "2017-10-14 15:46:03",
"id": "1",
"item_type": "Product",
"order_row_digital_content_key":
{
"id": "1",
"order_row_id": "1",
"drm_type_id": "1",
"download_key": "6593648b3e697bb9b6785bf3c3efa05535a592c1",
"purchase_type": "Purchase",
"created_at": "2017-10-14 15:46:03",
"updated_at": "2017-10-14 15:46:03"
}
}
],
"order_statuses": [
{
"message": "Order created",
"status": "Accepted",
"order_id": "1",
"updated_at": "2017-10-14 15:46:03",
"created_at": "2017-10-14 15:46:03",
"id": "1"
}
]
}
]Multiple Ebook purchase as Intermediator
When placing an intermediary order, where the end consumer will be stated as the purchaser, the end consumer (or customer) can be sent in the payload as a separate object.
When using this functionality the client_id points to the customer in Publit (and not the retailer), therefore it is best practice to omit the client_id for this kind of orders and instead only provide the client-object.
The intermediator_account_id is obligatory when placing an intermediary type order and the intermediator_account_id points to the account making the actual purchase.
Request:
POST ../trade/v2.0/orders
The request could also be sent to: POST ../trade/v2.0/order_preview
Payload data structure
{
"client_type":"Customer",
"intermediator_account_id":1, // This is the retailer account id (the authenticated account)
"client_order_reference":"customerref:1234",
"intermediator_order_reference":"ref:1234",
"client":{
"email":"anders@test.com",
"name":"Anders",
"lastname":"Andersson",
"country_id":216
},
"items":[
{
"item_isbn":"978xxxxxxxxx1",
"amount":"1",
"item_type":"Product"
},
{
"item_isbn":"978xxxxxxxxx2",
"amount":"1",
"item_type":"Product"
}
]
}Response
[
{
"contractor_id": "1",
"client_type": "Customer",
"client_id": "1",
"client_order_reference": "customerref:1234",
"intermediator_id": "1",
"intermediator_order_reference": "ref:1234",
"delivery_message": null,
"order_currency_id": "131",
"status": "Accepted",
"invoice_id": "1",
"updated_at": "2017-10-15 09:05:58",
"created_at": "2017-10-15 09:05:58",
"id": "1",
"order_rows": [
{
"order_row_type_id": "2",
"item_id": "1",
"amount": "1",
"price_per_unit_ex_vat": "100.000000", "vat_per_unit": "25.000000",
"total_inc_vat": "125.000000",
"vat_rate": "0.2500",
"currency_id": "131",
"order_row_description": "The Book title : Sbutitle : 978xxxxxxxxx1",
"raw_unit_price": "100.000000",
"publisher_retailer_discount": "0.00",
"order_row_message": null,
"order_id": "1",
"updated_at": "2017-10-15 09:05:59",
"created_at": "2017-10-15 09:05:59",
"id": "1",
"item_type": "Product",
"order_row_digital_content_key": {
"id": "1",
"order_row_id": "1",
"drm_type_id": "1",
"download_key": "e0258a8141e536ffdde056901ac2af614715e109",
"purchase_type": "Purchase"
}
},
{
"order_row_type_id": "2",
"item_id": "2",
"amount": "1",
"price_per_unit_ex_vat": "108.000000",
"vat_per_unit": "27.000000",
"total_inc_vat": "135.000000",
"vat_rate": "0.2500",
"currency_id": "131",
"order_row_description": "The Book title 2 : Subtitle : 978xxxxxxxxx2",
"raw_unit_price": "108.000000",
"publisher_retailer_discount": "0.00",
"order_row_message": null,
"order_id": "1",
"updated_at": "2017-10-15 09:05:59",
"created_at": "2017-10-15 09:05:59",
"id": "2",
"item_type": "Product",
"order_row_digital_content_key": {
"id": "2",
"order_row_id": "2",
"drm_type_id": "1",
"download_key": "546ed78f9b0d269715dcc523ce9ca974e11830ea",
"purchase_type": "Purchase",
"created_at": "2017-10-15 09:05:59",
"updated_at": "2017-10-15 09:05:59"
}
}
],
"order_statuses": [
{
"message": "Order created",
"status": "Accepted",
"order_id": "1",
"updated_at": "2017-10-15 09:05:59",
"created_at": "2017-10-15 09:05:59",
"id": "1"
}
]
}
]IndexGET/trade/v2.0/orders
Example URI
GET /trade/v2.0/orders
Response
200Returned if request was successful.
Headers
Content-Type: application/jsonBody
{
"id": "1",
"data": [
{
"id": "1",
"contractor_id": "1",
"invoice_id": "1",
"client_id": "1",
"client_type": "RetailerAccount",
"client_order_reference": "abc123",
"intermediator_id": "1",
"intermediator_order_reference": "123abc",
"delivery_message": "Some message",
"order_currency_id": "1",
"status": "Accepted",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"order_statuses": [
{
"id": "1",
"order_id": "1",
"status": "Accepted",
"message": "order created",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
],
"order_rows": [
{
"id": "1",
"order_id": "1",
"order_row_type_id": "1",
"item_id": "1",
"amount": "2",
"order_row_description": "My Book : My subtitle : 9781234567891",
"price_per_unit_ex_vat": "100.0000",
"vat_per_unit": "25.0000",
"total_inc_vat": "250.0000",
"vat_rate": "0.2500",
"currency_id": "1",
"publisher_retailer_discount": "0.00",
"raw_unit_price": "100.0000",
"order_row_message": "null",
"format": "Epub",
"item_type": "Product",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"order_row_digital_content_key": {
"id": "1",
"order_row_id": "1",
"drm_type_id": "1",
"download_key": "<hash>",
"purchase_type": "Purchase",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"drm_type": {
"id": "1",
"name": "Social"
}
}
}
],
"invoice": {
"id": "1",
"contractor_id": "1",
"client_id": "1",
"client_type": "RetailerAccount",
"invoice_date": "2017-08-31 23:59:59",
"pay_date": "2017-09-20 00:00:00",
"total_inc_vat": "250.0000",
"total_inc_vat_printable": "250.0000",
"rounding": "0",
"currency_id": "1",
"payment_provider_id": "1",
"invoice_email_address": "some@mail.com",
"invoice_address_firstname": "Anders",
"invoice_address_lastname": "Andersson",
"invoice_address_street": "Street 1",
"invoice_address_city": "City",
"invoice_address_zip": "123 45",
"invoice_address_country_id": "216",
"message": "some message",
"is_addable": "True",
"invoice_status": "Accepted",
"invoice_download_key": "<hash>",
"invoice_number": "123455",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"data": {
"type": "array",
"description": "List of orders"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
403Returned if retailer type is proxy.
Headers
Content-Type: text/html; charset=UTF-8Body
Forbidden.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/orders/{order_id}
Example URI
GET /trade/v2.0/orders/1234
URI Parameters
- order_id
number(required) Example: 1234Id of the requested order
Response
200Returned if request was successful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"contractor_id": "1",
"invoice_id": "1",
"client_id": "1",
"client_type": "RetailerAccount",
"client_order_reference": "abc123",
"intermediator_id": "1",
"intermediator_order_reference": "123abc",
"delivery_message": "Some message",
"order_currency_id": "1",
"status": "Accepted",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"order_statuses": [
{
"id": "1",
"order_id": "1",
"status": "Accepted",
"message": "order created",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
],
"order_rows": [
{
"id": "1",
"order_id": "1",
"order_row_type_id": "1",
"item_id": "1",
"amount": "2",
"order_row_description": "My Book : My subtitle : 9781234567891",
"price_per_unit_ex_vat": "100.0000",
"vat_per_unit": "25.0000",
"total_inc_vat": "250.0000",
"vat_rate": "0.2500",
"currency_id": "1",
"publisher_retailer_discount": "0.00",
"raw_unit_price": "100.0000",
"order_row_message": "null",
"format": "Epub",
"item_type": "Product",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"order_row_digital_content_key": {
"id": "1",
"order_row_id": "1",
"drm_type_id": "1",
"download_key": "<hash>",
"purchase_type": "Purchase",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"drm_type": {
"id": "1",
"name": "Social"
}
}
}
],
"invoice": {
"id": "1",
"contractor_id": "1",
"client_id": "1",
"client_type": "RetailerAccount",
"invoice_date": "2017-08-31 23:59:59",
"pay_date": "2017-09-20 00:00:00",
"total_inc_vat": "250.0000",
"total_inc_vat_printable": "250.0000",
"rounding": "0",
"currency_id": "1",
"payment_provider_id": "1",
"invoice_email_address": "some@mail.com",
"invoice_address_firstname": "Anders",
"invoice_address_lastname": "Andersson",
"invoice_address_street": "Street 1",
"invoice_address_city": "City",
"invoice_address_zip": "123 45",
"invoice_address_country_id": "216",
"message": "some message",
"is_addable": "True",
"invoice_status": "Accepted",
"invoice_download_key": "<hash>",
"invoice_number": "123455",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"contractor_id": {
"type": "string",
"description": "The contractor id"
},
"invoice_id": {
"type": "string",
"description": "The invoice id"
},
"client_id": {
"type": "string",
"description": "The id of the client (defined by the `client_type`)"
},
"client_type": {
"type": "string",
"enum": [
"RetailerAccount",
"Customer"
],
"description": "The type of client"
},
"client_order_reference": {
"type": "string",
"description": "The clients order reference"
},
"intermediator_id": {
"type": "string",
"description": "The id of the intermediator"
},
"intermediator_order_reference": {
"type": "string",
"description": "The intermediator order reference"
},
"delivery_message": {
"type": "string",
"description": "A delivery message that should be written on the parcel on delivery of physical books"
},
"order_currency_id": {
"type": "string",
"description": "Currency of the order"
},
"status": {
"type": "string",
"enum": [
"Accepted",
"Pending",
"Cancelled"
],
"description": "Status of the order"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
},
"order_statuses": {
"type": "array",
"description": "List of order statuses (Note: this does not convey print order statuses such as `Sent`)"
},
"order_rows": {
"type": "array",
"description": "List of related order rows"
},
"invoice": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"contractor_id": {
"type": "string",
"description": "The contractor id"
},
"client_id": {
"type": "string",
"description": "The client id (client is defined by client type)"
},
"client_type": {
"type": "string",
"enum": [
"RetailerAccount"
],
"description": "The client type"
},
"invoice_date": {
"type": "string",
"description": "The invoice timestamp"
},
"pay_date": {
"type": "string",
"description": "Invoice due timestamp"
},
"total_inc_vat": {
"type": "string",
"description": "The invoice total (Note: the invoice may be available before it has been sent, but the invoice totals will be recalculated when sent to assure the correct sums)"
},
"total_inc_vat_printable": {
"type": "string",
"description": "Rounded total"
},
"rounding": {
"type": "string",
"description": "The rounding of the invoice total"
},
"currency_id": {
"type": "string",
"description": "Proprietary currency id of the invoice"
},
"payment_provider_id": {
"type": "string",
"description": "Proprietary payment provider id"
},
"invoice_email_address": {
"type": "string",
"description": "The email to where the invoice is sent"
},
"invoice_address_firstname": {
"type": "string",
"description": "Firstname of recipient"
},
"invoice_address_lastname": {
"type": "string",
"description": "Lastname of recipient"
},
"invoice_address_street": {
"type": "string",
"description": "Invoice address street"
},
"invoice_address_city": {
"type": "string",
"description": "Invoice address city"
},
"invoice_address_zip": {
"type": "string",
"description": "Invoice address zip code"
},
"invoice_address_country_id": {
"type": "string",
"description": "Invoice address country id (proprietary country id)"
},
"message": {
"type": "string",
"description": "Invoice message"
},
"is_addable": {
"type": "string",
"enum": [
"True",
"False"
],
"description": "Indicates if invoice can be open for aggregating multiple orders"
},
"invoice_status": {
"type": "string",
"enum": [
"Accepted",
"Cancelled",
"Pending",
"Error"
],
"description": "Status of the invoice"
},
"invoice_download_key": {
"type": "string",
"description": "Download key of invoice. Use to download invoice"
},
"invoice_number": {
"type": "string",
"description": "The invoice number of the invoice (Note: the invoice number will be bound to the invoice once the invoice date has passed and is null otherwise)"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
}
},
"description": "Related Invoice"
}
}
}Response
404Returned if account order id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
403Returned if retailer type is proxy.
Headers
Content-Type: text/html; charset=UTF-8Body
Forbidden.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}StorePOST/trade/v2.0/orders
Example URI
POST /trade/v2.0/orders
Request
Headers
Content-Type: application/jsonBody
{
"client_type": "RetailerAccount",
"client_id": 1,
"intermediator_account_id": 1,
"client_order_reference": "abc123",
"intermediator_order_reference": "123abc",
"order_delivery_phone_number": "123456",
"delivery_address": {
"firstname": "Anders",
"lastname": "Andersson",
"street": "Street 1",
"city": "City",
"zip": "123 45",
"country_id": "1",
"company_name": "My company"
},
"client": {
"name": "Anders",
"lastname": "Andersson",
"email": "customer@mail.com",
"country_id": 1,
"customer_address": {
"firstname": "Anders",
"lastname": "Andersson",
"street": "Street 1",
"city": "City",
"zip": "123 45",
"country_id": "1",
"company_name": "My company"
}
},
"items": [
{
"item_id": 1,
"item_isbn": "9781234567891",
"item_type": "Product",
"amount": 1
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"client_type": {
"type": "string",
"enum": [
"RetailerAccount",
"Customer"
],
"description": "The client type of the order"
},
"client_id": {
"type": "number",
"description": "Id of the client performing the purchase. Either proprietary customer_id (if type is Customer) or proprietary account_id (if type is RetailerAccount). Required if type is RetailerAccount andif type is Customer but the customer is not sent through the customer struct."
},
"intermediator_account_id": {
"type": "number",
"description": "Intermediator account id (Publit retailer id), required if client_type is set to Customer"
},
"client_order_reference": {
"type": "string",
"description": "Client order reference"
},
"intermediator_order_reference": {
"type": "string",
"description": "Intermediator order reference"
},
"order_delivery_phone_number": {
"type": "string",
"description": "Phone number for delivery messaging (applicable for printed books)"
},
"delivery_address": {
"type": "object",
"properties": {
"firstname": {
"type": "string",
"description": "First name of recipient"
},
"lastname": {
"type": "string",
"description": "Last name of recipient"
},
"street": {
"type": "string",
"description": "Street address of recipient"
},
"city": {
"type": "string",
"description": "City address of recipient"
},
"zip": {
"type": "string",
"description": "Delivery address zip code"
},
"country_id": {
"type": "string",
"description": "Proprietary country id"
},
"company_name": {
"type": "string",
"description": "Company name of recipient"
}
},
"required": [
"firstname",
"street",
"city",
"zip",
"country_id"
],
"description": "Delivery address, if different from the accounts (applicable for printed books)"
},
"client": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of customer"
},
"lastname": {
"type": "string",
"description": "Last name of customer"
},
"email": {
"type": "string",
"description": "Customer email address"
},
"country_id": {
"type": "number",
"description": "Proprietary country id of customer"
},
"customer_address": {
"type": "object",
"properties": {
"firstname": {
"type": "string",
"description": "First name of recipient"
},
"lastname": {
"type": "string",
"description": "Last name of recipient"
},
"street": {
"type": "string",
"description": "Street address of recipient"
},
"city": {
"type": "string",
"description": "City address of recipient"
},
"zip": {
"type": "string",
"description": "Delivery address zip code"
},
"country_id": {
"type": "string",
"description": "Proprietary country id"
},
"company_name": {
"type": "string",
"description": "Company name of recipient"
}
},
"required": [
"firstname",
"street",
"city",
"zip",
"country_id"
],
"description": "Delivery address of customer"
}
},
"required": [
"name",
"email",
"country_id",
"customer_address"
],
"description": "Customer struct data"
},
"items": {
"type": "array",
"description": "Items to order"
}
},
"required": [
"client_type",
"client_id"
]
}Response
200Headers
Content-Type: application/jsonBody
[
{
"id": "1",
"contractor_id": "1",
"invoice_id": "1",
"client_id": "1",
"client_type": "RetailerAccount",
"client_order_reference": "abc123",
"intermediator_id": "1",
"intermediator_order_reference": "123abc",
"delivery_message": "Some message",
"order_currency_id": "1",
"status": "Accepted",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"order_statuses": [
{
"id": "1",
"order_id": "1",
"status": "Accepted",
"message": "order created",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
],
"order_rows": [
{
"id": "1",
"order_id": "1",
"order_row_type_id": "1",
"item_id": "1",
"amount": "2",
"order_row_description": "My Book : My subtitle : 9781234567891",
"price_per_unit_ex_vat": "100.0000",
"vat_per_unit": "25.0000",
"total_inc_vat": "250.0000",
"vat_rate": "0.2500",
"currency_id": "1",
"publisher_retailer_discount": "0.00",
"raw_unit_price": "100.0000",
"order_row_message": "null",
"format": "Epub",
"item_type": "Product",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"order_row_digital_content_key": {
"id": "1",
"order_row_id": "1",
"drm_type_id": "1",
"download_key": "<hash>",
"purchase_type": "Purchase",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"drm_type": {
"id": "1",
"name": "Social"
}
}
}
],
"invoice": {
"id": "1",
"contractor_id": "1",
"client_id": "1",
"client_type": "RetailerAccount",
"invoice_date": "2017-08-31 23:59:59",
"pay_date": "2017-09-20 00:00:00",
"total_inc_vat": "250.0000",
"total_inc_vat_printable": "250.0000",
"rounding": "0",
"currency_id": "1",
"payment_provider_id": "1",
"invoice_email_address": "some@mail.com",
"invoice_address_firstname": "Anders",
"invoice_address_lastname": "Andersson",
"invoice_address_street": "Street 1",
"invoice_address_city": "City",
"invoice_address_zip": "123 45",
"invoice_address_country_id": "216",
"message": "some message",
"is_addable": "True",
"invoice_status": "Accepted",
"invoice_download_key": "<hash>",
"invoice_number": "123455",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
}
]Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}Response
400Returned if request malformed or faulty.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
403Returned if retailer type is proxy.
Headers
Content-Type: text/html; charset=UTF-8Body
Forbidden.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Order Preview ¶
The order preview is a helper method to post an order request to the Publit without actually creating it.
This can be used to ascertain the total cost of the order and available payment providers before attempting to place it.
The resource uses the same data structures as the Orders resource, and the same calculation path but does not actually create the order.
Order PreviewPOST/trade/v2.0/order_preview
Example URI
POST /trade/v2.0/order_preview
Request
Headers
Content-Type: application/jsonBody
{
"client_type": "RetailerAccount",
"client_id": 1,
"intermediator_account_id": 1,
"client_order_reference": "abc123",
"intermediator_order_reference": "123abc",
"order_delivery_phone_number": "123456",
"delivery_address": {
"firstname": "Anders",
"lastname": "Andersson",
"street": "Street 1",
"city": "City",
"zip": "123 45",
"country_id": "1",
"company_name": "My company"
},
"client": {
"name": "Anders",
"lastname": "Andersson",
"email": "customer@mail.com",
"country_id": 1,
"customer_address": {
"firstname": "Anders",
"lastname": "Andersson",
"street": "Street 1",
"city": "City",
"zip": "123 45",
"country_id": "1",
"company_name": "My company"
}
},
"items": [
{
"item_id": 1,
"item_isbn": "9781234567891",
"item_type": "Product",
"amount": 1
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"client_type": {
"type": "string",
"enum": [
"RetailerAccount",
"Customer"
],
"description": "The client type of the order"
},
"client_id": {
"type": "number",
"description": "Id of the client performing the purchase. Either proprietary customer_id (if type is Customer) or proprietary account_id (if type is RetailerAccount). Required if type is RetailerAccount andif type is Customer but the customer is not sent through the customer struct."
},
"intermediator_account_id": {
"type": "number",
"description": "Intermediator account id (Publit retailer id), required if client_type is set to Customer"
},
"client_order_reference": {
"type": "string",
"description": "Client order reference"
},
"intermediator_order_reference": {
"type": "string",
"description": "Intermediator order reference"
},
"order_delivery_phone_number": {
"type": "string",
"description": "Phone number for delivery messaging (applicable for printed books)"
},
"delivery_address": {
"type": "object",
"properties": {
"firstname": {
"type": "string",
"description": "First name of recipient"
},
"lastname": {
"type": "string",
"description": "Last name of recipient"
},
"street": {
"type": "string",
"description": "Street address of recipient"
},
"city": {
"type": "string",
"description": "City address of recipient"
},
"zip": {
"type": "string",
"description": "Delivery address zip code"
},
"country_id": {
"type": "string",
"description": "Proprietary country id"
},
"company_name": {
"type": "string",
"description": "Company name of recipient"
}
},
"required": [
"firstname",
"street",
"city",
"zip",
"country_id"
],
"description": "Delivery address, if different from the accounts (applicable for printed books)"
},
"client": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of customer"
},
"lastname": {
"type": "string",
"description": "Last name of customer"
},
"email": {
"type": "string",
"description": "Customer email address"
},
"country_id": {
"type": "number",
"description": "Proprietary country id of customer"
},
"customer_address": {
"type": "object",
"properties": {
"firstname": {
"type": "string",
"description": "First name of recipient"
},
"lastname": {
"type": "string",
"description": "Last name of recipient"
},
"street": {
"type": "string",
"description": "Street address of recipient"
},
"city": {
"type": "string",
"description": "City address of recipient"
},
"zip": {
"type": "string",
"description": "Delivery address zip code"
},
"country_id": {
"type": "string",
"description": "Proprietary country id"
},
"company_name": {
"type": "string",
"description": "Company name of recipient"
}
},
"required": [
"firstname",
"street",
"city",
"zip",
"country_id"
],
"description": "Delivery address of customer"
}
},
"required": [
"name",
"email",
"country_id",
"customer_address"
],
"description": "Customer struct data"
},
"items": {
"type": "array",
"description": "Items to order"
}
},
"required": [
"client_type",
"client_id"
]
}Response
200Headers
Content-Type: application/jsonBody
[
{
"id": "1",
"contractor_id": "1",
"invoice_id": "1",
"client_id": "1",
"client_type": "RetailerAccount",
"client_order_reference": "abc123",
"intermediator_id": "1",
"intermediator_order_reference": "123abc",
"delivery_message": "Some message",
"order_currency_id": "1",
"status": "Accepted",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"order_statuses": [
{
"id": "1",
"order_id": "1",
"status": "Accepted",
"message": "order created",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
],
"order_rows": [
{
"id": "1",
"order_id": "1",
"order_row_type_id": "1",
"item_id": "1",
"amount": "2",
"order_row_description": "My Book : My subtitle : 9781234567891",
"price_per_unit_ex_vat": "100.0000",
"vat_per_unit": "25.0000",
"total_inc_vat": "250.0000",
"vat_rate": "0.2500",
"currency_id": "1",
"publisher_retailer_discount": "0.00",
"raw_unit_price": "100.0000",
"order_row_message": "null",
"format": "Epub",
"item_type": "Product",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"order_row_digital_content_key": {
"id": "1",
"order_row_id": "1",
"drm_type_id": "1",
"download_key": "<hash>",
"purchase_type": "Purchase",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"drm_type": {
"id": "1",
"name": "Social"
}
}
}
],
"invoice": {
"id": "1",
"contractor_id": "1",
"client_id": "1",
"client_type": "RetailerAccount",
"invoice_date": "2017-08-31 23:59:59",
"pay_date": "2017-09-20 00:00:00",
"total_inc_vat": "250.0000",
"total_inc_vat_printable": "250.0000",
"rounding": "0",
"currency_id": "1",
"payment_provider_id": "1",
"invoice_email_address": "some@mail.com",
"invoice_address_firstname": "Anders",
"invoice_address_lastname": "Andersson",
"invoice_address_street": "Street 1",
"invoice_address_city": "City",
"invoice_address_zip": "123 45",
"invoice_address_country_id": "216",
"message": "some message",
"is_addable": "True",
"invoice_status": "Accepted",
"invoice_download_key": "<hash>",
"invoice_number": "123455",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
}
]Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}Response
400Returned if request malformed or faulty.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
403Returned if retailer type is proxy.
Headers
Content-Type: text/html; charset=UTF-8Body
Forbidden.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Order download ¶
The order download resource downloads any digital format books purchased.
Example
Example for downloading an epub file through CURL:
$ curl -u "username;account_id:password" -o file.epub https://api.publit.com/v2.0/order/{order_id}/download/{download_key}DownloadGET/v2.0/order/{order_id}/download/{download_key}
Example URI
GET /v2.0/order/1234/download/
URI Parameters
- order_id
number(required) Example: 1234Id of the order the pruchased book belongs to
- download_key
number(required) Example: <download hash>The download key (hash as received from the
order_row_digital_content_keyobject - see the Orders resource)
Response
200Body
Returned if request was succesful, together with a file. The mime-type depends on the file that is downloaded.Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Sales And Settlements ¶
The Sales and Settlements resources are resources intended for reporting consumption (Sales) and for reporting Settlements (actual revenue value that will be paid). These resources are only available for retailers that don’t perform transactions directly in Publit via the Orders resource.
Sales ¶
The sales resource can be used to list and report sales/consumption of books fetched from Publit.
A sales row consists of a product, the total revenue the product has brought in and the total quantity sold during the sales period defined by start_date and end_date.
The sales resource is viewed as an aggregated sales list for a certain period of a time.
As this is merely for consumption reporting purposes the revenue can be omitted if it can not be calculated at the time of reporting. The quantity can be reported as a fixed float (8,2), meaning that partial consumptions of books can also be reported (eg: 0.50 means half of a consumption).
A sales row is unique for the time period and ISBN.
IndexGET/trade/v2.0/sales
Example URI
GET /trade/v2.0/sales
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1",
"retailer_id": "1",
"currency": "SEK",
"product_id": "1",
"business_model_id": "1",
"isbn": "9781234567890",
"amount": "1.5",
"revenue": "200.00",
"start_date": "2017-01-01 00:00:00",
"end_date": "2017-03-31 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array",
"description": "List of sales"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/sales/{sales_id}
Example URI
GET /trade/v2.0/sales/1
URI Parameters
- sales_id
number(required) Example: 1Id of the requested sales row
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"retailer_id": "1",
"currency": "SEK",
"product_id": "1",
"business_model_id": "1",
"isbn": "9781234567890",
"amount": "1.5",
"revenue": "200.00",
"start_date": "2017-01-01 00:00:00",
"end_date": "2017-03-31 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"retailer_id": {
"type": "string",
"description": "Retailer account id"
},
"currency": {
"type": "string",
"description": "ISO code of currency used for sale"
},
"product_id": {
"type": "string",
"description": "Id of product sold"
},
"business_model_id": {
"type": "string",
"description": "Id of business model"
},
"isbn": {
"type": "string",
"description": "ISBN of product sold"
},
"amount": {
"type": "string",
"description": "Quantity of sold products (for indicated time period). Fixed float (8,2)"
},
"revenue": {
"type": "string",
"description": "Revenue of sold products (whole revenue of row). Fixed float (10,2)"
},
"start_date": {
"type": "string",
"description": "Start date (timestamp) of reported sales period"
},
"end_date": {
"type": "string",
"description": "End date (tmestamp) of reported sales period"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
}
},
"required": [
"currency",
"isbn",
"amount",
"revenue",
"start_date",
"end_date"
]
}Response
404Returned if sales_id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}StorePOST/trade/v2.0/sales
Example URI
POST /trade/v2.0/sales
Request
Headers
Content-Type: application/jsonBody
{
"id": "1",
"retailer_id": "1",
"currency": "SEK",
"product_id": "1",
"business_model_id": "1",
"isbn": "9781234567890",
"amount": "1.5",
"revenue": "200.00",
"start_date": "2017-01-01 00:00:00",
"end_date": "2017-03-31 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"retailer_id": {
"type": "string",
"description": "Retailer account id"
},
"currency": {
"type": "string",
"description": "ISO code of currency used for sale"
},
"product_id": {
"type": "string",
"description": "Id of product sold"
},
"business_model_id": {
"type": "string",
"description": "Id of business model"
},
"isbn": {
"type": "string",
"description": "ISBN of product sold"
},
"amount": {
"type": "string",
"description": "Quantity of sold products (for indicated time period). Fixed float (8,2)"
},
"revenue": {
"type": "string",
"description": "Revenue of sold products (whole revenue of row). Fixed float (10,2)"
},
"start_date": {
"type": "string",
"description": "Start date (timestamp) of reported sales period"
},
"end_date": {
"type": "string",
"description": "End date (tmestamp) of reported sales period"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
}
},
"required": [
"currency",
"isbn",
"amount",
"revenue",
"start_date",
"end_date"
]
}Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
[
{
"id": "1",
"retailer_id": "1",
"currency": "SEK",
"product_id": "1",
"business_model_id": "1",
"isbn": "9781234567890",
"amount": "1.5",
"revenue": "200.00",
"start_date": "2017-01-01 00:00:00",
"end_date": "2017-03-31 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
]Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}Response
400Returned if request malformed or faulty.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
409Returned if a sales row for the specific ISBN and time period already exists
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Settlements ¶
The settlements resource can be used to report aggregated settlement data for a certain period.
The reported rows will be used by Publit as basis for invoicing the Retailer.
A settlements row consists of a product (via ISBN), the total revenue the product has brought in and the total quantity sold during the sales period defined by start_date and end_date.
The quantity can be reported as a fixed float (8,2), meaning that partial consumptions of books can also be reported (eg: 0.50 means half of a consumption).
A settlements row can also have the attributes retailer_reference and retailer_row_reference. These attributes can be used to match rows in the Publit system to the retailer system.
The retailer_reference is the reference Publit will use when sending the invoice - this is basically a means to match a Publit invoice to the retailers own payment reference.
The retailer_row_reference is a unique reference that can be set per reported row. This can be used by the Retailer to match certain reported settlement rows in the Publit system to their own system.
Immutability
A settlement row can only be altered during a specified time period after it has been sent (the period will be agreed upon by the Retailer and Publit). After which it will be “locked” and immutable. The time period is intended for double checking that the reported settlements are correct before Publit can invoice the Retailer.
In order to be able to create an invoice Publit will lock the settlements data shortly before invoicing. Any faults in the data that is found after this can be adjusted in the next reporting period.
IndexGET/trade/v2.0/settlements
Example URI
GET /trade/v2.0/settlements
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1",
"retailer_id": "1",
"retailer_reference": "abc",
"retailer_row_reference": "bcd",
"currency": "SEK",
"business_model_id": "1",
"isbn": "9781234567890",
"amount": "1.5",
"revenue": "200.00",
"start_date": "2016-12-01 00:00:00",
"end_date": "2016-12-31 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array",
"description": "List of settlements"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/settlements/{settlement_id}
Example URI
GET /trade/v2.0/settlements/1
URI Parameters
- settlement_id
number(required) Example: 1Id of the requested settlement row
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"retailer_id": "1",
"retailer_reference": "abc",
"retailer_row_reference": "bcd",
"currency": "SEK",
"business_model_id": "1",
"isbn": "9781234567890",
"amount": "1.5",
"revenue": "200.00",
"start_date": "2016-12-01 00:00:00",
"end_date": "2016-12-31 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"retailer_id": {
"type": "string",
"description": "Retailer account id"
},
"retailer_reference": {
"type": "string",
"description": "123 (string) - Retailer settlement reference"
},
"retailer_row_reference": {
"type": "string",
"description": "234 (string) - Retailer settlement row reference"
},
"currency": {
"type": "string",
"description": "ISO code of currency used for sale"
},
"business_model_id": {
"type": "string",
"description": "Id of business model"
},
"isbn": {
"type": "string",
"description": "ISBN of product sold"
},
"amount": {
"type": "string",
"description": "Quantity of sold products (for indicated time period). Fixed float (8,2)"
},
"revenue": {
"type": "string",
"description": "Revenue of sold products (whole revenue of row). Fixed float (10,2)"
},
"start_date": {
"type": "string",
"description": "Start date (timestamp) of reported sales period"
},
"end_date": {
"type": "string",
"description": "End date (tmestamp) of reported sales period"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
}
},
"required": [
"currency",
"isbn",
"amount",
"revenue",
"start_date",
"end_date"
]
}Response
404Returned if settlement_id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}StorePOST/trade/v2.0/settlements
Example URI
POST /trade/v2.0/settlements
Request
Headers
Content-Type: application/jsonBody
{
"id": "1",
"retailer_id": "1",
"retailer_reference": "abc",
"retailer_row_reference": "bcd",
"currency": "SEK",
"business_model_id": "1",
"isbn": "9781234567890",
"amount": "1.5",
"revenue": "200.00",
"start_date": "2016-12-01 00:00:00",
"end_date": "2016-12-31 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"retailer_id": {
"type": "string",
"description": "Retailer account id"
},
"retailer_reference": {
"type": "string",
"description": "123 (string) - Retailer settlement reference"
},
"retailer_row_reference": {
"type": "string",
"description": "234 (string) - Retailer settlement row reference"
},
"currency": {
"type": "string",
"description": "ISO code of currency used for sale"
},
"business_model_id": {
"type": "string",
"description": "Id of business model"
},
"isbn": {
"type": "string",
"description": "ISBN of product sold"
},
"amount": {
"type": "string",
"description": "Quantity of sold products (for indicated time period). Fixed float (8,2)"
},
"revenue": {
"type": "string",
"description": "Revenue of sold products (whole revenue of row). Fixed float (10,2)"
},
"start_date": {
"type": "string",
"description": "Start date (timestamp) of reported sales period"
},
"end_date": {
"type": "string",
"description": "End date (tmestamp) of reported sales period"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
}
},
"required": [
"currency",
"isbn",
"amount",
"revenue",
"start_date",
"end_date"
]
}Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
[
{
"id": "1",
"retailer_id": "1",
"retailer_reference": "abc",
"retailer_row_reference": "bcd",
"currency": "SEK",
"business_model_id": "1",
"isbn": "9781234567890",
"amount": "1.5",
"revenue": "200.00",
"start_date": "2016-12-01 00:00:00",
"end_date": "2016-12-31 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
]Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}Response
400Returned if request malformed or faulty.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}UpdatePUT/trade/v2.0/settlements/{settlement_id}
Example URI
PUT /trade/v2.0/settlements/1
URI Parameters
- settlement_id
number(required) Example: 1Id of the requested settlement row
Request
Headers
Content-Type: application/jsonBody
{
"id": "1",
"retailer_id": "1",
"retailer_reference": "abc",
"retailer_row_reference": "bcd",
"currency": "SEK",
"business_model_id": "1",
"isbn": "9781234567890",
"amount": "1.5",
"revenue": "200.00",
"start_date": "2016-12-01 00:00:00",
"end_date": "2016-12-31 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"retailer_id": {
"type": "string",
"description": "Retailer account id"
},
"retailer_reference": {
"type": "string",
"description": "123 (string) - Retailer settlement reference"
},
"retailer_row_reference": {
"type": "string",
"description": "234 (string) - Retailer settlement row reference"
},
"currency": {
"type": "string",
"description": "ISO code of currency used for sale"
},
"business_model_id": {
"type": "string",
"description": "Id of business model"
},
"isbn": {
"type": "string",
"description": "ISBN of product sold"
},
"amount": {
"type": "string",
"description": "Quantity of sold products (for indicated time period). Fixed float (8,2)"
},
"revenue": {
"type": "string",
"description": "Revenue of sold products (whole revenue of row). Fixed float (10,2)"
},
"start_date": {
"type": "string",
"description": "Start date (timestamp) of reported sales period"
},
"end_date": {
"type": "string",
"description": "End date (tmestamp) of reported sales period"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
}
},
"required": [
"currency",
"isbn",
"amount",
"revenue",
"start_date",
"end_date"
]
}Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
[
{
"id": "1",
"retailer_id": "1",
"retailer_reference": "abc",
"retailer_row_reference": "bcd",
"currency": "SEK",
"business_model_id": "1",
"isbn": "9781234567890",
"amount": "1.5",
"revenue": "200.00",
"start_date": "2016-12-01 00:00:00",
"end_date": "2016-12-31 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
]Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}Response
400Returned if request malformed or faulty.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
403Returned if the settlements row has become immutable.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
404Returned if settlement_id is not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}DeleteDELETE/trade/v2.0/settlements/{settlement_id}
Example URI
DELETE /trade/v2.0/settlements/1
URI Parameters
- settlement_id
number(required) Example: 1Id of the settlement row to delete
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"retailer_id": "1",
"retailer_reference": "abc",
"retailer_row_reference": "bcd",
"currency": "SEK",
"business_model_id": "1",
"isbn": "9781234567890",
"amount": "1.5",
"revenue": "200.00",
"start_date": "2016-12-01 00:00:00",
"end_date": "2016-12-31 23:59:59",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"retailer_id": {
"type": "string",
"description": "Retailer account id"
},
"retailer_reference": {
"type": "string",
"description": "123 (string) - Retailer settlement reference"
},
"retailer_row_reference": {
"type": "string",
"description": "234 (string) - Retailer settlement row reference"
},
"currency": {
"type": "string",
"description": "ISO code of currency used for sale"
},
"business_model_id": {
"type": "string",
"description": "Id of business model"
},
"isbn": {
"type": "string",
"description": "ISBN of product sold"
},
"amount": {
"type": "string",
"description": "Quantity of sold products (for indicated time period). Fixed float (8,2)"
},
"revenue": {
"type": "string",
"description": "Revenue of sold products (whole revenue of row). Fixed float (10,2)"
},
"start_date": {
"type": "string",
"description": "Start date (timestamp) of reported sales period"
},
"end_date": {
"type": "string",
"description": "End date (tmestamp) of reported sales period"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
}
},
"required": [
"currency",
"isbn",
"amount",
"revenue",
"start_date",
"end_date"
]
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
403Returned if the settlements row has become immutable.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
404Returned if settlement_id is not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Accounts ¶
Accounts ¶
The accounts resource allows for managing the Retailer accounts that the user is connected to.
IndexGET/trade/v2.0/accounts
Example URI
GET /trade/v2.0/accounts
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1",
"name": "Retailer account name",
"type": "Retailer",
"account_number": "12345",
"contractor_id": "1",
"country_id": "216",
"language_id": "430",
"organisation_type": "Company",
"company_name": "My company AB",
"contact_person_firstname": "Anders",
"contact_person_lastname": "Andersson",
"organisation_number": "123456-7890",
"vat_reg_number": "SE1234567890",
"primary_email": "email@company.com",
"invoice_email": "economy@company.com",
"phone": "12-34567890",
"alternate_phone": "23-45678901",
"profile_image_id": "null",
"active": "True",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"deleted_at": "NULL",
"language": {
"id": "1",
"iso3": "swe",
"iso2": "se",
"native_name": "Svenska",
"name": "Swedish"
},
"country": {
"id": "1",
"name": "Sweden",
"native_name": "Sverige",
"language_id": "1",
"iso2": "SE",
"iso3": "SWE",
"isonum": "752",
"currency_id": "131"
}
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array",
"description": "List of accounts"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/accounts/{account_id}
Example URI
GET /trade/v2.0/accounts/1
URI Parameters
- account_id
number(required) Example: 1Id of the requested account
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"name": "Retailer account name",
"type": "Retailer",
"account_number": "12345",
"contractor_id": "1",
"country_id": "216",
"language_id": "430",
"organisation_type": "Company",
"company_name": "My company AB",
"contact_person_firstname": "Anders",
"contact_person_lastname": "Andersson",
"organisation_number": "123456-7890",
"vat_reg_number": "SE1234567890",
"primary_email": "email@company.com",
"invoice_email": "economy@company.com",
"phone": "12-34567890",
"alternate_phone": "23-45678901",
"profile_image_id": "null",
"active": "True",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"deleted_at": "NULL",
"language": {
"id": "1",
"iso3": "swe",
"iso2": "se",
"native_name": "Svenska",
"name": "Swedish"
},
"country": {
"id": "1",
"name": "Sweden",
"native_name": "Sverige",
"language_id": "1",
"iso2": "SE",
"iso3": "SWE",
"isonum": "752",
"currency_id": "131"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"name": {
"type": "string",
"description": "Name of the account"
},
"type": {
"type": "string",
"enum": [
"Retailer"
],
"description": "Type of account"
},
"account_number": {
"type": "string",
"description": "Proprietary account number"
},
"contractor_id": {
"type": "string",
"description": "Contractor id (the id of the Publit entity connected to the account)"
},
"country_id": {
"type": "string",
"description": "Proprietary country id"
},
"language_id": {
"type": "string",
"description": "Proprietary language id"
},
"organisation_type": {
"type": "string",
"enum": [
"Company",
"Private"
],
"description": "Organisation type"
},
"company_name": {
"type": "string",
"description": "Company name"
},
"contact_person_firstname": {
"type": "string",
"description": "Contact person"
},
"contact_person_lastname": {
"type": "string",
"description": "Contact person"
},
"organisation_number": {
"type": "string",
"description": "Organisation number"
},
"vat_reg_number": {
"type": "string",
"description": "VAT registration number"
},
"primary_email": {
"type": "string",
"description": "Primary contact email address"
},
"invoice_email": {
"type": "string",
"description": "Invoice email address"
},
"phone": {
"type": "string",
"description": "Contact phone number"
},
"alternate_phone": {
"type": "string",
"description": "Alternative contact phone number"
},
"profile_image_id": {
"type": "string",
"description": "Profile image"
},
"active": {
"type": "string",
"enum": [
"True"
],
"description": "Indicates if the retailer account is active for ordering"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
},
"deleted_at": {
"type": "string",
"description": "Resource deleted date. Set automatically. (UTC)"
},
"language": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"iso3": {
"type": "string",
"description": "ISO three letter code of the language"
},
"iso2": {
"type": "string",
"description": "ISO two letter code of the language"
},
"native_name": {
"type": "string",
"description": "Name of the language in the native tongue"
},
"name": {
"type": "string",
"description": "Name of the language in english"
}
},
"description": "Related language"
},
"country": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"name": {
"type": "string",
"description": "Name of country"
},
"native_name": {
"type": "string",
"description": "Name of country in the native language of the country"
},
"language_id": {
"type": "string",
"description": "Proprietary language id of the related language spoken in the country"
},
"iso2": {
"type": "string",
"description": "iso2 (ISO-3166) code of the country"
},
"iso3": {
"type": "string",
"description": "iso3 (ISO-3166) code of the country"
},
"isonum": {
"type": "string",
"description": "numeric iso (ISO-3166) code of the country"
},
"currency_id": {
"type": "string",
"description": "proprietary currency id connected to the country"
}
},
"description": "Related country"
}
}
}Response
404Returned if account order id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}UpdatePUT/trade/v2.0/accounts/{account_id}
Example URI
PUT /trade/v2.0/accounts/1
URI Parameters
- account_id
number(required) Example: 1Id of the account to update
Request
Headers
Content-Type: application/jsonBody
{
"id": "1",
"name": "Retailer account name",
"type": "Retailer",
"account_number": "12345",
"contractor_id": "1",
"country_id": "216",
"language_id": "430",
"organisation_type": "Company",
"company_name": "My company AB",
"contact_person_firstname": "Anders",
"contact_person_lastname": "Andersson",
"organisation_number": "123456-7890",
"vat_reg_number": "SE1234567890",
"primary_email": "email@company.com",
"invoice_email": "economy@company.com",
"phone": "12-34567890",
"alternate_phone": "23-45678901",
"profile_image_id": "null",
"active": "True",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"deleted_at": "NULL",
"language": {
"id": "1",
"iso3": "swe",
"iso2": "se",
"native_name": "Svenska",
"name": "Swedish"
},
"country": {
"id": "1",
"name": "Sweden",
"native_name": "Sverige",
"language_id": "1",
"iso2": "SE",
"iso3": "SWE",
"isonum": "752",
"currency_id": "131"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"name": {
"type": "string",
"description": "Name of the account"
},
"type": {
"type": "string",
"enum": [
"Retailer"
],
"description": "Type of account"
},
"account_number": {
"type": "string",
"description": "Proprietary account number"
},
"contractor_id": {
"type": "string",
"description": "Contractor id (the id of the Publit entity connected to the account)"
},
"country_id": {
"type": "string",
"description": "Proprietary country id"
},
"language_id": {
"type": "string",
"description": "Proprietary language id"
},
"organisation_type": {
"type": "string",
"enum": [
"Company",
"Private"
],
"description": "Organisation type"
},
"company_name": {
"type": "string",
"description": "Company name"
},
"contact_person_firstname": {
"type": "string",
"description": "Contact person"
},
"contact_person_lastname": {
"type": "string",
"description": "Contact person"
},
"organisation_number": {
"type": "string",
"description": "Organisation number"
},
"vat_reg_number": {
"type": "string",
"description": "VAT registration number"
},
"primary_email": {
"type": "string",
"description": "Primary contact email address"
},
"invoice_email": {
"type": "string",
"description": "Invoice email address"
},
"phone": {
"type": "string",
"description": "Contact phone number"
},
"alternate_phone": {
"type": "string",
"description": "Alternative contact phone number"
},
"profile_image_id": {
"type": "string",
"description": "Profile image"
},
"active": {
"type": "string",
"enum": [
"True"
],
"description": "Indicates if the retailer account is active for ordering"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
},
"deleted_at": {
"type": "string",
"description": "Resource deleted date. Set automatically. (UTC)"
},
"language": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"iso3": {
"type": "string",
"description": "ISO three letter code of the language"
},
"iso2": {
"type": "string",
"description": "ISO two letter code of the language"
},
"native_name": {
"type": "string",
"description": "Name of the language in the native tongue"
},
"name": {
"type": "string",
"description": "Name of the language in english"
}
},
"description": "Related language"
},
"country": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"name": {
"type": "string",
"description": "Name of country"
},
"native_name": {
"type": "string",
"description": "Name of country in the native language of the country"
},
"language_id": {
"type": "string",
"description": "Proprietary language id of the related language spoken in the country"
},
"iso2": {
"type": "string",
"description": "iso2 (ISO-3166) code of the country"
},
"iso3": {
"type": "string",
"description": "iso3 (ISO-3166) code of the country"
},
"isonum": {
"type": "string",
"description": "numeric iso (ISO-3166) code of the country"
},
"currency_id": {
"type": "string",
"description": "proprietary currency id connected to the country"
}
},
"description": "Related country"
}
}
}Response
200Headers
Content-Type: application/jsonBody
{
"id": "1",
"name": "Retailer account name",
"type": "Retailer",
"account_number": "12345",
"contractor_id": "1",
"country_id": "216",
"language_id": "430",
"organisation_type": "Company",
"company_name": "My company AB",
"contact_person_firstname": "Anders",
"contact_person_lastname": "Andersson",
"organisation_number": "123456-7890",
"vat_reg_number": "SE1234567890",
"primary_email": "email@company.com",
"invoice_email": "economy@company.com",
"phone": "12-34567890",
"alternate_phone": "23-45678901",
"profile_image_id": "null",
"active": "True",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"deleted_at": "NULL",
"language": {
"id": "1",
"iso3": "swe",
"iso2": "se",
"native_name": "Svenska",
"name": "Swedish"
},
"country": {
"id": "1",
"name": "Sweden",
"native_name": "Sverige",
"language_id": "1",
"iso2": "SE",
"iso3": "SWE",
"isonum": "752",
"currency_id": "131"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"name": {
"type": "string",
"description": "Name of the account"
},
"type": {
"type": "string",
"enum": [
"Retailer"
],
"description": "Type of account"
},
"account_number": {
"type": "string",
"description": "Proprietary account number"
},
"contractor_id": {
"type": "string",
"description": "Contractor id (the id of the Publit entity connected to the account)"
},
"country_id": {
"type": "string",
"description": "Proprietary country id"
},
"language_id": {
"type": "string",
"description": "Proprietary language id"
},
"organisation_type": {
"type": "string",
"enum": [
"Company",
"Private"
],
"description": "Organisation type"
},
"company_name": {
"type": "string",
"description": "Company name"
},
"contact_person_firstname": {
"type": "string",
"description": "Contact person"
},
"contact_person_lastname": {
"type": "string",
"description": "Contact person"
},
"organisation_number": {
"type": "string",
"description": "Organisation number"
},
"vat_reg_number": {
"type": "string",
"description": "VAT registration number"
},
"primary_email": {
"type": "string",
"description": "Primary contact email address"
},
"invoice_email": {
"type": "string",
"description": "Invoice email address"
},
"phone": {
"type": "string",
"description": "Contact phone number"
},
"alternate_phone": {
"type": "string",
"description": "Alternative contact phone number"
},
"profile_image_id": {
"type": "string",
"description": "Profile image"
},
"active": {
"type": "string",
"enum": [
"True"
],
"description": "Indicates if the retailer account is active for ordering"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
},
"deleted_at": {
"type": "string",
"description": "Resource deleted date. Set automatically. (UTC)"
},
"language": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"iso3": {
"type": "string",
"description": "ISO three letter code of the language"
},
"iso2": {
"type": "string",
"description": "ISO two letter code of the language"
},
"native_name": {
"type": "string",
"description": "Name of the language in the native tongue"
},
"name": {
"type": "string",
"description": "Name of the language in english"
}
},
"description": "Related language"
},
"country": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"name": {
"type": "string",
"description": "Name of country"
},
"native_name": {
"type": "string",
"description": "Name of country in the native language of the country"
},
"language_id": {
"type": "string",
"description": "Proprietary language id of the related language spoken in the country"
},
"iso2": {
"type": "string",
"description": "iso2 (ISO-3166) code of the country"
},
"iso3": {
"type": "string",
"description": "iso3 (ISO-3166) code of the country"
},
"isonum": {
"type": "string",
"description": "numeric iso (ISO-3166) code of the country"
},
"currency_id": {
"type": "string",
"description": "proprietary currency id connected to the country"
}
},
"description": "Related country"
}
}
}Response
400Returned if request malformed or faulty.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Retailer Publisher Details ¶
The retailer publisher details list retailer specific details about the connected publishers.
If the retailer needs proprietary information about the publishers, such as retailer proprietary IDs, this is where it is stored. If the retailer does not need any proprietary information this resource may be of little interest.
Usually the retailer publisher details is loaded through relations from the products resource during product ingestion. But this resource can be used to fetch details separately. Can be used to check new connected publishers.
IndexGET/trade/v2.0/retailer_publisher_details
Example URI
GET /trade/v2.0/retailer_publisher_details
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1",
"retailer_account_id": "1",
"publisher_account_id": "1",
"retailer_publisher_identifier": "ABC-123",
"retailer_publisher_identification_format": "retailerA-ID",
"publit_handles_export": "True",
"publisher_name": "Publisher AB",
"retailer_name": "Retailer AB",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"publisher_account": {
"id": "1",
"name": "Retailer account name",
"type": "Retailer",
"account_number": "12345",
"contractor_id": "1",
"country_id": "216",
"language_id": "430",
"organisation_type": "Company",
"company_name": "My company AB",
"contact_person_firstname": "Anders",
"contact_person_lastname": "Andersson",
"organisation_number": "123456-7890",
"vat_reg_number": "SE1234567890",
"primary_email": "email@company.com",
"invoice_email": "economy@company.com",
"phone": "12-34567890",
"alternate_phone": "23-45678901",
"profile_image_id": "null",
"active": "True",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"deleted_at": "NULL"
}
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array",
"description": "List of retailer publisher details"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/retailer_publisher_details/{retailer_publisher_details_id}
Example URI
GET /trade/v2.0/retailer_publisher_details/1
URI Parameters
- retailer_publisher_details_id
number(required) Example: 1Id of the requested retailer publisher detail
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"retailer_account_id": "1",
"publisher_account_id": "1",
"retailer_publisher_identifier": "ABC-123",
"retailer_publisher_identification_format": "retailerA-ID",
"publit_handles_export": "True",
"publisher_name": "Publisher AB",
"retailer_name": "Retailer AB",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"publisher_account": {
"id": "1",
"name": "Retailer account name",
"type": "Retailer",
"account_number": "12345",
"contractor_id": "1",
"country_id": "216",
"language_id": "430",
"organisation_type": "Company",
"company_name": "My company AB",
"contact_person_firstname": "Anders",
"contact_person_lastname": "Andersson",
"organisation_number": "123456-7890",
"vat_reg_number": "SE1234567890",
"primary_email": "email@company.com",
"invoice_email": "economy@company.com",
"phone": "12-34567890",
"alternate_phone": "23-45678901",
"profile_image_id": "null",
"active": "True",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00",
"deleted_at": "NULL"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"retailer_account_id": {
"type": "string",
"description": "Proprietary retailer id"
},
"publisher_account_id": {
"type": "string",
"description": "Proprietary publisher id"
},
"retailer_publisher_identifier": {
"type": "string",
"description": "The retailers publisher ID"
},
"retailer_publisher_identification_format": {
"type": "string",
"description": "The type of identification format"
},
"publit_handles_export": {
"type": "string",
"enum": [
"True"
],
"description": "This flag indicates if distribution of the product is handled from Publit. (If _False_ the distribution (including order handling) is supposed to be handled elsewhere)."
},
"publisher_name": {
"type": "string",
"description": "Name of publisher"
},
"retailer_name": {
"type": "string",
"description": "Name of retailer"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
},
"publisher_account": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"name": {
"type": "string",
"description": "Name of the account"
},
"type": {
"type": "string",
"enum": [
"Retailer"
],
"description": "Type of account"
},
"account_number": {
"type": "string",
"description": "Proprietary account number"
},
"contractor_id": {
"type": "string",
"description": "Contractor id (the id of the Publit entity connected to the account)"
},
"country_id": {
"type": "string",
"description": "Proprietary country id"
},
"language_id": {
"type": "string",
"description": "Proprietary language id"
},
"organisation_type": {
"type": "string",
"enum": [
"Company",
"Private"
],
"description": "Organisation type"
},
"company_name": {
"type": "string",
"description": "Company name"
},
"contact_person_firstname": {
"type": "string",
"description": "Contact person"
},
"contact_person_lastname": {
"type": "string",
"description": "Contact person"
},
"organisation_number": {
"type": "string",
"description": "Organisation number"
},
"vat_reg_number": {
"type": "string",
"description": "VAT registration number"
},
"primary_email": {
"type": "string",
"description": "Primary contact email address"
},
"invoice_email": {
"type": "string",
"description": "Invoice email address"
},
"phone": {
"type": "string",
"description": "Contact phone number"
},
"alternate_phone": {
"type": "string",
"description": "Alternative contact phone number"
},
"profile_image_id": {
"type": "string",
"description": "Profile image"
},
"active": {
"type": "string",
"enum": [
"True"
],
"description": "Indicates if the retailer account is active for ordering"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
},
"deleted_at": {
"type": "string",
"description": "Resource deleted date. Set automatically. (UTC)"
}
},
"description": "Related publisher account"
}
}
}Response
404Returned if account order id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Static resources ¶
These resources serves as read-only helpers to understand and lookup data from the Publit Trade API.
Countries ¶
The countries resource shows information about countries mapped by Publit proprietary ids.
IndexGET/trade/v2.0/countries
Example URI
GET /trade/v2.0/countries
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1",
"name": "Sweden",
"native_name": "Sverige",
"language_id": "1",
"iso2": "SE",
"iso3": "SWE",
"isonum": "752",
"currency_id": "131",
"language": {
"id": "1",
"iso3": "swe",
"iso2": "se",
"native_name": "Svenska",
"name": "Swedish"
},
"currency": {
"id": "1",
"name": "Swedish Krona",
"iso3": "SEK",
"isonum": "752"
}
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/countries/{country_id}
Example URI
GET /trade/v2.0/countries/1
URI Parameters
- country_id
number(required) Example: 1Id of the requested country
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"name": "Sweden",
"native_name": "Sverige",
"language_id": "1",
"iso2": "SE",
"iso3": "SWE",
"isonum": "752",
"currency_id": "131",
"language": {
"id": "1",
"iso3": "swe",
"iso2": "se",
"native_name": "Svenska",
"name": "Swedish"
},
"currency": {
"id": "1",
"name": "Swedish Krona",
"iso3": "SEK",
"isonum": "752"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"name": {
"type": "string",
"description": "Name of country"
},
"native_name": {
"type": "string",
"description": "Name of country in the native language of the country"
},
"language_id": {
"type": "string",
"description": "Proprietary language id of the related language spoken in the country"
},
"iso2": {
"type": "string",
"description": "iso2 (ISO-3166) code of the country"
},
"iso3": {
"type": "string",
"description": "iso3 (ISO-3166) code of the country"
},
"isonum": {
"type": "string",
"description": "numeric iso (ISO-3166) code of the country"
},
"currency_id": {
"type": "string",
"description": "proprietary currency id connected to the country"
},
"language": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"iso3": {
"type": "string",
"description": "ISO three letter code of the language"
},
"iso2": {
"type": "string",
"description": "ISO two letter code of the language"
},
"native_name": {
"type": "string",
"description": "Name of the language in the native tongue"
},
"name": {
"type": "string",
"description": "Name of the language in english"
}
},
"description": "Related language"
},
"currency": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"name": {
"type": "string",
"description": "Name of the currency in english"
},
"iso3": {
"type": "string",
"description": "ISO-4217 standard format of the currency"
},
"isonum": {
"type": "string",
"description": "ISO-4217 standard numeric format of the currency"
}
},
"description": "Related currency"
}
}
}Response
404Returned if country id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Languages ¶
The languages resource shows information about languages mapped by Publit proprietary ids.
IndexGET/trade/v2.0/languages
Example URI
GET /trade/v2.0/languages
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1",
"iso3": "swe",
"iso2": "se",
"native_name": "Svenska",
"name": "Swedish"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array",
"description": "List of languages"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/languages/{language_id}
Example URI
GET /trade/v2.0/languages/1
URI Parameters
- language_id
number(required) Example: 1Id of the requested language
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"iso3": "swe",
"iso2": "se",
"native_name": "Svenska",
"name": "Swedish",
"countries": [
{
"id": "1",
"name": "Sweden",
"native_name": "Sverige",
"language_id": "1",
"iso2": "SE",
"iso3": "SWE",
"isonum": "752",
"currency_id": "131"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"iso3": {
"type": "string",
"description": "ISO three letter code of the language"
},
"iso2": {
"type": "string",
"description": "ISO two letter code of the language"
},
"native_name": {
"type": "string",
"description": "Name of the language in the native tongue"
},
"name": {
"type": "string",
"description": "Name of the language in english"
},
"countries": {
"type": "array",
"description": "Related countries"
}
}
}Response
404Returned if country id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Currencies ¶
The currencies resource shows information about currencies mapped by Publit proprietary ids.
IndexGET/trade/v2.0/currencies
Example URI
GET /trade/v2.0/currencies
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1",
"name": "Swedish Krona",
"iso3": "SEK",
"isonum": "752",
"countries": [
{
"id": "1",
"name": "Sweden",
"native_name": "Sverige",
"language_id": "1",
"iso2": "SE",
"iso3": "SWE",
"isonum": "752",
"currency_id": "131"
}
]
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array",
"description": "List of currencies"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/currencies/{currency_id}
Example URI
GET /trade/v2.0/currencies/1
URI Parameters
- currency_id
number(required) Example: 1Id of the requested currency
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"name": "Swedish Krona",
"iso3": "SEK",
"isonum": "752",
"countries": [
{
"id": "1",
"name": "Sweden",
"native_name": "Sverige",
"language_id": "1",
"iso2": "SE",
"iso3": "SWE",
"isonum": "752",
"currency_id": "131"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"name": {
"type": "string",
"description": "Name of the currency in english"
},
"iso3": {
"type": "string",
"description": "ISO-4217 standard format of the currency"
},
"isonum": {
"type": "string",
"description": "ISO-4217 standard numeric format of the currency"
},
"countries": {
"type": "array",
"description": "List of related countries"
}
}
}Response
404Returned if country id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Categories ¶
The categories resource shows category information.
Thema ¶
The Thema-category list shows the available Thema categories (as defined by http://www.editeur.org/151/thema) supported in the Publit system.
IndexGET/trade/v2.0/categories/thema/trade/v2.0/categories/thema{?=query string parameters
Example URI
GET /trade/v2.0/categories/thema/trade/v2.0/categories/thema{?=query string parameters
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1",
"code": "FBA",
"description": "Modern & contemporary fiction",
"parent_code": "FB"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array",
"description": "List of Thema categories"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/categories/thema/{thema_category_id}
Example URI
GET /trade/v2.0/categories/thema/1
URI Parameters
- thema_category_id
number(required) Example: 1Id of the requested Thema category code
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"code": "FBA",
"description": "Modern & contemporary fiction",
"parent_code": "FB"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"code": {
"type": "string",
"description": "Thema category code"
},
"description": {
"type": "string",
"description": "Description of the category"
},
"parent_code": {
"type": "string",
"description": "The parent code"
}
}
}Response
404Returned if thema category id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Category Convert ¶
The convert resource allows for converting a category from one type to another. Currently Publit supports conversion from Thema to Bic and vice versa.
ConvertGET/trade/v2.0/categories/convert/from/{category_type}/{code_list}
Example URI
GET /trade/v2.0/categories/convert/from/thema/F,FA
URI Parameters
- category_type
enum(required) Example: themaType of code to convert from.
-
thema
-
bic
-
- code_list
string(required) Example: F,FACodes of type defined by category_type to convert from. Separated by comma.
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"count": "1",
"data": [
{
"bic_code": "A",
"thema_code": "A",
"description": "The Arts"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"data": {
"type": "array",
"description": "list of converted codes"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Contributor Roles ¶
The contributor roles resource lists information about the available contributor roles supported by Publit.
IndexGET/trade/v2.0/contributor_roles
Example URI
GET /trade/v2.0/contributor_roles
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"count": "1",
"next": "../resource{?query}&limit=x,y",
"prev": "../resource{?query}&limit=x,y",
"data": [
{
"id": "1",
"role": "Author",
"onix_code": "A01",
"description": "Author of textual work.",
"use_as_primary": "True",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"count": {
"type": "string",
"description": "Count of resources returned"
},
"next": {
"type": "string",
"description": "URL to next page of results"
},
"prev": {
"type": "string",
"description": "URL to previous page of results"
},
"data": {
"type": "array",
"description": "List of contributor roles"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}ShowGET/trade/v2.0/contributor_roles/{contributor_role_id}
Example URI
GET /trade/v2.0/contributor_roles/1
URI Parameters
- contributor_role_id
number(required) Example: 1Id of the requested contributor role
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"id": "1",
"role": "Author",
"onix_code": "A01",
"description": "Author of textual work.",
"use_as_primary": "True",
"created_at": "2017-01-01 00:00:00",
"updated_at": "2017-01-01 00:00:00"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of resource (automatically assigned)"
},
"role": {
"type": "string",
"description": "Role name"
},
"onix_code": {
"type": "string",
"description": "Role ONIX code"
},
"description": {
"type": "string",
"description": "Description of role"
},
"use_as_primary": {
"type": "string",
"enum": [
"True"
],
"description": "Flag to indicate if the role can be used as primary contribution to a work"
},
"created_at": {
"type": "string",
"description": "Resource created date. Set automatically. (UTC)"
},
"updated_at": {
"type": "string",
"description": "Resource updated date. Set automatically. (UTC)"
}
}
}Response
404Returned if contributor role id was not found.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Aggregate resources ¶
Most of the resources in the API can be aggregated by using the different aggregate resource.
The aggregate resource allows for running an aggregate method of a set of results for different resources.
The following aggregate methods exist:
-
Count
-
Sum
-
Max
-
Min
-
Avg
Examples
Each resource to aggregate also accepts the same filters as can be used by the resource directly allowing for advanced use of aggregations.
Following examples uses count as aggregation method.
Example for counting countries that uses a specific language
Request:
GET <api>/v2.0/count/countries?language_id=130
Response:
{
"count": 49
}Example for counting countries and grouping it by language_id
This is slightly more complex but can be useful as it provides an aggregate for each group of results.
Request:
GET <api>/v2.0/count/countries?group_by=language_id
Response:
{
"count": [
{
"language_id": 9,
"count": 2
},
{
"language_id": 14,
"count": 1
},
...
]
}Example for counting countries and grouping it by language_id and loading the language relation
This is an even greater extension of the previous example as it does not only count each aggregate of groups but also loads the language relation to each group.
Request:
GET <api>/v2.0/count/countries?group_by=language_id
Response:
{
"count": [
{
"language_id": 19,
"count": 2,
"language": {
"id": 9,
"iso3": "afr",
"iso2": "af",
"native_name": "Afrikaans",
"name": "Afrikaans"
}
},
{
"language_id": 14,
"count": 1,
"language": {
"id": 14,
"iso3": "sqi",
"iso2": "sq",
"native_name": "Shqip",
"name": "Albanian"
}
},
...
]
}Count ¶
Counts number of resources.
ShowGET/<api>/v2.0/count/{resource}
Example URI
GET //v2.0/count/countries
URI Parameters
- resource
string(required) Example: countriesThe resource to count
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"count": 223
}Response
404Returned if resource was not found or could not be aggregated.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Sum ¶
Sums an aggregate of resources.
Sum takes two parameters (resource and attribute) separated by a semicolon ;.
If the attribute can not be summed the result will be {"sum":0}.
ShowGET/<api>/v2.0/sum/{resource_attribute}
Example URI
GET //v2.0/sum/sales;revenue
URI Parameters
- resource_attribute
string(required) Example: sales;revenueThe resource and attribute to count
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"sum": "10000.00"
}Response
404Returned if resource was not found or could not be aggregated.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Max ¶
Max retrieves the maximum value of the specified resources attribute.
Max takes two parameters (resource and attribute) separated by a semicolon ;.
ShowGET/<api>/v2.0/max/{resource_attribute}
Example URI
GET //v2.0/max/products;price
URI Parameters
- resource_attribute
string(required) Example: products;priceThe resource and attribute
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"max": "150.00"
}Response
404Returned if resource was not found or could not be aggregated.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Min ¶
Min retrieves the minimum value of the specified resources attribute.
Min takes two parameters (resource and attribute) separated by a semicolon ;.
ShowGET/<api>/v2.0/min/{resource_attribute}
Example URI
GET //v2.0/min/products;price
URI Parameters
- resource_attribute
string(required) Example: products;priceThe resource and attribute
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"max": "1.00"
}Response
404Returned if resource was not found or could not be aggregated.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Avg ¶
Avg retrieves the average value of the specified resources attribute.
Avg takes two parameters (resource and attribute) separated by a semicolon ;.
ShowGET/<api>/v2.0/avg/{resource_attribute}
Example URI
GET //v2.0/avg/products;price
URI Parameters
- resource_attribute
string(required) Example: products;priceThe resource and attribute
Response
200Returned if request was succesful
Headers
Content-Type: application/jsonBody
{
"avg": "25.37"
}Response
404Returned if resource was not found or could not be aggregated.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Response
401Returned if unauthorized.
Headers
Content-Type: text/html; charset=UTF-8Body
Invalid credentials.Response
500Returned if server had problems.
Headers
Content-Type: application/jsonBody
{
"Code": 1,
"Type": "Error type",
"Errors": [
{
"Info": "Some specific error information",
"Type": "Not found"
}
],
"CombinedInfo": "Some combined error information"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Code": {
"type": "number",
"description": "HTTP response code"
},
"Type": {
"type": "string",
"description": "Type of error"
},
"Errors": {
"type": "array",
"description": "Errors explanation"
},
"CombinedInfo": {
"type": "string",
"description": "Combined error information string"
}
}
}Status check ¶
The status check resource is a light weight resource that needs no authentication and shows information about if the API status is ok.
If any HTTP-status in the 300, 400 or 500 range is returned the server has problems nad can not be reached. Contact Publit for information if this happens.
The status check resource is not scoped to a specific API but available directly under https://api.publit.com/v2.0/status_check.
Status Check ¶
Status CheckGET/v2.0/status_check
Example URI
GET /v2.0/status_check
Response
200Returned if request was succesful.
Headers
Content-Type: application/jsonBody
{
"server_status": "OK"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"server_status": {
"type": "string",
"description": "Flag indicating the status of the server"
}
}
}