Pular para o conteúdo
Agenda

Listar reuniões

v1.0.0
GEThttps://api.staging.growthaisystem.com/api/v1/appointments
  • ExigeAuthorization: Bearer gos_…— Chave de API (gos_…)· escoposcalendars.read

Ordem por startAt crescente, paginação por cursor (nextCursor). from/to recortam por horário da reunião (opcionais). status default scheduled (canceladas fora, como sempre); use status=all para trazer canceladas com canceledAt. calendarKey = key de GET /calendars. Filtros de polling: createdAfter/updatedAfter. recoveredFromAppointmentId (issue #728): quando essa reunião foi criada pra um contato que tinha uma reunião anterior com outcome:"noshow" ainda sem recuperação, aponta pro id dela — carimbado sozinho na criação, nunca escolhido à mão. null = não recupera nada.

Google Agenda (`source`, desde 30/10/2026): sem source, a rota devolve as reuniões do CRM (crm e public_booking), como sempre. source=google_calendar traz os eventos das agendas Google que o time conectou na Agenda — os que foram criados FORA do CRM (a reunião que o CRM criou no Google já é a reunião do CRM e não aparece duas vezes). Dá para misturar: source=crm,public_booking,google_calendar devolve tudo numa ordem só de horário, com o mesmo cursor. Cada evento vem com source: "google_calendar", createdBySource: "google_calendar", externalId (o id no Google), calendarId, allDay, externalStatus, visibility, attendees (e-mail e resposta de cada convidado) e htmlLink; o id é estável (google_calendar:<conexão>:<evento>) e o dono da agenda vem em assigneeUserId. Os campos de reunião do CRM (contato, negócio, tipo de agenda, desfecho) vêm null, e o detalhe e o histórico (GET /appointments/{id}) são só das reuniões do CRM.

Privacidade: a API mostra do evento o que a tela da Agenda mostra. Agenda conectada em modo "só ocupado": título "Ocupado", visibility: "busy", attendees e htmlLink null. Só entram agendas com a conexão ativa. Login de pessoa (OAuth) precisa da área Agenda no papel (senão 403 forbidden_area) e, com "só os dados atribuídos", vê só os eventos das agendas dela.

Filtros com o Google: from/to e assigneeUserId (o dono da agenda) valem para os eventos; calendarKey, contactId, opportunityId e outcome só existem nas reuniões do CRM — com qualquer um deles, os eventos do Google ficam de fora. createdAfter/updatedAfter usam as datas do Google (created/updated). Evento espelhado antes desta versão da API fica sem attendees e htmlLink (e com createdAt = a última alteração no Google) até o próximo sync da agenda, que acontece pelo menos uma vez por dia.

Parâmetros de consulta

Vão na querystring, depois do ?.

  • fromstringopcional
  • tostringopcional
  • calendarKeystringopcional
    • tamanho 1–80
  • assigneeUserIdstringopcional
  • contactIdstringopcional
  • opportunityIdstringopcional
  • statusstringopcional
    • padrão "scheduled"
    • um de"scheduled""canceled""all"
  • outcomestringopcional
    • um de"realizada""noshow""reagendada"
  • createdAfterstringopcional
  • updatedAfterstringopcional
  • sourcestringopcional

    De onde vêm os itens, separados por vírgula: crm (marcada no CRM), public_booking (o lead marcou pela página pública) e google_calendar (evento da agenda Google conectada de alguém do time, criado fora do CRM). Ausente = crm,public_booking, o comportamento de sempre. Ex.: source=google_calendar só os eventos do Google; source=crm,public_booking,google_calendar tudo, numa ordem só de horário.

    • tamanho máx. 60
  • cursorstringopcional
  • limitintegeropcional
    • padrão 100
    • faixa 1–500

Respostas

6 respostas documentadas — o código, o que ele significa nesta rota e a forma do corpo.

200Deu certoapplication/json

Página de reuniões em ordem de horário crescente, com o cursor da próxima página em nextCursor (null quando acabou). Lembre que o default de status é scheduled: canceladas só aparecem com status=all ou status=canceled. Com source=google_calendar, os eventos das agendas Google conectadas entram na mesma ordem.

  • Cada item — V1Appointment

    • idstring
    • contactIdstring | null
    • contactNamestring | null
    • opportunityIdstring | null
    • titlestring
    • startAtstring | null
    • endAtstring | null
    • locationstring | null
    • conferenceUrlstring | null
    • calendarKeystring | null
    • assigneeUserIdstring | null
    • statusstring
      • um de"scheduled""canceled"
    • outcomestring | null
      • um de"realizada""noshow""reagendada"
    • sourcestring
    • createdAtstring
    • createdByUserIdstring | null
    • createdBySourcestring
      • um de"crm""public_booking""api""automation""import""system""google_calendar"
    • updatedAtstring
    • canceledAtstring | null
    • outcomeAtstring | null
    • recoveredFromAppointmentIdstring | null
    • externalIdstringpode faltar

      Só em source: "google_calendar": o id do evento no Google Agenda (o id do events.list).

    • calendarIdstringpode faltar

      Só em source: "google_calendar": a agenda do Google de onde o evento veio, como a conexão a guarda (primary = a agenda principal da conta conectada). O dono da conta é o assigneeUserId.

    • allDaybooleanpode faltar

      Só em source: "google_calendar": evento de dia inteiro (o startAt é a meia-noite UTC do dia).

    • externalStatusstringpode faltar

      Só em source: "google_calendar": a situação crua no Google — confirmed, tentative ou cancelled. status traduz para o vocabulário da API (cancelled → canceled; as outras → scheduled).

    • visibilitystringpode faltar

      Só em source: "google_calendar": a privacidade que o dono escolheu para a agenda conectada, a mesma da tela da agenda. busy ("só ocupado") = a API mostra exatamente o que a tela mostra: o horário, o dono e o título "Ocupado" — attendees e htmlLink vêm null. details = o título real, os convidados e o link (evento sem título no Google também sai "Ocupado", como na tela).

      • um de"details""busy"

    • Só em source: "google_calendar": os convidados com a resposta de cada um. [] = evento sem convidado. null = agenda em modo "só ocupado" (visibility: "busy"), ou evento espelhado antes desta versão da API que ainda não passou pelo próximo sync (o espelho regrava cada agenda pelo menos uma vez por dia).

      Cada item — V1CalendarAttendee

      • emailstring

        E-mail do convidado (minúsculas).

      • responseStatusstring | null

        A resposta ao convite, no vocabulário do Google: needsAction, accepted, tentative ou declined.

      • organizerboolean

        true = quem organiza o evento.

      • selfboolean

        true = a própria conta Google conectada (o dono da agenda).

    • htmlLinkstring | nullpode faltar

      Só em source: "google_calendar": o link do evento no Google Agenda (abre para quem tem acesso à agenda). null nos mesmos casos de attendees.

  • nextCursorstring | null

    Cursor opaco da PRÓXIMA página — passe em ?cursor=. null = acabou a lista.