Introducción a la API pública

En pocas palabras

La Open API de IDPOS le permite consultar y registrar, desde su propio sistema, información de las tiendas a las que tiene acceso. Cada operación, con sus parámetros, respuestas y errores, está en la sección Operaciones de la barra lateral.

Use la API cuando su sistema necesite la información a demanda, por ejemplo para cuadrar un periodo. Si necesita enterarse de un cambio en el momento en que ocurre, use los webhooks de IDPOS.

Credenciales y URL base

La URL base y las credenciales las proporciona IDBI. No existe una operación de la API para generar un token ni un registro de autoservicio.

URL base

Todas las operaciones cuelgan de la misma ruta base:

https://{host}/api/open/v1

Elemento	Valor
{host}	Nombre de host proporcionado por IDBI.
/api/open	Prefijo de la Open API.
/v1	Versión de la API. Esta referencia documenta únicamente la versión v1.

Las respuestas son JSON. Las fechas con hora de las respuestas están en UTC, en formato ISO 8601 con la letra Z al final, por ejemplo 2026-10-12T23:04:58Z. Las fechas sin hora, como birthdate del cliente, usan el formato AAAA-MM-DD y no tienen zona horaria.

Autenticación

Cada petición debe incluir las dos cabeceras siguientes. Si falta alguna, la respuesta es 401.

Cabecera	Contenido
I-Open-Api-Key	Identificador del token (clave pública).
I-Open-Api-Token	Valor secreto del token.

IDBI entrega ambos valores al integrador. Cada tienda u organización tiene un único token, con fecha de vencimiento, y IDBI puede deshabilitarlo. Trate I-Open-Api-Token como una contraseña:

• Conserve I-Open-Api-Token solo en su servidor.
• No lo use en un navegador, en una aplicación móvil ni en una URL.
• Manténgalo fuera de los registros (logs) de su sistema.
• Si se filtra, avise de inmediato a IDBI.

curl "https://{host}/api/open/v1/stores" \
  -H "Accept: application/json" \
  -H "I-Open-Api-Key: {key}" \
  -H "I-Open-Api-Token: {token}"

Qué puede consultar cada token

IDBI emite cada token para una tienda o para una organización. El tipo de token determina las tiendas a las que tiene acceso.

Tipo de token	Tiendas a las que accede	Resultado de GET /stores
Tienda	Solo la tienda del token.	Una tienda: la del token.
Organización	Todas las tiendas de la organización del token.	Todas las tiendas de la organización, ordenadas por nombre.

En las operaciones cuya ruta empieza por /stores/{storeKey}/, el valor de storeKey debe ser una de las tiendas del token. Obtenga esos identificadores con GET /stores: el campo id de cada tienda es el storeKey. Si la tienda no pertenece al token, la respuesta es 403.

La misma regla rige para las operaciones que empiezan por /orders/{orderKey}/ y /tables/{tableKey}/: la orden o la mesa debe pertenecer a una de las tiendas del token. Si pertenece a otra tienda o no existe, la respuesta es 403.

En PATCH /stores/{storeKey}/advances/{advance}/cancel, el anticipo debe pertenecer a la tienda indicada en storeKey. Si no existe o es de otra tienda, la respuesta es 404.

Operaciones

Las operaciones están en la sección Operaciones de la barra lateral, agrupadas por recurso. Cada una documenta su ruta, sus parámetros, sus respuestas y sus errores.

Relación con los webhooks

Cada elemento de data de sales tiene la misma estructura que data del evento Pago completo (order.paid_in_full). Cada elemento de data de shifts tiene la misma estructura que data del evento Cierre de turno (shift.closed).

Los valores de la consulta reflejan el estado de la orden o del turno en el momento de la consulta. El webhook trae el estado en el momento del evento, de modo que ambos pueden diferir si la orden o el turno cambió después.

Cabeceras comunes

Cabecera	Cuándo	Detalle
Accept: application/json	Siempre	Necesaria para recibir en JSON los errores que se generan fuera de la validación propia de la operación, como el 404 de PATCH /stores/{storeKey}/advances/{advance}/cancel.
Content-Type: application/json	POST y PATCH con cuerpo	Los cuerpos de petición son JSON.

Rango de fechas

sales y shifts reciben el rango en dos parámetros obligatorios, date_from y date_to, con formato AAAA-MM-DD.

Regla	Detalle
Días	Son días calendario de la zona horaria America/Lima (UTC-5). El día va de las 00:00:00 a las 23:59:59 hora de Lima.
Extremos	Ambos días se incluyen. Con date_from=2026-10-12 y date_to=2026-10-12 se obtiene el día completo del 12 de octubre en Lima.
Orden	date_to debe ser igual o posterior a date_from.
Longitud	El rango no puede superar 31 días: date_to puede ser, como máximo, date_from más 30 días.

El campo que se compara con el rango depende de la operación:

Operación	Campo comparado con el rango	Orden de los resultados
sales	paid_at: la fecha en que la orden quedó pagada. Incluye las órdenes que se anularon después de pagarse, con su estado en status.	paid_at y luego id.
shifts	closes_at: la fecha de cierre del turno. No incluye los turnos de cajas eliminadas.	closes_at y luego id.

Las respuestas siguen en UTC: una venta pagada a las 19:45 en Lima llega con paid_at igual a 2026-10-13T00:45:00Z.

Paginación

products, sales y shifts devuelven los resultados por páginas. stores y categories devuelven todos los registros en una sola respuesta.

Parámetro	Descripción
paginate	Cantidad de registros por página, de 1 a 100. Por defecto, 15.
page	Número de página, desde 1. Por defecto, 1.

curl "https://{host}/api/open/v1/stores/{storeKey}/sales?date_from=2026-10-12&date_to=2026-10-12&paginate=50&page=1" \
  -H "Accept: application/json" \
  -H "I-Open-Api-Key: {key}" \
  -H "I-Open-Api-Token: {token}"

La respuesta trae los registros en data, los enlaces de navegación en links y los totales en meta:

{
  "data": [],
  "links": {
    "first": "https://{host}/api/open/v1/stores/{storeKey}/sales?date_from=2026-10-12&date_to=2026-10-12&paginate=50&page=1",
    "last": "https://{host}/api/open/v1/stores/{storeKey}/sales?date_from=2026-10-12&date_to=2026-10-12&paginate=50&page=3",
    "prev": null,
    "next": "https://{host}/api/open/v1/stores/{storeKey}/sales?date_from=2026-10-12&date_to=2026-10-12&paginate=50&page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "links": [
      { "url": null, "label": "« Anterior", "active": false },
      { "url": "https://{host}/api/open/v1/stores/{storeKey}/sales?date_from=2026-10-12&date_to=2026-10-12&paginate=50&page=1", "label": "1", "active": true }
    ],
    "path": "https://{host}/api/open/v1/stores/{storeKey}/sales",
    "per_page": 50,
    "to": 50,
    "total": 120
  }
}

El ejemplo abrevia data y meta.links. Los enlaces de links conservan los parámetros de consulta de la petición. Para recorrer todos los resultados, siga links.next hasta que sea null, o repita la petición con page hasta meta.last_page.

Formato de errores

Los errores tienen tres formatos distintos, según dónde se origine el error. Distíngalos por la estructura del cuerpo y por el código de estado. Los mensajes están en español.

Código	Formato	Cuándo aparece
401	{"error": {"code", "message", "description"}}	Falta una cabecera o el token no es válido.
403	{"error": {"code", "message", "description"}}	El token no tiene acceso al recurso.
404	{"data": []}	GET /orders/{orderKey}/products de una orden propia sin productos.
422	{"message", "errors": {"campo": ["..."]}}	Los datos enviados no superan la validación.
400, 404, 409	{"message"}, {"error": {"message"}} o {"error": {"message", "description"}}	Errores propios de cada operación. El esquema exacto figura en cada operación.

En los errores 401 y 403, error.code siempre es 0.

El 404 de GET /orders/{orderKey}/products no es un error con mensaje: indica que la orden no tiene productos y devuelve data vacío.

401: no autorizado

La autenticación puede fallar por estos motivos. El campo error.description lo indica:

error.description	Causa
El token es obligatorio	Falta I-Open-Api-Key o I-Open-Api-Token.
El token no fue encontrado	La clave no existe.
El token es inválido	El token no corresponde a la clave.
El token está deshabilitado	IDBI deshabilitó el token.
El token expiró	El token superó su fecha de vencimiento.

{
  "error": {
    "code": 0,
    "message": "No autorizado",
    "description": "El token expiró"
  }
}

403: acceso denegado

El token es válido, pero no puede usar el recurso solicitado. Hay tres causas:

error.description	Causa
El token no tiene acceso a la tienda solicitada	El storeKey de una ruta /stores/{storeKey}/... no pertenece al token. La respuesta es la misma para una tienda ajena y para una tienda que no existe.
El token no tiene acceso a la orden solicitada	El orderKey de una ruta /orders/{orderKey}/... pertenece a una tienda ajena al token o no existe. La respuesta es la misma en ambos casos.
El token no tiene acceso a la mesa solicitada	El tableKey de una ruta /tables/{tableKey}/... pertenece a una tienda ajena al token o no existe. La respuesta es la misma en ambos casos.

{
  "error": {
    "code": 0,
    "message": "Acceso denegado",
    "description": "El token no tiene acceso a la tienda solicitada"
  }
}

422: datos no válidos

El campo errors agrupa los mensajes por nombre de campo. Ejemplo de una consulta con type=articles en las categorías de una tienda:

{
  "message": "Uno o más de los datos que has ingresado no cumplen con los requisitos mínimos.",
  "errors": {
    "type": ["El campo type es inválido."]
  }
}

Ejemplo de un rango de fechas de más de 31 días, con date_from=2026-10-12:

{
  "message": "Uno o más de los datos que has ingresado no cumplen con los requisitos mínimos.",
  "errors": {
    "date_to": ["El campo date_to debe ser una fecha anterior o igual a 2026-11-11."]
  }
}

Por lo general, la API comprueba primero la autenticación (401), luego el acceso a la tienda, la orden o la mesa (403) y por último los datos de la petición (422).

Siguientes pasos

1. Llame a Listar las tiendas del token para obtener los storeKey que puede consultar.
2. Elija una operación en la sección Operaciones de la barra lateral.
3. Si necesita recibir avisos en lugar de consultar, consulte los webhooks de IDPOS.