Ejemplos de solicitudes y respuestas de la API de exportación de datos

Utilice los ejemplos de este tema como punto de partida para su propia integración. Cada ejemplo muestra una URL de solicitud representativa junto con el cuerpo de la respuesta que devuelve la API.

Acerca de estos ejemplos

  • En los ejemplos se utilizan claves API e identificadores de impresora provisionales. Sustituya los valores por los de su propio entorno al adaptarlos.
  • En los ejemplos se utiliza el nombre de host de Estados Unidos y Japón. Si su cuenta está alojada en Europa, utilice en su lugar rpi-data-export.app-ricohsoftware.eu.
  • Los valores de fecha y hora se formatean como horas locales en la zona horaria indicada en la solicitud, siguiendo el formato YYYY-MM-DDTHH:MM:SS.sss.
  • Todas las duraciones se expresan en milisegundos. Todos los valores relativos a la tinta y al vaciado se expresan en centímetros cúbicos (cc).
  • Los ejemplos tienen carácter ilustrativo. Los valores numéricos, como el consumo de tinta, el número de páginas y la duración, representan datos operativos plausibles, no mediciones procedentes de una impresora concreta.

GET /printers

Recupera las impresoras disponibles para la clave API facilitada. El punto final no admite parámetros.

Solicitud:

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

Respuesta (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 los trabajos procesados por una o varias impresoras dentro de un intervalo de tiempo. En este ejemplo se solicita información sobre una sola impresora durante un intervalo de ocho horas en la zona horaria America/Denver, limitándose a los trabajos que se hayan impreso correctamente.

Solicitud:

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

Respuesta (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 vacío ([]) es una respuesta válida y significa que no hay coincidencias con los trabajos solicitados.

GET /printer-states (historial agregado)

El modo de respuesta predeterminado devuelve una fila por intervalo de estado por motor, con los campos de duración total e historial. En el ejemplo se solicita un intervalo de cuatro horas para una impresora.

Solicitud:

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

Respuesta (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 estado actual)

Cuando se establece `currentState=true`, la respuesta incluye una fila por motor con el estado actual. Se omiten los campos de duración e historial.

Solicitud:

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

Respuesta (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 categoría de estado)

Cuando se establece stateCategoryOnly=true, la respuesta omite el campo printerState sin procesar y solo indica la categoría de nivel superior. Se conservan los campos de duración e historial.

Solicitud:

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

Respuesta (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 los eventos de intervención que se produjeron en una o varias impresoras dentro de un intervalo de tiempo. En el ejemplo se solicita un intervalo de cuatro horas para una impresora y se piden descripciones de los eventos en inglés. Dado que la impresora de este ejemplo es un modelo de alimentación continua, los valores de interventionCode utilizan el formato de alimentación continua.

Solicitud:

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

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

Las dos primeras entradas tienen el campo jobName vacío, lo que significa que en el suceso no intervino ningún trabajo. La tercera entrada se produjo mientras se estaba imprimiendo un trabajo, por lo que se indica el nombre de dicho trabajo.

Ejemplos de respuestas de error

Todas las respuestas de error siguen la misma estructura: un objeto JSON que contiene un code, un message y un statusCode numérico. Algunos códigos de error incluyen campos adicionales, según la nota.

400 Solicitud incorrecta: zona horaria no válida:

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

400 Solicitud incorrecta: falta un parámetro obligatorio:

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

400 Solicitud incorrecta: el intervalo de fechas supera el máximo permitido:

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

400 Solicitud incorrecta — idioma no válido:

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

401 No autorizado — clave API no válida:

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

403 Prohibido: la solicitud incluye una impresora a la que la clave API no tiene acceso:

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

413 Carga útil demasiado grande: la respuesta superaría el límite de tamaño:

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

Error 500 del servidor interno:

{
  "code": "ERR_INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred.",
  "statusCode": 500
}
Tema principal: Cómo trabajar con la API de exportación de datos