A disponibilidade é uma foto do momento e não reserva nada. A confirmação é o POST /appointments, e 409 slot_conflict significa que o horário foi tomado no meio do caminho.

Disponibilidade

GET /availability é somente leitura. A resposta combina os horários de funcionamento, bloqueios, agenda do profissional, eventos do Google Calendar e agendamentos que existem apenas na OctoSolve.

Parâmetros

Existe um teto de 40 combinações de dia por profissional em cada chamada. O cálculo é dias × profissionais candidatos. Se ultrapassar 40, a API responde 422 validation_error. Reduza dias ou informe um profissional_id.

curl --request GET \
  --url "https://api.octosolve.com.br/api/v1/availability?servico_id=33333333-3333-4333-8333-333333333333&data=2026-08-20&dias=3&profissional_id=44444444-4444-4444-8444-444444444444" \
  --header "Authorization: Bearer osk_live_exemplo_ficticio_00000000000000000000000000" \
  --header "Accept: application/json"

Resposta

{
  "data": {
    "servico_id": "33333333-3333-4333-8333-333333333333",
    "duracao_minutos": 30,
    "dias": [
      {
        "dia": "2026-08-20",
        "profissionais": [
          {
            "profissional_id": "44444444-4444-4444-8444-444444444444",
            "slots": [
              {
                "inicio": "2026-08-20T12:00:00Z",
                "fim": "2026-08-20T12:30:00Z"
              }
            ]
          }
        ]
      }
    ]
  }
}

Os campos inicio e fim vêm em UTC e terminam em Z. Use inicio como data_hora ao criar o agendamento e preserve o valor exatamente como veio. Ao exibir o horário para o cliente final, converta para o fuso local, senão no horário de Brasília ele aparece 3 horas adiantado.

Em contas com agenda por profissional, dia fechado é uma resposta normal: o dia aparece com profissionais: []. Isso não é erro nem significa falha de integração.

Contas sem agenda por profissional recebem uma única entrada com profissional_id nulo.

Agenda não conectada ou Google Calendar indisponível

Se nenhuma agenda do Google estiver conectada à conta, a API responde 409 calendar_not_connected. Isso é uma configuração pendente da conta, então repetir a mesma requisição não resolve. Conecte a agenda no painel antes de consultar horários livres.

Se a conta tem uma agenda conectada, mas o Google Calendar não puder ser consultado, a API responde 503 service_unavailable com a mensagem Não foi possível consultar a agenda agora. Tente novamente. Ela não devolve uma lista vazia, porque isso faria uma falha parecer agenda lotada.

Espere e tente novamente com intervalo crescente. Não crie com base numa disponibilidade antiga sem estar preparado para tratar 409 slot_conflict no POST /appointments.

Receita para Make ou n8n

1. Receba servico_id, a primeira data desejada e, se houver escolha, profissional_id.
2. Faça GET /availability com dias entre 1 e 7.
3. Use um iterador sobre data.dias, depois sobre profissionais e por fim sobre slots.
4. Converta inicio para o fuso local ao mostrar ao cliente e guarde o valor completo do slot escolhido.
5. Envie esse inicio como data_hora no POST /appointments.
6. Se receber 409 slot_conflict, volte à consulta de disponibilidade e ofereça outro slot.
7. Se receber 409 calendar_not_connected, conecte a agenda no painel. Não repita a mesma requisição antes disso.
8. Se receber 503 service_unavailable, espere e tente novamente. Não trate como ausência de horários.
9. Se receber o erro do teto de 40 combinações, reduza os dias ou escolha um profissional antes de repetir.