add

Belege > REST Resource: receipts.v2 > add

Es ist möglich, über diese Methode zwei Szenarien zum Hinzufügen von Belegen in die Datenbank zu verwenden.

Direkte Zuordnung des Belegs zu einem App Nutzer

In diesem Fall steht die interne ID des App Nutzers zur Verfügung, zum Beispiel durch das Scannen des individuellen QR-Codes des App Nutzers (in der App > Übersicht > Neuer epap). Diese ID wird als userId im Request JSON Body gesendet und der Nutzer wird umgehend über einen neuen epap in der App informiert.

Indirekte Zuordnung des Belegs über einen QR-Code

In diesem Fall wird die interne ID des App Nutzers nicht benötigt, sodass auch die epap App für den Erhalt eines Belegs nicht erforderlich ist. Das Feld userId im Request JSON Body wird nicht gesendet und als Antwort wird ein QR-Code generiert, wobei sowohl eine Download-URL für den QR-Code als auch der dynamische Link, d.h. der Inhalt des QR-Codes, verfügbar sind. Im Hintergrund wird die Erstellung eines PDF Belegs begonnen. Scannt ein Kunde den QR-Code und hat die epap App auf dem Smartphone installiert, öffnet sich diese und der epap ist umgehend verfügbar. Ist die epap App nicht vorhanden, wird der Kunde auf eine Webseite geleitet, auf der der PDF Beleg zum Download zur Verfügung steht und optional auch in einem späteren Schritt in die epap App hinzugefügt werden kann.

post
add

https://europe-west1-epap-fg44.cloudfunctions.net/receipts/v2/add
Fügt einen Beleg zur Datenbank und unter Angabe der individuellen ID des App Nutzers auch bei diesem in der App hinzu.
Request
Response
Request
Headers
Authorization
required
string
Access Token im Format Bearer [ACCESS_TOKEN], wobei [ACCESS_TOKEN] der im Login Vorgang generierte Token ist.
client_id
required
string
Die ID des Clients. Von epap vergeben.
content-type
required
string
application/JSON
Body Parameters
userId
optional
string
Die interne ID des App Nutzers. Diese ID kann aus dem individuellen QR-Code des App Nutzers ausgelesen werden (in der App > Übersicht > Neuer epap).
category
required
string
enum (Category)
currencyISOCode
optional
string
Währungscode nach ISO 4217. Default: EUR
amount
required
string
Gesamtbetrag des Belegs (Brutto).
amountBeforeTaxes
optional
string
Gesamtbetrag des Belegs (Netto).
timestamp
required
string
Zeitpunkt der Belegerstellung in ISO 8601 Format. Beispiele: "2020-07-30T17:15:40.500Z" "2020-07-30T19:15:40.500+02:00"
receiptNumber
required
string
Belegnummer.
additionalInformation
optional
string
Frei wählbare, zusätzliche Informationen. Beispiel: "Es bediente Sie Frau/Herr Müller."
advertisement
optional
string
Ein Werbefeld, das HTML akzeptiert und in der App darstellt.
loyaltyProgram
optional
object
object (LoyaltyProgram)
store
required
object
object (Store)
securityInformation
optional
object
object (SecurityInformation)
coupons[]
optional
array
object (Coupon)
items[]
required
array
object (Item)
payments[]
required
array
object (Payment)
Response
200: OK
Mögliche erfolgreiche Antworten sind: • Der Beleg wurde erfolgreich zur Datenbank hinzugefügt und der App Nutzer wurde über einen neuen epap informiert. • Der Beleg wurde erfolgreich zur Datenbank hinzugefügt, ein PDF Beleg wird im Hintergrund erstellt und ist über den QR-Code verfügbar.
{
"data": {
"epap_id": epapId
},
"message": "Successfully added receipt. The user has been notified about a new epap.",
"status": "OK",
"status_code": 200
}
{
"data": {
"epap_id": epapId,
"qr_code_download_url": downloadUrl,
"short_dynamic_link": shortDynamicLink
},
"message": "Successfully added receipt. Pdf file is being generated and is available via qr code.",
"status": "OK",
"status_code": 200
}
400: Bad Request
Mögliche Ursachen sind: • Ein erforderlicher Parameter im Request Header fehlt, wobei [KEY] der Name des betreffenden Parameters ist. • Ein erforderlicher Parameter im Request Body fehlt, wobei [KEY] der Name des betreffenden Parameters ist.
{
"message": "Required key '[KEY]' in request headers is missing with no default. The server cannot process your request because the syntax is not valid. For detailed information visit www.docs.epap.app or contact us at contact@epap.app.",
"status": "Bad Request",
"status_code": 403
}
{
"message": "Required key '[KEY]' in request body is missing with no default. The server cannot process your request because the syntax is not valid. For detailed information visit www.docs.epap.app or contact us at contact@epap.app.",
"status": "Bad Request",
"status_code": 403
}
403: Forbidden
Mögliche Ursachen sind: • Die Client-ID ist unbekannt. • Der Access Token und damit die Authentifizierung ist abgelaufen. Zur weiteren Nutzung der Receipts API muss ein neuer Token generiert werden.
{
"message": "Value of key 'client_id' in request headers is unknown. The server cannot process your request because the syntax is not valid. For detailed information visit www.docs.epap.app or contact us at contact@epap.app.",
"status": "Forbidden",
"status_code": 403
}
{
"message": "Authorization for request has expired. Please generate a fresh access token. For detailed information visit www.docs.epap.app or contact us at contact@epap.app.",
"status": "Forbidden",
"status_code": 403
}
406: Not Acceptable
Mögliche Ursachen sind: • Der Wert eines Parameters im Request Header weist nicht den erwarteten Typ auf, wobei [KEY] der Name des betreffenden Parameters ist. • Der Request Body hat kein JavaScript Object Notation (JSON) Format. • Der Wert eines Parameters im Request Body weist nicht den erwarteten Typ auf, wobei [KEY] der Name des betreffenden Parameters ist und [...] eine genaue Beschreibung, welcher Typ erwartet wird. • Der Wert eines Parameters im Request Body ist nicht teil der unterstützten Enumeration-Elemente, wobei [KEY] der Name des betreffenden Parameters ist und [...] eine genau Beschreibung, welche Enumeration erwartet wird.
{
"message": "Type of key '[KEY]' in request headers is not a string. The server cannot process your request because the syntax is not valid. For detailed information visit www.docs.epap.app or contact us at contact@epap.app.",
"status": "Not Acceptable",
"status_code": 406
}
{
"message": "The request body is not a JSON object. The server cannot process your request because the syntax is not valid. For detailed information visit www.docs.epap.app or contact us at contact@epap.app.",
"status": "Not Acceptable",
"status_code": 406
}
{
"message": "Type of key '[KEY]' in request body is [...]. The server cannot process your request because the syntax is not valid. For detailed information visit www.docs.epap.app or contact us at contact@epap.app.",
"status": "Not Acceptable",
"status_code": 406
}
{
"message": "Value of key '[KEY]' in request body is not a supported [...] type. The server cannot process your request because the syntax is not valid. For detailed information visit www.docs.epap.app or contact us at contact@epap.app.",
"status": "Not Acceptable",
"status_code": 406
}
500: Internal Server Error
Ein interner Fehler bei der Verarbeitung der Request ist aufgetreten. In diesem Fall kontaktieren Sie bitte contact@epap.app.
{
"message": "An unknown error occured. Please contact us at contact@epap.app",
"status": "Internal Server Error",
"status_code": 500
}

Musterbody

{
"userId": "[USER_ID]",
"category": "FOOD",
"currencyISOCode": "EUR",
"amount": 157.31,
"amountBeforeTaxes": 135.83,
"timestamp": "2020-07-30T19:15:40.500+02:00",
"receiptNumber": "9988776655",
"additionalInformation": "Es bediente Sie Frau/Herr Müller.",
"advertisement": "<h1>Hier könnte Ihre Werbung stehen</h1>",
"loyaltyProgram": {
"awardUnit": "POINTS",
"description": "Das neue Bonusprogramm der epap GmbH",
"memberEmail": "contact@epap.app",
"memberId": "100200300",
"memberName": "epap Contact",
"memberStatus": "Gold",
"name": "BonusProgram 1",
"newUnits": 25,
"totalUnits": 1234
},
"securityInformation": {
"endTimestamp": "2020-07-30T19:15:40.500+02:00",
"hardwareId": "955002-00",
"qrCodeString": "V0;955002-00;Kassenbeleg-V1;Beleg^0.00_2.55_0.00_0.00_0.00^2.55:Bar; 18;112;2019-07-10T18:41:04.000Z;2019-07-10T18:41:04.000Z;ecdsa-plain- SHA256;unixTime;MEQCIAy4P9k+7x9saDO0uRZ4El8QwN+qTgYiv1DIaJIMWRiuAiAt+saFDGjK2Yi5Cxgy7PprXQ5O0seRgx4ltdpW9REvwA==;BHhWOeisRpPBTGQ1W4VUH95TXx2 GARf8e2NYZXJoInjtGqnxJ8sZ3CQpYgjI+LYEmW5A37sLWHsyU7nSJUBemyU=",
"startTimestamp": "2020-07-30T19:15:35.500+02:00",
"signature": "MEQCIAy4P9k+7x9saDO0uRZ4El8QwN+qTgYiv1DIaJIM- WRiuAiAt+saFDGjK2Yi5Cxgy7PprXQ5O0seRgx4ltdpW9REvwA==",
"signatureCounter": "112",
"transactionNumber": "18",
"type": "TSE"
},
"store": {
"address": "Walderseestr. 7, 30419 Hannover, Deutschland",
"chain": "epap GmbH",
"chainId": "r1U8Rg33HRajPfUzZvu3",
"description": "Hannover",
"email": "contact@epap.com",
"name": "epap",
"openingTimes": [
"MO - SA: 08:00 - 21:00 Uhr"
],
"phone": "+49 123 45678910",
"placeId": "ChIJvzgjKnVzsEcRv2a-KizpyGI",
"storeId": "12345",
"ustId": "DE999999999",
"website": "www.epap.app"
},
"coupons": [
{
"code": "123456789",
"codeType": "BARCODE",
"description": "Sample barcode coupon.",
"validFrom": "2020-09-01T00:00:00+02:00",
"validUntil": "2020-09-30T24:00:00+02:00"
},
{
"code": "123456789",
"codeType": "QR",
"description": "Sample qr code coupon.",
"validFrom": "2020-09-01T00:00:00+02:00",
"validUntil": "2020-09-30T24:00:00+02:00"
}
],
"items": [
{
"amount": 0.85,
"amountBeforeTaxes": 0.79,
"bestBefore": "2020-08-05T00:00:00+02:00",
"category": "FOOD",
"description": "Any additional description",
"factor": 0.314,
"gtin": "1020304050",
"name": "Paprika Rot",
"pricing": [
{
"amount": 0.94,
"amountBeforeTaxes": 0.88,
"type": "BASE_PRICE"
},
{
"amount": 0.09,
"amountBeforeTaxes": 0.08,
"percentage": 0.1,
"taxPercentage": 0.0935,
"type": "DISCOUNT"
}
],
"taxPercentage": 0.07,
"type": "PRODUCT",
"unit": "KILOGRAM",
"unitPrice": 2.99,
"unitPriceBeforeTaxes": 2.79
},
{
"amount": 2.22,
"amountBeforeTaxes": 2.07,
"bestBefore": "2020-08-05T00:00:00+02:00",
"category": "FOOD",
"description": "Any additional description",
"gtin": "0123456789",
"name": "Avocados",
"quantity": 2,
"taxPercentage": 0.07,
"type": "PRODUCT",
"unitPrice": 1.11,
"unitPriceBeforeTaxes": 1.04
},
{
"amount": 154.24,
"amountBeforeTaxes": 132.97,
"category": "TECH",
"description": "Mehr Informationen finden Sie unter www.kafeemaschine.de!",
"gtin": "1122334455",
"name": "Kaffeemaschine",
"pricing": [
{
"type": "BASE_PRICE",
"amount": 184.24,
"amountBeforeTaxes": 158.83
},
{
"type": "DISCOUNT",
"amount": 30,
"amountBeforeTaxes": 25.86,
"description": "30€ geschenkt"
}
],
"taxPercentage": 0.16,
"type": "PRODUCT",
"warrantyUntil": "2025-07-30T24:00:00+02:00"
}
],
"payments": [
{
"amount": 87.31,
"cardNumber": "###############1019 0000",
"cardTerminalhardwareId": "03403439",
"cardType": "Mastercard",
"contactless": true,
"description": "Any additional description",
"timestamp": "2020-07-30T19:15:40.500+02:00",
"transactionNumber": "12345678",
"type": "CARD"
},
{
"amount": 30,
"amountChange": 0,
"description": "Any additional description",
"timestamp": "2020-07-30T19:15:40.500+02:00",
"transactionNumber": "12345678",
"type": "CASH"
},
{
"amount": 5,
"description": "Any additional description",
"timestamp": "2020-07-30T19:15:40.500+02:00",
"transactionNumber": "12345678",
"type": "MISC"
},
{
"amount": 10,
"description": "Any additional description",
"provider": "Paypal",
"timestamp": "2020-07-30T19:15:40.500+02:00",
"transactionNumber": "12345678",
"type": "ONLINE"
},
{
"amount": 25,
"description": "Any additional description",
"timestamp": "2020-07-30T19:15:40.500+02:00",
"transactionNumber": "12345678",
"type": "VOUCHER"
}
]
}