Acceso vía API — Documentación

Agenda / MAB — integración externa y API administrativa

Actualización técnica: 23-08-2026

Esta versión amplía la documentación original en dos direcciones: incorpora la operación confirm_appointment y registra las capacidades que ya existen en la API utilizada por el sistema administrativo, pero que no estaban descritas en el documento anterior.

URL de servicio usada en los ejemplos: [url_base]/ws/mab_web_service

Índice rápido

1. Introducción
2. Convenciones básicas
3. Catastro de funcionalidades
4. Estrategia de integración externa
5. Ejercicio guiado paso a paso
6. Endpoints de integración externa
7. API administrativa de reservas
8. Operaciones auxiliares
9. Auditoría de sesiones y tickets
10. Preguntas frecuentes

Introducción

La API permite dos familias de uso relacionadas, pero conceptualmente distintas:

• Integración externa de agendamiento: login, catálogo, disponibilidad, creación, confirmación/cancelación y auditoría.
• Operación administrativa: consulta y exportación de reservas, colores operativos, vistas personalizadas y filtros guardados.

El objetivo de esta guía es que un desarrollador pueda integrarse con URL base + usuario + contraseña + esta documentación, y que el sistema administrativo PHP pueda apoyarse en un contrato API explícito en vez de depender de conocimiento implícito del código.

El flujo externo normal queda así:

1. Obtener token y hash del catálogo.
2. Obtener catálogo completo o filtrado.
3. Consultar disponibilidad.
4. Crear reserva.
5. Confirmar reserva cuando el flujo de negocio lo requiera.
6. Cancelar reserva cuando corresponda.
7. Logout.

La confirmación y la cancelación son operaciones posteriores sobre un ticket ya creado e identificado por bookingId.

Convenciones básicas

Catastro de funcionalidades

La documentación anterior publicaba login, catálogo, disponibilidad, creación, cancelación, logout y auditoría. El servidor actual expone además varias operaciones utilizadas o destinadas al sistema administrativo.

Capacidades operativas que deben quedar documentadas

Superficie auxiliar existente

El servidor también registra operaciones auxiliares como get_user, get_info, get_conditioned_values, get_catalogo_plano y mecanismos de códigos de un solo uso/handoff. Se describen más adelante como superficie auxiliar, porque su existencia técnica no significa automáticamente que deban formar parte del contrato público principal.

Operaciones que no se promueven como contrato público

En la revisión del código hay mensajes que no conviene presentar como funcionalidad pública estable: authenticate actualmente no entrega una respuesta operativa y la obtención de módulos de atención está incompleta en su respuesta. Se dejan fuera del catálogo funcional público hasta que exista un contrato definido.

Estrategia de integración externa

1. Hacer login y guardar tkn y catalogo_hash.
2. Si no existe catálogo local o el hash cambió, volver a solicitar y almacenar el catálogo.
3. Usar el catálogo para traducir dimensiones y registros a IDs operativos.
4. Consultar disponibilidad con una selection parcial que represente el filtro de negocio.
5. Elegir una entrada disponible en disponibilidad[fecha][indice].
6. Tomar seleccion[indice] y revisar catalogo.agendas para obtener las combinaciones completas que calzan con esa selección.
7. Elegir la combinación final y crear el ticket con selectionId.
8. Persistir el bookingId retornado; ese identificador se usa para confirmación, cancelación, color y auditoría.

Punto clave: las agendas siempre son distintas entre sí. En el ejercicio automotriz las diferencias se entienden bien a través del modelo del vehículo, pero en otro sistema podrían diferir por cualquier otra dimensión del catálogo.

Ejercicio guiado paso a paso

Objetivo: crear un ticket para un Mantenimiento en Sucursal Las Condes para un vehículo Citroën, escogiendo un horario realmente disponible y, luego, confirmar el ticket.

Paso 1. Login

curl -X POST -H "Content-Type: application/json" \
  -d '{ "type":"login", "user":"[usuario]", "password":"[password]" }' \
  [url_base]/ws/mab_web_service

Guardar tkn y catalogo_hash.

Paso 2. Refrescar catálogo solo cuando corresponda

• Si no tienes catálogo almacenado, solicítalo.
• Si el hash cambió, vuelve a solicitarlo.
• Si el hash no cambió, puedes reutilizar la copia local.

Paso 3. Obtener catálogo

curl -X POST --location '[url_base]/ws/mab_web_service' \
  --header 'Content-Type: application/json' \
  --data '{ "tkn":"<token>", "type":"get_catalogo" }'

Para este ejercicio interesan al menos estos registros:

• 1048 = MANTENIMIENTO
• 482 = Sucursal Las Condes
• 684 = Citroën

Paso 4. Consultar disponibilidad

curl -X POST --location '[url_base]/ws/mab_web_service' \
  --header 'Content-Type: application/json' \
  --data '{"tkn":"<token>","selection":[1048,482,684],"yyyymmdd_from":20251020,"yyyymmdd_until":20251024,"includeCatalog":true,"type":"get_availability"}'

Paso 5. Interpretar la disponibilidad

Ejemplo reducido:

{
  "disponibilidad": {
    "20251020": {
      "0": [
        { "a": 830, "b": 845 },
        { "a": 845, "b": 900 }
      ]
    }
  },
  "seleccion": {
    "0": {
      "catalogo.agendas": [298,299,311,313,315,316,318,320,322,324,326,328,329],
      "seleccion": { "0":1429, "1":1048, "2":482, "3":873, "5":684 }
    }
  }
}

La selección parcial consultada fue [1048,482,684], pero el sistema devolvió una selección disponible más completa. catalogo.agendas identifica las combinaciones completas del catálogo que contienen esa selección disponible.

Paso 6. Elegir la combinación completa

Tomando los IDs de catalogo.agendas, se revisa qué valor toma la dimensión correspondiente al vehículo/modelo. Supongamos que se elige selectionId = 322, correspondiente a CACTUS.

Paso 7. Elegir el tramo horario

• yyyymmdd = 20251020
• hhmm_from = 830
• hhmm_until = 845

Paso 8. Crear el ticket

curl -X POST --location '[url_base]/ws/mab_web_service' \
  --header 'Content-Type: application/json' \
  --data '{
    "tkn":"[token]",
    "selectionId":322,
    "yyyymmdd":20251020,
    "hhmm_from":830,
    "hhmm_until":845,
    "form":{
      "contact":{"dni":"[rut]","phones":"[celular 9 digitos]","emails":"[correo valido]","names":"[nombres]","scndnames":"[apellidos]"},
      "vehiculo":{"patente":"[patente]","xkilometraje":"[kilometraje]","year":"[año]"},
      "mensaje":{"msg":"[mensaje opcional]"}
    },
    "type":"new_appointment"
  }'

Respuesta esperada:

{
  "errors": [],
  "appointmentIds": [116326],
  "errorCode": 0,
  "type": "new_appointment.answer",
  "tkn": "",
  "t_init": 1760288918848,
  "t_end": 1760288995068
}

Paso 9. Guardar el ticket

El integrador debe persistir el ID retornado en appointmentIds. En el ejemplo, bookingId = 116326.

Paso 10. Confirmar el ticket, si corresponde

curl -X POST --location '[url_base]/ws/mab_web_service' \
  --header 'Content-Type: application/json' \
  --data '{
    "type":"confirm_appointment",
    "tkn":"[token]",
    "bookingId":116326
  }'

Respuesta exitosa:

{
  "errorCode":0,
  "type":"confirm_appointment.answer",
  "tkn":"",
  "t_init":1760290000000,
  "t_end":1760290000010
}

La operación es idempotente: si el ticket ya está confirmado, vuelve a responder errorCode: 0 sin ejecutar nuevamente la acción de confirmación. Solo un ticket en estado ingresado/no confirmado puede pasar a confirmado. Un ticket inexistente, de otro cluster, cancelado o en otro estado no confirmable responde errorCode: -1.

Endpoints de integración externa

EP-001 Obtener token — login

Método: POST

curl -X POST -H "Content-Type: application/json" \
  -d '{ "type":"login", "user":"[usuario]", "password":"[password]" }' \
  [url_base]/ws/mab_web_service

Respuesta exitosa de ejemplo:

{
  "type":"login.answer",
  "tkn":"BTTrTGbvlkMKOmMAlMxxG1S7uOdq6fWj",
  "catalogo_hash":"129978891caec621a7b5a4979d32b7103f2cd64c619aff4dd6ae644a57dc781a",
  "t_init":1760123792796,
  "t_end":1760123792802
}

EP-002 Obtener catálogo — get_catalogo

Devuelve dimensiones, registros y agendas válidas. Permite proyección con selected_dimensions y filtrado por selection.

{
  "type":"get_catalogo",
  "tkn":"[token]"
}

EP-003 Consultar disponibilidad — get_availability

La respuesta expone disponibilidad y seleccion. Cada selección puede incluir catalogo.agendas con las combinaciones completas candidatas.

{
  "type":"get_availability",
  "tkn":"[token]",
  "selection":[1048,482,684],
  "yyyymmdd_from":20251020,
  "yyyymmdd_until":20251024,
  "includeCatalog":true
}

EP-004 Crear reserva — new_appointment

La creación usa selectionId y devuelve uno o más IDs en appointmentIds.

EP-005 Confirmar reserva — confirm_appointment

Entrada: tkn, bookingId.

{
  "type":"confirm_appointment",
  "tkn":"[token]",
  "bookingId":116326
}

Semántica:

• Verifica que el ticket exista.
• Verifica que pertenezca al mismo cluster de la sesión autenticada.
• Si ya está confirmado, responde éxito sin repetir la acción.
• Solo permite transición desde ingresado/no confirmado.
• errorCode = 0: éxito o ya confirmado.
• errorCode = -1: ticket inexistente, cluster incorrecto, estado no confirmable o fallo de la operación.

La acción usa el flujo de alto nivel de confirmación del sistema, incluyendo los efectos normales asociados a la confirmación, como las notificaciones configuradas para ese flujo.

EP-006 Cancelar reserva — cancel_appointment

curl -X POST --location '[url_base]/ws/mab_web_service' \
  --header 'Content-Type: application/json' \
  --data '{ "tkn":"[token]", "bookingId":116327, "type":"cancel_appointment" }'

EP-007 Logout — logout

curl -X POST --location '[url_base]/ws/mab_web_service' \
  --header 'Content-Type: application/json' \
  --data '{ "tkn":"[token]", "type":"logout" }'

EP-008 Consultar auditoría — booking_audit_get_json_messages

Permite recuperar las comunicaciones auditadas de una sesión buscando por token histórico y/o por appointment_id. Ver Auditoría de sesiones y tickets.

API administrativa de reservas

Estas operaciones corresponden a capacidades ya presentes en la capa API que utiliza el sistema administrativo y que no estaban explicadas en el documento original.

AD-001 Consultar reservas — get_appointments

Permite obtener reservas dentro de una ventana de fechas, filtrar por valores del catálogo, incluir/excluir estados, realizar búsqueda textual y opcionalmente devolver la clasificación de dimensiones/registros necesaria para interpretar la selección histórica.

{
  "type":"get_appointments",
  "tkn":"[token]",
  "selection":[],
  "yyyymmdd_from":20260801,
  "yyyymmdd_until":20260831,
  "includeCatalog":true,
  "include_entered":true,
  "include_confirmed":true,
  "include_cancelled":false,
  "search_text":""
}

La respuesta contiene appointments, dimensiones y registros.

La búsqueda textual puede considerar datos visibles de la reserva, como ID, canal/empresa de origen, estado, fecha/hora, valores conceptuales de dimensiones y valores almacenados en associated_data[*].data.

AD-002 Exportar reservas a Excel — get_appointments_as_excel

Usa la misma idea de ventana temporal, selección y estados, pero la respuesta es un archivo XLSX.

{
  "type":"get_appointments_as_excel",
  "tkn":"[token]",
  "selection":[],
  "yyyymmdd_from":20260801,
  "yyyymmdd_until":20260831,
  "include_entered":true,
  "include_confirmed":true,
  "include_cancelled":false
}

MIME esperado: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.

AD-003 Obtener colores — get_colors

Obtiene la paleta de colores disponible para identificación visual de tickets. En el dispatcher actual esta operación está expresamente permitida sin autenticación.

{
  "type":"get_colors"
}

AD-004 Asignar color — set_color

Asigna colorId a bookingId y actualiza tanto persistencia como representación en memoria.

{
  "type":"set_color",
  "tkn":"[token]",
  "bookingId":116326,
  "colorId":3
}

Esta operación requiere un token de acceso válido. A diferencia de get_colors, set_color se procesa dentro del flujo autenticado de la API.

AD-005 Vistas de la tabla de reservas

Una vista guarda una preferencia de presentación: qué columnas se muestran, en qué orden y si están habilitadas. No modifica los datos de la reserva.

Operaciones:

• get_reservations_views
• create_reservations_view
• update_reservations_view
• delete_reservations_view

Consultar vistas

{
  "type":"get_reservations_views",
  "tkn":"[token]",
  "resource_set_id":null
}

La respuesta entrega dos colecciones relacionadas por reservation_view_id: views[] y columns[]. Si no existen vistas, ambas pueden venir vacías y la interfaz puede conservar el comportamiento por defecto mostrando todas las columnas.

Crear vista

En el código más reciente revisado cada elemento de columns contiene el texto literal final de la columna y su estado enabled; la posición del elemento determina idx.

{
  "type":"create_reservations_view",
  "tkn":"[token]",
  "resource_set_id":null,
  "code":"taller",
  "label":"Taller",
  "columns":[
    {"column_label":"Reserva","enabled":true},
    {"column_label":"Estado","enabled":true},
    {"column_label":"Patente","enabled":true},
    {"column_label":"Correo","enabled":false}
  ]
}

column_label es deliberadamente el texto literal producido por el postproceso de columnas, no el nombre físico de una columna SQL.

Modificar vista

{
  "type":"update_reservations_view",
  "tkn":"[token]",
  "reservation_view_id":12,
  "code":"taller",
  "label":"Taller principal",
  "columns":[
    {"column_label":"Reserva","enabled":true},
    {"column_label":"Patente","enabled":true},
    {"column_label":"Estado","enabled":true}
  ]
}

La lista enviada representa la definición completa deseada. La modificación no mueve la vista a otro resource_set_id.

Eliminar vista

{
  "type":"delete_reservations_view",
  "tkn":"[token]",
  "reservation_view_id":12
}

AD-006 Filtros guardados de reservas

Los filtros son preferencias reutilizables asociadas al cluster y, opcionalmente, a un resource_set_id explícito. Cuando resource_set_id es null, se trabaja con el juego implícito de dimensiones del cluster.

Operaciones:

• get_reservations_filters
• create_reservations_filter
• update_reservations_filter
• delete_reservations_filter

Consultar filtros

{
  "type":"get_reservations_filters",
  "tkn":"[token]",
  "resource_set_id":null
}

La respuesta separa cabeceras, grupos y condiciones en filters[], groups[] y conditions[].

Crear filtro

{
  "type":"create_reservations_filter",
  "tkn":"[token]",
  "resource_set_id":null,
  "code":"mantenciones_las_condes",
  "label":"Mantenciones Las Condes",
  "groups":[
    [1048,482],
    [501,482]
  ]
}

groups es una lista ordenada de grupos; cada grupo contiene IDs x del catálogo. La API valida, entre otras cosas, que exista al menos un grupo, que ningún grupo esté vacío, que no se repita un x dentro del mismo grupo, que no haya dos valores de una misma dimensión dentro del mismo grupo y que cada x pertenezca al catálogo válido del contexto.

Modificar filtro

{
  "type":"update_reservations_filter",
  "tkn":"[token]",
  "reservation_filter_id":8,
  "code":"mantenciones_las_condes",
  "label":"Mantenciones — Las Condes",
  "groups":[
    [1048,482]
  ]
}

La colección groups enviada reemplaza la definición anterior.

Eliminar filtro

{
  "type":"delete_reservations_filter",
  "tkn":"[token]",
  "reservation_filter_id":8
}

Operaciones auxiliares

Estas capacidades existen en el servidor, pero se recomienda mantenerlas separadas del contrato público principal hasta definir qué integradores deben utilizarlas.

La existencia de estas operaciones en el dispatcher demuestra que forman parte de la superficie técnica, pero su exposición a terceros debe decidirse explícitamente.

Auditoría de sesiones y tickets

Operación

• Tipo: booking_audit_get_json_messages
• Método: POST
• URL: [url_base]/ws/mab_web_service
• Autorización: tkn
• Criterios: search_by_access_token y/o search_by_appointment_id

tkn autoriza la consulta actual. search_by_access_token identifica el token histórico cuya conversación se desea investigar.

Buscar por token

{
  "type":"booking_audit_get_json_messages",
  "tkn":"[token_que_autoriza_la_consulta]",
  "search_by_access_token":"[token_de_la_sesion_auditada]"
}

Buscar por appointment_id

{
  "type":"booking_audit_get_json_messages",
  "tkn":"[token_que_autoriza_la_consulta]",
  "search_by_appointment_id":116326
}

El appointment_id identifica la sesión en que se creó ese ticket y la API devuelve el historial completo del token de esa sesión. Por eso pueden aparecer otros tickets creados con el mismo token.

appointment_id consultado
    → identifica la sesión de creación
    → identifica el token de acceso de esa sesión
    → recupera todas las comunicaciones conocidas de ese token

Si se envían ambos criterios, se combinan con AND. Si no se envía ninguno, la respuesta contiene messages: [].

Cada elemento de messages agrupa request y response, con sus marcas de tiempo, JSON interpretado cuando corresponde, texto bruto cuando no es JSON y eventual exception.

Preguntas frecuentes

1. Si consulto disponibilidad con una selección parcial, ¿por qué devuelve varias agendas?

Porque la selección puede estar contenida en múltiples combinaciones completas. catalogo.agendas enumera esas candidatas.

2. ¿Las agendas en catalogo.agendas son iguales?

No. Son combinaciones distintas que contienen la selección parcial disponible.

3. ¿Cuál es la diferencia entre catálogo y disponibilidad?

El catálogo enumera combinaciones válidas; la disponibilidad indica cuáles están libres en un intervalo concreto.

4. ¿Cuándo debo volver a pedir el catálogo?

Cuando no tengas copia local o cuando cambie catalogo_hash.

5. ¿Para qué sirve selected_dimensions en get_catalogo?

Permite proyectar el catálogo sobre dimensiones específicas.

6. ¿Para qué sirve selection en get_catalogo?

Permite filtrar por registros específicos; puede admitir más de un valor por dimensión.

7. ¿Por qué new_appointment usa selectionId?

Porque el código vigente crea el ticket a partir de la combinación completa identificada por selectionId.

8. ¿Qué debo guardar localmente?

Como mínimo: catálogo, hash, IDs relevantes y los appointmentIds de los tickets creados.

9. ¿Confirmar dos veces un ticket genera dos confirmaciones?

No. confirm_appointment fue definido como operación idempotente: un ticket ya confirmado devuelve éxito sin ejecutar nuevamente la acción de confirmación.

10. ¿Confirmar y cancelar son equivalentes?

No. Son transiciones de estado diferentes y usan acciones de negocio diferentes. Ambas operan sobre bookingId.

11. ¿Por qué una auditoría por appointment_id puede mostrar otros tickets?

Porque el ticket se usa para localizar su sesión de creación y luego se devuelve la conversación completa de esa sesión.

MAB Soluciones y Servicios Informáticos Ltda.

Contacto: contacto@mab.cl

Soporte API: tomas@mab.cl

WhatsApp: +56 9 6540 2720

Ubicación: Las Condes, Santiago, Chile

Sitios: ia.mab.cl · www.mab.cl

Horario: Lunes a Viernes 8:00 AM – 6:00 PM

© MAB. Todos los derechos reservados.

API Access — Documentation

Agenda / MAB — external integration and administrative API

Technical update: 2026-08-23

This version expands the previous documentation in two directions: it adds the confirm_appointment operation and inventories capabilities that are already present in the API used by the administrative system but were not described in the previous document.

Service URL used in the examples: [base_url]/ws/mab_web_service

Quick index

1. Introduction
2. Basic conventions
3. Functionality inventory
4. External integration strategy
5. Step-by-step exercise
6. External integration endpoints
7. Administrative reservations API
8. Auxiliary operations
9. Session and ticket audit
10. FAQ

Introduction

The API supports two related but conceptually different families of use:

• External booking integration: login, catalog, availability, creation, confirmation/cancellation and audit.
• Administrative operation: reservation queries and exports, operational colors, custom table views and saved filters.

The goal is for a developer to integrate using base URL + username + password + this document, and for the PHP administrative system to rely on an explicit API contract rather than implicit knowledge of the source code.

The normal external flow is now:

1. Obtain a token and catalog hash.
2. Obtain the full or filtered catalog.
3. Query availability.
4. Create a reservation.
5. Confirm the reservation when required by the business flow.
6. Cancel it when appropriate.
7. Logout.

Confirmation and cancellation are operations on an already-created ticket identified by bookingId.

Basic conventions

Functionality inventory

The previous document covered login, catalog, availability, creation, cancellation, logout and audit. The current server also exposes several operations used by or intended for the administrative system.

Operational capabilities that should be documented

Existing auxiliary surface

The server also registers operations such as get_user, get_info, get_conditioned_values, get_catalogo_plano, and one-time-code/handoff mechanisms. They are listed later as auxiliary API surface, because technical existence does not automatically make them part of the main public contract.

Operations not promoted as a public contract

Some registered messages should not yet be presented as stable public functionality: authenticate currently does not produce an operational response and attention-module retrieval is incomplete in its returned payload. They are intentionally excluded from the public functional inventory until their contracts are defined.

External integration strategy

1. Login and store tkn plus catalogo_hash.
2. If there is no local catalog or the hash changed, fetch and store the catalog again.
3. Use the catalog to translate dimensions and records into operational IDs.
4. Query availability with a partial selection representing the business filter.
5. Choose an available entry in disponibilidad[date][index].
6. Read seleccion[index] and inspect catalogo.agendas to obtain the complete catalog combinations matching that available selection.
7. Choose the final combination and create the ticket with selectionId.
8. Persist the returned bookingId; it is used later for confirmation, cancellation, color and audit operations.

Key point: agendas are always distinct combinations. In the automotive example the difference is easy to visualize through the vehicle model, but another implementation may differ on any catalog dimension.

Step-by-step exercise

Goal: create a Maintenance booking at Las Condes Branch for a Citroën, choose an actually available time slot, and then confirm the ticket.

Step 1. Login

curl -X POST -H "Content-Type: application/json" \
  -d '{ "type":"login", "user":"[username]", "password":"[password]" }' \
  [base_url]/ws/mab_web_service

Store tkn and catalogo_hash.

Step 2. Refresh the catalog only when needed

• Fetch it if you do not have a local copy.
• Fetch it again if the hash changed.
• Reuse the local copy while the hash remains unchanged.

Step 3. Get the catalog

curl -X POST --location '[base_url]/ws/mab_web_service' \
  --header 'Content-Type: application/json' \
  --data '{ "tkn":"<token>", "type":"get_catalogo" }'

For this example, assume these catalog records are relevant:

• 1048 = MAINTENANCE
• 482 = Las Condes Branch
• 684 = Citroën

Step 4. Query availability

curl -X POST --location '[base_url]/ws/mab_web_service' \
  --header 'Content-Type: application/json' \
  --data '{"tkn":"<token>","selection":[1048,482,684],"yyyymmdd_from":20251020,"yyyymmdd_until":20251024,"includeCatalog":true,"type":"get_availability"}'

Step 5. Interpret availability

Reduced example:

{
  "disponibilidad": {
    "20251020": {
      "0": [
        { "a": 830, "b": 845 },
        { "a": 845, "b": 900 }
      ]
    }
  },
  "seleccion": {
    "0": {
      "catalogo.agendas": [298,299,311,313,315,316,318,320,322,324,326,328,329],
      "seleccion": { "0":1429, "1":1048, "2":482, "3":873, "5":684 }
    }
  }
}

The initial partial selection was [1048,482,684], but the server returned a more complete available selection. catalogo.agendas identifies the complete catalog combinations containing it.

Step 6. Choose the complete combination

Inspect the IDs in catalogo.agendas and determine the value of the vehicle/model dimension. Assume selectionId = 322 is selected for CACTUS.

Step 7. Choose the time interval

• yyyymmdd = 20251020
• hhmm_from = 830
• hhmm_until = 845

Step 8. Create the ticket

curl -X POST --location '[base_url]/ws/mab_web_service' \
  --header 'Content-Type: application/json' \
  --data '{
    "tkn":"[token]",
    "selectionId":322,
    "yyyymmdd":20251020,
    "hhmm_from":830,
    "hhmm_until":845,
    "form":{
      "contact":{"dni":"[id]","phones":"[phone]","emails":"[valid email]","names":"[given names]","scndnames":"[surnames]"},
      "vehiculo":{"patente":"[license plate]","xkilometraje":"[mileage]","year":"[year]"},
      "mensaje":{"msg":"[optional message]"}
    },
    "type":"new_appointment"
  }'

Expected response:

{
  "errors": [],
  "appointmentIds": [116326],
  "errorCode": 0,
  "type": "new_appointment.answer",
  "tkn": "",
  "t_init": 1760288918848,
  "t_end": 1760288995068
}

Step 9. Store the ticket ID

Persist the ID returned in appointmentIds. In this example, bookingId = 116326.

Step 10. Confirm the ticket, when applicable

curl -X POST --location '[base_url]/ws/mab_web_service' \
  --header 'Content-Type: application/json' \
  --data '{
    "type":"confirm_appointment",
    "tkn":"[token]",
    "bookingId":116326
  }'

Successful response:

{
  "errorCode":0,
  "type":"confirm_appointment.answer",
  "tkn":"",
  "t_init":1760290000000,
  "t_end":1760290000010
}

The operation is idempotent: if the ticket is already confirmed, it returns errorCode: 0 without executing the confirmation action again. Only an entered/unconfirmed ticket can transition to confirmed. A missing ticket, a ticket from a different cluster, a cancelled ticket, or another non-confirmable state returns errorCode: -1.

External integration endpoints

EP-001 Get access token — login

curl -X POST -H "Content-Type: application/json" \
  -d '{ "type":"login", "user":"[username]", "password":"[password]" }' \
  [base_url]/ws/mab_web_service

Successful response example:

{
  "type":"login.answer",
  "tkn":"BTTrTGbvlkMKOmMAlMxxG1S7uOdq6fWj",
  "catalogo_hash":"129978891caec621a7b5a4979d32b7103f2cd64c619aff4dd6ae644a57dc781a",
  "t_init":1760123792796,
  "t_end":1760123792802
}

EP-002 Get catalog — get_catalogo

Returns valid dimensions, records and agendas. It also supports dimension projection through selected_dimensions and record filtering through selection.

EP-003 Query availability — get_availability

Returns disponibilidad and seleccion. Each selection may include catalogo.agendas containing candidate complete combinations.

EP-004 Create reservation — new_appointment

Creation uses selectionId and returns one or more IDs in appointmentIds.

EP-005 Confirm reservation — confirm_appointment

Input: tkn, bookingId.

{
  "type":"confirm_appointment",
  "tkn":"[token]",
  "bookingId":116326
}

Semantics:

• Checks that the ticket exists.
• Checks that it belongs to the same cluster as the authenticated session.
• Returns success without repeating the action when already confirmed.
• Only allows transition from entered/unconfirmed.
• errorCode = 0: success or already confirmed.
• errorCode = -1: missing ticket, wrong cluster, non-confirmable state, or operation failure.

The operation invokes the system's high-level confirmation flow and therefore its normally configured confirmation side effects, including configured notifications.

EP-006 Cancel reservation — cancel_appointment

{
  "type":"cancel_appointment",
  "tkn":"[token]",
  "bookingId":116327
}

EP-007 Logout — logout

{
  "type":"logout",
  "tkn":"[token]"
}

EP-008 Query audit — booking_audit_get_json_messages

Retrieves audited communications for a historical session using an access token and/or the appointment_id of a ticket created during that session.

Administrative reservations API

These operations are already present in the API layer used by the administrative application and were missing from the previous public document.

AD-001 Query reservations — get_appointments

Retrieves reservations within a date window, filters by catalog values and statuses, supports free-text search, and can optionally return catalog classification needed to interpret historical selections.

{
  "type":"get_appointments",
  "tkn":"[token]",
  "selection":[],
  "yyyymmdd_from":20260801,
  "yyyymmdd_until":20260831,
  "includeCatalog":true,
  "include_entered":true,
  "include_confirmed":true,
  "include_cancelled":false,
  "search_text":""
}

The response contains appointments, dimensiones, and registros.

Text search can inspect visible reservation data such as booking ID, origin company/channel, status, date/time, conceptual dimension values, and values stored in associated_data[*].data.

AD-002 Export reservations to Excel — get_appointments_as_excel

Uses the same date, selection and status concepts, but returns an XLSX file.

{
  "type":"get_appointments_as_excel",
  "tkn":"[token]",
  "selection":[],
  "yyyymmdd_from":20260801,
  "yyyymmdd_until":20260831,
  "include_entered":true,
  "include_confirmed":true,
  "include_cancelled":false
}

Expected MIME: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.

AD-003 Get colors — get_colors

Returns the palette available for visual ticket identification. The current dispatcher explicitly allows this operation without authentication.

AD-004 Assign color — set_color

Assigns colorId to bookingId and updates both persistence and the in-memory representation.

{
  "type":"set_color",
  "tkn":"[token]",
  "bookingId":116326,
  "colorId":3
}

This operation requires a valid access token. Unlike get_colors, set_color is processed through the authenticated API flow.

AD-005 Reservation table views

A view stores display preferences: which columns are shown, their order and whether they are enabled. It does not alter reservation data.

Operations:

• get_reservations_views
• create_reservations_view
• update_reservations_view
• delete_reservations_view

Get views:

{
  "type":"get_reservations_views",
  "tkn":"[token]",
  "resource_set_id":null
}

The response contains views[] and columns[], linked by reservation_view_id. When no views exist, the administrative UI can preserve its default behavior and display all columns.

Create view:

{
  "type":"create_reservations_view",
  "tkn":"[token]",
  "resource_set_id":null,
  "code":"workshop",
  "label":"Workshop",
  "columns":[
    {"column_label":"Reservation","enabled":true},
    {"column_label":"Status","enabled":true},
    {"column_label":"License plate","enabled":true},
    {"column_label":"Email","enabled":false}
  ]
}

In the latest reviewed code, each column includes the literal final column_label and enabled; array position determines idx. column_label intentionally refers to the final post-processed display label, not a physical SQL column name.

Update view:

{
  "type":"update_reservations_view",
  "tkn":"[token]",
  "reservation_view_id":12,
  "code":"workshop",
  "label":"Main workshop",
  "columns":[
    {"column_label":"Reservation","enabled":true},
    {"column_label":"License plate","enabled":true},
    {"column_label":"Status","enabled":true}
  ]
}

The submitted list is the complete desired definition. Updating a view does not move it to another resource_set_id.

Delete view:

{
  "type":"delete_reservations_view",
  "tkn":"[token]",
  "reservation_view_id":12
}

AD-006 Saved reservation filters

Saved filters belong to the cluster and optionally to an explicit resource_set_id. A null resource set represents the cluster's implicit dimension set.

Operations:

• get_reservations_filters
• create_reservations_filter
• update_reservations_filter
• delete_reservations_filter

Get filters:

{
  "type":"get_reservations_filters",
  "tkn":"[token]",
  "resource_set_id":null
}

The response separates headers, groups and conditions into filters[], groups[], and conditions[].

Create filter:

{
  "type":"create_reservations_filter",
  "tkn":"[token]",
  "resource_set_id":null,
  "code":"maintenance_las_condes",
  "label":"Maintenance — Las Condes",
  "groups":[
    [1048,482],
    [501,482]
  ]
}

groups is an ordered list of groups containing catalog x IDs. The API validates that there is at least one non-empty group, that an x is not duplicated within a group, that a group does not contain two values from the same dimension, and that every x belongs to the catalog valid for the filter context.

Update filter:

{
  "type":"update_reservations_filter",
  "tkn":"[token]",
  "reservation_filter_id":8,
  "code":"maintenance_las_condes",
  "label":"Maintenance — Las Condes",
  "groups":[
    [1048,482]
  ]
}

The submitted groups collection replaces the previous definition.

Delete filter:

{
  "type":"delete_reservations_filter",
  "tkn":"[token]",
  "reservation_filter_id":8
}

Auxiliary operations

These capabilities exist on the server, but should remain separate from the primary public contract until it is decided which external integrators should use them.

Their registration in the dispatcher proves that they are part of the technical API surface; exposing them to third parties should be a deliberate contract decision.

Session and ticket audit

Operation

• Type: booking_audit_get_json_messages
• Method: POST
• URL: [base_url]/ws/mab_web_service
• Authorization: tkn
• Criteria: search_by_access_token and/or search_by_appointment_id

tkn authorizes the current query. search_by_access_token identifies the historical session to inspect.

Search by historical token:

{
  "type":"booking_audit_get_json_messages",
  "tkn":"[token_authorizing_the_query]",
  "search_by_access_token":"[historical_session_token]"
}

Search by appointment_id:

{
  "type":"booking_audit_get_json_messages",
  "tkn":"[token_authorizing_the_query]",
  "search_by_appointment_id":116326
}

The appointment_id is used to locate the session in which the ticket was created; the API then returns the complete audited conversation associated with that session token. Therefore other tickets created with the same token may also appear.

queried appointment_id
    → identifies the creation session
    → identifies that session's access token
    → retrieves all known communications for that token

When both criteria are supplied they are combined with logical AND. When neither is supplied the response contains messages: [].

Each messages entry groups request and response, including timestamps, parsed JSON when applicable, raw text when content is not JSON, and any recorded exception.

FAQ

1. Why can a partial availability selection return several agendas?

Because the partial selection can be contained in multiple complete catalog combinations. catalogo.agendas lists those candidates.

2. Are the agendas inside catalogo.agendas identical?

No. They are distinct complete combinations that contain the same partial available selection.

3. What is the difference between catalog and availability?

The catalog defines valid combinations; availability tells you which of those combinations are free in a specific interval.

4. When should I fetch the catalog again?

When no local copy exists or when catalogo_hash changes.

5. What does selected_dimensions do in get_catalogo?

It projects the catalog onto selected dimensions.

6. What does selection do in get_catalogo?

It filters the catalog by specific record IDs and may accept multiple values for a dimension.

7. Why does new_appointment use selectionId?

Because the current implementation creates the ticket from the complete combination identified by selectionId.

8. What should an integration store locally?

At minimum: catalog, catalog hash, relevant IDs, and the appointmentIds returned for created tickets.

9. Does confirming the same ticket twice trigger confirmation twice?

No. confirm_appointment is idempotent: an already-confirmed ticket returns success without rerunning the confirmation action.

10. Are confirm and cancel equivalent operations?

No. They are different state transitions and invoke different business actions. Both operate on bookingId.

11. Why can an audit query by appointment_id show other tickets?

Because the ticket identifies its creation session, and the API then returns the entire conversation for that session token.

MAB Soluciones y Servicios Informáticos Ltda.

Contact: contacto@mab.cl

API support: tomas@mab.cl

WhatsApp: +56 9 6540 2720

Location: Las Condes, Santiago, Chile

Sites: ia.mab.cl · www.mab.cl

Hours: Monday to Friday, 8:00 AM – 6:00 PM

© MAB. All rights reserved.