EDI – Vollständige API-Referenz

Fach-API für EDI-Protokolle, die Zuordnung zum Kunden oder Lieferanten und die Übertragung. Basis ist https://core-backend.reybex.com/api (Staging: https://io-staging-partner.reybex.com/api). Authentifizierung wie im API: --header "authorization: Basic $TOKEN".

Verkaufsbelege stehen unter Auftragsverwaltung, Einkaufsbelege unter Einkauf-Verwaltung. Partner unter Kunden- und Lieferantenverwaltung.

Der schreibende Weg des Protokolls ist POST /api/commProtocoll/. Der der Zuordnung ist POST /api/commCustomerConfig/. Der der Nachricht ist POST /api/commMessage/. Der Körper ist der Datensatz selbst, ohne Umschlag. Leere Objekte werden zu null.

1. Grundlagen

Objekt	Rolle
CommProtocoll	Kanal, Nachrichtenart, Richtung und Template
CommCustomerConfig	Partner, Belegart, FTP und Protokoll
CommMessage	Eine Übertragung mit Status und Inhalt

type des Protokolls ist der Kanal, zum Beispiel EDI oder EMAIL. kind ist die Nachrichtenart, zum Beispiel INVOICE, ORDERS oder ORDERDISPATCH. postway 0 ist eingehend, 1 ist ausgehend. Standard ist 1.

Die Zahlen in den Beispielen sind Beispiel-Ids eines Mandanten. 9601 ist das Protokoll. 30001 ist der Partner. 510100 ist ein Einkaufsbeleg.

1.1 Suchschlüssel

Ziel	Suchschlüssel
Partner an anderen Fach-APIs	customerNo
Nummernkreis, E-Mail-Konto	code oder name, sonst id
Protokoll an der Zuordnung	id

Die Zuordnung speichert customerNo als Text, nicht als Partner-Objekt.

1.2 Antwort- und Fehlerformat

Aufruf	Response
Protokoll	{ "commProtocollId": 9601 }
Zuordnung	{ "commCustomerConfigId": 9701 }
Nachricht	{ "commMessageId": 9801 }
Export	{ "success": true }

Situation	Körper
Export ohne Ids	financeExport.ids.not.found
Einkaufsbeleg nicht gefunden	commMessage.exportEdi.purheads.not.found
Versand ohne Nachrichten-Ids	HTTP 404
Fehlende Anmeldung	HTTP 401

2. Protokoll

POST /api/commProtocoll/ legt an, wenn keine id im Körper steht.

2.1 Felder

Feld	Bedeutung
name	Bezeichnung
type	Kanal, EDI oder EMAIL
kind	Nachrichtenart
postway	0 eingehend, 1 ausgehend
template	Freemarker-Template
numberRanges	Nummernkreis der Datei-Id
groupCollectiveBy	Gruppierung der Sammelrechnung. Standard customerNo
emailAccount	Konto bei type EMAIL
sender	Absenderadresse

2.2 Pflichtfelder

Auflösung, wenn ein Pflichtfeld fehlt

Die API setzt Pflicht-Referenzen nicht von selbst. Fehlt ein Feld, in dieser Reihenfolge füllen. Der erste Treffer gilt.

1. Angabe – Wert aus dem Auftrag für dieses Feld.
2. Vorlage – dasselbe Feld aus GET /api/commProtocoll/{id}. id nicht übernehmen. Ist eine Vorlage genannt, diese lesen. Ist keine genannt, keine raten, mit Schritt 3 weiter.
3. Standard – Wert aus der Tabelle.
4. Domäne – Nummernkreis über GET /api/domains/numberRanges?take=1&sort=code, wenn der Auftrag einen Kreis verlangt.
5. Stopp – Name, Kanal oder Art fehlen. Protokoll nicht anlegen.

Feld	Pflicht	Vorlage	Standard	Domäne
name	ja	name	—	—
type	ja	type	EDI	—
kind	ja	kind	—	—
postway	nein	postway	1 ausgehend	—
groupCollectiveBy	nein	groupCollectiveBy	customerNo	—

2.3 Ausgangsrechnung

{
  "name": "Rechnung EDI",
  "type": "EDI",
  "kind": "INVOICE",
  "postway": 1,
  "groupCollectiveBy": "customerNo"
}

Response: { "commProtocollId": 9601 }

Felder eines Belegs für das Template: POST /api/commProtocoll/objectFields.

Lesen: GET /api/commProtocoll/9601. Löschen: DELETE /api/commProtocoll/ mit { "ids": [9601] }. Eine Id, die nicht gelöscht werden kann, steht in fails.

3. Kundenzuordnung

POST /api/commCustomerConfig/

customerNo ist die Partnernummer. docType ist die Belegart als Text. type 0 ist der Standard der Zuordnung. exportMode und saveMode steuern Datei und Ablage. isSecured true ist SFTP.

{
  "customerNo": "KD-1000",
  "customerName": "Nordlicht GmbH",
  "docType": "INVOICE",
  "commProtocoll": { "id": 9601 },
  "ftp": "edi.example",
  "ftpPort": "22",
  "ftpUploadUrl": "/out",
  "user": "edi-user",
  "fileExtension": "edi",
  "isSecured": true,
  "isCollectiveInvoice": false,
  "type": 0,
  "exportMode": 0
}

Response: { "commCustomerConfigId": 9701 }

Verbindung prüfen: POST /api/commCustomerConfig/ftpCheckConnection mit denselben FTP-Feldern.

targetTenant ist die Id des Zielmandanten. Steht sie, wird targetDocType.id nach targetDocTypeId übernommen. Ohne Zielmandant wird targetDocTypeId geleert.

Lesen: GET /api/commCustomerConfig/9701. Löschen: DELETE /api/commCustomerConfig/ mit { "ids": [9701] }.

4. Nachricht

POST /api/commMessage/ speichert eine Nachricht. status, content, docNumber, docType und customerNo beschreiben den Vorgang. tryCount zählt Wiederholungen. isExported true und exportDate markieren den Versand.

{
  "customerNo": "KD-1000",
  "docNumber": "RE-100",
  "docType": "INVOICE",
  "type": "EDI",
  "postway": 1,
  "status": "offen",
  "commCustomerConfig": { "id": 9701 }
}

Response: { "commMessageId": 9801 }

Ausgehende Nachrichten versenden: POST /api/commMessage/exportSalesHeads

{ "commMessageIds": "9801" }

Nur Nachrichten mit postway 1 werden genommen. Fehlt commMessageIds: HTTP 404. Antwort { "success": true }.

Einkaufsbelege exportieren: POST /api/commMessage/exportEdi

{ "ids": [510100] }

Die Ids sind Einkaufsbelege. Ohne Ids: financeExport.ids.not.found. Kein Beleg: commMessage.exportEdi.purheads.not.found. Die Zuordnung muss customerNo und docType des Belegs treffen.

Bestellungen einlesen: GET /api/commMessage/importOrders. Antwort { "success": true }.

Tageszusammenfassung: GET /api/commMessage/sendCommMessageSummary.

Lesen: GET /api/commMessage/9801. Löschen: DELETE /api/commMessage/ mit { "ids": [9801] }.

5. Weitere Beispiele

5.1 Rechnung an den Handelspartner

1. Protokoll INVOICE, postway 1, Abschnitt Ausgangsrechnung.
2. Zuordnung auf customerNo KD-1000 und docType INVOICE.
3. FTP prüfen.
4. Nachricht anlegen oder aus dem Beleg erzeugen.
5. POST /api/commMessage/exportSalesHeads mit der Nachrichten-Id.

6. Endpoint-Katalog

Methode	Pfad	Bedeutung
GET	/api/commProtocoll/{id}	Ein Protokoll oder die Liste
POST	/api/commProtocoll/	Protokoll speichern
DELETE	/api/commProtocoll/	Löschen, Body ids
POST	/api/commProtocoll/objectFields	Template-Felder
GET	/api/commCustomerConfig/{id}	Eine Zuordnung oder die Liste
POST	/api/commCustomerConfig/	Zuordnung speichern
DELETE	/api/commCustomerConfig/	Löschen, Body ids
POST	/api/commCustomerConfig/ftpCheckConnection	FTP prüfen
GET	/api/commMessage/{id}	Eine Nachricht oder die Liste
POST	/api/commMessage/	Nachricht speichern
DELETE	/api/commMessage/	Löschen, Body ids
POST	/api/commMessage/exportSalesHeads	Ausgang versenden, Body commMessageIds
POST	/api/commMessage/exportEdi	Einkaufsbelege, Body ids
GET	/api/commMessage/importOrders	Bestellungen einlesen
GET	/api/commMessage/sendCommMessageSummary	Tageszusammenfassung

7. Häufige Fehler

Situation	Ursache
financeExport.ids.not.found	exportEdi ohne ids
commMessage.exportEdi.purheads.not.found	Keine der Ids ist ein Einkaufsbeleg
HTTP 404 bei exportSalesHeads	commMessageIds fehlt
Versand überspringt die Nachricht	postway ist nicht 1
Keine Datei	Zur customerNo und docType gibt es keine Zuordnung
FTP schlägt fehl	Host, Port, Benutzer oder isSecured passen nicht