Skip to content
KivraAPI Reference
This is a new version of the Kivra Developer Docs. Report issues or share feedback at avsandare.support@kivra.se. The previous version can be found here.

Create or link chain

POST
/dr/v1/chains
curl --request POST \
  --url https://sender.sandbox-api.kivra.com/dr/v1/chains \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Demo chain", "vat": "SE555555555501", "address": { "street1": "Gatan 1", "postalcode": "13254", "city": "onebuying", "country": "SWE" }, "icon": { "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=", "content_type": "image/png" }, "item_display_fields": [ "article_number_pos" ] }'

Creates a chain or links to an existing chain.

Access scope

  • PARTNER

Matching

To determine if this is an existing chain the following fields need to match

  • name
  • vat

It is only possible to create one chain per VAT number.

Validation rules

  • Either vat or external_id (or both) must be provided - A chain cannot have both retained_activated and greenbin_activated set to true - The partner must have the respective feature activated before a chain can activate it

Activation defaults

If neither retained_activated nor greenbin_activated is provided in the request, the chain will inherit the activation setting from the partner. If the partner has retained receipts enabled (e.g. via send-to-all), the chain will have retained_activated set to true by default. To opt out, explicitly set retained_activated to false. If only one of the two fields is provided, the omitted field defaults to false.

Request Bodyrequired

Section titled “Request Bodyrequired”

Takes in a chain object with required information to create a new chain

Media typeapplication/json
Any of:
AddChain
object
external_id

External identifier for the chain, unique per partner

string
/^.{5,128}$/
name

The name of the chain

string
>= 1 characters
vat
required

The VAT number of the chain

string
/^((SE)?[0-9]{12})$"/
phone

The phone number of the store

string
address

The address of the store

object
street1
required
string
street2
string
street3
string
postalcode
required
string
city
string
state
string
country
required
string
>= 3 characters <= 3 characters
icon

Icon displayed on the receipt

object
data
required

Base64 encoded image

string
content_type
required

The image content type

string
logo

Logo displayed on the receipt

object
data
required

Base64 encoded image

string
content_type
required

The image content type

string
item_display_fields

The extra fields from receipt items that should be displayed in the app

Array<string>
Allowed values: article_number_pos article_number_gtin
retained_activated

Whether retained receipts are activated for this chain. If omitted along with greenbin_activated, defaults to the partner’s setting. If the other field is provided but this one is omitted, defaults to false.

boolean
Examples

Create chain with VAT

{
  "name": "Demo chain",
  "vat": "SE555555555501",
  "address": {
    "street1": "Gatan 1",
    "postalcode": "13254",
    "city": "onebuying",
    "country": "SWE"
  },
  "icon": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
    "content_type": "image/png"
  },
  "item_display_fields": [
    "article_number_pos"
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Chain already exists

Media typeapplication/json
AddChainResponse
object
chain_id
string
vat
string
created
boolean
Example
{
  "chain_id": "15594097555922f97bfeb148d6b9a6ef76f76ebdce",
  "vat": 55555,
  "created": false
}

201

Section titled “201”

Chain successfully created

Media typeapplication/json
AddChainResponse
object
chain_id
string
vat
string
created
boolean
Example
{
  "chain_id": "15594097555922f97bfeb148d6b9a6ef76f76ebdce",
  "vat": 55555,
  "created": true
}

400

Section titled “400”

Bad request

Media typeapplication/json
ErrorResponse
object
error_code
string
short_message
string
long_message
string
error_detail
Array<string>
Examples
{
  "error_code": "40000",
  "short_message": "bad request",
  "long_message": "body is missing required fields or has invalid fields"
}

401

Section titled “401”

Unauthorized

Media typeapplication/json
ErrorResponse
object
error_code
string
short_message
string
long_message
string
error_detail
Array<string>
Examples
Exampleunauthorized
{
  "error_code": "40100",
  "short_message": "unauthorized",
  "long_message": "permission denied"
}

404

Section titled “404”

Not found

Media typeapplication/json
ErrorResponse
object
error_code
string
short_message
string
long_message
string
error_detail
Array<string>
Examples
Exampleresource_not_found
{
  "error_code": "40400",
  "short_message": "not found",
  "long_message": "the requested resource could not be found"
}

409

Section titled “409”

Conflict

Media typeapplication/json
ErrorResponse
object
error_code
string
short_message
string
long_message
string
error_detail
Array<string>
Examples
Examplevat_exists
{
  "error_code": "40900",
  "short_message": "conflict",
  "long_message": "company with the given vat exists"
}

500

Section titled “500”

Internal server error

Media typeapplication/json
ErrorResponse
object
error_code
string
short_message
string
long_message
string
error_detail
Array<string>
Example
{
  "error_code": "50000",
  "short_message": "internal server error",
  "long_message": "unknown error ocurred"
}