API pública para assistentes de IA

Atualizado em quarta-feira, 4 de novembro de 2026

Como um assistente de IA ou o seu próprio software consulta negócios, serviços, preços e horários livres da Citauno e monta o link de agendamento.

A Citauno tem uma API pública só de leitura: um assistente de IA (ChatGPT, Claude, Gemini, Perplexity) ou qualquer programa pode buscar negócios, ler seus serviços com preço e duração, suas unidades e horários, e ver os horários livres de verdade de um serviço. Para agendar, a API devolve o link do formulário de agendamento com tudo já escolhido: a pessoa abre, revisa, coloca seus dados e confirma.

Não é preciso se cadastrar nem pedir uma chave. Os assistentes que aceitam servidores MCP se conectam direto em https://citauno.com/mcp (veja Conectar um assistente (MCP)).

Quais negócios aparecem

Os mesmos que aparecem em Explorar (/explorar): publicados, com “Mostrar no marketplace e nas buscas” marcado, com os agendamentos online ativos e prontos para agendar (pelo menos um serviço ativo, uma unidade com um dia aberto e um profissional que aceite agendamentos). Um negócio pausado, excluído, oculto do marketplace ou com os agendamentos online desligados não aparece, e o seu endereço na API responde 404.

Se você tem um negócio e não quer aparecer, desmarque “Mostrar no marketplace e nas buscas” em Ajustes. Seu perfil e seu link de agendamento continuam funcionando para quem já os tem.

O que devolve e o que não

Devolve só o que qualquer pessoa vê no seu perfil e na sua página de agendamento:

nome, categoria, descrição, capa e logo, avaliação (só se aparece no perfil);
unidades com endereço, cidade, coordenadas e horário de funcionamento;
serviços agendáveis online, com duração e preço na moeda do negócio (“a partir de” quando o preço depende do profissional);
dias e horários livres, calculados como na página de agendamento, sem escolher profissional.

Não devolve telefones, e-mails, nomes de profissionais, clientes, agendamentos nem nada que só o dono vê. Não cria agendamentos: só monta o link para a pessoa confirmar.

Os endereços

Todos respondem JSON em https://citauno.com/api/v1. O idioma dos nomes e das mensagens é escolhido com ?locale=es, pt ou en (espanhol se não for indicado).

Endereço	O que devolve	Parâmetros
`GET /api/v1/businesses`	Negócios que correspondem à busca, de 20 em 20	`q` (texto), `city`, `country` (código, ex. `BR`), `category[]` (categoria do Explorar, ex. `barberia`), `service` (nome do serviço), `page`, `per_page` (até 50)
`GET /api/v1/businesses/{slug}`	Um negócio com unidades, horários e serviços
`GET /api/v1/businesses/{slug}/availability`	Os dias com pelo menos um horário livre	`service_ids[]` (obrigatório, até 5), `location_id`, `from` e `to` (AAAA-MM-DD; até 62 dias)
`GET /api/v1/businesses/{slug}/slots`	Os horários livres de um dia, cada um com o seu link de agendamento	`service_ids[]`, `date` (obrigatório), `location_id`
`GET /api/v1/businesses/{slug}/booking_link`	O link do formulário de agendamento com tudo escolhido	`service_ids[]`, `location_id`, `date`, `starts_at` (ISO 8601)

O slug é o final do link do perfil: o de citauno.com/barbearia-centro é barbearia-centro. Os id de serviços e unidades vêm do endereço do negócio. Sem location_id é usada a primeira unidade, como na página de agendamento.

Um exemplo

Buscar barbearias em Asunción:

GET https://citauno.com/api/v1/businesses?q=barbearia&city=Asuncion&locale=pt
Ler um negócio e seus serviços:

GET https://citauno.com/api/v1/businesses/barbearia-centro?locale=pt
Ver em quais dias há vaga para o serviço 12:

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

Ver os horários de um dia. Cada horário traz o seu booking_url:

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

{
  "business": "barbearia-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/pt/businesses/barbearia-centro/book?..."
    }
  ]
}

Entregar à pessoa o booking_url. Ele abre o formulário com o serviço, a unidade, o dia e a hora já escolhidos; ela coloca seu nome e seu WhatsApp e confirma. O agendamento fica marcado como vindo de um assistente de IA.

Os horários vêm no fuso do negócio, com seu deslocamento (-03:00), e timezone é o nome IANA desse fuso (America/Asuncion, America/Sao_Paulo), que qualquer linguagem de programação entende.

Quando um dia não tem horários, slots vem vazio e reason diz por quê: closed_day (a unidade fecha nesse dia), fully_booked (tudo ocupado), all_past (já passaram), outside_window (antes de hoje ou além dos dias em que o negócio aceita agendamentos), entre outros.

Conectar um assistente (MCP)

Os assistentes que aceitam servidores MCP remotos (Claude, ChatGPT, Cursor e outros) se conectam sem programar nada. O endereço do servidor é:

https://citauno.com/mcp

Adicione-o como conector personalizado ou servidor MCP no seu assistente. Não pede login nem chave. O assistente vê quatro ferramentas, todas só de leitura:

Ferramenta	O que faz
`search_businesses`	Busca negócios por texto, cidade, país, categoria ou serviço
`get_business`	Um negócio com suas unidades, horários e serviços com preço
`get_availability`	Os dias com algum horário livre ou, com `date`, os horários desse dia
`booking_link`	O link do formulário de agendamento com tudo escolhido

Elas respondem o mesmo que os endereços acima, para os mesmos negócios. O idioma se escolhe com locale (es, pt ou en) em cada ferramenta, ou para todas no endereço: com https://citauno.com/mcp?locale=pt o assistente lê as ferramentas e as respostas em português. Também não agendam: o assistente entrega à pessoa o link e ela confirma. Um erro chega como resultado da ferramenta com isError e a mesma mensagem que a API dá.

Para programadores: é um servidor MCP por Streamable HTTP, sem estado (não há Mcp-Session-Id), que responde cada POST com um JSON. Um teste pelo 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"}}}'

Limites e erros

Limite por conexão: 300 consultas a cada 5 minutos, somando a API e o servidor MCP. Ao passar dele, a resposta é 429 com Retry-After.
Sem cookies nem sessão. Pode ser chamada do navegador de qualquer site (CORS aberto para GET na API e para POST em /mcp).
As respostas podem ser guardadas por um minuto (30 segundos os horários).

Um erro traz um code fixo e uma message no idioma pedido:

{ "error": { "code": "service_not_found", "message": "Algum dos serviços não existe neste negócio ou não é agendável online." } }

`code`	Status	Quando
`business_not_found`	404	O negócio não existe ou não aparece no Explorar
`services_required`	400	Faltam os `service_ids[]`
`too_many_services`	400	Mais de 5 serviços
`service_not_found`	400	Um serviço não é desse negócio ou não é agendável online
`location_not_found`	400	O `location_id` não é desse negócio
`date_required`, `invalid_date`	400	Falta `date` ou não está em AAAA-MM-DD
`invalid_starts_at`	400	`starts_at` não é uma data e hora válida
`rate_limited`	429	O limite foi ultrapassado
`route_not_found`	404	O endereço não existe

A API é a versão 1 (/api/v1). Uma mudança que quebre o que já funciona irá numa versão nova.