PSI Productfinder (Beta)
Documentation Powered by ReDoc

PSI Backend API (1.0.1)

This is the PSI Backend API Documentation.

Authentication

JSON-Web-Token

You'll need an access_token to make Requests to the API.

Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Auth

All Auth related Endpoints

Authorize with API and get an Access and Refresh Token

This Endpoint will provide you with an access_token which will be used on every Request. You can login with you 'normal' PSI Account. To avoid changes in code due to user password changes, we recommend to create a specific Sub-Account for API Access in https://www.psi-network.de/.

Request Body schema: application/json
username
required
string

Your Username - is the same as you login to other PSI Services (Productfinder, Network..), can be an E-Mail Adress or the PSI-Number.

password
required
string

Your Password

Responses

200

Successful Response

400

Credentials wrong

405

Wrong/Missing Parameters

post /auth
API Test Environment
https://api-stage-cf.psiproductfinder.de/v1/auth
API Live Environment
https://api-cf.psiproductfinder.de/v1/auth

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "username": "40000",
  • "password": "password"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImp0aSI6IjQ5ODU2In0.eyJpc3MiOiJwc2lwcm9kdWN0ZmluZGVyLmRlIiwiYXVkIjoicHNpcHJvZHVjdGZpbmRlci5kZSIsImp0aSI6IjQ5ODU2IiwiaWF0IjoxNTIwNDI1MDQzLCJuYmYiOjE1MjA0MjUwNDMsImV4cCI6MTUyMDQyODY0MywicGF5bG9hZCI6eyJwc2lubyI6IjQ5ODU2IiwiYWRtaW4iOiIxIn19.MNmwi_HZZCiALFW1_v-ahuCaX-ocFLxijQ8rbjh_358",
  • "refresh_token": "2095f7fbe636169aff00724154215fa66b9bdf79",
  • "expires_in": "1526466172"
}

Refresh Access Token via Refresh Token

If your Access Token expires after 1 hour, you need to generate a new one. You could login again, or use the Refresh Token.

Request Body schema: application/json
username
required
string

Your PSI-Number, at the moment you can not use a sub account here.

refresh_token
required
string

Your Refresh Token.

Responses

200

Successful Response

400

Refresh Token not found

405

Wrong/Missing Parameters

post /refresh
API Test Environment
https://api-stage-cf.psiproductfinder.de/v1/refresh
API Live Environment
https://api-cf.psiproductfinder.de/v1/refresh

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "username": "100000",
  • "refresh_token": "example-token"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImp0aSI6IjQ5ODU2In0.eyJpc3MiOiJwc2lwcm9kdWN0ZmluZGVyLmRlIiwiYXVkIjoicHNpcHJvZHVjdGZpbmRlci5kZSIsImp0aSI6IjQ5ODU2IiwiaWF0IjoxNTIwNDI1MDQzLCJuYmYiOjE1MjA0MjUwNDMsImV4cCI6MTUyMDQyODY0MywicGF5bG9hZCI6eyJwc2lubyI6IjQ5ODU2IiwiYWRtaW4iOiIxIn19.MNmwi_HZZCiALFW1_v-ahuCaX-ocFLxijQ8rbjh_358",
  • "expires_in": "1526466172"
}

Entities

With the entity endpoint you can get, create and delete your Product in the Productfinder. Of course you can only edit Products of your own PSI Number. It is the central Endpoint for using the API.

Data Model Entites: Products - Variants - Translations

The API manages Products. Those Products can have 1 to n Variants and each Variant can have Translations. A Product itself is never shown in the Productfinder Frontend till it only holds infos shared by the Variants. We call those Products Master-Product or Blueprint. A simple representation is like that:

  • product
    • variant 1
      • translation de
      • translations XY (right now only german is available)
    • variant 2
      • translation de
      • translations XY (right now only german is available)
    • variant 3
      • translation de
      • translations XY (right now only german is available)

Translation Handling

There are two different language parameters:

Parameter Values Description
locale default: en, en, de this is the GUI language and will switch the language of labels. for updating and creating of products it has no meaning.
language default: en, en, de the language of the entity. This decides which translation of the variant is listed, updated, deleted or created

Default get single english product with english labels: 

// Request
{
  "action": "@entities/v-23741a23"
}

// Response
{
  "data": {
    [...]
    "identifier": "v-23741a23",
    "name": "This is my product",
    "description": "The description",
    "properties": {
      "color_group": [
        "Black",
        "White"
      ],
      [...]
    }
  }
}

get english product with german labels:

// Request
{
  "action": "@entities/v-23741a23",
    "locale": "de"
}

// Response
{
  "data": {
    [...]
    "identifier": "v-23741a23",
    "name": "This is my product",
    "description": "The description",
    "properties": {
      "color_group": [
        "Schwarz",
        "Weiß"
      ],
      [...]
    }
  }
}

get german product with german labels:

// Request
{
  "action": "@entities/v-23741a23",
    "language": "de",
    "locale": "de"
}

// Response
{
  "data": {
    [...]
    "identifier": "v-23741a23",
    "name": "Das ist mein Produkt",
    "description": "Die Beschreibung",
    "properties": {
      "color_group": [
        "Schwarz",
        "Weiß"
      ],
      [...]
    }
  }
}

get german product with english labels:

// Request
{
  "action": "@entities/v-23741a23",
    "language": "de"
}

// Response
{
  "data": {
    [...]
    "identifier": "v-23741a23",
    "name": "Das ist mein Produkt",
    "description": "Die Beschreibung",
    "properties": {
      "color_group": [
        "Black",
        "White"
      ],
      [...]
    }
  }
}

Create a product process

Till the Frontend only renders Variants and their translations it is not necessary to add a Master Product. If you add an new variant, which do not have a parent product , the master product will be generated automaticaly.

So the simplest way to add a new product is just create a single variant. A complete call to the API to create a new variant:

{
  "action": "@entities",
  "payload":
  {
    "master_product_number":"API-TEST-HK2", 
    "product_number":"API-TEST-HK2-blue",
    "name":"API-Test filing strip blue",
      "description": "API-Test Filing strip in the color blue, holds punched documents together. It fits in regular files, suspension files, folders and ring binders. Plastic-coated welded filing bar and markings ensure correct positioning. Polypropylene filing strips. With 4 punched holes. Short with plastic cover strip.",
    "brand": "API-Test-Brand",
    "tags": "filing strip, fastener",
    "ean_code": "4001234567890",
    "groups":["09042018"],
    "properties": {
      "certificates": [
        "CERT-05300000",
        "CERT-04190000"
      ],
      "color":"blue metal",
      "color_group":[
        "CG-BLUE4",
        "CG-BROE6"
      ],
      "material":"Polypropylene & Brass",    
      "material_group":
      [
        "MG-BRAS5",
        "MG-PPPE18"                
      ],
      "measurement": {
        "length": 150,
        "width": 34,
        "height": 1
        },
      "measurement_info": "34 150 mm (W x L)",
      "size" : "3.4 x 15 cm (W x L)",
      "weight_netto": "1",
      "weight_brutto": "2",
      "target_group": "Office Clerks",
      "country_origin": "CC-DE" ,
      "made_in" : "Germany",
      "stock_available" : true,
      "minimum_order_amount": 250,
      "packaging" : "250 pieces/ pack",
      "legal_information" : "brass products might cause allergic reaction",
      "price_ranges": [
        {
          "amount": 250,
          "price_ek": 1.59,
          "price_uvp": 1.79
        }, {
          "amount": 500,
          "price_ek": 1.49,
          "price_uvp": 1.69
        }
      ],
      "price_ranges_info" : "Please call for special price ranges.",
      "minimum_order_amount": 250,
      "delivery_time": {
        "min": 5,
        "max": 60
      },
      "finishings": [
          {
            "group": "FG-EMBG9",
            "included": false,
            "description": "We can emboss characters on the lid."
          }, {
            "group": "FG-ADHEFL13",
            "included": true,
            "description": "We can attach different sizes of adhesive foil."
          }
        ],
      "finishings_info" : "Please call for further finishing options.",
      "images": [
        {
          "src": "https://legacy.psiproductfinder.de/de/products/image/zoom/27575/591003/2",
          "name": "top view filing strip blue",
          "description": "This is the top view of filing strip blue."
        }, {
          "src": "https://legacy.psiproductfinder.de/de/products/image/zoom/27575/591003/3",
          "name": "bottom view filing strip blue",
          "description": "This is the bottom view of filing strip blue."
        }, {
          "src": "https://legacy.psiproductfinder.de/de/products/image/zoom/27575/591003/4",
          "name": "open view filing strip blue",
          "description": "This is the open view of filing strip blue."
        }, {
          "src": "https://legacy.psiproductfinder.de/de/products/image/zoom/27575/591009/2",
          "name": "side view filing strip blue",
          "description": "This is the side view of filing strip blue."
        }, {
          "src": "https://legacy.psiproductfinder.de/de/products/image/zoom/27575/591009/3",
          "name": "top view filing without lid strip blue",
          "description": "This is the top view without lid of filing strip blue."
        }
      ]
    }
  }
}

create a translation of the same product, master_product_number and product_number must be identical:

{
  "action": "@entities",
  "language": "de",
  "payload": {
    "master_product_number":"API-TEST-HK2", 
    "product_number":"API-TEST-HK2-blue",
    "name":"API-Test Heftstreifen blau",
      "description" : "Verwalten Sie Ihre Dokumente mit Präzision und Leichtigkeit. Mit diesen farbigen Heftstreifen strukturieren Sie Unterlagen einfach und wirkungsvoll. Die Heftstreifen sind aus Polypropylen, haben eine Deckleiste und eine robuste Metallheftzunge.",
    "brand": "API-Test-Brand",
    "tags": "Heftstreifen, Aktendulli",
    "ean_code": "4001234567890",
    "groups":["09042018"],
    "properties": {
      "certificates": [
        "CERT-05300000",
        "CERT-04190000"
      ],
      "color":"Blau Metal",
      "color_group":[
        "CG-BLUE4",
        "CG-BROE6"
      ],
      "material":"Polypropylen & Messing",    
      "material_group":
      [
        "MG-BRAS5",
        "MG-PPPE18"                
      ],
      "measurement": {
        "length": 150,
        "width": 34,
        "height": 1
        },
      "measurement_info": "34 x 150 mm (B x L)",
      "size" : "3.4 x 15 cm (B x L)",
      "weight_netto": "1",
      "weight_brutto": "2",
      "target_group": "Büro-Organistion",
      "country_origin": "CC-DE" ,
      "made_in" : "Deutschland",
      "stock_available" : true,
      "minimum_order_amount": 250,
      "packaging" : "250 Stück/Packung",
      "legal_information" : "Messing kann Allergien auslösen",
      "price_ranges": [
        {
          "amount": 250,
          "price_ek": 1.59,
          "price_uvp": 1.79
        }, {
          "amount": 500,
          "price_ek": 1.49,
          "price_uvp": 1.69
        }
      ],
      "price_ranges_info" : "Gerne geben wir Ihnen auf Anfrage spezielle Preiskonditionen",
      "minimum_order_amount": 250,
      "delivery_time": {
        "min": 5,
        "max": 60
      },
      "finishings": [
          {
            "group": "FG-EMBG9",
            "included": false,
            "description": "Wir können Buchstaben auf die Messingteile stanzen."
          }, {
            "group": "FG-ADHEFL13",
            "included": true,
            "description": "Es ist möglich, Klebefolie in verschiedenen Größen anzubringen."
          }
        ],
      "finishings_info" : "Gerne nennen wir Ihnen weitere Veredelungs-Möglichkeiten.",
      "images": [
        {
          "src": "https://legacy.psiproductfinder.de/de/products/image/zoom/27575/591003/2",
          "name": "Aufsicht Heftklammer blau",
          "description": "Hier sehen Sie die blaue Heftklammer von oben."
        }, {
          "src": "https://legacy.psiproductfinder.de/de/products/image/zoom/27575/591003/3",
          "name": "Bodenansicht Heftklammer blau",
          "description": "Hier sehen Sie die blaue Heftklammer von unten."
        }, {
          "src": "https://legacy.psiproductfinder.de/de/products/image/zoom/27575/591003/4",
          "name": "Aufsicht Heftklammer blau (geöffnet)",
          "description": "Hier sehen Sie die blaue Heftklammer von oben und geöffnet."
        }, {
          "src": "https://legacy.psiproductfinder.de/de/products/image/zoom/27575/591009/2",
          "name": "Seitenansicht Heftklammer blau",
          "description": "Hier sehen Sie die blaue Heftklammer von der Seite."
        }, {
          "src": "https://legacy.psiproductfinder.de/de/products/image/zoom/27575/591009/3",
          "name": "Aufsicht Heftklammer blau ohne Metallstreifen",
          "description": "Hier sehen Sie die blaue Heftklammer von oben und ohne Metallstreifen."
        }
      ]
    }
  }
}

Get Entities

To get a list of entities you can use the /request endpoint with some options. You will only get products of your psi-number

Authorizations:
JSON-Web-Token
Request Body schema: application/json
action
required
string

@entities

language
string
Default: "en"
Enum:"en" "de"

The language of the entity. This decides which translation of the variant is listed, updated, deleted or created.

locale
string
Default: "en"
Enum:"en" "de"

This is the GUI language and will switch the language of labels. for updating and creating of products it has no meaning.

page
integer
Default: 1

the results are paginated. By default you get 15 items per request. with the page attribute you can navigate.

Responses

200

Successful Response

400

Error Response

post /request#getEntities
API Test Environment
https://api-stage-cf.psiproductfinder.de/v1/request#getEntities
API Live Environment
https://api-cf.psiproductfinder.de/v1/request#getEntities

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "action": "@entities",
  • "language": "en",
  • "locale": "en",
  • "page": 1
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "data":
    [
    ],
  • "meta":
    {
    }
}

Get Entity

Used to get one specific product or variant. You can use the internal identifier field which is generated out of your master_product_number, psi number and product_number and should be unique. You can although use your product_number as identifier. The identifier begins with a "p-" for the master product and with a "v-" for a variant. If you call a master product you get all variants.

Authorizations:
JSON-Web-Token
Request Body schema: application/json
action
required
string

@entities/v-123456

language
string
Default: "en"
Enum:"en" "de"

The language of the entity. This decides which translation of the variant is listed, updated, deleted or created.

locale
string
Default: "en"
Enum:"en" "de"

This is the GUI language and will switch the language of labels. It can be ignored if working with the api.

Responses

200

Successful Response

400

Error Response

post /request#getEntity
API Test Environment
https://api-stage-cf.psiproductfinder.de/v1/request#getEntity
API Live Environment
https://api-cf.psiproductfinder.de/v1/request#getEntity

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "action": "@entities/{identifier}",
  • "language": "en",
  • "locale": "en"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "data":
    {
    }
}

Create Entity

To create a variant or translation you just need to post a payload with the needed parameters. If you specify a different language than default (en) a translation is added.

For example:

{
  "action": "@entities",
  "payload": {
    "product_number": "ID-of-your-variant-231412",
    "master_product_number": "wrapper-id-of-all-variants"
    "name": "Name of the product",
    "properties" {
      ....
    }
  }
}
Authorizations:
JSON-Web-Token
Request Body schema: application/json
action
required
string
language
string
Default: "en"
Enum:"en" "de"
payload
required
object (UpdateBaseEntityWithoutPsiNumber)

Responses

200

Successful Response

400

Error Response

405

Wrong Input Response

post /request#createEntity
API Test Environment
https://api-stage-cf.psiproductfinder.de/v1/request#createEntity
API Live Environment
https://api-cf.psiproductfinder.de/v1/request#createEntity

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "action": "@entities",
  • "language": "en",
  • "payload":
    {
    },
  • "entity": "ProductEntityWithoutPsiNumber"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": "6ad65e80-b5b3-11e8-8c18-afb942bcccd1",
  • "master_article_number": "49003S5053495F50564F5F31",
  • "brand": "BRAND NAME",
  • "product_number": "PRONR_0001",
  • "name": "Example Product",
  • "description": "This is a Product Description",
  • "tags": "tag1,tag2,tag3",
  • "ean": "123456789",
  • "products": 2,
  • "groups":
    [
    ],
  • "properties":
    {
    },
  • "deactivated": "",
  • "created": "2017-01-01 12:00:00",
  • "updated": "2018-01-01 14:00:00",
  • "_overlayed": [ ]
}

Update Entity

To update variants and translations. You need to specify the variant identifier (v-21412415) or product_number and for a translation the language parameter.

If you update values in the properties object, all old values will be overwritten, even values you have not updated!

For example:

{
  "action": "@entities/update/v-1245151",
  "payload": {
    "description": 'New variant description'
  }
}

This will change the description of a variant with identifier: v-1245151.

Authorizations:
JSON-Web-Token
Request Body schema: application/json
action
required
string

@entities/update/{identifier}

language
string
Default: "en,"
Enum:"en" "de"

The language of the entity. This decides which translation of the variant is listed, updated, deleted or created.

payload
required
object (BaseEntityWithoutPsiNumber)

Responses

200

Successful Response

400

Error Response

405

Wrong Input Response

post /request#updateEntity
API Test Environment
https://api-stage-cf.psiproductfinder.de/v1/request#updateEntity
API Live Environment
https://api-cf.psiproductfinder.de/v1/request#updateEntity

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "action": "@entities/update/{identifier}",
  • "language": "en,",
  • "payload":
    {
    },
  • "entity": "UpdateProductEntityWithoutPsiNumber"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": "6ad65e80-b5b3-11e8-8c18-afb942bcccd1",
  • "master_article_number": "49003S5053495F50564F5F31",
  • "brand": "BRAND NAME",
  • "product_number": "PRONR_0001",
  • "name": "Example Product",
  • "description": "This is a Product Description",
  • "tags": "tag1,tag2,tag3",
  • "ean": "123456789",
  • "products": 2,
  • "groups":
    [
    ],
  • "properties":
    {
    },
  • "deactivated": "",
  • "created": "2017-01-01 12:00:00",
  • "updated": "2018-01-01 14:00:00",
  • "_overlayed": [ ]
}

Delete Entity

To delete an variant, translation or product you need the identifier or product_number and the language (if not english)

For example:

{
  "action": "@entities/delete/v-70270492",
  "language": "en"
}

This will delete the english variant with identifier: v-70270492.

Authorizations:
JSON-Web-Token
Request Body schema: application/json
action
required
string

@entities/delete/{identifier}

language
string
Default: "en"
Enum:"en" "de"

The language of the entity. This decides which translation of the variant is deleted or.

Responses

200

Successful Response

400

Error Response

post /request#deleteEntity
API Test Environment
https://api-stage-cf.psiproductfinder.de/v1/request#deleteEntity
API Live Environment
https://api-cf.psiproductfinder.de/v1/request#deleteEntity

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "action": "@entities/delete/v-70270492",
  • "language": "en"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "id": "6e32f900-4001-11e9-95d1-1fc20bd9b25b",
  • "identifier": "v-70270492"
}

Image Upload Identifier

to upload an image the system needs a unique identifier for each image, it is like an access token to upload one image. First call the endpoint to get the identifier, then upload image with the identifier

Authorizations:
JSON-Web-Token
Request Body schema: application/json
action
required
string

@upload

Responses

200

Successful Response

post /request#getImageUploadIdentifier
API Test Environment
https://api-stage-cf.psiproductfinder.de/v1/request#getImageUploadIdentifier
API Live Environment
https://api-cf.psiproductfinder.de/v1/request#getImageUploadIdentifier

Request samples

application/json
Copy
 Expand all Collapse all
{
  • "action": "@upload"
}

Response samples

application/json
Copy
 Expand all Collapse all
{
  • "identifier": "18f5277e-2af1-45ee-af47-0d16d8291502"
}

Upload Images

Multipart Form - Upload images directly to the productfinder with a unique identifier, the returned urls can be inserted as image urls in the variants

Authorizations:
JSON-Web-Token
Request Body schema: multipart/form-data
action
required
string

@upload

identifier
required
string

this identifier has to be unqiue per image upload, get one with the endpoint described above

image
required
file

The actual image file, must be in jpg format.

Responses

200

Successful Response

post /request#uploadImage
API Test Environment
https://api-stage-cf.psiproductfinder.de/v1/request#uploadImage
API Live Environment
https://api-cf.psiproductfinder.de/v1/request#uploadImage

Response samples

application/json
Copy
 Expand all Collapse all
{}