Citas #

La API de Citas le permite reservar citas para sus contactos en sus tipos de eventos, y luego obtener, listar, actualizar, cancelar o eliminar dichas citas. También responde a la pregunta que surge primero en la mayoría de los flujos de reserva —qué horarios están realmente libres— y cubre el aspecto del calendario: listar los calendarios de Google que tiene conectados e importar eventos que ya existen en ellos. Cuando una conexión de Google Calendar está activa, el evento de calendario correspondiente se crea y se mantiene sincronizado automáticamente en segundo plano. Los restaurantes que utilizan Zenchef, Formitable, OpenTable o TheFork para su propio sistema de reservas también pueden ser verificados y conectados aquí, de modo que el Agente de IA reserve mesas reales en lugar de citas internas; las empresas de citas que gestionan su agenda en Trafft pueden conectarse de la misma manera.

Todas las rutas en esta página son relativas a la URL base https://api.dmchamp.com/v1. Cada solicitud requiere su clave de API; consulte Autenticación para ver la lista completa de formas de enviarla. Los ejemplos a continuación utilizan el encabezado X-API-Key, y un ejemplo de cURL muestra también el formato de consulta ?apiKey=.

Eventos vs. citas: Un tipo de evento es una definición de espacio reservable (el tipo de reunión, su duración, sus salas). Una cita es una instancia reservada de un tipo de evento para un contacto específico. Usted reserva una cita haciendo referencia al contacto y al tipo de evento.

El objeto de cita #

Cada endpoint que devuelve una cita utiliza la misma estructura:

Acerca de la sincronización de calendario: Justo después de reservar o cambiar una cita, google_calendar_event_id puede seguir siendo null y calendar_synced puede ser false porque la sincronización se ejecuta en segundo plano un momento después. Vuelva a obtener la cita poco después para ver los campos de calendario completados.

Encontrar espacios disponibles #

GET /appointments/available-slots

Devuelve los horarios que están realmente libres en un tipo de evento entre dos momentos. Esta suele ser la primera llamada en un flujo de reserva: mostrar estos espacios, dejar que la persona elija uno y, a continuación, enviar la hora elegida a Reservar una cita.

La respuesta ya tiene en cuenta el horario de apertura y la duración del espacio del tipo de evento, sus salas, las citas que ya ha reservado en él y todo lo bloqueado en los calendarios de Google conectados; por lo tanto, un espacio que se devuelve aquí es uno que puede reservar.

Los resultados se devuelven agrupados por día y, cuando el tipo de evento utiliza salas, un grupo por sala por día:

Cada entrada en available_slots tiene:

Los horarios son locales al tipo de evento, no UTC. date, start_time y end_time son valores de reloj de pared en la zona horaria propia del tipo de evento (su anulación, o la zona horaria de su cuenta cuando no tiene ninguna). Reservar una cita espera un instante UTC en formato ISO 8601, así que convierta el espacio que eligió antes de enviarlo.

cURL

curl "https://api.dmchamp.com/v1/appointments/available-slots?event_id=event_xyz789&start_time=2026-06-15T00:00:00.000Z&end_time=2026-06-19T00:00:00.000Z" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  event_id: "event_xyz789",
  start_time: "2026-06-15T00:00:00.000Z",
  end_time: "2026-06-19T00:00:00.000Z",
});
const res = await fetch(
  `https://api.dmchamp.com/v1/appointments/available-slots?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.data);

Python

import requests

res = requests.get(
    "https://api.dmchamp.com/v1/appointments/available-slots",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "event_id": "event_xyz789",
        "start_time": "2026-06-15T00:00:00.000Z",
        "end_time": "2026-06-19T00:00:00.000Z",
    },
)
print(res.json()["data"])

Respuesta (200 OK):

{
  "success": true,
  "data": [
    {
      "date": "15/06/2026",
      "day": "monday",
      "room_name": "Room A",
      "available_slots": [
        { "start_time": "10:00", "end_time": "10:30", "available": true },
        { "start_time": "10:30", "end_time": "11:00", "available": true }
      ]
    },
    {
      "date": "16/06/2026",
      "day": "tuesday",
      "room_name": "Room A",
      "available_slots": [
        { "start_time": "09:00", "end_time": "09:30", "available": true, "spots_left": 2 }
      ]
    }
  ]
}

Un día sin disponibilidad simplemente no aparece. Si faltan event_id, start_time o end_time, se devuelve 400; un tipo de evento que no está en su cuenta devuelve 404.

Reservar una cita #

POST /appointments

Reserva una nueva cita para un contacto en uno de sus tipos de evento. La hora de finalización se calcula automáticamente a partir de la duración del espacio del tipo de evento.

La reserva se verifica para detectar conflictos: si el espacio solicitado se superpone con una cita confirmada existente en el mismo tipo de evento, la solicitud falla con un 409 y no se crea nada.

cURL (usando el formato de consulta ?apiKey=)

curl -X POST "https://api.dmchamp.com/v1/appointments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "start_time": "2026-06-15T10:00:00.000Z",
    "room_name": "Room A"
  }'

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/appointments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contact_id: "contact_abc123",
    event_id: "event_xyz789",
    start_time: "2026-06-15T10:00:00.000Z",
    room_name: "Room A",
  }),
});
const data = await res.json();
console.log(data.appointment_id);

Python

import requests

res = requests.post(
    "https://api.dmchamp.com/v1/appointments",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "contact_id": "contact_abc123",
        "event_id": "event_xyz789",
        "start_time": "2026-06-15T10:00:00.000Z",
        "room_name": "Room A",
    },
)
print(res.json()["appointment_id"])

Respuesta (201 Created):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T10:30:00.000Z",
    "created_at": "2026-06-10T09:00:00.000Z",
    "last_modified_at": "2026-06-10T09:00:00.000Z",
    "room_name": "Room A",
    "google_calendar_event_id": null,
    "calendar_synced": false
  }
}

Obtener una cita #

GET /appointments/{appointmentId}

Devuelve una única cita por su ID, incluido su estado de sincronización de calendario.

cURL

curl "https://api.dmchamp.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.dmchamp.com/v1/appointments/aBcD1234eFgH5678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.appointment);

Python

import requests

res = requests.get(
    "https://api.dmchamp.com/v1/appointments/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["appointment"])

Respuesta (200 OK):

{
  "success": true,
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T10:30:00.000Z",
    "room_name": "Room A",
    "google_calendar_event_id": "abc123googleevent",
    "calendar_synced": true
  }
}

Listar citas #

GET /appointments

Enumera las citas de su cuenta, de la más reciente a la más antigua, con paginación basada en cursor.

Algunas reglas a tener en cuenta:

• Sin filtros, obtendrá todas las citas de la cuenta, página por página.
• Por contacto: establezca contact_id para ver las citas confirmadas de un contacto. Puede restringir esto a un solo día pasando también date.
• Por estado: establezca status (sin contact_id) para listar solo las citas Confirmed o solo las Canceled en toda la cuenta.
• El filtro date sin contact_id, o status=Canceled junto con contact_id, devuelve un 400.

cURL

curl "https://api.dmchamp.com/v1/appointments?contact_id=contact_abc123&date=2026-06-15" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  contact_id: "contact_abc123",
  date: "2026-06-15",
});
const res = await fetch(
  `https://api.dmchamp.com/v1/appointments?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.appointments, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.dmchamp.com/v1/appointments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"contact_id": "contact_abc123", "date": "2026-06-15"},
)
data = res.json()
print(data["appointments"], data["next_cursor"])

Respuesta (200 OK):

{
  "success": true,
  "appointments": [
    {
      "id": "aBcD1234eFgH5678",
      "contact_id": "contact_abc123",
      "event_id": "event_xyz789",
      "status": "Confirmed",
      "start_time": "2026-06-15T10:00:00.000Z",
      "end_time": "2026-06-15T10:30:00.000Z",
      "calendar_synced": true
    }
  ],
  "next_cursor": null
}

Para paginar los resultados, pase el next_cursor de una respuesta como el cursor de la siguiente solicitud. Continúe hasta que next_cursor sea null. Consulte Errores y paginación para conocer el patrón de paginación compartido.

Actualizar una cita #

PUT /appointments/{appointmentId}

Reprogramar una cita o cambiar sus detalles. Envíe solo los campos que desea cambiar; al menos uno es obligatorio. El inicio y el fin combinados deben permanecer en orden cronológico (end_time debe ser posterior a start_time). Los cambios se sincronizan automáticamente con el evento del calendario vinculado.

cURL

curl -X PUT "https://api.dmchamp.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2026-06-16T10:00:00.000Z",
    "end_time": "2026-06-16T10:30:00.000Z"
  }'

JavaScript

const res = await fetch(
  "https://api.dmchamp.com/v1/appointments/aBcD1234eFgH5678",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      start_time: "2026-06-16T10:00:00.000Z",
      end_time: "2026-06-16T10:30:00.000Z",
    }),
  }
);
const data = await res.json();
console.log(data.appointment);

Python

import requests

res = requests.put(
    "https://api.dmchamp.com/v1/appointments/aBcD1234eFgH5678",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "start_time": "2026-06-16T10:00:00.000Z",
        "end_time": "2026-06-16T10:30:00.000Z",
    },
)
print(res.json()["appointment"])

Respuesta (200 OK):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-16T10:00:00.000Z",
    "end_time": "2026-06-16T10:30:00.000Z",
    "calendar_synced": true
  }
}

Cancelar una cita #

POST /appointments/{appointmentId}/cancel

Cancela una cita confirmada, registrando opcionalmente un motivo. La cita permanece en su cuenta con el estado Canceled y el evento de calendario vinculado se elimina automáticamente en segundo plano. Cancelar una cita que ya ha sido cancelada devuelve un 400.

cURL

curl -X POST "https://api.dmchamp.com/v1/appointments/aBcD1234eFgH5678/cancel" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_reason": "Client asked to reschedule next month"
  }'

JavaScript

const res = await fetch(
  "https://api.dmchamp.com/v1/appointments/aBcD1234eFgH5678/cancel",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      cancellation_reason: "Client asked to reschedule next month",
    }),
  }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.post(
    "https://api.dmchamp.com/v1/appointments/aBcD1234eFgH5678/cancel",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"cancellation_reason": "Client asked to reschedule next month"},
)
print(res.json()["success"])

Respuesta (200 OK):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678"
}

Eliminar una cita #

DELETE /appointments/{appointmentId}

Elimina permanentemente una cita y sus referencias. Si solo desea cancelar la reserva manteniendo el registro, utilice cancelar en su lugar.

cURL

curl -X DELETE "https://api.dmchamp.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.dmchamp.com/v1/appointments/aBcD1234eFgH5678",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.delete(
    "https://api.dmchamp.com/v1/appointments/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

Respuesta (200 OK):

{
  "success": true
}

Listar sus calendarios de Google conectados #

GET /appointments/google-calendars

Devuelve los calendarios de Google disponibles en esta cuenta, directamente desde Google; es útil para mostrar al titular de la cuenta un selector desde el cual importar, o simplemente para confirmar que la conexión está activa.

Esto solo funciona una vez que la cuenta ha conectado Google Calendar (Ajustes → Integraciones) con al menos acceso de lectura. Si no lo ha hecho, o si el acceso concedido ya no incluye el ámbito de lectura de calendario, obtendrá un 400 que le indicará que lo (re)conecte.

cURL

curl "https://api.dmchamp.com/v1/appointments/google-calendars" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/appointments/google-calendars", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data);

Python

import requests

res = requests.get(
    "https://api.dmchamp.com/v1/appointments/google-calendars",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["data"])

Respuesta (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "primary",
      "summary": "jane@example.com",
      "timeZone": "America/New_York",
      "accessRole": "owner",
      "primary": true
    },
    {
      "id": "abcdefg1234567890@group.calendar.google.com",
      "summary": "Bookings",
      "timeZone": "America/New_York",
      "accessRole": "writer"
    }
  ]
}

Cada entrada tiene la forma del propio CalendarListEntry de Google, por lo que los nombres de los campos siguen el camelCase de Google, no el snake_case habitual de esta API; es decir, son los datos de Google transmitidos tal cual, no los nuestros. Una conexión faltante o revocada devuelve un 400 con un error que explica que Google Calendar debe ser (re)conectado.

Importar eventos desde un Google Calendar #

POST /appointments/import-calendar-events

Extrae los eventos que ya se encuentran en los Google Calendar conectados de una campaña o un Agente de IA y los convierte en citas; es útil la primera vez que conecta un calendario que ya tiene reservas. Esto puede llevar tiempo (cada evento pasa por un proceso de extracción para determinar a quién pertenece), por lo que nunca se ejecuta en línea: la solicitud pone en cola un trabajo en segundo plano y le devuelve un job_id para realizar consultas.

Envíe exactamente uno de campaign_id / agent_id, nunca ambos y nunca ninguno; cualquier otra combinación devuelve un 400. Cualquiera que envíe debe pertenecer a su cuenta, o recibirá un 404.

cURL

curl -X POST "https://api.dmchamp.com/v1/appointments/import-calendar-events?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "identifier": "EMAIL"
  }'

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/appointments/import-calendar-events", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: "agent_abc123",
    identifier: "EMAIL",
  }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "https://api.dmchamp.com/v1/appointments/import-calendar-events",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"agent_id": "agent_abc123", "identifier": "EMAIL"},
)
print(res.json()["job_id"])

Respuesta (202 Accepted):

{
  "success": true,
  "job_id": "jK9mQ2xR7pL4wN1t",
  "status": "queued",
  "campaign_id": null,
  "agent_id": "agent_abc123"
}

campaign_id y agent_id devuelven el valor que usted envió; el otro es siempre null.

Consultar el trabajo de importación #

GET /appointments/import-calendar-events/{jobId}

curl "https://api.dmchamp.com/v1/appointments/import-calendar-events/jK9mQ2xR7pL4wN1t" \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta (200 OK):

{
  "success": true,
  "job_id": "jK9mQ2xR7pL4wN1t",
  "status": "completed",
  "message": "Imported 12 events as appointments.",
  "error": null
}

GET en un jobId que no existe (o que pertenece a una cuenta diferente) devuelve un 404.

Integraciones de reserva externas (Zenchef / Formitable / OpenTable / TheFork / Trafft) #

Zenchef y Formitable son sistemas de reserva de restaurantes a través de los cuales su Agente de IA puede reservar mesas reales; Trafft es una plataforma de programación para empresas de citas, que se conecta una vez por cuenta en lugar de por restaurante. Las dos plataformas de restaurantes tienen cada una un widget de reserva público y sin autenticación (https://api.dmchamp.com/v1/zenchef-widget/... y https://api.dmchamp.com/v1/formitable-widget/...) que se muestra dentro del chat para el comensal; esas rutas de widget son páginas HTML simples destinadas a abrirse en un navegador, no puntos finales de API JSON, por lo que no están documentadas aquí. A continuación se presentan los puntos finales de gestión de cuentas: verificar que un ID de restaurante pertenece al titular de la cuenta y, luego, añadirlo, actualizarlo o eliminarlo.

Zenchef #

Conectar un restaurante de Zenchef es una verificación de dos pasos, por lo que el titular de la cuenta demuestra que realmente dirige el restaurante antes de que se conecte al bot: primero se comprueba que el ID existe (sin revelar el nombre) y, a continuación, se le pide que escriba el nombre del restaurante para verificar que coincide.

Paso 1 — Comprobar que existe un ID de restaurante

POST /appointments/zenchef-restaurants/check

curl -X POST "https://api.dmchamp.com/v1/appointments/zenchef-restaurants/check?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345" }'

Respuesta (200 OK):

{
  "success": true,
  "data": { "exists": true, "requiresNameVerification": true }
}

exists: false significa que ningún restaurante de Zenchef tiene ese ID; no hay nada más que hacer. Limitado a 10 comprobaciones por cada 5 minutos por cuenta; exceder este límite devuelve 429.

Paso 2 — Verificar el nombre del restaurante

POST /appointments/zenchef-restaurants/verify-name

curl -X POST "https://api.dmchamp.com/v1/appointments/zenchef-restaurants/verify-name?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345", "user_input_name": "The Blue Door Bistro" }'

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "id": "12345",
      "name": "The Blue Door Bistro",
      "address": "1 Rue de Rivoli, Paris",
      "status": "active"
    }
  }
}

verified: false significa que el nombre no coincidió; restaurantDetails se omite, pida al titular de la cuenta que lo intente de nuevo. Limitado a 3 intentos cada 5 minutos (más estricto que la comprobación de existencia, ya que este es el paso de prueba real). Un restaurant_id que ya no se resuelve en Zenchef devuelve 404.

Paso 3 — Guardar el restaurante

POST /appointments/zenchef-restaurants

curl -X POST "https://api.dmchamp.com/v1/appointments/zenchef-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345", "restaurant_name": "The Blue Door Bistro" }'

Respuesta (201 Created):

{ "success": true, "data": { "restaurantId": "12345" } }

Actualizar un restaurante Zenchef guardado

PUT /appointments/zenchef-restaurants/{restaurantId}

curl -X PUT "https://api.dmchamp.com/v1/appointments/zenchef-restaurants/12345" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Respuesta (200 OK): misma estructura que la respuesta de guardado anterior.

Eliminar un restaurante Zenchef

DELETE /appointments/zenchef-restaurants/{restaurantId}

curl -X DELETE "https://api.dmchamp.com/v1/appointments/zenchef-restaurants/12345" \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta (200 OK): { "success": true, "data": { "restaurantId": "12345" } }

Un restaurantId que no esté actualmente en la cuenta devuelve 404 al intentar actualizar o eliminar.

Formitable #

Formitable no necesita la prueba de nombre de dos pasos que requiere Zenchef; sus ID de restaurante ya están definidos por negocio, por lo que una llamada de verificación es suficiente. También cuenta con una búsqueda de detalles que se utiliza para almacenar en caché la URL del sitio web del restaurante durante la configuración.

Verificar un ID de restaurante

POST /appointments/formitable-restaurants/verify

curl -X POST "https://api.dmchamp.com/v1/appointments/formitable-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "the-blue-door", "language": "en" }'

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "the-blue-door",
      "productCount": 4,
      "sampleProductTitle": "Dinner for two",
      "language": "en"
    }
  }
}

Un restaurant_id que Formitable no reconoce devuelve 404. Limitado a 10 intentos por cada 5 minutos por cuenta.

Obtener detalles del restaurante

GET /appointments/formitable-restaurants/{restaurantId}/details?language=en

Obtiene el perfil público del restaurante desde Formitable, incluida su página web; se utiliza para almacenar en caché la URL del sitio web mientras se configura el restaurante. language es un parámetro de consulta opcional, cuyo valor predeterminado es "en".

curl "https://api.dmchamp.com/v1/appointments/formitable-restaurants/the-blue-door/details?language=en" \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "uid": "the-blue-door",
    "name": "The Blue Door Bistro",
    "website": "https://thebluedoorbistro.com",
    "email": "info@thebluedoorbistro.com",
    "telephone": "+31201234567",
    "streetAddress": "Prinsengracht 1",
    "zipcode": "1015 AB",
    "city": "Amsterdam",
    "country": "Netherlands",
    "countryCode": "NL",
    "currency": "EUR"
  }
}

Guardar el restaurante

POST /appointments/formitable-restaurants

curl -X POST "https://api.dmchamp.com/v1/appointments/formitable-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "restaurant_id": "the-blue-door",
    "restaurant_name": "The Blue Door Bistro",
    "language": "en",
    "website_url": "https://thebluedoorbistro.com"
  }'

Respuesta (201 Created): { "success": true, "data": { "restaurantId": "the-blue-door" } }

Actualizar un restaurante Formitable guardado

PUT /appointments/formitable-restaurants/{restaurantId}

curl -X PUT "https://api.dmchamp.com/v1/appointments/formitable-restaurants/the-blue-door" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Respuesta (200 OK): misma estructura que la respuesta de guardado anterior.

Eliminar un restaurante Formitable

DELETE /appointments/formitable-restaurants/{restaurantId}

curl -X DELETE "https://api.dmchamp.com/v1/appointments/formitable-restaurants/the-blue-door" \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta (200 OK): { "success": true, "data": { "restaurantId": "the-blue-door" } }

Un restaurantId que no esté actualmente en la cuenta devuelve 404 al intentar actualizar o eliminar.

OpenTable #

Se accede a los restaurantes de OpenTable a través de las credenciales de socio de OpenTable de la plataforma, y OpenTable solo permite que esas credenciales vean los restaurantes que conectaron el listado de la plataforma dentro del Marketplace de Integraciones de OpenTable. Por lo tanto, al igual que con Formitable, una llamada de verificación es suficiente: un ID de restaurante accesible (el “RID” numérico) demuestra tanto que el restaurante existe como que ha conectado la integración. Hasta que el listado de socio de OpenTable esté habilitado en la plataforma, la llamada de verificación responderá 503.

Verificar un restaurante de OpenTable

POST /appointments/opentable-restaurants/verify

curl -X POST "https://api.dmchamp.com/v1/appointments/opentable-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "1038007" }'

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "1038007",
      "diningAreaCount": 2,
      "diningAreaNames": ["Main Room", "Garden"],
      "tableTypes": ["default", "outdoor", "bar"]
    }
  }
}

verified: false significa que ningún restaurante de OpenTable tiene ese ID. Un 403 significa que el restaurante existe pero aún no ha conectado la integración de la plataforma dentro de OpenTable. Limitado a 10 intentos por cada 5 minutos por cuenta.

Añadir un restaurante de OpenTable

POST /appointments/opentable-restaurants

curl -X POST "https://api.dmchamp.com/v1/appointments/opentable-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "1038007", "restaurant_name": "The Blue Door", "website_url": "https://thebluedoor.example" }'

Respuesta (201 Created): { "success": true, "data": { "restaurantId": "1038007" } }

Actualizar un restaurante de OpenTable guardado

PUT /appointments/opentable-restaurants/{restaurantId}

Envíe cualquiera de restaurant_name, is_active (pausar con false) o website_url (una cadena vacía lo borra); los campos omitidos se dejan sin cambios.

curl -X PUT "https://api.dmchamp.com/v1/appointments/opentable-restaurants/1038007" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Respuesta (200 OK): { "success": true, "data": { "restaurantId": "1038007" } }

Eliminar un restaurante de OpenTable

DELETE /appointments/opentable-restaurants/{restaurantId}

curl -X DELETE "https://api.dmchamp.com/v1/appointments/opentable-restaurants/1038007" \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta (200 OK): { "success": true, "data": { "restaurantId": "1038007" } }

Un restaurantId que no se encuentra actualmente en la cuenta devuelve 404 al actualizar.

TheFork #

Se accede a los restaurantes de TheFork a través de las credenciales de socio de TheFork de la plataforma, y TheFork solo permite que esas credenciales vean los restaurantes que tienen habilitado al socio de la plataforma en su cuenta de TheFork. Por lo tanto, al igual que con Formitable y OpenTable, una llamada de verificación es suficiente: un ID de restaurante accesible demuestra tanto que el restaurante existe como que el socio está habilitado en él. El ID es el UUID que TheFork asigna al restaurante en TheFork Manager, enviado como una cadena de texto. Hasta que TheFork haya aprobado a la plataforma como socio y emitido las credenciales, la llamada de verificación responderá 503; consulte TheFork para saber qué significa esto hoy en día.

Verificar un restaurante de TheFork

POST /appointments/thefork-restaurants/verify

curl -X POST "https://api.dmchamp.com/v1/appointments/thefork-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" }'

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60",
      "partySizes": [1, 2, 3, 4, 5, 6, 7, 8]
    }
  }
}

partySizes son los tamaños de grupo que el restaurante acepta en línea durante los próximos 30 días. Un 404 o 403 significa que TheFork no nos proporcionó un restaurante con ese ID; ya sea porque el ID es incorrecto o porque el socio de la plataforma aún no está habilitado en ese restaurante; un 400 significa que el ID no es un UUID. Limitado a 10 intentos por cada 5 minutos por cuenta.

Añadir un restaurante de TheFork

POST /appointments/thefork-restaurants

curl -X POST "https://api.dmchamp.com/v1/appointments/thefork-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60", "restaurant_name": "The Blue Door", "website_url": "https://thebluedoor.example" }'

Respuesta (201 Created): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

Actualizar un restaurante de TheFork guardado

PUT /appointments/thefork-restaurants/{restaurantId}

Envíe cualquiera de restaurant_name, is_active (pausar con false) o website_url (una cadena vacía lo borra); los campos omitidos se dejan sin cambios.

curl -X PUT "https://api.dmchamp.com/v1/appointments/thefork-restaurants/9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Respuesta (200 OK): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

Eliminar un restaurante de TheFork

DELETE /appointments/thefork-restaurants/{restaurantId}

curl -X DELETE "https://api.dmchamp.com/v1/appointments/thefork-restaurants/9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta (200 OK): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

Un restaurantId que no esté actualmente en la cuenta devuelve 404 al intentar actualizar o eliminar.

Trafft #

Trafft se conecta una vez para toda la cuenta, no por ubicación: una dirección de empresa más las credenciales de API del panel de administración de Trafft (Features & Integrations → API & Connectors, parte del plan Business de Trafft). La llamada de conexión verifica esas credenciales con Trafft antes de almacenar nada, por lo que una dirección incorrecta, credenciales erróneas o un plan sin acceso a la API fallarán aquí en lugar de durante una conversación con el cliente. El secreto del cliente se almacena cifrado y nunca se devuelve mediante ningún punto final.

Las tres llamadas de escritura (POST, PUT, DELETE) requieren el permiso de edición de Integraciones; el estado GET requiere el permiso de visualización de Integraciones.

Conectar Trafft

POST /appointments/trafft/connect

curl -X POST "https://api.dmchamp.com/v1/appointments/trafft/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "acme",
    "client_id": "YOUR_TRAFFT_CLIENT_ID",
    "client_secret": "YOUR_TRAFFT_CLIENT_SECRET",
    "company_name": "Acme Salon"
  }'

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "subdomain": "acme",
    "service_count": 12,
    "employee_count": 4,
    "location_count": 2
  }
}

Los recuentos se devuelven desde Trafft durante la verificación; son la forma más rápida de confirmar que las credenciales apuntan a la cuenta que usted pretendía.

Obtener el estado de la conexión

GET /appointments/trafft

curl "https://api.dmchamp.com/v1/appointments/trafft" \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "connected": true,
    "subdomain": "acme",
    "hostname": "acme.admin.trafft.com",
    "client_id": "YOUR_TRAFFT_CLIENT_ID",
    "company_name": "Acme Salon",
    "is_active": true,
    "service_count": 12,
    "employee_count": 4,
    "location_count": 2
  }
}

connected: false significa que aún no se ha configurado nada. El secreto del cliente nunca se incluye en esta respuesta.

Actualizar la conexión

PUT /appointments/trafft

curl -X PUT "https://api.dmchamp.com/v1/appointments/trafft" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Respuesta (200 OK): el mismo objeto de conexión que el GET anterior.

Desconectar Trafft

DELETE /appointments/trafft

curl -X DELETE "https://api.dmchamp.com/v1/appointments/trafft" \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta (200 OK): { "success": true }

La desconexión solo elimina las credenciales almacenadas. Las citas que ya están en Trafft permanecen intactas.

Formato de error en todos los endpoints de Zenchef/Formitable/OpenTable/TheFork: a diferencia del resto de esta página, los errores aquí incluyen el estado dos veces (una vez como estado HTTP y otra como error_code en el cuerpo); por ejemplo, { "success": false, "error": "Restaurant not found", "error_code": 404 }. Manéjelo de la misma manera que cualquier otro error: verifique success y lea error para obtener el mensaje.

Errores de la API de citas #

Los endpoints de citas devuelven el sobre de error estándar:

{
  "success": false,
  "error": "Appointment not found"
}

Los códigos compartidos que puede devolver cualquier endpoint — 401, 403 (su plan no incluye acceso a la API), 429 (límite de tasa) y 500 — se enumeran con orientación sobre reintentos en Errores y paginación.

curl -X PUT "https://api.dmchamp.com/v1/account-config/google-oauth-client?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "123456789012-abcdefghijklmnop.apps.googleusercontent.com",
    "client_secret": "GOCSPX-your-client-secret"
  }'

{
  "success": true,
  "configured": true,
  "client_id": "123456789012-abcdefghijklmnop.apps.googleusercontent.com",
  "redirect_uris": [
    "https://api.youragency.com/v1/auth-google-callback",
    "https://api.dmchamp.com/v1/auth-google-callback"
  ],
  "scopes": [
    "https://www.googleapis.com/auth/calendar.events",
    "https://www.googleapis.com/auth/calendar.readonly"
  ],
  "setup": ["…"]
}

Próximos pasos #

• Contactos — cree y busque los contactos para los que realiza reservas.
• Mensajes y conversaciones — envíe a un contacto una confirmación o un recordatorio.
• Webhooks — reciba notificaciones cuando cambien las citas.