GuruAgenda API#

A API do GuruAgenda dá acesso aos dados da sua organização: equipe, serviços, clientes, horários livres, agendamentos, Fila Online, sinais e eventos. Use-a para integrar a agenda com CRM (HubSpot, Pipedrive, RD Station…), automações (n8n, Make, Zapier) e sistemas próprios.

Cada rota, campo e exemplo está na referência interativa, gerada do próprio código. Esta página explica as regras que valem para todas elas. Para receber avisos na hora em que algo acontece, veja Webhooks; para montar integrações sem código, n8n, Make e Zapier.

Vai usar uma IA ou um assistente de código para montar a integração? O botão Copiar para IA, no topo desta página, copia a documentação inteira (guias e todas as rotas) num texto só. O mesmo texto fica em /docs/llms-full.txt.

Começando#

1. Peça ao dono da conta para criar uma chave em Configurações → API e Webhooks, escolhendo os escopos (veja abaixo). A chave aparece uma vez só: guarde-a num cofre de senhas ou na credencial da sua ferramenta.
2. Teste a chave:

curl https://api.guruagenda.com.br/v1/me \
  -H "Authorization: Bearer ga_live_SUA_CHAVE"

A resposta traz a organização, o plano, as funcionalidades ligadas e o nome e os escopos da chave. É a mesma chamada que o botão Test credential do n8n faz.

A API faz parte dos planos superiores. Sem ela no plano, toda chamada responde 403 com o código feature_not_enabled.

Autenticação e escopos#

Toda requisição leva a chave no header Authorization: Bearer ga_live_…. Não aceitamos a chave na URL nem em cookie. A chave é da organização, não de uma pessoa, e o dono pode revogá-la a qualquer momento na mesma tela.

Rota fora dos escopos da chave responde 403 com forbidden_scope. Recurso de outra organização responde sempre 404, nunca 403.

Formato dos dados#

• JSON em UTF-8 nos dois sentidos (Content-Type: application/json).
• Datas e horas em ISO 8601 com o fuso: 2026-10-20T14:30:00-03:00. Ao enviar, inclua o fuso (-03:00 ou Z). Datas sem hora: 2026-10-20.
• Dinheiro em texto com duas casas, mais a moeda: "price": "250.00", "currency": "BRL". Nunca número de ponto flutuante.
• Duração em minutos inteiros (duration_minutes).
• Telefone sai em E.164 (+5511999999999). Na entrada, aceitamos o formato que vier ((11) 99999-9999) e normalizamos.
• CPF e CNPJ só com dígitos.
• Campos nunca somem: sem valor, o campo vem com null. Isso facilita mapear campos no n8n e no Make.
• Referências vêm como *_id e um mini-objeto com o nome ("client_id": 4821, "client": {"id": 4821, "name": "Maria Souza", …}). Algumas rotas aceitam ?expand= para trazer o objeto completo; a referência diz quais.

Paginação#

Listas vêm em páginas de até 200 itens (padrão 50, parâmetro limit):

{
  "data": [ … ],
  "has_more": true,
  "next_cursor": "WzkwMzIxXQ",
  "next": "https://api.guruagenda.com.br/v1/appointments?limit=50&cursor=WzkwMzIxXQ"
}

next é a URL completa da próxima página (null na última). No nó HTTP Request do n8n, use a paginação Response Contains Next URL com {{ $response.body.next }}. Quem monta a URL à mão usa cursor=<next_cursor>. O cursor é opaco: não tente decodificá-lo.

Filtros com vários valores aceitam as duas formas, status[]=CONFIRMED&status[]=PENDING e status=CONFIRMED,PENDING.

Para sincronizar só o que mudou, as listas de clientes e agendamentos aceitam updated_since (data e hora ISO 8601). Para receber mudanças na hora, sem consultar de tempos em tempos, use webhooks.

Repetir um POST com segurança#

Ferramentas de automação repetem uma etapa quando a rede falha. Para que a repetição não crie um segundo agendamento, mande o header Idempotency-Key com um valor único por operação (até 255 caracteres; um UUID serve):

curl -X POST https://api.guruagenda.com.br/v1/appointments \
  -H "Authorization: Bearer ga_live_SUA_CHAVE" \
  -H "Idempotency-Key: 6f1c2b9e-1d3a-4f57-9a0e-5b2d8c7e4a10" \
  -H "Content-Type: application/json" \
  -d '{"service_ids": [3], "start": "2026-10-20T14:30:00-03:00", "client_id": 4821}'

Mesma chave e mesmo corpo nas 24 horas seguintes devolvem a resposta original, com o header Idempotent-Replayed: true. Mesma chave com corpo diferente responde 409 duplicate_request. A referência marca as rotas que aceitam o header.

Limites de uso#

Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Acima do limite, a resposta é 429 rate_limited com Retry-After em segundos: espere esse tempo antes de tentar de novo.

Erros#

Erros respondem em application/problem+json, com um code estável em inglês. Trate o erro pelo code; o texto em detail é para pessoas e pode mudar. Todos os códigos estão em Erros.

Toda resposta, de sucesso ou de erro, traz o header X-Request-Id. Ao falar com o suporte, informe esse valor.

Versões#

A versão vai na URL (/v1/). Dentro da v1 só fazemos mudanças que não quebram integrações: campo novo, evento novo, valor novo numa lista de opções. Por isso, ignore campos que você não conhece e não trave em valores desconhecidos. Remover ou renomear um campo só numa v2.