API (OP-Belege)
Um über die PayJoe-API Offene Posten automatisiert übertragen zu können, müssen Sie zunächst einen entsprechenden Zugang anlegen.
API-OP-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 (OPBelege)
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/opbelegupload
- Content-Type: JSON
- Tag im Header: Content-Type: application/json
Upload von OP-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 OPBelegZugangID
ARRAY[] OPAuftragsposten
// m - 100
// m - 100
// m
// m
Darin sind die oben genannten Zugangsdaten zu setzen sowie ein Array von PayJoe-Objekten zu übermitteln.
Feldinformationen PayJoeOP-Belege
Folgende Felder können in einem PayJoe Belegdatensatz (PayJoeOPBeleg) übertragen werden:
OPAuftragsposten
objekt OPBeleg
objekt OPBelegLieferadresse
objekt OPBelegRechnungsadresse
ARRAY[] OPBelegposition
// m
// m
// m
// m
OPBeleg
int OPBelegZugangID
OPBelegTyp OPBelegtyp
string OPZahlungsArt
string OPBelegHerkunft
DateTime OPBelegdatum
string OPBelegNummer
string OPBelegKundenNr
string OPBelegDebitorenNr
string OPBelegBestellNr
Waehrung OPBelegWaehrung
string OPBelegUstID
string OPBelegTransaktionsID
DateTime OPBelegFaelligBis
string OPBelegReferenz1
string OPBelegReferenz2
string OPBelegReferenz3
string OPBelegReferenz4
string OPBelegReferenz5
// m
// m
// o - 50
// o
// m
// m - 30
// o - 30
// o - 30
// o - 40
// o
// o
// o
// o
// o - 200
// o - 200
// o - 200
// o - 200
// o - 200
OPBelegLieferadresse / OPBelegRechnungsadresse
string OPBelegAdresseLand
string OPBelegAdresseFirma
string OPBelegAdresseName
string OPBelegAdresseVorname
string OPBelegAdresseEmail
string OPBelegAdresseStrasse
string OPBelegAdressePLZ
string OPBelegAdresseOrt
// m
// m
// m
// m
// m
// m
// m
// m
OPBelegposition
OPBelegBuchungstext OPBelegBuchungstext
string OPSteuerschluessel
string OPBelegKostenstelle
string OPBelegKostentraeger
float OPBelegPostenGesamtNetto
float OPBelegPostenGesamtBrutto
float OPBelegSteuersatz
string OPBelegHabenKonto
string OPBelegSollKonto
// m
// o
// o
// o
// m
// m
// m
// m
// m
Dabei steht OPBelegTyp = 0 für Rechnung und OPBelegTyp = 1 für Gutschrift. Dabei können auch die Begrifflichkeiten „Rechnung“ oder „Gutschrift“ übertragen werden.
Als Waehrung 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 Waehrung finden Sie hier: https://de.wikipedia.org/wiki/ISO_4217.
Dabei steht OPBelegBuchungstext = 0 für die Artikelposition, OPBelegBuchungstext = 1 für GutscheinRabatt und
OPBelegBuchungstext = 2 für Versandkosten.
OPBelegPositionen dürfen nur entweder den Parameter OPBelegHabenKonto oder den Parameter OPBelegSollKonto gesetzt haben, nicht beide gleichzeitig. Wenn keines von beiden gesetzt ist, muss dafür OPBelegAdresseLand der OPBelegLieferadresse einen Wert enthalten.
Ein OPBeleg ist anhand seines OPBelegdatum und seiner OPBelegNummer eindeutig bestimmt und kann in dieser Form nur einmal hochgeladen werden.
Eine OPBelegPosition ist anhand folgender Kombination von Parametern eindeutig bestimmt und kann in dieser Konstellation nur einmal hochgeladen werden: OPBelegdatum und OPBelegNummer (beides aus dem OPBeleg-Objekt), OPBelegHabenKonto oder. OPBelegSollKonto, OPBelegBuchungstext und OPBelegSteuersatz.
Werden bereits hochgeladene OPBelege bzw. OPBelegPositonen erneut hochgeladen, wird der komplette OPAuftragsposten mit entsprechender Fehlermeldung abgelehnt.
Es werden nicht mehr als 500 OPAuftragsposten pro Request angenommen.
JSON-Beispiel OP-Beleg
Der Inhalt einer JSON-Nachricht sieht dann beispielsweise wie folgt aus:
{
"UserName":"kunde@payjoe.de",
"APIKey":"i5YStP:=k[!w",
"OPBelegZugangID":431,
"OPAuftragsposten":[{
"OPBeleg" :{
"OPBelegZugangID":431,
"OPBelegtyp":0,
"OPZahlungsArt":"Rechnungskauf",
"OPBelegHerkunft":"Webshop",
"OPBelegdatum":"2015-12-07T13:17:22.2426324+01:00",
"OPBelegNummer":"546985",
"OPBelegKundeNr":"C637732",
"OPBelegDebitorenNr":"1265",
"OPBelegBestellNr":"512G5OSG",
"OPBelegBelegWaehrung":978,
"OPBelegUstID":"549562214558"
"OPBelegTransaktionsID":"55GK45SGW58"
"OPBelegFaelligBis":"2015-12-07T13:17:22.2426324+01:00",
"OPBelegReferenz1":null,
"OPBelegReferenz2":null,
"OPBelegReferenz3":null,
"OPBelegReferenz4":null,
"OPBelegReferenz5":null
},
"OPBelegLieferadresse" :{
"OPBelegAdresseLand":"Deutschland",
"OPBelegAdresseFirma":"Muster GmbH",
"OPBelegAdresseName":"Mayer",
"OPBelegAdresseVorname":"Max",
"OPBelegAdresseEmail":"max.muster@web.de",
"OPBelegAdresseStrasse":"Marienstrasse 7",
"OPBelegAdressePLZ":"73230",
"OPBelegAdresseOrt":"Kirchheim unter Teck"
},
"OPBelegRechnungsadresse" :{
"OPBelegAdresseLand":"Deutschland",
"OPBelegAdresseFirma":"Muster GmbH",
"OPBelegAdresseName":"Mayer",
"OPBelegAdresseVorname":"Max",
"OPBelegAdresseEmail":"max.mayer@web.de",
"OPBelegAdresseStrasse":"Marienstrasse 7",
"OPBelegAdressePLZ":"73230",
"OPBelegAdresseOrt":"Kirchheim unter Teck"
},
"OPBelgeposition" :[{
"OPBelegBuchungstext":"2",
"OPSteuerschluessel":"3",
"OPBelegKostenstelle":"Materiallager",
"OPBelegKostentraeger":"Produkt1",
"OPBelegPostenGesamtNetto":"250",
"OPBelegGesamtBrutto":"297,50",
"OPBelegSteuersatz":19.0,
"OPBelegHabenKonto":null,
"OPBelegSollKonto":"3400"
}]
}]
Rückmeldung
Als Antwort bekommen Sie im Erfolgsfall untenstehende Objekte als JSON zurückgeliefert. Das Feld LetztesOPBelegdatum enthält das neueste Datum eines OPBelegs, 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 OPBelege mit einem Aufruf zu übertragen.
Erfolgreich Erfolgreich/nicht erfolgreich (boolean)
LetztesOPBelegdatum DateTime
Fehlerliste Array von Fehlerobjekten
Hier der Inhalt der Antwort bei erfolgreichem Beleg-Upload:
{
"Erfolgreich":true,
"LetztesOPBelegdatum":"2018-01-07T14:50:55.26"
}