Einführung
Die API-Schnittstelle der Print Lounge ermöglicht einen automatisierten, maschinengeeigneten Zugriff auf Daten aus der Print Lounge. Dies ermöglicht eine Integration in interne Prozesse und Tools. Die API ist ein zusätzliches Modul und kann für jeden Mandanten aktiviert werden. Für die Nutzung sind keine speziellen Pakete oder Optionen erforderlich. Die verfügbaren Daten entsprechen den Daten aus der Print Lounge. Auf dieser Seite werden generelle API-Informationen bereitgestellt. Der Abruf von Print Lounge-Daten geschieht über die URL.
API-Authentifizierung
Die Authentifizierung erfolgt durch eine Basic-Authentication. Hierfür werden API-Benutzer und API-Key übermittelt.
Der API-Benutzer/API-Key kann in der Administration unter Verwaltung → Shops → bearbeiten → API gesetzt werden. Beim Passwort wird die Passwortrichtlinie angewendet.
Der API-Benutzer/API-Key muss bei allen Abfragen übermittelt werden. Geschieht dieses nicht oder werden ungültige API-Daten verwendet, meldet die API den Fehlercode „401 Unauthorized“. Um API-Daten zu erhalten, kontaktieren Sie bitte Ihren Shopbetreiber.
Wird bei der Authentifizierung mehrfach ein falsches Passwort verwendet, wird der Zugriff für 15 Minuten gesperrt. Nach der Sperrzeit ist keine manuelle Freischaltung notwendig, dies passiert automatisch und kann anschließend wieder verwendet werden.
Artikel
Verfügbare Daten
Über die API kann auf folgende Daten zugegriffen werden.
URL | Daten | Parameter | Rückgabe |
---|---|---|---|
{*}.print-server.net/api/article.php | Artikel | status = 1|0 offset limit sortby sort = ASC|DESC format = json|serialize|print | Array ( [data] => Array ( [39336] => Array ( [name] => Artikelbezeichung [name_internal] => Artikelbezeichung Intern [created] => 2016-03-01T15:19:41+0100 [changed] => 2016-04-13T12:19:27+0200 ) ) [error] => ) |
Ausgabeformat
Alle Anfragen und Rückgabewerte sind UTF-8 kodiert. Standardmäßig erfolgt die Rückgabe der API-Schnittstelle im Json-Format. Alternativ kann eine serialisierte Rückgabe oder zu Testzwecken auf Ausgabe umgestellt werden. Dafür ist der Parameter „format“ mit dem Wert „json“, „serialize“ oder „print“ an jede URL anzuhängen.
REST-API
Jedes Kommando für die API – Schnittstelle ist eine HTTP Anfrage.
In der URL wird das Ziel, das gewünschte Datenobjekt angegeben und die HTTP Methode (GET, POST, PUT, DELETE) gibt an, was gemacht werden soll.
- GET: Liefert einen oder mehrere Datenobjekte.
- POST: Erstellt ein neues Datenobjekt.
- PUT: Ändert ein bestehendes Datenobjekt.
- DELETE: Löscht ein bestehendes Datenobjekt.
Artikel
HTTP Methode | Pfad | Parameter | Request-Body | Beispiel | Rückgabeformat |
---|---|---|---|---|---|
GET | /api/article | - | http://shop.printlounge.local /api/article | [ 25: Handelsware | |
GET | /api/article/{article-id} | - | http://shop.printlounge.local /api/article/4711 | { |
Verfügbare Daten
Bestellung
HTTP Methode | Pfad | Parameter | Request-Body | Beispiel | Rückgabeformat |
---|---|---|---|---|---|
Fürs eine Auflistung der aktuellsten Bestellungen, siehe Bestellstatus: /api/order/ | [ | ||||
GET | /api/cart/{order-code} | - | https://shop.printlounge.local/api/cart/XABCDE | { "id": 645135 "client_id": 1234 "order_customer_id": 3124 "order_budgetgroup_user_id": 564231 "order_budgetgruppe": "example content" "order_code": "example content" "order_number": 231 "order_desc": "example content" "order_total": 0 "order_deliver_address_company": "example content" "order_deliver_address_company2": "example content" "order_deliver_address_name": "example content" "order_deliver_address_firstname": "example content" "order_deliver_address_lastname": "example content" "order_deliver_address_title": "example content" "order_deliver_address_street": "example content" "order_deliver_address_zip": 12345 "order_deliver_address_town": "example content" "order_deliver_address_country_code": "example content" "order_deliver_address_email": "example content" "order_deliver_address_email2": "example content" "order_payment_method": 0 "order_deliver_address_department": "example content" "order_deliver_address_cost_center": "example content" "order_deliver_address_customer_order_number": "example content" "order_deliver_address_phone": "example content" "order_deliver_address_fax": "example content" "order_deliver_address_country": "example content" "order_bank_code": "example content" "order_bank_name": "example content" "order_depositor": "example content" "order_tax_id": "example content" "invoice_address_company1": "example content" "invoice_address_company2": "example content" "invoice_address_company3": "example content" "invoice_address_title": "example content" "invoice_address_name": "example content" "invoice_address_firstname": "example content" "invoice_address_lastname": "example content" "invoice_address_phone": "example content" "invoice_address_street": "example content" "invoice_address_zip": 12345 "invoice_address_town": "example content" "invoice_address_country": "example content" "invoice_address_country_code": "example content" "order_customer_user_id": 984563 "order_user_name": "example content" "serviceprovider_id": 0 "serviceprovider_x_id": 0 "serviceprovider_status": "example content" "cart_table": 1 "order_express_delivery": 0 "order_express_delivery_surcharge": "example content" "order_delivery_method": "example content" "order_comment": "example content" "order_budget_before": 0.00 "order_budget_booking": 0.00 "order_budget_booking_after": 0.00 "order_status": 62 "order_delivery_date": "example content" "packages": 0 "weight": 0 "barcode": "example content" "order_approval": "example content" "approval_email": "example content" "order_approval_explaination": "example content" "pdate": "example content" "sdate": "example content" "mdate": "example content" "cdate": "example content" "status": 3 "status_paid": 0 "date_paid": "example content" "status_sendmail": 1 "opentrans_status": 0 "printshop": 0 "order_type_print_job": 1 "order_type_pdf": 0 "emailing_name": "example content" "emailing_email": "example content" "emailing_additional_text": "example content" "invoice_number": 0 "individual_order_code": "example content" "individual_order_item_code": 0 "individual_invoice_number": "example content" "individual_order_item_code_invoice": 0 "coupon_code": 0 "payment_interface": 0 "md5_order_consolidation": 0 "md5": "example content" "collective_price_scale": 0 "approved_by": "example content" "order_language": "example content" "order_budged": "example content" "shipping_charges": 9.99 "vat_amount": 0.00 "net_amount": 10.00 "gross_amount": 10.00 "auth_micropayment": "example content" "budgedgroup_discount": 0 "budgedgroup_discount_amount": "example content" "position_feedback": 0 "vat_included": 54 "date_of_invoice": "example content" "cartItems": { "1": { "id": 121314 "client_id": 1234 "order_id": 645135 "parent_id": 0 "type": 1 "aid": 231450 "article_type": 26 "persdata": "example content" "persdata_array": "example content" "additional_fields_array": "example content" "cart_additional_fields_array": "example content" "article_options_remark": "example content" "quantity": 370169 "quantity_value": 1 "remark": "example content" "filename": "example content" "pdf_filenames": "example content" "cost_center": "example content" "mdate": "example content" "cdate": "example content" "rdate": "example content" "r_remark": "example content" "r_short": "example content" "r_email": "example content" "s_desc": "example content" "s_quantity_value": 1 "s_cost_center": "example content" "s_total": "example content" "s_ntotal": 1 "s_vat": 2 "mailing_count": 0 "status": "example content" "send_reminder": 0 "printshop": 0 "payment_interface": 0 "md5": "example content" "show": 1 "jobname": "example content" "premium_interactive_editor": 0 "premium_image_upload": 0 "page_count": 1 "download_count": 0 "article_options": "example content" "pdf_download_only": 0 "local_order_workflow_step_id": 0 "uploadpath": "example content" "direct_download": 0 "cart_addresses_array": 0 "serviceprovider_id": 0 "serviceprovider_status": "example content" "order_number": 133 "do_not_calculate": 0 "postage_graduation": 0 "ftp_checksum": "example content" "ftp_download": 0 "ftp_error": 0 "data_id": 0 "status_sendmail": 1 "reorder": 0 "article_reorder": 0 "voucher": 0 "voucher_id": 0 "voucher_array": "example content" "approval_address_id": 0 "mailing": 0 "report_group_id": 0 } } } |
Bestellstatus
HTTP Methode | Pfad | Parameter | Request-Body | Beispiel | Rückgabeformat |
---|---|---|---|---|---|
GET | /api/order/ | Zum Blättern:
Zum Filtern:
| /api/order/?limit=20&lastSeenId=4711&orderStatus=61&status=1&statusPaid=1 | [ | |
GET | /api/order/{order-code} | - | https://shop.printlounge.local/api/order | { "order_code": "XABCDE" "order_status": 61 } | |
PUT/PATCH | /api/order/{order-code} | - | {"order_status":"137"} | http://shop.printlounge.local/api/order/39293 |
Die folgende Tabelle stellt alle möglichen Statuswerte dar:
Status | Bezeichnung |
---|---|
61 | in Produktion |
62 | im Versand |
63 | geliefert |
69 | Storno |
73 | auf Freigabe warten |
74 | Freigabe abgelehnt |
88 | Freigabe erteilt |
117 | erledigt |
137 | abgerechnet |
140 | warte auf Zahlungsanbieter |
144 | warte auf Kostenfreigabe |
Tracking/Sendungsverfolgung
HTTP Methode | Pfad | Parameter | Request-Body | Beispiel | Rückgabeformat |
---|---|---|---|---|---|
GET | /api/order-tracking/{order-code}[?cart_item_id={cart_item_id}] | cart_item_id=134 | https://shop.printlounge.local:4432/api/order-tracking/PMOAEG?cart_item_id=134 | [ { "id":"134", "delivery_service_id":"6", "delivery_service_name":"Hermes", "delivery_service_tracking_id":"" } ] | |
PUT/PATCH | /api/order-tracking/{order-code} | - | { "tracking_id":"tracking code 123-456-789", "tracking_service_id":2, "cart_item_id":132453 } | http://shop.printlounge.local/api/order/39293 |
Der Parameter tracking_service_id enthält die ID des Zustelldienstes, die zuvor im Backend der Print Lounge angelegt werden muss. Über den optionalen Parameter order_item_id kann die ID der Bestellposition übergeben werden, sofern der Trackingcode nur für eine bestimmte Position hinterlegt werden soll.
Benutzer
Für {user-id} kann die Id oder der username verwendet werden
HTTP Methode | Pfad | Parameter | Request-Body | Beispiel | Rückgabeformat |
---|---|---|---|---|---|
GET | /api/user/{user-id} | http://shop.printlounge.local/api/user/42 | { | ||
PUT/PATCH | /api/user/{user-id} | { | http://shop.printlounge.local/api/user/42 oder | "" |
Adressbuch
HTTP Methode | Pfad | Parameter | Request-Body | Beispiel | Rückgabeformat |
---|---|---|---|---|---|
GET | /api/address-book/ | customer_user_id | http://shop.printlounge.local /api/address-book/ ?customer_user_id=123456 | { | |
GET | /api/address-book/{address-id} | customer_user_id | http://shop.printlounge.local /api/address-book/42 ?customer_user_id=123456 | { "id":"42" “company":"BE.BEYOND", “company_addition":”GmbH", “company_addition2":"& Co KG”, “contact_person":"Herr Mustermann", “first_name":"John", “last_name":"Doe", “street":”Hanns-Martin-Schleyer-Straße", “postcode":"35", “location":"Willich", “phone":”+49 (0) 2154 / 48 09-0", “mail":”info@bebeyond.de”, “cost_location":"4711", } | |
PUT/PATCH | /api/address-book/{address-id} | customer_user_id | { | http://shop.printlounge.local /api/address-book/42 ?customer_user_id=123456 | "" |
Lagerbestand
HTTP Methode | Pfad | Parameter | Request-Body | Beispiel | Rückgabeformat |
---|---|---|---|---|---|
GET | /api/article-stock/{article-id} | http://shop.printlounge.local /api/article-stock/4711 | {"stock":"123"} | ||
PUT/PATCH | /api/article-stock/{article-id} | [addToStock] | {"stock":"500"} | http://shop.printlounge.local /api/article-stock/4711?addToStock=1 | "" |
Wenn der Parameter addToStock gesetzt ist, dann wird der übermittelte Lagerbestand (stock) zum Aktuellen hinzugefügt.
Fehlt dieser Parameter, wird der übermittelte Lagerbestand gesetzt.
Order-Cart
Status
HTTP Methode | Pfad | Parameter | Request-Body | Beispiel | Rückgabeformat |
---|---|---|---|---|---|
GET | /api/order-cart-status/ | order_code | http://shop.printlounge.local /api/order-cart-status/?order_code=PSYADU | [{ | |
GET | /api/order-cart-status/{order-cart-id} | http://shop.printlounge.local /api/order-cart-status/123321 | { | ||
PUT/PATCH | /api/order-cart-status/{order-cart-id} | { "status":"2", "service_provider_status":"3" } | http://shop.printlounge.local /api/order-cart-status/123321 |
In der folgenden Tabelle ist die Zuordnung zwischen Status und der Nummerierung:
Nummer | Order Cart Status | Service Provider Status |
---|---|---|
1 | OK | new |
2 | AUF FREIGABE WARTEN | active |
3 | AUF ZAHLUNG WARTEN | closed |
4 | DRUCKFREIGABE ANFORDERN | storno |
5 | DRUCKFREIGABE ABGELEHNT | cleared |
6 | PACKED | |
7 | SHIPPED | |
8 | FREIGABE ABGELEHNT | |
9 | STORNO | |
10 | GELÖSCHT | |
11 | TEMP |
Details
HTTP Methode | Pfad | Parameter | Request-Body | Beispiel | Rückgabeformat |
---|---|---|---|---|---|
GET | /api/cart-item/{cart-item-id} | http://shop.printlounge.local /api/cart-item/4711 | { |
Infos
HTTP Methode | Pfad | Parameter | Request-Body | Beispiel | Rückgabeformat |
---|---|---|---|---|---|
GET | /api/cart-item/{cart-item-id}/info | https://dev.localhost/api/cart-item/4711/info | [ | ||
GET | /api/cart-item/{cart-item-id}/info/sapNumber | https://dev.localhost/api/cart-item/4711/info/sapNumber | "mySAP-1" |
DHL Mailoptimizer/Portooptimierung
HTTP Methode | Pfad | Parameter | Request-Body | Beispiel | Rückgabeformat |
---|---|---|---|---|---|
PUT/PATCH | /api/dhlmailoptimizer/{process_id} | { "status":"1" } | http://shop.printlounge.local /api/dhlmailoptimizer/PC08E6 |
Rückgabewerte/Response codes
Es wird ein entsprechender HTTP Statuscode zurückgegeben um den Erfolgs- oder Fehlerfall mitzuteilen.
200 OK
GET, PUT oder DELETE Kommando war erfolgreich.
201 Created
POST Kommando war erfolgreich.
400 Bad request
Die Anfrage ist unvollständig oder existiert nicht. Es muss die URL oder Parameter anpepasst werden.
401 Unauthorized
Der Benutzer ist nicht angemeldet.
403 Forbidden
Der Benutzer hat keine Rechte um die Anfrage auszuführen.
404 Not found
Das Ziel konnte nicht gefunden werden.
500 Internal Server Error
Dieser tritt meistens bei Validierungsfehler auf. Die Fehlerinformationen sind im „Body“ der Antwort vorhanden und haben folgenden Aufbau:
{
"error": "Parameter nicht beschreibbar"
}
Alle Anfragen und Rückgabewerte sind UTF-8 codiert. Die Rückgabe erfolgt im Json-Format.
Schnittstelle im Browser testen
Zum Testen kann entweder ein Rest Api Plugin für den Browser installiert werden, oder die Browser-Entwickleroption verwendet werden.
Mit dem Firefox wird die Entwickleroption mit F12 aktiviert. Dort muss dann der Reiter Netzwerkanalyse ausgewählt und die Seite neu geladen werden.
Dort werden alle Netzwerkabfragen aufgelistet. In diesem Beispiel sollte es nur eine Anfrage sein. Diese müsste markiert werden, dann öffnet sich zur rechten Details.
In den Details wird die Antwort vom Server ordentlich als JSON dargestellt:
Bei der Kopfzeile kann durch Bearbeiten und erneut senden die einzelnen Funktionen getestet werden. Hierfür auf den entsprechenden Button geklickt werden:
Für ein PUT muss das GET aus der oberen linken Box abgeändert werden. Ebenso muss im Request-Body der zu ändernden Parameter wie folgt angegeben werden:
{"order_status":"117"}
Durch das Betätigen des Knopfes "Senden" wird die überarbeitete Anfrage versendet.
Wird ein Status-Code 200 zurückgegeben, ist dies erfolgreich gewesen. Bei anderen gibt es eine entsprechende Fehlermeldung in der Antwort.