O agendamento foi criado em um sistema. O cliente está cadastrado em outro. E, no meio dos dois, alguém copia manualmente de um lado para o outro — todo dia, a cada novo registro. Enquanto a digitação acompanha o ritmo, parece que funciona. Mas basta um esquecimento, um número trocado ou um horário que mudou em um sistema e não no outro para a operação trabalhar com duas verdades diferentes sobre o mesmo cliente.
Esse é o custo de manter dados em dois lugares: não é só o tempo gasto digitando duas vezes, é o risco constante de informação desencontrada. E informação desencontrada, no atendimento, vira cliente confirmando um horário que o outro sistema já tinha cancelado.
Por que a digitação dupla nunca se resolve sozinha
A digitação dupla aparece sempre que dois sistemas precisam saber a mesma coisa, mas não conversam entre si. Cada um guarda sua versão, e manter as duas iguais vira tarefa manual.
O problema tem duas faces. A primeira é o trabalho repetitivo: alguém precisa lembrar de replicar cada cadastro e cada agendamento de um lado no outro. A segunda, mais perigosa, é a janela de divergência — o intervalo entre a mudança acontecer em um sistema e ser copiada no outro. Nesse intervalo, os dois sistemas discordam, e qualquer decisão tomada com base no sistema desatualizado nasce errada.
Resolver isso não é digitar mais rápido. É fazer os dois sistemas trocarem informação sozinhos. E aí entram dois recursos complementares: a API e os webhooks.
A API: consultar e movimentar dados sem passar pelo painel
A API do xLumen permite que um sistema externo consulte e movimente dados sem depender do uso manual do painel. É a ponte por onde o sistema próprio do cliente conversa com o xLumen de forma programada.
Hoje a documentação pública cobre dois grupos de recursos. No grupo de clientes, a API permite listar, buscar, criar, consultar e atualizar clientes, além de gerenciar os contatos de cada cliente. No grupo de calendário, permite listar e filtrar agendamentos — por período, por cliente, por prestador —, consultar, criar, reagendar, concluir e cancelar agendamento.
Na prática, isso cobre os dois lados da sincronização que antes era manual: o cadastro do cliente e o agendamento. Quando o sistema externo cria um cliente, ele pode refletir esse cliente no xLumen pela API, sem ninguém redigitar.
O identificador que costura os dois sistemas
Há um detalhe que faz a integração funcionar sem confusão: o idExterno. O agendamento pode usar esse campo como identificador de correlação com o sistema externo, e a API expõe a consulta de agendamento por idExterno.
Isso resolve o problema clássico de "qual registro de lá corresponde a qual registro daqui". O sistema externo guarda o seu próprio identificador no agendamento e, depois, localiza esse mesmo agendamento no xLumen pela sua chave — sem precisar manter uma tabela de equivalência à parte.
Os webhooks: ser avisado, em vez de ficar perguntando
A API resolve metade da sincronização: o sistema externo consulta e movimenta dados quando quer. Mas e quando algo muda dentro do xLumen? Ficar consultando a API de tempos em tempos para descobrir novidades é desperdício. É exatamente o que os webhooks eliminam.
Um webhook faz o caminho inverso: em vez de o sistema externo perguntar, o xLumen avisa. Sempre que um agendamento é criado ou alterado, ele envia uma requisição para a URL configurada pelo cliente. Os eventos disponíveis são AGENDAMENTO_CRIADO, quando um novo agendamento é registrado, e AGENDAMENTO_ATUALIZADO, disparado em qualquer alteração — incluindo mudança de status, como cancelamento, reagendamento e conclusão. Um mesmo webhook pode escutar um ou os dois eventos.
O envio chega em JSON, com os dados do agendamento e identificadores como o do tenant e o nome do evento. Quando o sistema receptor precisa de mais do que veio no aviso, consulta a API usando o identificador recebido. É a dupla trabalhando junta: o webhook avisa que algo aconteceu, a API entrega o detalhe quando preciso.
Uma integração que dá para confiar
Notificar automaticamente só ajuda se a notificação for confiável. Os webhooks trazem três cuidados para isso.
- Assinatura. O webhook pode ser assinado com um secret, usando HMAC-SHA256 sobre o corpo da requisição. Com a assinatura, o sistema receptor confirma que o aviso veio mesmo do xLumen, sem precisar consultar a API para validar autenticidade.
- Tentativas e desativação. O envio é considerado bem-sucedido quando o destino responde com status 2xx. A cada falha, o sistema tenta de novo, até três tentativas por evento. Se o webhook acumular dez erros, é desativado automaticamente e precisa de reativação manual — um freio que evita ficar disparando para um endpoint que está fora do ar.
- Log de envios. O xLumen mantém, no próprio frontend, um log com o histórico de envios, a resposta do destino e o status retornado. É por ele que a operação acompanha a saúde da integração e identifica problemas no endpoint receptor.
A operação pode manter até dois webhooks ativos ao mesmo tempo.
Conclusão
Digitar o mesmo dado em dois sistemas não é só perda de tempo — é a porta de entrada para informação desencontrada, e informação desencontrada custa caro no atendimento. A saída não é digitar mais rápido, é fazer os sistemas trocarem dados sozinhos.
É o que a API e os webhooks do xLumen oferecem juntos: a API para consultar e movimentar clientes, contatos e agendamentos — com o idExterno correlacionando os dois lados — e os webhooks para avisar o sistema externo automaticamente quando um agendamento é criado ou alterado, com assinatura, reenvio e log de envios. Se a sua operação ainda mantém alguém copiando dados de um sistema para o outro, vale conhecer como o xLumen elimina essa digitação dupla.
Se sua operação também lida com vários prestadores na mesma agenda, veja Como organizar a agenda de vários prestadores sem choque de horário.
Quer parar de digitar o mesmo dado em dois sistemas?
O xLumen junta WhatsApp, agenda e IA num lugar só — e você começa com 7 dias de garantia. Ver planos e começar