Release Notes Public API 1.3

Swagger Dokumentation

• Die aktuelle Swagger Dokumentation finden Sie hier: 

  https://app.paychexplus.de/publicapi/v1.3/
   

Bekanntes, ungewünschtes Verhalten

• zur Zeit keine Themen bekannt

2026-07-21

• Self Service zur Erstellung von API Keys

  • Unter "Unternehmen - Einstellungen - Integration - API-Zugangsdaten" können Sie nun Ihre API Keys einsehen, die Sie für den aktuell angemeldeten User erstellt haben. Dies Übersicht enthält auch die Gültigkeitsdauer und die API Version der Keys.

  • Hier können Sie mit "API Schlüssel erstellen" auch neue API Keys selbst erstellen, und zwar einzeln für jede API Version. Die maximale Gültigkeit beträgt ein Jahr oder die Gültigkeit der gewählten API Version.
    
     

  • Danach wird der Key einmal angezeigt und kann kopiert werden. Bitte speichern Sie sich den Key, er kann nicht erneut angezeigt werden. Geht er verloren, können Sie einen neuen Key erzeugen.
     

  • Nach Abschluss wird der API Key in der Übersicht angezeigt.
    

  • Dieses Feature kann auf Anfrage beim Support freigeschaltet werden. Für Kunden, die bereits API Keys haben, wurde es bereits freigeschaltet.
      

• API Keys werden versionsbezogen

  • Jeder API key bezieht sich von nun an auf eine API Version. Andere Versionen können damit nicht benutzt werden. Benötigen Sie zusätzlich eine andere API Version, legen Sie sich bitten einen zusätzlichen Schlüssel an.

     

• End of Live (EOL) der Api Versionen

  • Ab sofort werden die EOLs von Versionen eingeführt. Wird eine neue Version auf Grund eines Breaking Change nötig, werden die vorherigen Versionen mit einem EOL von 6 Monaten gesetzt. Sind Sie davon betroffen, dann werden die User der API Keys darüber per E-Mail benachrichtigt. Sie haben dann diese 6 Monate Zeit, auf die neuere API Version zu wechseln.

  • Zusätzlich erhalten die User 90, 30, 14, 7 Tage und einen Tag vor dem EOL eine Erinnerung. Danach erfolgt noch eine E-Mail nach erfolgter Deaktivierung.   

  • Bisher haben noch alle Versionen volle Gültigkeit, allerdings werden die Versionen vor der Version 1.3 demnächst mit einer Gültigkeit von 6 Monaten versehen. Wir raten daher dazu, zügig auf die Version 1.3 zu wechseln.
     

• Meldungen an Sozialversicherungen und Finanzämter senden

  • Die Endpunkte /companies/ und /companies/{uid}/ wurden um den Parameter send_messages_to_authorities erweitert.

  • Wenn send_messages_to_authorities auf false gesetzt ist (Standard und bisheriges Verhalten), werden KEINE Meldungen an die Sozialversicherungsträger und Finanzämter gesendet. Dies wird für Testfirmen oder zum Einrichten von Firmen verwendet. Wenn die Firma für echte Lohnabrechnungen verwendet wird, muss send_messages_to_authorities auf true gesetzt werden. Dies kann auch nachträglich mit PUT oder PATCH erfolgen.

2026-06-05

• Das Feld "type_of_taxation" wurde aus dem Endpunkt /companies/{company_uid}/employees/{employee_uid}/march-clausula-preceding-values/ entfernt
   

• Der Endpunkt /companies/{company_id}/billing/ wurde entfernt  
   

2026-05-12

• Anfragebegrenzung (Rate Limiting) pro API Key auf 300 Zugriffe / Minute

  • Dies soll einen stabilen und zuverlässigen Betrieb mit gleichbleibend gute Performance für alle Nutzer sicherstellen, da einzelne Anwendungen nicht mehr die Verfügbarkeit für andere beeinträchtigen können.

  • Wenn dieses Limit überschritten wird, senden wir die Fehlermeldung 429 mit der Angabe der Sekunden, ab dem der Zugriff wieder verfügbar ist (in der Regel unter 60 Sekunden)
     

• Neuer Endpunkt:

  • /companies/{company_uid}/tax-data/

  • Neuer Endpunkt um die Steuerdaten eines Unternehmens zu erfassen

  • GET / PUT / PATCH

• Endpunkt /companies/{company_uid}/employing-companies/{uid}/, Adresse hinzugefügt

  • GET / PUT / PATCH

    • hinzufügen der Felder 

      • Street / street number / Addition to Address / ZIP / City / Country / Federal state

  • Das Feld Address ist kein Pflichtfeld in version 1.3 (um abwärtskompatible zu bleiben), ab Version 1.4 wird es Pflicht.

• Endpunkt /companies/{company_uid}/employing-companies/, Adresse hinzugefügt

  • POST

    • hinzufügen der Felder 

      • Street / street number / Addition to Address / ZIP / City / Country / Federal state

  • Das Feld Address ist kein Pflichtfeld in version 1.3 (um abwärtskompatible zu bleiben), ab Version 1.4 wird es Pflicht.

• Endpunkt /companies/{uid}/, Adresse hinzugefügt

  • GET

    • hinzufügen der Felder 

      • Street / street number / Addition to Address / ZIP / City / Country / Federal state

• Zusätzliche Validierung:

  • /companies/{company_uid}/employees/{employee_uid}/salary-components/
    Es erfolgt eine Überprüfung und Fehlermeldung, wenn die Freigrenze für den Sachbezug überschritten wird (analog zur Frontend). 

2026-04-24

• Fehlerbehebung Geldbetrag: 

  • Im Endpunkt /companies/{company_uid}/employees/{employee_uid}/absence/,  
    Anfrageklasse  MaternityLeaceAbsenceRequest ,
    Feld net_of_other_employments
    wurde bisher der Betrag falsch in Euro übermitttelt. 
    Richtig ist aber (wie alle bei allen Geldbeträgen) Eurocent. 
    Dies wurde nun auf Eurocent umgestellt.
     

• Umbenennung der Billing Transaction Beschreibung

  • Im Endpunkt /companies/{company_uid}/billing/,
    Anfrageklasse transaction_description
    wurden die Beschreibungen von "Paychex Plus" auf "Paychex Europe Payroll" geändert.
     

• Änderungen in der Dokumenten Kategorie UV Jahresmeldungen

  • Alt:

    • UV Jahresmeldungen (mit Personalbezug) (ohne Personalbezug) 

  • Neu:

    • UV Jahresmeldungen (mit Personalbezug) (ohne Personalbezug) 

    • UV Jahresmeldungen gesamt (ohne Personalbezug) 

  • Hinweis zu einem Breaking Change in der nächsten API Version: 
    Ab der nächsten API Version wird UV Jahresmeldungen nur noch mit Personalbezug nutzbar sein. Für Dokumente ohne Personalbezug muss dann UV Jahresmeldungen gesamt genutzt werden.
     

  • Änderungen in der Dokumenten Kategorie Lohnkonten

    • Alt:

      • Lohnkonten (mit Personalbezug) (ohne Personalbezug) 

    • Neu:

      • Lohnkonten (mit Personalbezug) (ohne Personalbezug) 

      • Lohnkonten gesamt (ohne Personalbezug) 

    • Hinweis zu einem Breaking Change in der nächsten API Version: 
      Ab der nächsten API Version wird Lohnkonten nur noch mit Personalbezug nutzbar sein. Für Dokumente ohne Personalbezug muss dann Lohnkonten gesamt genutzt werden.
       

    • Änderungen in der Dokumenten Kategorie Sonstige Auswertungen

      • Alt:

        • Sonstige Auswertungen (mit Personalbezug) (ohne Personalbezug) 

      • Neu:

        • Sonstige Auswertungen (mit Personalbezug) (ohne Personalbezug) 

        • Sonstige Auswertungen gesamt (ohne Personalbezug) 

      • Hinweis zu einem Breaking Change in der nächsten API Version: 
        Ab der nächsten API Version wird Sonstige Auswertungen nur noch mit Personalbezug nutzbar sein. Für Dokumente ohne Personalbezug muss dann Sonstige Auswertungen gesamt genutzt werden.
         

    • Änderungen in der Dokumenten Kategorie Bescheinigungen

      • Alt:

        • Bescheinigungen (mit Personalbezug) 

      • Neu:

        • Bescheinigungen (mit Personalbezug) 

        • Bescheinigungen gesamt (ohne Personalbezug) 
           

2026-01-30

• Die Personalnummer wird auf maximal 9 Zeichen begrenzt.

  • Im Frontend ist die Personalnummer auf 9 Zeichen begrenzt. Dies wurde in den beiden Endpunkten 
    - PUT /companies/{company_uid}/employees/{employee_uid}/contract/
    - PATCH /companies/{company_uid}/employees/{employee_uid}/contract/
    nun ebenfalls eingeführt

• Die Personalnummer muss innerhalb einer Firma eindeutig sein.

  • Im Frontend gibt es bereits die Validierung, dass eine Personalnummer innerhalb einer Firma eindeutig ist. Dies wurde nun im Endpunkt
    - /companies/{company_uid}/employees/{employee_uid}/contract/
    ebenfalls eingeführt.

2025-11-03

• Erstellung der Version 1.3 der Public API

  • Die Versionierung von den API-Schnittstellen gewährleistet Stabilität und unterstützt eine klare Struktur für die Integration und Nutzung durch externe Nutzer. Durch die Versionierung wird sichergestellt, dass bestehende Integrationen und Anwendungen weiterhin mit der API arbeiten können, auch wenn neue Funktionen oder Änderungen hinzugefügt werden.

  • Wir empfehlen die Umstellung und Nutzung dieser Version 1.3