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. Telefone pode ser da família (mãe e filha no mesmo número): aí vem mais de uma, a ativa mais nova primeiro, e quem conversa pergunta o nome. O telefone é procurado nos três campos da ficha (principal, residencial e comercial), então o segundo número da família também reconhece.

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. Cada item de proximas diz em podeReporSeCancelarAgora se cancelar neste momento ainda dá direito à reposição: consulte antes de confirmar o cancelamento, porque depois do DELETE a resposta chega tarde. O veredito envelhece, ele vale para o instante da consulta. Observação e data de nascimento nunca aparecem aqui: são dados de ficha, e ficha é da tela. modalidadeUnica traz servicoId e nome quando os contratos ativos dela são de uma modalidade só, e null quando são mais de uma ou nenhuma: com ela o bot não precisa perguntar qual aula.

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", "inicio": "2026-08-18T10:00:00Z", "servico": "Pilates solo",
      "origem": "recorrente", "status": "esperada",
      "podeReporSeCancelarAgora": true, "minutosAteAula": 1440 }
  ],
  "reposicoesAbertas": [
    { "participacaoId": "1c44...", "data": "2026-08-04", "hora": "07:00",
      "servico": "Pilates solo", "motivo": "falta_avisada" }
  ],
  "regraDeCancelamento": { "minutosMinimos": 120, "porExtenso": "2h" }
}

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"
}

Uma marcação, e se dá tempo de cancelar

Diz o dia, a hora e o serviço de uma marcação, e responde a pergunta que vem antes de cancelar: se desmarcar agora, a pessoa ainda ganha a reposição?

Consulte esta rota depois que a pessoa escolher a aula e antes de chamar o DELETE. O campo avisoParaConfirmar já vem com a frase pronta para mostrar quando estiver fora do prazo, e vem null quando não há nada a avisar. O veredito vale para o instante da consulta e envelhece: quem grava a decisão é o DELETE, que refaz a conta na hora do aviso.

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

{
  "participacaoId": "5e90...",
  "pessoaId": "77c0...",
  "nome": "Marina Alves",
  "sessaoId": "a41f...",
  "data": "2026-08-18",
  "hora": "07:00",
  "inicio": "2026-08-18T10:00:00Z",
  "servico": "Pilates solo",
  "servicoId": "b2d1...",
  "origem": "recorrente",
  "status": "esperada",
  "jaPassou": false,
  "podeCancelar": true,
  "podeReporSeCancelarAgora": false,
  "minutosAteAula": 45,
  "regraDeCancelamento": { "minutosMinimos": 120, "porExtenso": "2h" },
  "avisoParaConfirmar": "Você está tentando cancelar a aula de 18/08 às 07:00 fora do prazo de 2h. Se confirmar, essa aula não poderá ser reposta. Deseja prosseguir?"
}

Desmarcar

Registra a falta justificada (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 justificada (`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. Quem avisa com menos antecedência do que a conta exige desmarca do mesmo jeito, mas fica com status falta e temCredito false: a vaga abre e a reposição não. Chamar de novo devolve 200 com jaEstavaAssim true, para a reentrega não virar erro.

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,
  "temCredito": true,
  "minutosDeAntecedencia": 1440,
  "minutosExigidos": 120
}

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
}

Avisar que voltou de licença

A pessoa diz no WhatsApp que voltou. Com reagendou true (ela marcou aula na conversa) a licença fecha. Com reagendou false a licença continua aberta e nada mais muda: quem segue a conversa é a equipe, no atendimento.

Quem não tem licença aberta recebe 200 com tinhaLicenca false, e não erro: a pessoa diz que voltou mesmo quando ninguém registrou a saída. A ficha (GET /pessoas/{pessoaId}) traz licenca com inicio e voltaPrevista, ou null.

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

{
  "pessoaId": "77c0...",
  "tinhaLicenca": true,
  "licencaAberta": false
}

Resumo do período

Presença, falta, reposição, aula experimental que virou matrícula, matrícula nova e quem saiu, num período de até 400 dias. Só números, nenhum nome: é para relatório, não para lista.

Presença conta só aula que já aconteceu e não foi cancelada pela casa; licença fica fora da taxa. Matrícula nova é o primeiro contrato da pessoa, e sair é encerrar o contrato sem ter outro ativo ou pausado hoje: trocar de plano não conta como saída.

curl "https://verandi.4yu.com.br/api/v1/relatorio?de=2026-10-01&ate=2026-10-31" \
  -H "Authorization: Bearer vr_sua_chave_aqui"

{
  "de": "2026-10-01",
  "ate": "2026-10-31",
  "presencas": 412,
  "faltas": 38,
  "faltasAvisadas": 51,
  "taxaDePresenca": 0.82,
  "reposicoesFeitas": 44,
  "experimentais": 12,
  "experimentaisQueMatricularam": 7,
  "matriculasNovas": 9,
  "sairam": 3,
  "alunosAtivos": 118
}

Ligar os avisos no AutoFluxos

O AutoFluxos se registra como destino dos avisos da conta, num clique do lado de lá. Daí em diante cada evento chega assinado com o segredo que ele mandou.

Pela API só um endereço do AutoFluxos é aceito: com uma chave vazada não dá para desviar os avisos, que levam nome e telefone, para outro lugar. Outro destino se configura na tela, pelo dono.

curl -X PUT https://verandi.4yu.com.br/api/v1/webhook \
  -H "Authorization: Bearer vr_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://autofluxos.4yu.com.br/api/webhook/verandi/…", "segredo": "…" }'

{
  "ativo": true,
  "url": "https://autofluxos.4yu.com.br/api/webhook/verandi/…"
}

Desligar os avisos no AutoFluxos

Para de mandar os avisos para o AutoFluxos. Desliga, não apaga: o histórico de entregas continua.

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

{
  "ativo": false,
  "desligou": true
}