OCT-Datenintegration

Inhalte der hr:exchange API (i)

Diese Seite verschafft einen Überblick über den Umfang der hr:exchange API. Die Beispiele zeigen die vollständige Feldlisten mit Beispielwerten.


/client-data

Response mit Beispielwerten

JSON
  {
    "name": "Mandant 1 GmbH"
    "current_accounting_month": "2026-08-01",
    "is_test_client": false,
    "salary_types": [
        {"id": 1, "name": "Festbez. vert. Kst/Std"},
        {"id": 2, "name": "Lohngruppe"}
      ]

    ,"cost_centers": [
        {"id": "1509000", "name": "Zentralverwaltung Allgemein"},
        {"id": "1509001", "name": "Geschäftsleitung"}
      ]

    ,"health_insurers": [
        {"company_number_of_health_insurer": "29720865", "name": "AOK Niedersachsen. Die"},
        {"company_number_of_health_insurer": "05174740", "name": "AOK PLUS Die Gesundhei"} 
      ]

    ,"business_units": [
        {"id": "1", "name": "Mandant 1 GmbH"}
      ]

    ,"departments": [
        {"id": "1", "name": "1"},
        {"id": "10", "name": "10"}
      ]

    ,"program": {
      "product": "LODAS", "variant": 2, "version": "15.7"
    }
    ,"instant_registration_required": false
  }

Hinweise

  • health_insurers sollte eigentlich laut DATEV-Dokumentation eine ID pro Krankenkasse enthalten, im Produktivabruf wird dort jedoch keine ID geliefert.

  • salary_types enthält nicht unbedingt alle Lohnarten (gelöschte Lohnarten?)

/employees

Response mit Beispielwerten

JSON
{
  "employees":
  [
    {
      "personnel_number":13,
      "company_personnel_number":"BX1dd2",
      "surname":"John",
      "first_name":"Jackson",
      "business_unit_id":"1",
      "payment_method":"5",
      "employment_id":null,
      "account":
      {
          "iban":"DE02500105170137075030",
          "bic":"GENODEF1P17",
          "differing_account_holder":null
      },
      "activity":
      {
          "highest_level_of_professional_training":2,
          "highest_level_of_education":2,
          "allocation_of_working_hours_monday":5,
          "allocation_of_working_hours_tuesday":5,
          "allocation_of_working_hours_wednesday":5,
          "allocation_of_working_hours_thursday":5,
          "allocation_of_working_hours_friday":5,
          "allocation_of_working_hours_saturday":null,
          "allocation_of_working_hours_sunday":null,
          "weekly_working_hours":25,
          "individual_cost_center_id":"HEY",
          "occupational_title":"DevOps Engineer",
          "job_carried_out": "51311",
          "employee_type":101,
          "contractual_structure":1,
          "activity_type":3,
          "department_id": "29",
          "personnel_leasing":1
      }
    ,"address":
      {
          "street":"Bahnhofstr.",
          "house_number":"12a",
          "city":"Nuernberg",
          "postal_code":"90429",
          "country":"D",
          "address_affix":"auf"
      },
    "employment_periods":
      [
        {
          "date_of_commencement_of_employment":"2001-01-01",
          "date_of_termination_of_employment":"2005-12-31"
        },
        {
          "date_of_commencement_of_employment":"2007-04-01",
          "date_of_termination_of_employment":"2007-04-30"
        },
        {
          "date_of_commencement_of_employment":"2008-07-15"
        }
      ],
    "personal_data":{
        "academic_title":"Bachelor of Eng.",
        "name_prefix":"an",
        "name_affix":"Baron",
        "birth_name_prefix":"von",
        "birth_name_affix":"Erbgraf",
        "birth_name":"Hilfiger",
        "nationality":"000",
        "sex":"M",
        "social_security_number":"15070649C103",
        "european_social_security_number":"15070649C103",
        "country_of_birth":"122",
        "place_of_birth":"Bruegge",
        "date_of_birth":"2000-01-02",
        "email":"baron@erbgraf.de",
        "phone":null,
        "work_permit":"2000-02-02",
        "residency_permit":"2000-03-02",
        "certificate_of_study":"2000-04-02",
        "intitial_day_of_entrance": null
    }
    ,"social_insurance":
      {
        "company_number_of_health_insurer":"21203214",
        "contribution_class_health_insurance":3,
        "contribution_class_nursing_insurance":1,
        "contribution_class_pension_insurance":1,
        "contribution_class_unemployment_insurance":2,
        "health_insurance_id":1,
        "is_additional_contribution_to_nursing_insurance_for_childless_ignored":true,
        "health_insurer_for_marginal_employee":null
      }
    ,"tax_card":
      {
        "annual_tax_allowance":1200,
        "child_tax_allowances":80,
        "denomination":"rk",
        "factor":null,
        "monthly_tax_allowance":300,
        "spouses_denomination":"ev",
        "tax_class":2
      }
    ,"taxation":
      {
        "employment_type":"2",
        "requested_annual_allowance":123,
        "tax_identification_number":"12345678912",
        "flat_rate_tax":2
      }
    ,"vacation_entitlement":
      {
        "basic_vacation_entitlement":30
      }
    ,"vocational_training":
      {
        "start": null,
        "expected_end": null,
        "actual_end": null
      }
    }
  ]
  ,"errors":[]
}

Hinweise:

der Endpunkt liefert anscheinend immer den zum Zeitpunkt des Abrufs aktuellen Stand der Mitarbeiterliste des reference_date Monats

/absences/lodas

Response mit Beispielwerten

JSON
 {
  "absences_lodas": [
  {
    "personnel_number":1,
    "absence_start_date":"2022-01-01",
    "absence_end_date":"2022-01-02",
    "reason_for_absence":33
    }
  ]
  "errors": []
}

Hinweise:

  • Abwesenheiten scheinen immer auf Tage aufgesplittet aus der API zu kommen

  • der reference_date Filter funktioniert anscheinend nicht, es kommen immer alle verfügbaren historischen und zukünftigen (gepl. Urlaub) Abwesenheiten

  • reason_for_absence Schlüssel wird nicht über die client-data geliefert → noch abzuklären wo diese IDs in DATEV hinterlegt sind, ansonsten ist ein manueller Abgleich an Beispieldatensätzen notwendig


/month-records

Response mit Beispielwerten

JSON
{
  "personnel_number":1,
  "value":12.75,
  "salary_type_id":121,
  "differing_factor":98.5,
  "cost_center_id":"COSTCTR12345",
  "month_of_emergence":"2024-03",
  "processing_code":3
}

Hinweise:

  • enthält anscheinend Einmalzahlungen wie Prämien, Boni

  • kann aber auch Kürzungen wie z.B. bei Umwandlung der SuE-Zulage in freie Tage enthalten (value wäre dann mit negativem Vorzeichen versehen)

  • value ist normalerweise Brutto, aber manchmal wird auch der Nettowert hinterlegt und im Lohnartnamen als Netto gekennzeichnet

  • es können salary_type_id existieren die nicht mit den Client-data abgerufen werden können (gelöschte Lohnarten?)

  • differing_factor und cost_center_id meistens nicht gepflegt →können “null” enthalten

  • month_of_emergence: Monat für den dieser Wert gültig ist. Sehr häufig auch “null”

  • processing_code: noch keine Infos dazu gefunden


Last updated: