Exemples de requêtes et de réponses de l'API d'exportation de données

Utilisez les exemples présentés dans cette rubrique comme point de départ pour votre propre intégration. Chaque exemple présente une URL de requête représentative ainsi que le corps de la réponse renvoyée par l'API.

À propos de ces exemples

  • Les exemples utilisent des clés API et des identifiants d'imprimante fictifs. Lorsque vous les adaptez, remplacez les valeurs par celles de votre propre environnement.
  • Les exemples utilisent le nom d'hôte correspondant aux États-Unis et au Japon. Si votre compte est hébergé en Europe, veuillez utiliser plutôt rpi-data-export.app-ricohsoftware.eu.
  • Les valeurs de date et d'heure sont formatées selon l'heure locale du fuseau horaire indiqué dans la requête, selon le format YYYY-MM-DDTHH:MM:SS.sss.
  • Toutes les durées sont exprimées en millisecondes. Toutes les valeurs relatives à l'encre et au vidage sont exprimées en centimètres cubes (cc).
  • Les exemples sont donnés à titre d'illustration. Les valeurs numériques telles que la consommation d'encre, le nombre de pages et les durées correspondent à des données d'exploitation plausibles, et non à des mesures provenant d'une imprimante spécifique.

GET /printers

Récupère les imprimantes disponibles pour la clé API fournie. Le point de terminaison ne prend aucun paramètre.

Requête :

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

Réponse (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

Récupère les travaux traités par une ou plusieurs imprimantes au cours d'une période donnée. Dans cet exemple, on recherche une seule imprimante pour une plage horaire de huit heures, selon l'heure locale America/Denver, en limitant la recherche aux travaux dont l'impression s'est terminée avec succès.

Requête :

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

Réponse (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
  }
]

Un tableau vide ([]) constitue une réponse valide et signifie qu'aucun travail n'a été apparié à la requête.

GET /printer-states (historique agrégé)

Le mode de réponse par défaut renvoie une ligne par intervalle d'état et par moteur, avec les champs de durée totale et d'historique. Dans cet exemple, on demande une plage horaire de quatre heures pour une imprimante.

Requête :

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

Réponse (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 (état actuel uniquement)

Lorsque vous définissez currentState=true, la réponse comprend une ligne par moteur indiquant son état actuel. Les champs « Durée » et « Historique » sont omis.

Requête :

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

Réponse (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 (catégorie d'état uniquement)

Lorsque vous définissez stateCategoryOnly=true, la réponse omet le champ printerState brut et ne renvoie que la catégorie de haut niveau. Les champs « Durée » et « Historique » sont conservés.

Requête :

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

Réponse (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

Récupère les événements d'intervention survenus sur une ou plusieurs imprimantes au cours d'une période donnée. Dans cet exemple, on demande une plage horaire de quatre heures pour une imprimante et on souhaite que les descriptions des événements soient en anglais. L'imprimante utilisée dans cet exemple étant un modèle à alimentation en continu, les valeurs interventionCode adoptent le format propre à ce type d'alimentation.

Requête :

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

Réponse (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"
  }
]

Les deux premières entrées comportent un champ jobName vide, ce qui signifie qu'aucun travail n'était concerné par cet événement. La troisième entrée s'est produite alors qu'un travail était en cours d'impression ; c'est pourquoi le nom du travail est indiqué.

Exemples de réponses d'erreur

Chaque réponse d'erreur suit la même structure : un objet JSON comprenant un code, un message et un statusCode numérique. Certains codes d'erreur comportent des champs supplémentaires, comme noté.

400 Erreur de requête — fuseau horaire non valide :

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

400 Erreur de requête — paramètre obligatoire manquant :

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

400 Erreur de requête — la plage de dates dépasse la limite maximale autorisée :

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

400 Erreur de requête — langage non valide :

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

401 Non autorisé — clé API non valide :

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

403 Accès interdit — la requête inclut une imprimante à laquelle la clé API n'a pas accès :

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

413 Charge utile trop volumineuse — la réponse dépasserait la limite de taille :

{
  "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 Erreur interne du serveur :

{
  "code": "ERR_INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred.",
  "statusCode": 500
}
Rubrique parente : Utilisation de l'API d'exportation de données