Beispiele für Anfragen und Antworten der Datenexport-API

Nutzen Sie die Beispiele in diesem Abschnitt als Ausgangspunkt für Ihre eigene Integration. Jedes Beispiel zeigt eine repräsentative Anfrage-URL zusammen mit dem Antworttext, den die API zurückgibt.

Zu diesen Beispielen

  • In den Beispielen werden Platzhalter für API-Schlüssel und Drucker-IDs verwendet. Ersetzen Sie bei der Anpassung die Werte durch die für Ihre Umgebung geltenden.
  • In den Beispielen wird der Hostname für die USA und Japan verwendet. Falls Ihr Konto in Europa gehostet wird, verwenden Sie bitte stattdessen rpi-data-export.app-ricohsoftware.eu.
  • Datums- und Zeitangaben werden als Ortszeit in der mit der Anfrage angegebenen Zeitzone im Format JJJJ-MM-DDTHH:MM:SS.sss formatiert.
  • Alle Zeitangaben sind in Millisekunden angegeben. Alle Werte für die Tintenmenge und das Spülen sind in Kubikzentimetern (cc) angegeben.
  • Die Beispiele dienen der Veranschaulichung. Zahlenwerte wie Tintenverbrauch, Seitenzahlen und Laufzeiten stellen plausible Betriebsdaten dar, nicht jedoch Messwerte eines bestimmten Druckers.

GET /printers

Ruft die Drucker ab, die für den angegebenen API-Schlüssel verfügbar sind. Der Endpunkt nimmt keine Parameter entgegen.

Anforderung:

GET https://rpi-data-export.app-ricohsoftware.com/api/v1/printers
x-api-key: YOUR_API_KEY

Antwort (200 OK):

[
  {
    "printerName": "VC60000_Line1",
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "engines": 2,
    "manufacturer": "Ricoh",
    "model": "RICOH Pro VC60000",
    "printerMode": "duplex",
    "printerType": "continuous_feed",
    "serialNumber": "Printer 1: 10-11111 and Printer 2: 10-22222",
    "connectionStatus": "connected"
  },
  {
    "printerName": "VC80_2",
    "printerId": "0bc6b7b3-8df9-4293-cdd4-5ae3162c4d4c",
    "engines": 2,
    "manufacturer": "Ricoh",
    "model": "RICOH Pro VC80000",
    "printerMode": "duplex",
    "printerType": "continuous_feed",
    "serialNumber": "Printer 1: 10-33333 and Printer 2: 10-33334",
    "connectionStatus": "not_connected"
  },
  {
    "printerName": "IP 5000",
    "printerId": "0f8726da-8a37-4c3b-8710-065d7c265122",
    "engines": 1,
    "manufacturer": "InfoPrint",
    "model": "InfoPrint 5000 GP v3.17.129",
    "printerMode": "simplex",
    "printerType": "continuous_feed",
    "serialNumber": "10-1111111",
    "connectionStatus": "connected"
  }
]

GET /jobs

Ruft die Jobs ab, die von einem oder mehreren Druckern innerhalb eines bestimmten Zeitraums verarbeitet wurden. In diesem Beispiel wird ein einzelner Drucker für ein achtstündiges Zeitfenster in Ortszeit America/Denver abgefragt, wobei die Abfrage auf Jobs beschränkt ist, deren Druckvorgang erfolgreich abgeschlossen wurde.

Anforderung:

GET https://rpi-data-export.app-ricohsoftware.com/api/v1/jobs
    ?printerId=f7932e31-6545-4bff-8971-f84ef5f5b3dc
    &timezone=America/Denver
    &startDateTime=2026-03-15T08:00:00
    &endDateTime=2026-03-15T16:00:00
    &jobState=printed
x-api-key: YOUR_API_KEY

Antwort (200 OK):

[
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "jobId": "5ae3162c4d4c-1771233448485-Cust_MH_Arena.pdf-13925",
    "jobName": "Cust_MH_Arena.pdf",
    "jobPrintingSide": "duplex",
    "jobAction": "printed",
    "jobStartTime": "2026-03-15T08:14:22.000",
    "jobEndTime": "2026-03-15T08:47:51.000",
    "jobDuration": 2009000,
    "printedCopies": 1,
    "printedPages": 4800,
    "printedImpressions": 4800,
    "printedSheets": 2400,
    "printedRollFeet": 1640.5,
    "printedRollMeters": 500.02,
    "inkC": 184.6,
    "inkM": 172.3,
    "inkY": 198.1,
    "inkK": 245.7,
    "flushingC": 2.4,
    "flushingM": 2.4,
    "flushingY": 2.4,
    "flushingK": 2.4
  },
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "jobId": "5ae3162c4d4c-1771237012003-DM_Spring_Promo.pdf-13926",
    "jobName": "DM_Spring_Promo.pdf",
    "jobPrintingSide": "duplex",
    "jobAction": "printed",
    "jobStartTime": "2026-03-15T09:22:10.000",
    "jobEndTime": "2026-03-15T11:05:44.000",
    "jobDuration": 6214000,
    "printedCopies": 25000,
    "printedPages": 50000,
    "printedImpressions": 50000,
    "printedSheets": 25000,
    "printedRollFeet": 17082.0,
    "printedRollMeters": 5206.9,
    "inkC": 1923.4,
    "inkM": 1810.7,
    "inkY": 2055.2,
    "inkK": 2540.8,
    "flushingC": 12.6,
    "flushingM": 12.6,
    "flushingY": 12.6,
    "flushingK": 12.6
  }
]

Ein leeres Array ([]) ist eine gültige Antwort und bedeutet, dass keine Jobs mit der Anfrage übereinstimmten.

GET /printer-states (zusammengefasster Verlauf)

Im Standard-Antwortmodus wird pro Motor eine Zeile pro Zustandsintervall zurückgegeben, einschließlich der Felder für die Gesamtdauer und den Verlauf. In diesem Beispiel wird ein vierstündiges Zeitfenster für einen Drucker angefordert.

Anforderung:

GET https://rpi-data-export.app-ricohsoftware.com/api/v1/printer-states
    ?printerId=f7932e31-6545-4bff-8971-f84ef5f5b3dc
    &timezone=America/Denver
    &startDateTime=2026-03-15T08:00:00
    &endDateTime=2026-03-15T12:00:00
x-api-key: YOUR_API_KEY

Antwort (200 OK):

[
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "engine": "engine_1",
    "stateCategory": "idle",
    "printerState": "ready",
    "printerStateDuration": 854000,
    "historyStartTime": "2026-03-15T08:00:00.000",
    "historyEndTime": "2026-03-15T08:14:14.000"
  },
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "engine": "engine_1",
    "stateCategory": "up",
    "printerState": "printing",
    "printerStateDuration": 2017000,
    "historyStartTime": "2026-03-15T08:14:14.000",
    "historyEndTime": "2026-03-15T08:47:51.000"
  },
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "engine": "engine_1",
    "stateCategory": "down",
    "printerState": "maintenance",
    "printerStateDuration": 1980000,
    "historyStartTime": "2026-03-15T08:47:51.000",
    "historyEndTime": "2026-03-15T09:20:51.000"
  },
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "engine": "engine_2",
    "stateCategory": "idle",
    "printerState": "sleeping",
    "printerStateDuration": 14400000,
    "historyStartTime": "2026-03-15T08:00:00.000",
    "historyEndTime": "2026-03-15T12:00:00.000"
  }
]

GET /printer-states (nur aktueller Status)

Wenn Sie currentState=true festlegen, enthält die Antwort eine Zeile pro Motor mit dem aktuellen Status. Die Felder „Dauer“ und „Verlauf“ werden weggelassen.

Anforderung:

GET https://rpi-data-export.app-ricohsoftware.com/api/v1/printer-states
    ?printerId=f7932e31-6545-4bff-8971-f84ef5f5b3dc
    &timezone=America/Denver
    &currentState=true
x-api-key: YOUR_API_KEY

Antwort (200 OK):

[
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "engine": "engine_1",
    "stateCategory": "up",
    "printerState": "printing"
  },
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "engine": "engine_2",
    "stateCategory": "idle",
    "printerState": "ready"
  }
]

GET /printer-states (nur Zustandskategorie)

Wenn Sie stateCategoryOnly=true festlegen, wird in der Antwort das Feld printerState (Rohdaten) weggelassen und es wird lediglich die übergeordnete Kategorie angegeben. Die Felder „Dauer“ und „Verlauf“ bleiben erhalten.

Anforderung:

GET https://rpi-data-export.app-ricohsoftware.com/api/v1/printer-states
    ?printerId=f7932e31-6545-4bff-8971-f84ef5f5b3dc
    &timezone=America/Denver
    &startDateTime=2026-03-15T08:00:00
    &endDateTime=2026-03-15T12:00:00
    &stateCategoryOnly=true
x-api-key: YOUR_API_KEY

Antwort (200 OK):

[
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "engine": "engine_1",
    "stateCategory": "idle",
    "printerStateDuration": 854000,
    "historyStartTime": "2026-03-15T08:00:00.000",
    "historyEndTime": "2026-03-15T08:14:14.000"
  },
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "engine": "engine_1",
    "stateCategory": "up",
    "printerStateDuration": 2017000,
    "historyStartTime": "2026-03-15T08:14:14.000",
    "historyEndTime": "2026-03-15T08:47:51.000"
  }
]

GET /printer-interventions

Ruft die Interventionsereignisse ab, die innerhalb eines bestimmten Zeitraums auf einem oder mehreren Druckern aufgetreten sind. In diesem Beispiel wird ein vierstündiges Zeitfenster für einen Drucker angefordert und um Ereignisbeschreibungen in englischer Sprache gebeten. Da es sich bei dem Drucker in diesem Beispiel um ein Modell mit Endlosdruck handelt, entsprechen die Werte für interventionCode dem Endlosdruckformat.

Anforderung:

GET https://rpi-data-export.app-ricohsoftware.com/api/v1/printer-interventions
    ?printerId=f7932e31-6545-4bff-8971-f84ef5f5b3dc
    &timezone=America/Denver
    &startDateTime=2026-03-15T08:00:00
    &endDateTime=2026-03-15T12:00:00
    &language=en
x-api-key: YOUR_API_KEY

Antwort (200 OK):

[
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "interventionStartDate": "2026-03-15T08:47:51.000",
    "interventionEndDate": "2026-03-15T09:20:51.000",
    "duration": 1980000,
    "description": "Media empty",
    "engine": "engine_1",
    "jobName": "",
    "interventionCode": "CA00"
  },
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "interventionStartDate": "2026-03-15T09:05:33.000",
    "interventionEndDate": "2026-03-15T09:41:12.000",
    "duration": 2139000,
    "description": "Media empty",
    "engine": "engine_2",
    "jobName": "",
    "interventionCode": "CA00"
  },
  {
    "printerId": "f7932e31-6545-4bff-8971-f84ef5f5b3dc",
    "interventionStartDate": "2026-03-15T10:12:04.000",
    "interventionEndDate": "2026-03-15T10:19:47.000",
    "duration": 463000,
    "description": "Paper jam",
    "engine": "engine_1",
    "jobName": "DM_Spring_Promo.pdf",
    "interventionCode": "40000006"
  }
]

Die ersten beiden Einträge weisen ein leeres jobName-Feld auf, was bedeutet, dass an dem Ereignis kein Job beteiligt war. Der dritte Eintrag erfolgte während des Druckvorgangs eines Jobs, daher wird der Name des Jobs angegeben.

Beispiele für Fehlermeldungen

Jede Fehlermeldung weist dieselbe Struktur auf: ein JSON-Objekt mit einem code, einer message und einem numerischen statusCode. Als Anmerkung: Einige Fehlercodes enthalten zusätzliche Felder.

400 Ungültige Anforderung – ungültige Zeitzone:

{
  "code": "ERR_INVALID_TIMEZONE",
  "message": "The supplied timezone is not a valid IANA timezone identifier.",
  "statusCode": 400
}

400 Ungültige Anforderung – erforderlicher Parameter fehlt:

{
  "code": "ERR_MISSING_PRINTER_ID",
  "message": "At least one printerId value is required.",
  "statusCode": 400
}

400 Ungültige Anforderung – Der Datumsbereich überschreitet den maximal zulässigen Bereich:

{
  "code": "ERR_DATE_RANGE_EXCEEDED",
  "message": "The requested date range exceeds the maximum allowed range.",
  "statusCode": 400
}

400 Ungültige Anforderung – ungültige Sprache:

{
  "code": "ERR_INVALID_LANGUAGE",
  "message": "The supplied language is not a supported language code.",
  "statusCode": 400
}

401 Nicht autorisiert – ungültiger API-Schlüssel:

{
  "code": "ERR_INVALID_APIKEY",
  "message": "Failed to validate API key.",
  "statusCode": 401
}

403 Zugriff verweigert – Die Anfrage umfasst einen Drucker, auf den der API-Schlüssel keinen Zugriff hat:

{
  "code": "ERR_UNAUTHORIZED_PRINTERS",
  "message": "Unauthorized printers.",
  "statusCode": 403
}

413 Nutzlast zu groß – die Antwort würde die Größenbeschränkung überschreiten:

{
  "code": "ERR_RESPONSE_LIMIT_EXCEEDED",
  "message": "The response would exceed the maximum allowed size. Narrow the date range or request fewer printers.",
  "statusCode": 413,
  "maxJobs": 8000
}

500 Interner Serverfehler:

{
  "code": "ERR_INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred.",
  "statusCode": 500
}
Übergeordnetes Thema: Arbeiten mit der Datenexport-API