Produto · Agendamento on-line · Para desenvolvedores

Agendamento on-line para desenvolvedores web

Como o site de uma empresa manda pedidos de limpeza para a Glue. O link, o código para incorporar, e o endpoint, os campos e a prova humana para um site com formulário próprio.

A notificação na Glue quando um site manda um pedido: o cliente e a casa, prontos para confirmar

Escrito para: quem faz ou mantém o site de uma empresa. O guia do dono é a página de agendamento on-line.

O terceiro de três jeitos de receber pedidos: um site com formulário próprio, talvez uma calculadora de preço, mandando as respostas direto para a Glue. Os outros dois não precisam de código: compartilhar o link e colocar o formulário no site. A empresa primeiro escolhe um nome curto na aba Booking, explicado nessas páginas. O seu formulário funciona com a página hospedada ativa ou não.

Enviar do seu próprio formulário

POST https://useglueapp.com/nodejs/book/<slug>
Content-Type: application/json

Os nomes de campo e valores são os do inglês; a tabela é a mesma.

Field Required Values
name yes the visitor's name, 2 to 80 characters
email yes a valid e-mail; a known customer's e-mail attaches the request to them
phone no digits, spaces, parentheses and dashes
address one of address or zipcode street and number
unit no apartment or suite
city no
zipcode one of address or zipcode
serviceType no residential (default), commercial, rental
cleaningType no regular (default), deep
serviceDate no YYYY-MM-DD, today or later. With a day, the request also becomes an order on the calendar; without one, only the customer and the quote facility are created
bedrooms, bathrooms no numbers; bathrooms accepts halves
rooms no number, for commercial places
squareFeet no number
pet no yes or no
frequency no one_time, weekly, biweekly, monthly
timePreference no morning, afternoon
estimatedPrice no the price the site's own calculator showed, in dollars; it lands on the facility as its estimate
note no up to 500 characters
humanCheck in production the ALTCHA solution, see below
website no honeypot: leave it out or empty; anything in it is treated as a bot

Respostas:

Status Body Meaning
200 { "success": true } received; the company was notified
400 { "code": "VALIDATION_ERROR", "message": "…" } show message to the visitor as is
400 { "code": "CAPTCHA_FAILED", "message": "…" } the human check failed; solve a fresh one and retry
404 { "code": "NOT_FOUND" } unknown slug
429 too many requests from one address; wait

Dois limites deixam o lixo de fora: um e-mail pode mandar 3 pedidos por dia, e a página de uma empresa recebe 40 por dia; depois responde 400 com uma mensagem até o dia seguinte e a empresa fica sabendo. Um pedido nunca é uma ordem: a empresa confirma o preço e o dia primeiro.

Esses endpoints respondem a qualquer origem, então não há nada para configurar do lado da Glue para um site novo: a prova humana e o limite de frequência são a barreira. Não mande cookies com o pedido.

A prova humana

A Glue recusa um pedido que não prova que um navegador fez o trabalho, a mesma barreira que o login dela usa. Não há widget, nem caixinha, nem nada que o visitante veja. O seu código faz três coisas:

  1. Pede um desafio à Glue quando o visitante começa a preencher o formulário.
  2. Resolve com a biblioteca altcha-lib. Leva mais ou menos um segundo em um laptop e roda em segundo plano enquanto o visitante digita.
  3. Manda o resultado no campo humanCheck junto com o resto do formulário.

Isso roda no navegador do visitante, então a biblioteca vai no frontend do site, junto do formulário: npm install altcha-lib, ou uma tag <script type="module"> de um CDN. O navegador manda o formulário direto para a Glue. Se o seu formulário passa primeiro pelo seu próprio backend, deixe a resolução no navegador e repasse a string humanCheck como está: resolver em um servidor não prova nada e gasta o limite de pedidos do seu próprio servidor. Depois:

import { solveChallenge } from "altcha-lib";
import { deriveKey } from "altcha-lib/algorithms/web/pbkdf2";

const base = "https://useglueapp.com/nodejs";

// O que o formulário junta. Obrigatórios: name e email. O resto decide o que a Glue cria.
const form = {
  name: "Rana Duarte",
  email: "rana@example.com",
  phone: "(954) 555-0101", // opcional
  address: "1200 SE 17th Street", // opcional; com rua ou CEP a casa é criada ou encontrada
  city: "Fort Lauderdale", // opcional
  zipcode: "33316", // opcional
  serviceType: "residential", // opcional: residential, commercial, rental
  cleaningType: "regular", // opcional: regular, deep
  serviceDate: "2026-10-24", // opcional, YYYY-MM-DD; com ele o pedido entra no calendário
  timePreference: "morning", // opcional: morning, afternoon
  note: "Gate code 1234", // opcional
};

// 1. Ask Glue for a challenge. Do it when the visitor starts filling the form.
const challenge = await (
  await fetch(`${base}/humanCheck/challenge?action=booking`)
).json();

// 2. Solve it. About a second, in the background.
const solution = await solveChallenge({ challenge, deriveKey, timeout: 60_000 });

// 3. Pack both into one string and send it with the form.
const humanCheck = btoa(JSON.stringify({ challenge, solution }));

await fetch(`${base}/book/<slug>`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ ...form, humanCheck }),
});

Regras para saber:

  • Um desafio vale uma vez só e por dez minutos. Se o visitante demorar mais, ou apertar Enviar duas vezes, peça um novo. Um usado ou vencido responde 400 com o código CAPTCHA_FAILED; mostre a mensagem e tente de novo com um desafio novo.
  • O desafio é assinado para o formulário booking; um pedido para outro formulário é recusado.
  • Fora de produção a prova está desligada e humanCheck pode ser omitido, o que ajuda enquanto você desenvolve contra uma empresa de teste.
  • O campo website é uma isca: não mostre como campo real, e não mande, ou mande vazio.

Mensagens de um formulário de contato

O mesmo endereço com /contact recebe uma mensagem simples e não cria nada na Glue: nem cliente nem lead. Os gerentes recebem uma notificação, um e-mail do tipo "Pedidos do site" e um texto, e respondem da própria caixa de entrada.

POST https://useglueapp.com/nodejs/book/<slug>/contact
Content-Type: application/json
Campo Obrigatório Valores
name sim de 2 a 80 caracteres
email sim um e-mail válido, para onde vai a resposta
phone não
message sim até 1000 caracteres
humanCheck em produção a mesma solução ALTCHA de cima

Mesmas respostas, mesma prova humana, mesmos limites diários, compartilhados com os pedidos.

O que acontece na Glue

Uma chamada faz até três coisas, conforme o que traz:

  • O cliente. Encontrado pelo e-mail, ou criado como um cliente ativo normal; só a casa leva o status "orçamento". Ele não consegue entrar até a empresa mandar as boas-vindas. Só nome e e-mail criam um contato para a empresa ligar.
  • A casa. Com rua ou CEP: a casa que o cliente já tem nessa rua e CEP, se tiver; senão, uma casa nova com status "orçamento" com o nome do visitante ("Casa da Rana"), marcada no mapa quando o Google conhece o endereço. Mande o número junto com a rua ("1200 SE 17th Street"); a Glue separa os dois. Sem lugar, um cliente conhecido com uma só casa recebe essa.
  • A ordem. Com dia e casa, uma ordem "Pedida" espera no calendário; planejar (equipe e horário) confirma ao cliente. Sem dia, a empresa cria as ordens depois de confirmar o orçamento.

De qualquer jeito os gerentes recebem uma notificação no sino que abre o lugar certo (o cliente com "Confirmar orçamento", a ordem ou a casa), um e-mail do tipo "Pedidos do site" e uma mensagem no telefone de notificações. O e-mail vai para os endereços do cartão "Who gets booking requests" da aba Booking, ou para o endereço da empresa se nenhum foi adicionado; responder a ele chega ao visitante. Cada pedido fica registrado com o que criou.