Voorbeelden van verzoeken en antwoorden voor de gegevensexport-API

Gebruik de voorbeelden in dit onderwerp als uitgangspunt voor uw eigen integratie. Elk voorbeeld toont een representatieve aanvraag-URL, samen met de inhoud van het antwoord dat de API retourneert.

Over deze voorbeelden

  • In de voorbeelden worden tijdelijke API-sleutels en printer-ID’s gebruikt. Vul bij het aanpassen de waarden in die voor uw eigen omgeving gelden.
  • In de voorbeelden wordt de hostnaam voor de Verenigde Staten en Japan gebruikt. Indien uw account in Europa wordt gehost, gebruikt u in plaats daarvan rpi-data-export.app-ricohsoftware.eu.
  • Datum- en tijdwaarden worden weergegeven als lokale tijden in de tijdzone die bij het verzoek is opgegeven, volgens het patroon JJJJ-MM-DDTHH:MM:SS.sss.
  • Alle tijdsduur wordt uitgedrukt in milliseconden. Alle waarden voor inkt en spoelen worden uitgedrukt in kubieke centimeter (cc).
  • De voorbeelden dienen ter verduidelijking. Cijfergegevens zoals inktverbruik, paginatellingen en looptijden zijn representatieve bedrijfsgegevens, en geen metingen van een specifieke printer.

GET /printers

Haal de printers op die beschikbaar zijn voor de opgegeven API-sleutel. Het eindpunt heeft geen parameters.

Aanvraag:

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

Antwoord (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

Haal de taken die door één of meer printers binnen een bepaald tijdsbestek zijn verwerkt, op. In dit voorbeeld wordt een verzoek ingediend voor één printer gedurende een periode van acht uur volgens de lokale tijd in America/Denver, waarbij alleen taken worden meegenomen die met succes zijn voltooid.

Aanvraag:

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

Antwoord (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
  }
]

Een lege array ([]) is een geldig antwoord en betekent dat er geen overeenkomende taken zijn gevonden.

GET /printer-states (geaggregeerde geschiedenis)

De standaardresponsmodus levert één rij per statusinterval per motor op, met velden voor de volledige duur en de geschiedenis. In het voorbeeld wordt een tijdsvenster van vier uur aangevraagd voor één printer.

Aanvraag:

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

Antwoord (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 (alleen de huidige status)

Wanneer u currentState=true instelt, bevat het antwoord één rij per motor met de huidige status. De velden „Duur” en „Geschiedenis” worden weggelaten.

Aanvraag:

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

Antwoord (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 (alleen de categorie ‘status’)

Wanneer u stateCategoryOnly=true instelt, wordt het ruwe printerState-veld in het antwoord weggelaten en wordt alleen de categorie op hoog niveau weergegeven. De velden ‘Duur’ en ‘Geschiedenis’ blijven behouden.

Aanvraag:

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

Antwoord (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-ingrepen

Haal de interventiegebeurtenissen op die zich binnen een bepaald tijdsbestek op één of meer printers hebben voorgedaan. In het voorbeeld wordt een tijdsbestek van vier uur aangevraagd voor één printer en wordt gevraagd om gebeurtenisbeschrijvingen in het Engels. Aangezien de printer in dit voorbeeld een model met doorloopvoeding is, hanteren de waarden van de interventionCode het formaat voor doorloopvoeding.

Aanvraag:

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

Antwoord (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"
  }
]

Bij de eerste twee vermeldingen is het veld jobName leeg, wat betekent dat er bij de gebeurtenis geen taak betrokken was. De derde vermelding vond plaats terwijl een taak werd afgedrukt; daarom wordt de naam van de taak vermeld.

Voorbeelden van foutmeldingen

Elke foutmelding heeft dezelfde structuur: een JSON-object met een code, een message en een numerieke statusCode. Er is een opmerking gemaakt over het feit dat sommige foutcodes extra velden bevatten.

400 Ongeldige aanvraag — ongeldige tijdzone:

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

400 Ongeldige aanvraag — vereiste parameter ontbreekt:

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

400 Ongeldige aanvraag — het datumbereik overschrijdt de maximaal toegestane waarde:

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

400 Ongeldige aanvraag — ongeldige taal:

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

401 Niet geautoriseerd — ongeldige API-sleutel:

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

403 Toegang geweigerd — het verzoek betreft een printer waartoe de API-sleutel geen toegang heeft:

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

413 Payload te groot — het antwoord zou de maximale grootte overschrijden:

{
  "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 Interne serverfout:

{
  "code": "ERR_INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred.",
  "statusCode": 500
}
Ouder onderwerp: Werken met de gegevensexport-API