NAV Navbar

Overview

Introduction

The 3POS Public API operates over HTTPS and uses JSON as its data format.

API Host: https://publicapi.3pos.de

Getting Started

First you will need API credentials. You can get them over the POS / Admin Menu. There you can decide which modules / rights the API Credentials shall get.

Auth credentials consists of an API Code and API Key.

Authentication

All requests to the API must be authenticated with the API credentials. Include your API Token and your API Key in every request you send to the API with the 3POSTOKEN and 3POSKEY HTTP header.

Headers
3POSTOKEN: <token>
3POSKEY: <key>

You can also include the following parameters in your request body as JSON to send the API Credentials to the API.

Parameter Type Description
apiToken string
apiKey string

Itemgroups

Get itemgroups

Returns all itemgroups

HTTP Request

POST https://publicapi.3pos.de/get/itemgroups/

Request headers

Content-Type: application/json

Request

Request body

{
    "displayAll": 1,
    "start": 0,
    "limit": 2
}
Parameter Type Description
start number Set start with entry optional
limit number Set limit of recieved Itemgroup entries optional
displayAll number If set to 1, all itemgroups will be displayed. Also itemgroups which are hidden in POS system optional

Response headers

Content-Type: application/json

Response body

{
    "success": true,
    "result": [
        {
            "id": 1,
            "itemGroupName": "Eis außer Haus",
            "isChildOf": 0
        },
        {
            "id": 2,
            "itemGroupName": "Kindereisbecher",
            "isChildOf": 0
        }
    ]
}

Items

Get items

Returns all items

HTTP Request

POST https://publicapi.3pos.de/get/items/

Request headers

Content-Type: application/json

Request

Request body

{
    "displayAll": 1,
    "start": 0,
    "limit": 2,
    "itemType": 1,
    "filterType": 1,
    "filterVar": 2
}
Parameter Type Description
start number Start optional
limit number Limit optional
filterType number 1: filter by itemgroup
2: filter by itemname
3: filter by EAN
4: filter by internal item number		 optional
filterVar string / number When using this parameter, it is required to set the parameter filterType optional
itemType number 1: items
2: garnish
3: inventory items
4; ingredients		 optional
displayAll number If set to 1, all items will be displayed. Also items which are hidden in POS system optional

Response headers

Content-Type: application/json

Response body

{
    "success": true,
    "result": [
        {
            "id": 11,
            "ean": "21000001",
            "internWareID": "",
            "itemName": "Caffe Creme 0,2 l",
            "itemGroupID": 2,
            "buyingPriceNet": 0.08,
            "sellingPriceNet": 1.932773,
            "sellingPriceTotal": 2.3,
            "itemWeight": 0,
            "itemDescription": "",
            "taxValuePercent": 19
        },
        {
            "id": 34,
            "ean": "21000003",
            "internWareID": "",
            "itemName": "Cappuccino 0,2 l",
            "itemGroupID": 2,
            "buyingPriceNet": 0,
            "sellingPriceNet": 2.101,
            "sellingPriceTotal": 2.5,
            "itemWeight": 0,
            "itemDescription": "",
            "taxValuePercent": 19
        }
    ]
}

Get item

Returns item

HTTP Request

POST https://publicapi.3pos.de/get/item/

Request headers

Content-Type: application/json

Request

Request body

{
    "item": 173
}
Parameter Type Description
item number ID of the item

Response headers

Content-Type: application/json

Response body

{
    "success": true,
    "result": {
        "id": 173,
        "ean": "11001003",
        "internWareID": "",
        "itemName": "Buy one get one free",
        "itemGroupID": 19,
        "buyingPriceNet": 0,
        "sellingPriceNet": 1.260504,
        "sellingPriceTotal": 1.5,
        "itemWeight": 0,
        "itemDescription": "",
        "taxValuePercent": 19,
        "mealSizes": [
            {
                "id": 1,
                "sizeName": "klein",
                "price": 0.00
            }   
        ]
    }
}

Get item extras

Return extras of item

HTTP Request

POST https://publicapi.3pos.de/get/itemExtras/

Request headers

Content-Type: application/json

Request

Request body

{
    "item": 2
}
Parameter Type Description
item number ID of the item
mealSize number ID of the mealsize optional

Response headers

Content-Type: application/json

Response body

{
  "success": true,
  "result": [
    {
      "id": 1,
      "name": "Saucen",
      "position": 1,
      "minChoose": 0,
      "maxChoose": 5,
      "extras": [
        {
          "id": 1,
          "extraName": "Ketchup",
          "sellingPriceTotal": 0.49
        },
        {
          "id": 2,
          "extraName": "Mayo",
          "sellingPriceTotal": 0.79
        }
      ]
    }
  ] 
}

Get item image

Return Base64 encoded image of item

HTTP Request

POST https://publicapi.3pos.de/get/itemImage/

Request headers

Content-Type: application/json

Request

Request body

{
    "item": 25
}
Parameter Type Description
item number ID of the item

Response headers

Content-Type: application/json

Response body

{
    "success": true,
    "result": {
        "base64Image": "data:image/jpeg;base64,/9j/4AAQ ...."
    }
}

Sale

Create sale

Creates a sale

HTTP Request

POST https://publicapi.3pos.de/create/sale/

Request headers

Content-Type: application/json

Request

Request body

{
    "posVersion": "retail",
    "saleAction": "cashout",
    "paymentType": 1,
    "moneyGiven": 15.8,
    "orderID": 0,
    "printPDF": true,
    "items": [
        {
            "id": 259,
            "quantity": 1,
            "price":9.99,
            "description": "ITEM DESCRIPTION STRING",
            "freeText": "Without milk",
            "extras": [
                {
                    "id": 1,
                    "price": 0,
                    "quantity": 1
                },
                {
                    "id": 2,
                    "price": 0,
                    "quantity": 1
                }
            ],
            "mealSizeID": 0
        }
    ],
    "customer": {
        // Use ID for existing customer
        "id": 1,
        // Or create new customer
        "firstName": "Max",
        "lastName": "Mustermann",
        "email": "max@mustermann.de",
        "street": "Schauenburgerstraße 116",
        "zip": 12345,
        "city": "Kiel",
        "country": "DE",
        "phone": "043112345"
    },
    "customerShippingAddress": {
        "firstName": "Max2",
        "lastName": "Mustermann2",
        "email": "max@mustermann.de2",
        "street": "Schauenburgerstraße 2",
        "zip": 12345,
        "city": "Kiel2",
        "country": "DE",
        "phone": "043112345"
    },
    "customerBillingAddress": {
        "firstName": "Max3",
        "lastName": "Mustermann3",
        "email": "max@mustermann.de3",
        "street": "Schauenburgerstraße 3",
        "zip": 12345,
        "city": "Kiel3",
        "country": "DE",
        "phone": "043112345"
    }
}
Parameter Type Description
posVersion string Gastro, Retail, Facture, Delivery
saleAction string cashout
paymentType number 1: Cash
2: Voucher
3: EC
4: Invoice
5: ELV
9: Creditcard
moneyGiven number
printPDF boolean Returns the document as base64 mime multi-part email attachment (RFC 2045)
orderID number Order ID optional
items array Contains the items as object of the sale - For example: look at the JSON Request
customer object Search customer by id, when customer does not exists, a new one will be created optional
customerShippingAddress object Provide a customer shipping address optional
customerBillingAddress object Provide a customer billing address. This will replace the customer data for the created pdf invoice optional

Response headers

Content-Type: application/json

Response body

{
    "success": true,
    "result": {
        "invoiceID": 1060,
        "pdf": "Content-Type: application/pdf;\r\n name=\"\"\r\nContent-Transfer-Encoding: base64\r\nContent-Disposition: attachment;\r\n filename=\"\"\r\n\r\nJVBERi0xLjcKJeLjz9MKN ...",
        "tickets": [
            {
                "id": 1,
                "code": "75c448c8-c8ba-11e9-a32f-2a2ae2dbcce4",
                "position": 1
            },
            {
                "id": 21,
                "code": "8ecc5cd4-c8ba-11e9-a32f-2a2ae2dbcce4",
                "position": 2
            },
            {
                "id": 451,
                "code": "94040512-c8ba-11e9-a32f-2a2ae2dbcce4",
                "position": 3
            }
        ],
        "customerID": 1
    }
}

Payment

Get additional payment options

Returns the additional payment options

HTTP Request

POST https://publicapi.3pos.de/get/additionalPaymentOptions/

Request headers

Content-Type: application/json

Response headers

Content-Type: application/json

Response body

{
    "success": true,
    "result": [
        {
            "id": 500,
            "name": "Payment Option 1"
        },
        {
            "id": 501,
            "name": "Payment Option 2"
        }
    ]
}

Customers

Get customers

Returns all customers

HTTP Request

POST https://publicapi.3pos.de/get/customers/

Request headers

Content-Type: application/json

Request

Request body

{
    "start": 0,
    "limit": 1,
    "filterType": 1,
    "filterVar": "inqsfhhdnw@Googlemail.Com"
}
Parameter Type Description
start number Start optional
limit number Limit optional
filterType number 1: email
2: lastName
3: company
4: zip
5: city		 optional
filterVar string Is required when using filerType optional

Response headers

Content-Type: application/json

Response body

{
    "success": true,
    "result": [
        {
            "id": 184,
            "company": "",
            "firstName": "MANUEL WALTER",
            "lastName": "BAEHR",
            "street": "Duepenweg 2",
            "zip": "46338",
            "city": "Wolfsburg",
            "country": "DE",
            "email": "inqsfhhdnw@Googlemail.Com"
        }
    ]
}

Get customer

Returns all customers

HTTP Request

POST https://publicapi.3pos.de/get/customer/

Request headers

Content-Type: application/json

Request

Request body

{
    "customer": 184
}
Parameter Type Description
customer number CustomerID optional

Response headers

Content-Type: application/json

Response body

{
    "success": true,
    "result": {
        "id": 184,
        "company": "",
        "firstName": "MANUEL WALTER",
        "lastName": "BAEHR",
        "street": "Duepenweg 2",
        "zip": "46338",
        "city": "Wolfsburg",
        "country": "DE",
        "email": "inqsfhhdnw@Googlemail.Com"
    }  
}