Esempi di richieste e risposte dell'API di esportazione dei dati

Utilizzi gli esempi riportati in questa sezione come punto di partenza per la propria integrazione. Ciascun esempio illustra un URL di richiesta rappresentativo insieme al corpo della risposta restituita dall'API.

Informazioni su questi esempi

  • Gli esempi utilizzano chiavi API e ID delle stampanti fittizi. Quando li adatterete, sostituite i valori con quelli relativi al vostro ambiente.
  • Negli esempi viene utilizzato il nome-host relativo agli Stati Uniti e al Giappone. Se il Suo account è ospitato in Europa, utilizzi invece rpi-data-export.app-ricohsoftware.eu.
  • I valori relativi alla data e all'ora sono formattati come ora locale nel fuso orario specificato nella richiesta, secondo il formato YYYY-MM-DDTHH:MM:SS.sss.
  • Tutte le durate sono espresse in millisecondi. Tutti i valori relativi all’inchiostro e allo scaricamento sono espressi in centimetri cubi (cc).
  • Gli esempi hanno scopo illustrativo. I valori numerici quali il consumo di inchiostro, il numero di pagine e la durata rappresentano dati operativi plausibili, non misurazioni relative a una stampante specifica.

GET /printers

Recupera le stampanti disponibili per la chiave API specificata. L'endpoint non accetta parametri.

Richiesta:

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

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

Recupera i lavori elaborati da una o più stampanti in un determinato intervallo di tempo. L'esempio richiede i dati relativi a una singola stampante per una finestra temporale di otto ore nell'ora locale di America/Denver, limitandosi ai lavori la cui stampa è stata completata con esito positivo.

Richiesta:

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

Risposta (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 array vuoto ([]) costituisce una risposta valida e indica che nessun processo corrispondeva alla richiesta.

GET /printer-states (cronologia aggregata)

La modalità di risposta predefinita restituisce una riga per ogni intervallo di stato per ciascun motore, con i campi completi relativi alla durata e alla cronologia. Nell’esempio si richiede una finestra temporale di quattro ore per una stampante.

Richiesta:

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

Risposta (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 (solo stato attuale)

Quando si imposta currentState=true, la risposta include una riga per ciascun motore con lo stato corrente. I campi relativi alla durata e alla cronologia vengono omessi.

Richiesta:

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

Risposta (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 (solo categoria di stato)

Quando si imposta stateCategoryOnly=true, la risposta omette il campo printerState non elaborato e riporta solo la categoria di livello superiore. I campi relativi alla durata e alla cronologia vengono mantenuti.

Richiesta:

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

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

Recupera gli eventi di intervento verificatisi su una o più stampanti in un determinato intervallo di tempo. L'esempio richiede una finestra temporale di quattro ore per una stampante e richiede che le descrizioni degli eventi siano in inglese. Poiché la stampante utilizzata in questo esempio è un modello a alimentazione continua, i valori di interventionCode utilizzano il formato proprio di tale tipo di alimentazione.

Richiesta:

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

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

Le prime due voci presentano un campo jobName vuoto, il che significa che nessun lavoro è stato coinvolto nell'evento. La terza registrazione si è verificata mentre era in corso la stampa di un lavoro, pertanto viene riportato il nome del lavoro.

Esempi di risposte di errore

Ogni risposta di errore utilizza la stessa struttura: un oggetto JSON con un code, un message e un statusCodenumerico. Come indicato in una nota, alcuni codici di errore includono campi aggiuntivi.

400 Richiesta non valida — fuso orario non valido:

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

400 Richiesta non valida — parametro obbligatorio mancante:

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

400 Richiesta non valida — l'intervallo di date supera il limite massimo consentito:

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

400 Richiesta non valida — lingua non valida:

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

401 Non autorizzato — chiave API non valida:

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

403 Accesso negato — la richiesta include una stampante a cui la chiave API non può accedere:

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

413 Payload troppo grande—la risposta supererebbe il limite di dimensione:

{
  "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
}

Errore 500 del server interno:

{
  "code": "ERR_INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred.",
  "statusCode": 500
}
Argomento collegato: Utilizzo dell'API di esportazione dei dati