API pública para asistentes de IA

Actualizado el miércoles 04 de noviembre de 2026

Cómo un asistente de IA o tu propio software consulta negocios, servicios, precios y horarios libres de Citauno, y arma el enlace de reserva.

Citauno tiene una API pública de solo lectura: un asistente de IA (ChatGPT, Claude, Gemini, Perplexity) o cualquier programa puede buscar negocios, leer sus servicios con precio y duración, sus locales y horarios, y ver los horarios libres de verdad de un servicio. Para reservar, la API devuelve el enlace al formulario de reserva con todo ya elegido: la persona lo abre, revisa, pone sus datos y confirma.

No hace falta registrarse ni pedir una clave. Los asistentes que aceptan servidores MCP se conectan directo en https://citauno.com/mcp (ver Conectar un asistente (MCP)).

Qué negocios aparecen

Los mismos que aparecen en Explorar (/explorar): publicados, con “Mostrar en el home del marketplace y búsquedas” marcado, con las reservas online activas y listos para reservar (al menos un servicio activo, un local con un día abierto y un profesional que acepte reservas). Un negocio pausado, eliminado, oculto del marketplace o con las reservas online apagadas no aparece, y su dirección en la API responde 404.

Si tenés un negocio y no querés aparecer, desmarcá “Mostrar en el home del marketplace y búsquedas” en Ajustes. Tu perfil y tu enlace de reservas siguen funcionando para quien ya los tiene.

Qué devuelve y qué no

Devuelve solo lo que cualquiera ve en tu perfil y en tu página de reservas:

nombre, categoría, descripción, portada y logo, calificación (solo si se muestra en el perfil);
locales con dirección, ciudad, coordenadas y horario de atención;
servicios que se reservan online, con duración y precio en la moneda del negocio (“desde” cuando el precio depende del profesional);
días y horarios libres, calculados igual que en la página de reservas, sin elegir profesional.

No devuelve teléfonos, emails, nombres de profesionales, clientes, reservas ni nada que solo ve el dueño. No crea reservas: solo arma el enlace para que la persona confirme.

Las direcciones

Todas responden JSON en https://citauno.com/api/v1. El idioma de los nombres y mensajes se elige con ?locale=es, pt o en (español si no se indica).

Dirección	Qué devuelve	Parámetros
`GET /api/v1/businesses`	Negocios que coinciden con la búsqueda, de a 20	`q` (texto), `city`, `country` (código, ej. `PY`), `category[]` (categoría de Explorar, ej. `barberia`), `service` (nombre del servicio), `page`, `per_page` (hasta 50)
`GET /api/v1/businesses/{slug}`	Un negocio con locales, horarios y servicios
`GET /api/v1/businesses/{slug}/availability`	Los días con al menos un horario libre	`service_ids[]` (obligatorio, hasta 5), `location_id`, `from` y `to` (AAAA-MM-DD; hasta 62 días)
`GET /api/v1/businesses/{slug}/slots`	Los horarios libres de un día, cada uno con su enlace de reserva	`service_ids[]`, `date` (obligatorio), `location_id`
`GET /api/v1/businesses/{slug}/booking_link`	El enlace al formulario de reserva con todo elegido	`service_ids[]`, `location_id`, `date`, `starts_at` (ISO 8601)

El slug es el final del enlace del perfil: el de citauno.com/barberia-el-centro es barberia-el-centro. Los id de servicios y locales salen de la dirección del negocio. Sin location_id se usa el primer local, como en la página de reservas.

Un ejemplo

Buscar barberías en Asunción:

GET https://citauno.com/api/v1/businesses?q=barberia&city=Asuncion
Leer un negocio y sus servicios:

GET https://citauno.com/api/v1/businesses/barberia-el-centro
Ver qué días hay lugar para el servicio 12:

GET https://citauno.com/api/v1/businesses/barberia-el-centro/availability?service_ids[]=12

Ver los horarios de un día. Cada horario trae su booking_url:

GET https://citauno.com/api/v1/businesses/barberia-el-centro/slots?service_ids[]=12&date=2026-11-10

{
  "business": "barberia-el-centro",
  "timezone": "America/Asuncion",
  "location_id": 3,
  "service_ids": [12],
  "date": "2026-11-10",
  "slots": [
    {
      "starts_at": "2026-11-10T09:00:00-03:00",
      "ends_at": "2026-11-10T09:30:00-03:00",
      "booking_url": "https://citauno.com/businesses/barberia-el-centro/book?..."
    }
  ]
}

Darle a la persona el booking_url. Abre el formulario con el servicio, el local, el día y la hora ya elegidos; pone su nombre y su WhatsApp y confirma. La reserva queda marcada como llegada desde un asistente de IA.

Las horas vienen en la zona horaria del negocio, con su desfase (-03:00), y timezone es el nombre IANA de esa zona (America/Asuncion, America/Sao_Paulo), que entiende cualquier lenguaje de programación.

Cuando un día no tiene horarios, slots viene vacío y reason dice por qué: closed_day (el local cierra ese día), fully_booked (todo ocupado), all_past (ya pasaron), outside_window (antes de hoy o más allá de los días que el negocio acepta reservas), entre otros.

Conectar un asistente (MCP)

Los asistentes que aceptan servidores MCP remotos (Claude, ChatGPT, Cursor y otros) se conectan sin programar nada. La dirección del servidor es:

https://citauno.com/mcp

Agregala como conector personalizado o servidor MCP en tu asistente. No pide inicio de sesión ni clave. El asistente ve cuatro herramientas, todas de solo lectura:

Herramienta	Qué hace
`search_businesses`	Busca negocios por texto, ciudad, país, categoría o servicio
`get_business`	Un negocio con sus locales, horarios y servicios con precio
`get_availability`	Los días con algún horario libre o, con `date`, los horarios de ese día
`booking_link`	El enlace al formulario de reserva con todo elegido

Responden lo mismo que las direcciones de arriba, para los mismos negocios. El idioma se elige con locale (es, pt o en) en cada herramienta, o para todas en la dirección: con https://citauno.com/mcp?locale=en el asistente lee las herramientas y las respuestas en inglés. Tampoco reservan: el asistente le da a la persona el enlace y ella confirma. Un error llega como resultado de la herramienta con isError y el mismo mensaje que da la API.

Para programadores: es un servidor MCP por Streamable HTTP, sin estado (no hay Mcp-Session-Id), que responde cada POST con un JSON. Una prueba desde la terminal:

curl -X POST https://citauno.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_businesses","arguments":{"city":"Asunción"}}}'

Límites y errores

Límite por conexión: 300 consultas cada 5 minutos, sumando la API y el servidor MCP. Al pasarlo, la respuesta es 429 con Retry-After.
Sin cookies ni sesión. Se puede llamar desde el navegador de cualquier sitio (CORS abierto para GET en la API y para POST en /mcp).
Las respuestas se pueden guardar un minuto (30 segundos los horarios).

Un error trae un code fijo y un message en el idioma pedido:

{ "error": { "code": "service_not_found", "message": "Alguno de los servicios no existe en este negocio o no se reserva online." } }

`code`	Estado	Cuándo
`business_not_found`	404	El negocio no existe o no aparece en Explorar
`services_required`	400	Faltan los `service_ids[]`
`too_many_services`	400	Más de 5 servicios
`service_not_found`	400	Un servicio no es de ese negocio o no se reserva online
`location_not_found`	400	El `location_id` no es de ese negocio
`date_required`, `invalid_date`	400	Falta `date` o no es AAAA-MM-DD
`invalid_starts_at`	400	`starts_at` no es una fecha y hora válida
`rate_limited`	429	Se pasó el límite
`route_not_found`	404	La dirección no existe

La API es la versión 1 (/api/v1). Un cambio que rompa lo que ya funciona irá en una versión nueva.