API (Belege)
Um ein beliebiges Warenwirtschaftssystem oder Rechnungserstellungsprogramm an PayJoe anzubinden, können Sie die API-Belegschnittstelle nutzen.
API-Belegzugang in PayJoe anlegen
1. PayJoe öffnen.
2. Neuen Zugang anlegen:
a. wählen.
b. Das Plus-Symbol rechts unten in der Hauptansicht anklicken:
Die Seite Zugänge > Neu wird geöffnet:
3. Der Schritt-für-Schritt-Eingabe folgen und dabei folgende Daten eingeben:
- Vorgangstyp: Kombinierter Zugang
- Zahlungszugang: Beliebig
- Belegzugang: Neuer Zugang vom Typ API (Belege)
4. Bestätigen Sie Ihre Auswahl mit Weiter.
5. Der Schritt-für-Schritt-Eingabe weiter folgen, bis Sie den Zugang erfolgreich erstellt haben.
- Bevor die Daten an PayJoe übermittelt werden können, muss Ihr Entwickler sie in die geeignete Form bringen und via API an PayJoe übermitteln.
- Ihr Entwickler benötigt dafür u.a. die API-Zugangsdaten. Diese können Sie auch nachträglich in PayJoe einsehen (siehe Zugangsdaten einsehen).
6. Geben Sie die API-Zugangsdaten und die folgenden Informationen aus dem Punkt Informationen für Entwickler an Ihre Entwicklung weiter.
Informationen für Entwickler
- URL für POST-Request: https://api.payjoe.de/belegupload
- Content-Type: JSON
- Tag im Header: Content-Type: application/json
Upload von Belegen
Die Information, ob ein Feld zwingend benötigt wird (m = muss / o = optional) und die maximale Länge der String-Inhalte stehen jeweils als Kommentar hinter den Feldern.
Jeweils eines der folgende Objekte muss im Body des Requests enthalten sein:
string UserName
string APIKey
int ZugangID
PayJoeBeleg[] Belege
// m - 100
// m - 100
// m
// m
Darin sind die oben genannten Zugangsdaten zu setzen sowie ein Array von PayJoeBeleg-Objekten zu übermitteln.
Feldinformationen PayJoe Belege
Folgende Felder können in einem PayJoe Belegdatensatz (PayJoeBeleg) übertragen werden:
int BelegBerichtID
string BelegIDExtern
string BelegMandantenRefID
DateTime Belegdatum
BelegTyp Belegtyp
double BelegBetrag
Waehrung BelegWaehrung
string ZahlungsArt
string BelegVorname
string BelegNachname
string BelegFirma
string BelegExterneBestellNr
string BelegKundenNr
string BelegDebitorenNr
string BelegEmail
string BelegNummer
string BelegReferenz1
string BelegReferenz2
string BelegReferenz3
string BelegReferenz4
string BelegReferenz5
string BelegReferenz6
string BelegReferenz7
string BelegReferenz8
string BelegReferenz9
string BelegReferenz10
// o
// o - 30
// o - 50
// m
// m
// m
// m
// o - 50
// o - 100
// o - 100
// o - 100
// o - 40
// o - 30
// o - 30
// o - 100
// o - 30
// o - 200
// o - 200
// o - 200
// o - 200
// o - 200
// o - 200
// o - 200
// o - 200
// o - 200
// o - 200
Dabei steht BelegTyp = 0 für Rechnung und BelegTyp = 1 für Gutschrift. Dabei können auch die Begrifflichkeiten „Rechnung“ oder „Gutschrift“ übertragen werden.
Als wird der internationale numerische Währungs-Code verwendet: Euro ist dabei beispielsweise 978, US-Dollar 840 und das Britische Pfund 826. Es können dafür auch die Abkürzungen wie beispielsweise „EUR“ oder „USD“ übertragen werden. Weitere Informationen zur Waehrungfinden Sie hier: https://de.wikipedia.org/wiki/ISO_4217.
JSON-Beispiel Beleg
Der Inhalt einer JSON-Nachricht sieht dann beispielsweise für zwei Belege wie folgt aus:
{
"UserName":"kunde@payjoe.de",
"APIKey":"i5YStP:=k[!w",
"ZugangID":818,
"Belege":[{
"BelegBerichtID":23,
"BelegIDExtern":"8711",
"BelegMandantenRefID":"F8",
"Belegdatum":"2015-12-07T13:17:22.2426324+01:00",
"Belegtyp":0,
"BelegBetrag":29.99,
"BelegWaehrung":978,
"ZahlungsArt":"Rechnungskauf",
"BelegVorname":"Max",
"BelegNachname":"Mustermann",
"BelegFirma":null,
"BelegExterneBestellNr":"479873",
"BelegKundenNr":"C637732",
"BelegDebitorenNr":"24338",
"BelegEmail":"max.mustermann@t-online.de",
"BelegNummer":"53427",
"BelegReferenz1":null,
"BelegReferenz2":null,
"BelegReferenz3":null,
"BelegReferenz4":null,
"BelegReferenz5":null,
"BelegReferenz6":null,
"BelegReferenz7":null,
"BelegReferenz8":null,
"BelegReferenz9":null,
"BelegReferenz10":null
},{
"BelegBerichtID":23,
"BelegIDExtern":"8712",
"BelegMandantenRefID":"F8",
"Belegdatum":"2015-12-07T15:47:02.2120334+01:00",
"Belegtyp":0,
"BelegBetrag":79.5,
"BelegWaehrung":978,
"ZahlungsArt":"PayPal",
"BelegVorname":"Monika"
"BelegNachname":"Mustermann",
"BelegFirma":null,
"BelegExterneBestellNr":"479874",
"BelegKundenNr":"C637711",
"BelegDebitorenNr":"24334",
"BelegEmail":"monika.mustermann@gmx.net",
"BelegNummer":"53453",
"BelegReferenz1":null,
"BelegReferenz2":null,
"BelegReferenz3":null,
"BelegReferenz4":null,
"BelegReferenz5":null,
"BelegReferenz6":null,
"BelegReferenz7":null,
"BelegReferenz8":null,
"BelegReferenz9":null,
"BelegReferenz10":null
}]
}
Erfolgsmeldung
Als Antwort bekommen Sie im Erfolgsfall untenstehende Objekte als JSON zurückgeliefert. Das Feld LetztesBuchungsdatum enthält das neueste Datum eines Belegs, das in der Datenbank abgelegt ist. Auf diese Art können Sie den Upload in kleinere Pakete zerteilen. Es wird empfohlen nicht mehr als 500 Belege mit einem Aufruf zu übertragen.
bool Erfolgreich
DateTime LetztesBuchungsdatum
Hier der Inhalt der Antwort bei erfolgreichem Beleg-Upload:
{
"Erfolgreich":true,
"LetztesBuchungsdatum":"2018-01-07T14:50:55.26"
}