La API de MercaMap permite que los sistemas de una cuenta lean los datos que el portal le muestra, por semana ISO (de lunes a domingo, hora peninsular). Forma parte del plan Enterprise (consulta los planes); en los demás planes, quien administra la cuenta ve su página en gris en el menú de «Ajustes de la cuenta», con un candado. Sus operaciones de escritura, y todo lo que llega al módulo de campo (incidencias, visitas, pedidos, albaranes, campañas, cuadros de mando e importaciones), vienen con el módulo de campo: sus permisos aparecen en el portal mientras el módulo está abierto para la cuenta. Una cuenta de establecimiento con el plan Localizador o Tienda Pro también tiene claves, solo para el Localizador (locator:read, más abajo).
Crear una clave
Las claves las crea un administrador de la cuenta (el rol «Administrador/a») en «Ajustes de la cuenta» › «API», en la tarjeta «Claves de API». La página de cada herramienta de BI en «Conectores» crea con el mismo formulario una clave de solo lectura para ella. Crear, revocar o cambiar una clave exige un segundo factor acreditado hace poco en la sesión (consulta segundo factor).
- Rellena «Nombre (qué la usará)» y elige una validez en «Validez», de 1 año como máximo.
- Marca a qué puede llegar la clave en «Qué puede usar». Una clave solo llega a lo que marques; los datos del lineal y las semanas publicadas vienen marcados.
- Pulsa «Crear clave» y copia la clave en ese mismo momento, con «Copiar», junto a ella: solo se muestra esta vez, y nosotros guardamos únicamente un resumen criptográfico (hash) de su secreto.
Una clave tiene la forma mmk_<key id>_<secret>. El identificador de la clave es público: la página muestra cada clave como mmk_<key id>_… junto a su estado («activa», «caducada» o «revocada»), sus fechas y su último uso, con sus peticiones y filas de los últimos 7 días. Una cuenta tiene como máximo 10 claves activas. «Revocar» detiene una clave al momento, tras preguntar una vez más y decir qué se cancela con ella; para renovarla, crea la clave nueva, pasa tu sistema a ella y después revoca la antigua. La actividad de la cuenta registra quién creó, cambió o revocó cada clave, nunca su secreto.
Guarda las claves en secreto y úsalas solo desde tus propios sistemas: quien tenga una puede leer los datos de la cuenta hasta que caduque o se revoque. Una clave también deja de funcionar al momento si la cuenta pierde un plan con API.
Permisos
| Permiso | Nombre en el portal | Disponible |
|---|---|---|
data:read |
Datos del lineal, por semana (lectura) | Hoy |
releases:read |
Semanas publicadas (lectura) | Hoy |
issues:read |
Incidencias y visitas (lectura) | Con el módulo de campo |
issues:write |
Incidencias: abrir, mover y comentar | Con el módulo de campo |
orders:read |
Pedidos (lectura) | Con el módulo de campo |
orders:write |
Pedidos: la respuesta del ERP | Con el módulo de campo |
deliveries:read |
Albaranes (lectura) | Con el módulo de campo |
campaigns:read |
Campañas (lectura) | Con el módulo de campo |
scorecards:read |
Cuadro de mando (lectura) | Con el módulo de campo |
catalogue:read |
Catálogo: importaciones y sus resultados (lectura) | Con el módulo de campo |
catalogue:write |
Catálogo: importar archivos | Con el módulo de campo |
webhooks:read |
Webhooks: suscripciones y los últimos avisos de cada evento (lectura) | Hoy |
webhooks:write |
Webhooks: crear y cancelar suscripciones de herramientas de automatización | Hoy |
locator:read |
Localizador: dónde está y rutas de preparación (lectura) | Cuentas de establecimiento con Localizador o Tienda Pro |
catalogue:write envía archivos y filas para importar y confirma sus columnas; catalogue:read lee las importaciones, el resultado de sus filas y la propuesta de columnas de un archivo, así que una clave que importa suele llevar los dos. Un asistente de IA puede recibir catalogue:read, nunca catalogue:write (importar por la API). Las claves creadas antes de que existieran los permisos conservan data:read y releases:read. Los permisos de una clave activa se cambian en su propio «Qué puede usar» y después con «Guardar»; una clave conserva siempre al menos uno. Da un permiso de escritura solo al sistema que lo necesite.
webhooks:write crea y cancela las suscripciones de una herramienta de automatización, y webhooks:read lista las direcciones de la cuenta y lee los últimos avisos de cada evento; los dos necesitan además el permiso de lectura de cada evento (data:read para los del lineal, orders:read para los de un pedido, como los lista suscripciones por la API). Revocar una clave cancela las suscripciones que creó. Ningún asistente de IA recibe ninguno de los dos.
locator:read es solo de las cuentas de establecimiento: en los planes Localizador y Tienda Pro, también durante su piloto, es el único permiso que puede llevar la clave de una cuenta de establecimiento, y ninguna clave de una marca ni ningún asistente de IA lo recibe. Da acceso a las tres operaciones del Localizador sobre las tiendas de la propia cuenta, list_locator_stores, locate_product y plan_picking_route (consulta el Localizador).
Enviar la clave
Envía la clave como token de portador (bearer) en la cabecera Authorization de cada petición:
curl -H "Authorization: Bearer mmk_…" https://mercamap.com/api/portal/v1/releases
Cada clave lee solo su propia cuenta. Los datos del lineal llegan por semana ISO; el trabajo de tu propio equipo (incidencias, pedidos, albaranes) lleva la fecha y la hora en que ocurrió. La descripción completa, pública y sin datos, está en /api/portal/v1/openapi.json; la referencia de la API recoge cada operación con su permiso.
Errores
Todos los errores responden con el mismo sobre JSON, en el que details es opcional:
{ "error": { "code": "INSUFFICIENT_SCOPE", "message": "This needs the scope data:read", "details": { "scope": "data:read" } } }
| Estado | Código | Qué significa |
|---|---|---|
| 400 | VALIDATION_ERROR |
La petición no se ajusta a la operación; details dice qué corregir |
| 401 | UNAUTHORIZED |
Falta la clave; o no es válida, ha caducado o se ha revocado, y en esos casos la respuesta es la misma |
| 403 | FORBIDDEN |
El plan no lo incluye, la cuenta no tiene acceso o está en solo lectura |
| 403 | INSUFFICIENT_SCOPE |
A la clave le falta el permiso que indica details; los permisos del módulo de campo solo se pueden dar a una clave mientras el módulo está abierto para la cuenta |
| 404 | NOT_FOUND |
No existe; una operación del módulo de campo responde 404 a una clave con su permiso mientras el módulo está desactivado |
| 409 | CONFLICT |
La fila ha cambiado entretanto, o ya hay una incidencia abierta que la cubre |
| 413 | PAYLOAD_TOO_LARGE |
El cuerpo es mayor de lo que admite la operación |
| 422 | UNPROCESSABLE |
Las reglas lo rechazan, con el motivo en details |
| 429 | RATE_LIMITED |
Demasiadas peticiones o escrituras, o se han agotado las filas del día |
| 503 | BUSY o FEATURE_DISABLED |
Ocupado, así que reintenta tras Retry-After, o desactivado por un tiempo |
Un fallo inesperado responde 500 con INTERNAL. Si el cambio de una escritura se ha hecho pero su respuesta no se ha podido leer, details lleva "committed": true: no vuelvas a enviar esa escritura. El artículo sobre los límites explica el 429 y la cabecera Retry-After.