API da Verandi

Catálogo

Serviços, profissionais e locais ativos da conta, mais as palavras que este negócio usa para cada coisa. É por aqui que se começa: os identificadores daqui entram como filtro nas outras rotas.

O vocabulário vem junto porque cada conta chama as coisas do jeito dela. Um estúdio diz "aula" e uma clínica diz "sessão"; quem escreve a mensagem para a pessoa deve usar a palavra da conta, não a nossa.

curl https://verandi.4yu.com.br/api/v1/catalogo \
  -H "Authorization: Bearer vr_sua_chave_aqui"

{
  "servicos": [
    { "servicoId": "9f1c...", "nome": "Pilates solo", "duracaoMin": 60, "capacidadePadrao": 4 }
  ],
  "profissionais": [
    { "profissionalId": "2b7e...", "nome": "Marina" }
  ],
  "locais": [
    { "localId": "6d33...", "nome": "Sala 1" }
  ],
  "vocabulario": {
    "servico": { "singular": "Modalidade", "plural": "Modalidades" }
  }
}

Horários com vaga

Os horários de um intervalo, separados em livres e cheios. É a rota que responde "tem aula quinta de manhã?".

Ofereça apenas o que vier em livres. Horário cheio nunca entra nessa lista, nem quando falta pouco: a decisão de encaixar alguém acima da lotação é de quem está no balcão, olhando para a pessoa. cheios existe para o seu sistema saber a diferença entre "não há horário nesse dia" e "há, e está lotado", que são duas conversas diferentes. Para quem ainda não é aluno, use experimental=1: a aula experimental tem grade própria, mais estreita que a agenda, e oferecer fora dela é prometer o que o estúdio não dá.

curl "https://verandi.4yu.com.br/api/v1/disponibilidade?de=2026-08-17&ate=2026-08-23" \
  -H "Authorization: Bearer vr_sua_chave_aqui"

{
  "de": "2026-08-17",
  "ate": "2026-08-23",
  "livres": [
    {
      "sessaoId": "a41f...",
      "data": "2026-08-18", "hora": "07:00", "duracaoMin": 60,
      "servico": "Pilates solo",
      "profissionalId": "2b7e...", "profissional": "Marina",
      "localId": "6d33...", "local": "Sala 1",
      "capacidade": 4, "ocupadas": 2, "livres": 2
    }
  ],
  "cheios": []
}

Procurar uma pessoa

Por telefone, para reconhecer quem chegou; ou por nome, sem acento e sem diferenciar maiúscula. Chame sempre antes de cadastrar, senão a mesma pessoa vira três cadastros porque escreveu o nome de três jeitos.

Pelo telefone é como um robô reconhece quem está falando: quem escreve "oi" não disse nome nenhum. Procuramos por todas as formas do mesmo número (com e sem o país, com e sem o nono dígito), porque contas antigas do WhatsApp vêm sem ele. Número sem DDD não é procurado: ele pode ser de onze estados, e reconhecer a pessoa errada não tem conserto. Não achar responde 200 com lista vazia, e não 404: no cadastro real 30% não têm telefone, então não reconhecer é o caminho normal desta rota.

curl "https://verandi.4yu.com.br/api/v1/pessoas?telefone=5544998887766" \
  -H "Authorization: Bearer vr_sua_chave_aqui"

{
  "total": 1,
  "pessoas": [
    { "pessoaId": "77c0...", "nome": "Marina Alves", "telefone": "11988887777", "ativa": true }
  ]
}

Cadastrar uma pessoa

Cadastra quem a busca não achou. Nome é o único campo obrigatório.

A rota não recusa nomes parecidos. "Ana" e "Ana Paula" podem ser a mesma pessoa ou duas, e quem sabe é a conversa, não o banco. Procure antes.

curl -X POST https://verandi.4yu.com.br/api/v1/pessoas \
  -H "Authorization: Bearer vr_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: conversa-8f21a" \
  -d '{ "nome": "Marina Alves", "telefone": "11988887777" }'

201 Created

{
  "pessoaId": "77c0...",
  "nome": "Marina Alves",
  "telefone": "11988887777",
  "ativa": true
}

A agenda de uma pessoa

Os horários fixos dela, o que vem pela frente e quantas reposições estão em aberto. É a rota que responde "quais são meus horários?" e "quantas aulas eu tenho para repor?".

É daqui que sai o participacaoId, e sem ele não há como desmarcar. Guarde o identificador quando marcar, ou consulte esta rota antes de cancelar. Observação e data de nascimento nunca aparecem aqui: são dados de ficha, e ficha é da tela.

curl https://verandi.4yu.com.br/api/v1/pessoas/77c0... \
  -H "Authorization: Bearer vr_sua_chave_aqui"

{
  "pessoaId": "77c0...",
  "nome": "Marina Alves",
  "telefone": "11988887777",
  "ativa": true,
  "situacao": "ativa",
  "ultimaPresenca": "2026-08-11",
  "horariosFixos": [
    { "vagaId": "13aa...", "diaSemana": 2, "hora": "07:00", "servico": "Pilates solo",
      "profissional": "Marina", "desde": "2026-03-02", "ate": null }
  ],
  "proximas": [
    { "participacaoId": "5e90...", "sessaoId": "a41f...", "data": "2026-08-18",
      "hora": "07:00", "servico": "Pilates solo", "origem": "recorrente", "status": "esperada" }
  ],
  "reposicoesAbertas": [
    { "participacaoId": "1c44...", "data": "2026-08-04", "hora": "07:00",
      "servico": "Pilates solo", "motivo": "falta_avisada" }
  ]
}

Marcar em um horário

Coloca uma pessoa em um horário. O sessaoId vem da rota de disponibilidade.

A vaga é conferida no momento de gravar, e não no momento em que você leu a disponibilidade. Entre uma coisa e outra alguém pode ter ocupado, e nesse caso a resposta é 409. Trate o 409 como resposta normal do fluxo, não como falha.

curl -X POST https://verandi.4yu.com.br/api/v1/participacoes \
  -H "Authorization: Bearer vr_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: conversa-8f21b" \
  -d '{ "pessoaId": "77c0...", "sessaoId": "a41f..." }'

201 Created

{
  "participacaoId": "5e90...",
  "pessoaId": "77c0...",
  "sessaoId": "a41f...",
  "origem": "avulso",
  "status": "esperada"
}

Desmarcar

Registra que a pessoa avisou que não vem. A vaga volta a ser oferecida na mesma hora, e a pessoa ganha o crédito de reposição se a conta trabalhar assim.

Apesar do verbo, nada é apagado: a marcação fica no histórico com o estado de falta avisada. É isso que preserva o crédito de reposição e a contagem do negócio. Só funciona para horário futuro; aula que já aconteceu tem a chamada feita por quem estava na sala.

curl -X DELETE https://verandi.4yu.com.br/api/v1/participacoes/5e90... \
  -H "Authorization: Bearer vr_sua_chave_aqui"

{
  "participacaoId": "5e90...",
  "status": "falta_avisada",
  "jaEstavaAssim": false
}

Entrar na fila de um horário cheio

Quando a disponibilidade devolve o horário em cheios, esta rota transforma o não em "te aviso se abrir". Quando alguém desmarca, sai o evento vaga.aberta com quem está na frente.

Entrar na fila não reserva nada. Quando a vaga abre, a pessoa é chamada e precisa marcar como qualquer um. Reservar sozinho seria a integração decidindo, e criaria a pior conversa possível: "você foi marcada numa aula que não pediu".

curl -X POST https://verandi.4yu.com.br/api/v1/espera \
  -H "Authorization: Bearer vr_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: conversa-8f21c" \
  -d '{ "pessoaId": "77c0...", "sessaoId": "a41f..." }'

201 Created

{
  "esperaId": "4d10...",
  "pessoaId": "77c0...",
  "sessaoId": "a41f...",
  "posicao": 2
}

Sair da fila

A pessoa entrou na espera de terça, conseguiu marcar na quinta, e não quer mais ser avisada. Sem isto, o estúdio oferece uma vaga que ela já não precisa.

curl -X DELETE https://verandi.4yu.com.br/api/v1/espera/4d10... \
  -H "Authorization: Bearer vr_sua_chave_aqui"

{
  "esperaId": "4d10...",
  "jaEstavaAssim": false
}