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.

Send prescription specification

POST
/dr/v1/prescription-specifications
curl --request POST \
  --url https://sender.sandbox-api.kivra.com/dr/v1/prescription-specifications \
  --header 'Content-Type: application/json;profile=https://se.kivra.com/schemas/json/retail/ps/v1.0' \
  --data '{ "business_unit": { "contact": { "address": { "locality": "City", "postal_code": "123 45", "street_address": "Östra storgatan 6", "type": { "type": "business" } }, "email": "info@ta.se", "phone": "0123456789" }, "name": "Test apoteket", "organization_number": "112233-4455", "service_id": "16399966934684ed5d5d534373b33ef89846460b06", "unit_id": "5" }, "cashier": { "id": "T02SUIT" }, "receipt_identifier": { "sequence_number": 123456, "extended_number": { "value": "0123456123", "type": "EAN8", "context": "store" } }, "time_of_purchase": "2023-03-27T08:49:00+01:00", "customer": { "id": { "birth_date": "19900805" }, "name": "Knapp, Lena" }, "expedition": { "id": "T02 AAN631", "details": [ "Inköp på expedition T02 AAN631" ] }, "human": { "high_cost": { "previous_period": { "gross": 8982.64, "net": 2350, "start_date": "2021-07-12T08:00:00+02:00", "end_date": "2022-07-11T08:00:00+02:00" }, "current_period": { "gross": 28198.71, "net": 2400, "start_date": "2022-07-12T08:00:00+02:00", "end_date": "2023-07-11T08:00:00+02:00" }, "next_period": { "gross": 0, "net": 0, "start_date": "2023-07-13T08:00:00+02:00", "end_date": "2024-07-11T08:00:00+02:00" }, "amount_left_to_reimbursement": { "gross": 100, "net": 100 } } }, "amount_with_benefit": 58.27, "amount_without_benefit": 5.38, "amount_paid_by_benefit": 58.27, "amount_to_pay": 5.38 }'

Sends a prescription specification to Kivra. Following credentials are needed in order to create prescription specifications.

  • storeID : add to the “service_id” element in the prescription specification body

  • token : the JWT bearer token used for authorization. Partner, chain or store token can be used.

    Access scope

    • PARTNER
    • CHAIN

    Headers

    The Content-Type must be set according to the prescription specification format:

    • Content-Type: application/json;profile=https://se.kivra.com/schemas/json/retail/ps/v1.0

    The profile tells what version of the JSON schema that the prescription specification is based on.

    This schema is available for download in JSON.

Request Bodyrequired

Section titled “Request Bodyrequired”

Sends a prescription specification

Media typeapplication/json;profile=https://se.kivra.com/schemas/json/retail/ps/v1.0
One of:
Prescription v1.0

Prescription specification issued by pharmacies and connected to a receipt in Kivra. The format is based on discussions with pharmacies and data from the Swedish eHealth Agency. Version 1.0 — first release 2025-03-11.

object
business_unit
required

Merchant information (the pharmacy issuing the specification).

object
name
required
string
service_id
required

Id created when then business is registered in kivra

string
>= 42 characters <= 42 characters /^[0-9]{10}[0-9a-fA-F]{32}$/
unit_id

Internal merchant shop/business unit id

string
organization_number
required

Swedish organisationsnummer or vat reg number

string
contact
required

Merchant contact information name, address, phone etc

object
address
Any of:
address

An address following the convention of http://microformats.org/wiki/hcard

object
street_address
required
string
extended_address
string
post_box
string
locality
string
postal_code
string
region
string
country_name
string
type
address type

Is address (physical/email) related to business, home, etc

object
type
Allowed values: home business
email
string format: email
phone
generic phone number

Generic format for phone numbers where strict format can not be enforced, use only for phone number to be displayed

string
/^(\(?((\+|(00))[0-9]{1,3})\)?)?( ?-?\(?[0-9]+\)?)+$/
website
string format: uri
geo_location
Geographic location (long/lat)

A geographical coordinate

object
latitude
required
number
longitude
required
number
cashier
required
cashier name and id

Identifies the person handling the purchase if applicable

object
id
string
name
string
receipt_identifier
required
receipt identifier

Receipt identifiers: sequence number and/or extended number with or without barcode representation

object
sequence_number

A sequence number as stipulated by the swedish tax authorities, not mandatory for PS.

integer
extended_number
required

A more complex receipt number if applicable, must be unique in given context

object
value
required

Data that will be presented as a barcode on the receipt

string
type

Barcode representation of any data

string
Allowed values: Interleaved2Of5 EAN13 EAN8 Codabar Code39 Code93 Code128 AztecCode Datamatrix PDF417 QRCode
context
required

In what context is the value (receipt number) unique, note GLOBAL can only be used if a digital receipt provider receipt id is used

string
Allowed values: store chain global
time_of_purchase
required

ISO 8601 date/time format: YYYY-MM-DDThh:mm:ssTZD

string format: date-time
currency
ISO-4217 currency codes

The receipt default currency. This gives the currency for all amounts in the receipt. If applicable overriding currencies can be added to the tender parts

string
/^[a-zA-Z]{3}$/
amount_with_benefit

Amount with the high-cost benefit applied. Human prescriptions only; usually equals amount_paid_by_benefit but differs when insurances are involved.

number
amount_without_benefit
required

Amount without the high-cost benefit. Given on both animal and human prescriptions.

number
amount_paid_by_benefit

Amount paid by the high-cost benefit. Human prescriptions only; usually equals amount_with_benefit but differs when insurances are involved.

number
amount_to_pay
required

Final amount the customer pays. Given on both animal and human prescriptions.

number
totals

Total amounts and types, for example vat, gross, paid. Included when the prescription contains goods/services the customer pays tax on; the VAT is then added here.

Array
One of:
Paid total amount

Paid: gross amount including discount and rounding.

object
amount
required
number
refund

True if amount to customer, example: on return of goods

boolean
type
required
string
Allowed values: paid
sub_totals
Array
Any of:
Amount received from customer

Use with total/paid if paid gives the total amount paid and the subtotal gives what is given by customer

object
type
required
string
Allowed values: received
amount
required
number
text

Optional explaining text

object
type
required
string
Allowed values: array
collection
required

Arbitray array of strings used where additional info needed at some part

Array<string>
customer
Any of:

Defines valid customer identifiers

object
id
One of:

The customer ssn

object
civic_registration_number
required

Swedish personnummer 12 digits

string
/^[12]{1}[90]{1}[0-9]{6}-?[0-9]{4}$/
animal
required

Specific properties related to animal prescriptions

object
id
required

Identifies the animal to whom the prescription is issued

string
human

Human prescription data related to high-cost reimbursement, given as previous, current and next periods.

object
high_cost
required

Defines properties related to high cost reimbursement

object
previous_period
required
object
gross
required
number
net
required
number
start_date
required

High cost period start date-time, ISO 8601 date/time format: YYYY-MM-DDThh:mm:ssTZD

string format: date-time
end_date

High cost period end date-time, ISO 8601 date/time format: YYYY-MM-DDThh:mm:ssTZD

string format: date-time
current_period
required
object
gross
required
number
net
required
number
start_date
required

High cost period start date-time, ISO 8601 date/time format: YYYY-MM-DDThh:mm:ssTZD

string format: date-time
end_date

High cost period end date-time, ISO 8601 date/time format: YYYY-MM-DDThh:mm:ssTZD

string format: date-time
next_period
required
object
gross
required
number
net
required
number
start_date
required

High cost period start date-time, ISO 8601 date/time format: YYYY-MM-DDThh:mm:ssTZD

string format: date-time
end_date

High cost period end date-time, ISO 8601 date/time format: YYYY-MM-DDThh:mm:ssTZD

string format: date-time
amount_left_to_reimbursement

The amount left to high cost reimbursement

object
gross
required
number
net
required
number
medications

List of medications issued and their cost. Can be used on both animal and human prescriptions.

Array<object>
object
description
required
string
amount
number
expedition
required

Expedition / prescription details. The format differs between pharmacies, so the user-facing part is carried as the ‘details’ array of strings.

object
id
required

Expedition id, prescription id, etc. For internal use and exchange with other systems

string
details
required

This is what the user will see

Array<string>
>= 1 items
Examples

Human specification one — expedition id & high-cost reimbursement

Basic elements of a human prescription specification based on an expedition id, with high-cost periods and amount left to high-cost reimbursement.

{
  "business_unit": {
    "contact": {
      "address": {
        "locality": "City",
        "postal_code": "123 45",
        "street_address": "Östra storgatan 6",
        "type": {
          "type": "business"
        }
      },
      "email": "info@ta.se",
      "phone": "0123456789"
    },
    "name": "Test apoteket",
    "organization_number": "112233-4455",
    "service_id": "16399966934684ed5d5d534373b33ef89846460b06",
    "unit_id": "5"
  },
  "cashier": {
    "id": "T02SUIT"
  },
  "receipt_identifier": {
    "sequence_number": 123456,
    "extended_number": {
      "value": "0123456123",
      "type": "EAN8",
      "context": "store"
    }
  },
  "time_of_purchase": "2023-03-27T08:49:00+01:00",
  "customer": {
    "id": {
      "birth_date": "19900805"
    },
    "name": "Knapp, Lena"
  },
  "expedition": {
    "id": "T02 AAN631",
    "details": [
      "Inköp på expedition T02 AAN631"
    ]
  },
  "human": {
    "high_cost": {
      "previous_period": {
        "gross": 8982.64,
        "net": 2350,
        "start_date": "2021-07-12T08:00:00+02:00",
        "end_date": "2022-07-11T08:00:00+02:00"
      },
      "current_period": {
        "gross": 28198.71,
        "net": 2400,
        "start_date": "2022-07-12T08:00:00+02:00",
        "end_date": "2023-07-11T08:00:00+02:00"
      },
      "next_period": {
        "gross": 0,
        "net": 0,
        "start_date": "2023-07-13T08:00:00+02:00",
        "end_date": "2024-07-11T08:00:00+02:00"
      },
      "amount_left_to_reimbursement": {
        "gross": 100,
        "net": 100
      }
    }
  },
  "amount_with_benefit": 58.27,
  "amount_without_benefit": 5.38,
  "amount_paid_by_benefit": 58.27,
  "amount_to_pay": 5.38
}

Responses

Section titled “Responses”

201

Section titled “201”

Prescription specification successfully sent

Media typeapplication/json
PrescriptionSpecificationResponse
object
receipt_id
string
prescription_specification_id
string
Example
{
  "receipt_id": "15594097555922f97bfeb148d6b9a6ef76f76ebdce",
  "prescription_specification_id": "17594097555904f97adeb148d6b9a6ef76f76ebdba"
}

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",
  "error_message": "body is missing from the request"
}

401

Section titled “401”

Unauthorized

Media typeapplication/json
ErrorResponse
object
error_code
string
short_message
string
long_message
string
error_detail
Array<string>
Examples
{
  "error_code": "40100",
  "error_message": "jwt token missing"
}

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"
}