O sistema da administradora já sabe quais unidades têm taxa vencendo na sexta e quem foi convocado para a assembleia. Com a API do zapon, esse mesmo sistema envia o aviso e o boleto para cada unidade, recebe a confirmação de presença por webhook e devolve ao síndico uma lista de quórum — sem ninguém colar papel no elevador nem digitar mensagem uma a uma.
Administração de condomínio é comunicação repetida com um público que não escolheu ser seu público. O morador não assinou nada para receber aviso de manutenção; ele comprou ou alugou um apartamento. Isso muda tudo na hora de escrever e de disparar: o canal precisa ser útil, previsível e discreto, ou vira incômodo — e incômodo, no WhatsApp, vira bloqueio.
O que a API resolve é a parte mecânica: enviar para cada unidade o que hoje se envia para o prédio inteiro no quadro de avisos, e trazer a resposta de volta para dentro do sistema. É uma API REST comum — header token, JSON entrando e saindo, base https://api.zapon.dev —, chamada pelo software da administradora ou por uma rotina que lê a base de unidades. Abaixo estão o fluxo, os endpoints em cURL e Node, o evento que chega quando o morador responde e as regras de conduta que separam um canal aceito de um número denunciado.
Porque o comunicado foi publicado, não entregue. Papel no elevador é visto por quem passa e olha; e-mail de administradora cai em uma caixa que muita gente não abre; boleto no escaninho depende de o morador descer até a portaria. Nenhum desses caminhos gera prova de que a mensagem chegou àquela unidade. O WhatsApp gera: o envio tem identificador, a resposta tem horário, e o que a pessoa respondeu fica registrado.
Na prática, a administradora convive com três buracos ao mesmo tempo:
Porque o canal oficial é lento e o morador é prático: ele manda no número que tem. Aí a conversa de condomínio entra no celular particular de uma pessoa que não é funcionária, sem registro, sem horário e sem quem cubra as férias. Passar os avisos para um número institucional da administradora não elimina o contato direto, mas tira do celular pessoal aquilo que é processo: cobrança, comunicado, convocação e confirmação.
Um prédio de 90 unidades tem 90 boletos por mês. Fazer isso na mão significa alguém abrindo conversa, anexando PDF e conferindo nome noventa vezes, todo mês, em cada prédio da carteira — e errando em algum. Para a API é a mesma chamada repetida em laço, com pausa entre uma e outra, e um registro do que saiu para cada unidade.
Um número de WhatsApp que o condomínio ou a administradora controle, uma conexão no zapon com esse número (por QR Code ou código de pareamento) e uma base de unidades com o telefone do responsável por cada uma. Do lado de quem dispara, basta algo capaz de fazer uma requisição HTTP: o sistema da administradora, uma rotina própria ou uma ferramenta de automação lendo a base.
token, que é a credencial de todas as chamadas daquele número. É o header token, copiado do painel: não é Authorization, não é Bearer, não há OAuth.Depende de quem é o remetente na cabeça do morador. Se o prédio tem identidade própria e portaria própria, um número por condomínio faz o aviso parecer o que é: comunicação daquele prédio. Se a administradora atende dezenas de prédios pequenos, um número por administradora concentra a operação e a equipe. A conta muda: cada número conectado é R$ 27 por mês, independentemente de quantas unidades ele atende. Trocar de remetente no código é trocar o header token da chamada.
Do sistema que a administradora já usa. Se ele tem área de integração, o próprio sistema chama a API quando gera a cobrança do mês. Se é fechado, o caminho é exportar — relatório, banco, planilha de posição — e disparar dali. A API não precisa saber o que é uma taxa condominial: ela recebe telefone, texto e, quando for o caso, um arquivo.
Cinco etapas: (1) alguns dias antes do vencimento, cada unidade recebe o aviso com o boleto em PDF; (2) no dia do vencimento sai uma mensagem curta com o meio de pagamento; (3) quando a baixa entra no financeiro, a régua para para aquela unidade; (4) o que continua em aberto entra numa régua de atraso espaçada, discreta e com fim; (5) em paralelo, comunicados e o edital de assembleia saem por unidade, com confirmação de presença em botões que volta por webhook e vira a lista de quórum do síndico.
Cada passo tem um objetivo próprio. Repetir a mesma mensagem quatro vezes é o jeito mais rápido de ensinar o morador a ignorar o canal.
Um aviso de conveniência, não uma cobrança — a taxa nem venceu. Três dias costumam ser suficientes: tempo de pagar sem correria, perto o bastante para não esquecer. Conteúdo: identificação da unidade, mês de competência, data de vencimento e o boleto anexado em PDF. É aqui que o envio de documento resolve o problema do escaninho: o morador recebe o arquivo no mesmo lugar onde lê tudo o resto.
Duas coisas que não entram: valor em destaque com tom de alerta e qualquer referência à situação de outros meses. Este envio é operacional e neutro.
Curto. Uma linha lembrando a data de hoje e o meio de pagamento — a linha digitável ou o código para copiar. Nada de reenviar o PDF: quem quer o arquivo já tem, e repetir anexo pesa a conversa. Se o condomínio aceita mais de uma forma de pagamento, diga as duas em uma frase, sem explicação longa.
A confirmação é a mensagem que compra credibilidade para todas as outras: quem paga e recebe um "recebemos" para de duvidar do canal. Ela é disparada pela baixa no financeiro, não por um horário fixo.
E daqui sai a regra mais importante da página: a rotina lê o status de cada unidade no momento do envio, nunca uma lista montada no dia anterior. Cobrar quem já pagou é o erro que faz o síndico mandar desligar o sistema — e ele acontece sempre que alguém gera a lista de manhã e dispara à tarde.
Espaçada, discreta e com fim. Um aviso poucos dias depois do vencimento, outro mais adiante, e ponto: depois disso o assunto sai da automação e vira tarefa de uma pessoa da administradora, que trata caso a caso. Cada mensagem precisa oferecer um caminho — segunda via e o contato do financeiro — e nenhuma delas precisa de adjetivo. O tom é o de quem avisa, não o de quem pressiona.
O que não entra em nenhuma hipótese: menção a consequência, comparação com outras unidades, texto em letras maiúsculas e envio repetido no mesmo dia. Multa e encargo são o que estiver na convenção do condomínio — assunto para a administradora explicar, não para a mensagem automática afirmar.
O edital vai em PDF, unidade por unidade, com uma mensagem curta dizendo data, horário, local (ou o formato, quando for por vídeo) e a pauta em uma linha. Junto, um pedido de confirmação em botões: participo, não participo, participo por procuração. Cada toque volta pelo webhook com o identificador que você colocou no botão, e o sistema monta uma contagem por unidade.
Essa contagem não é o quórum — quórum se apura na assembleia, com a lista de presença e as procurações válidas. Ela é uma estimativa que permite ao síndico agir antes: reforçar o convite, remarcar ou preparar a segunda convocação. Diga isso na própria mensagem, para ninguém confundir uma confirmação por WhatsApp com voto.
Quatro dão conta do ciclo inteiro: POST /chat/send/text para os avisos, POST /chat/send/document para boleto e edital em PDF, POST /chat/send/buttons para a confirmação de presença e POST /user/check para conferir se o telefone do cadastro ainda tem WhatsApp. São 49 endpoints publicados com schema — 23 de /chat, 18 de /group e 8 de /user —, mas o dia a dia do condomínio vive nesses quatro.
Todas as chamadas usam a base https://api.zapon.dev e o header token. Trate o token como senha: quem o tem envia mensagem em nome do condomínio.
Um POST em /chat/send/text com dois campos: Phone, o número em formato internacional só com dígitos, e Body, o texto.
curl -X POST https://api.zapon.dev/chat/send/text \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": "5511999999999", "Body": "Condomínio Alameda das Palmeiras — unidade 42, bloco B.\n\nA taxa de março vence em 10/03 (terça). O boleto vai na próxima mensagem.\n\nQualquer dúvida, é só responder por aqui que a administradora retorna em horário comercial." }'
A resposta traz o identificador da mensagem no WhatsApp:
{
"code": 200,
"success": true,
"data": {
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2026-03-07T09:12:08-03:00"
}
}Guarde esse Id ligado à unidade e à competência. É ele que responde à pergunta "vocês avisaram a minha unidade?" com data e hora, e é ele que impede o mesmo aviso de sair duas vezes se a rotina rodar de novo.
Uma rotina diária varre as unidades por faixa de dias em relação ao vencimento e decide o que cada uma recebe — sempre consultando a posição financeira imediatamente antes de enviar.
// taxas.js — roda todo dia útil às 9h const API = "https://api.zapon.dev"; const TOKEN = process.env.ZAPON_TOKEN_ALAMEDA; async function enviarTexto(phone, body) { const r = await fetch(`${API}/chat/send/text`, { method: "POST", headers: { "token": TOKEN, "Content-Type": "application/json" }, body: JSON.stringify({ Phone: phone, Body: body }) }); const json = await r.json(); if (!r.ok || !json.success) throw new Error(json.error || `HTTP ${r.status}`); return json.data.Id; } const pausa = (ms) => new Promise((r) => setTimeout(r, ms)); for (const u of await unidadesDoCondominio()) { const t = await posicaoDaTaxa(u.id); // lida AGORA, não ontem if (t.pago || u.optOut) continue; // pagou ou pediu para sair: fora const etapa = t.diasParaVencer === 3 ? "pre" : t.diasParaVencer === 0 ? "dia" : t.diasEmAtraso === 5 ? "atraso1" : t.diasEmAtraso === 15 ? "atraso2" : null; if (!etapa) continue; // a régua acaba aqui: o resto é com a equipe if (await jaEnviado(u.id, t.competencia, etapa)) continue; try { const id = await enviarTexto(u.telefoneResponsavel, textoDa(etapa, u, t)); await registrarEnvio(u.id, t.competencia, etapa, id); } catch (e) { await registrarFalha(u.id, etapa, String(e)); // vira tarefa da administradora } await pausa(5000); // 90 unidades não saem no mesmo minuto }
Quatro detalhes desse laço são o que separa uma régua que dura de uma que gera reclamação na próxima assembleia. A leitura da posição dentro do laço evita cobrar quem pagou de manhã. O optOut respeita quem pediu para sair. O jaEnviado impede repetição quando a rotina roda duas vezes. E a pausa fraciona o disparo: uma torre inteira saindo no mesmo instante é exatamente o comportamento que um número humano nunca tem.
O POST /chat/send/document recebe o arquivo em Document, como data URI em base64, mais FileName e um Caption opcional. O nome do arquivo importa mais do que parece: é o que o morador vê na conversa e o que ele vai procurar seis meses depois.
curl -X POST https://api.zapon.dev/chat/send/document \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": "5511999999999", "Document": "data:application/pdf;base64,JVBERi0xLjQKJcfs...", "FileName": "edital-agv-2027-03.pdf", "Caption": "Edital de convocação — assembleia geral em 22/03, às 19h30, no salão de festas. Pauta: previsão orçamentária e obra da fachada." }'
O mesmo endpoint entrega o boleto da competência (taxa-03-2027-unidade-42B.pdf) e a prestação de contas do mês. Entre as 13 formas de envio da API há ainda imagem, localização, lista e enquete — a imagem serve bem para a foto de um aviso da portaria, e a localização, para o endereço de uma assembleia fora do prédio.
O POST /chat/send/buttons envia botões de resposta rápida, cada um com um id que você define e um text curto — o rótulo cabe em cerca de 20 caracteres. Coloque a unidade e a assembleia dentro do id: a resposta volta amarrada ao registro certo, sem depender de interpretar texto. Além da resposta rápida, o mesmo endpoint monta botão que abre um link ("type": "cta_url"), botão que abre o discador ("type": "cta_call") e botão que copia um código ("type": "copy") — e os tipos convivem na mesma mensagem. O toque em resposta rápida volta no webhook; os outros três agem no aparelho de quem recebe.
POST https://api.zapon.dev/chat/send/buttons token: SEU_TOKEN { "Phone": "5511999999999", "Body": "Unidade 42B — assembleia geral em 22/03, às 19h30, no salão de festas. Você pretende participar? A resposta ajuda a estimar a presença; a lista oficial é assinada na hora.", "Footer": "Condomínio Alameda das Palmeiras", "Buttons": [ { "id": "agv2703|42B|sim", "text": "Vou participar" }, { "id": "agv2703|42B|nao", "text": "Não vou" }, { "id": "agv2703|42B|procuracao", "text": "Por procuração" } ] }
Cadastro de condomínio envelhece rápido: inquilino que saiu, proprietário que trocou de número, unidade vendida. O POST /user/check recebe uma lista de telefones e diz quais têm conta no WhatsApp — é o jeito de limpar a base antes do primeiro disparo e de gerar a lista de unidades cujo contato precisa ser atualizado na portaria.
curl -X POST https://api.zapon.dev/user/check \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": ["5511999999999", "5511888888888"] }' // resposta { "code": 200, "success": true, "data": { "Users": [ { "Query": "5511999999999", "IsInWhatsapp": true, "JID": "[email protected]" }, { "Query": "5511888888888", "IsInWhatsapp": false, "JID": "" } ] } }
Cada conexão tem o seu webhook: você cadastra no painel a URL do seu sistema e escolhe quais eventos quer receber. A partir daí, toda mensagem que chega naquele número vira um POST nessa URL, com o conteúdo inteiro no corpo — telefone, identificador, horário, texto e, quando é resposta de botão, o id que você definiu. Não existe polling: não há nada para ficar consultando.
São três peças que não se misturam: o webhook entrega o evento, a sua regra interpreta e a ação acontece no seu sistema. A API não sabe o que é uma unidade nem o que é quórum; ela sabe que chegou uma mensagem.
O corpo traz o tipo do evento e a mensagem completa. Assim chega o morador que respondeu por escrito:
{
"type": "Message",
"event": {
"Info": {
"ID": "3EB0C767D26A1B5F7C83",
"Chat": "[email protected]",
"Sender": "[email protected]",
"IsFromMe": false, "IsGroup": false,
"PushName": "Marcos — 42B",
"Timestamp": "2026-03-11T18:04:22-03:00"
},
"Message": { "conversation": "já paguei ontem" }
}
}
// quando ele toca num botão, muda só o bloco Message:
"Message": { "buttonsResponseMessage": {
"selectedButtonID": "agv2703|42B|sim",
"Response": { "SelectedDisplayText": "Vou participar" }
} }Duas observações que evitam retrabalho: o corpo pode chegar como JSON puro ou como formulário codificado, com o JSON dentro de um campo — aceite os dois formatos. E o que o próprio número envia também gera evento, com IsFromMe igual a true: ignore, ou a portaria respondendo um morador dispara a sua automação.
Responda 200 primeiro, processe depois; descarte o que não interessa; identifique a unidade pelo id do botão ou pelo telefone; e devolva uma confirmação ao morador, para ele não ficar na dúvida se a resposta valeu.
app.post("/condominio/eventos", express.json(), async (req, res) => { res.sendStatus(200); // responda primeiro, processe depois const ev = req.body?.event ?? req.body, info = ev?.Info ?? {}; if (info.IsFromMe || info.IsGroup) return; // eco da portaria e grupos, fora if (await jaProcessado(info.ID)) return; // o mesmo evento pode chegar 2x const telefone = String(info.Chat || "").split("@")[0]; const botao = ev?.Message?.buttonsResponseMessage?.selectedButtonID ?? ""; const texto = (ev?.Message?.conversation ?? ev?.Message?.extendedTextMessage?.text ?? "").trim().toLowerCase(); if (botao) { const [assembleia, unidade, resposta] = botao.split("|"); await registrarPresenca(assembleia, unidade, resposta); // estimativa, não quórum return enviarTexto(telefone, resposta === "nao" ? "Anotado, obrigado por responder." : "Anotado. A lista de presença é assinada no dia, no local."); } const un = await unidadePorTelefone(telefone); if (!un) return filaDaAdministradora(telefone, texto); // número desconhecido if (/^(ja paguei|já paguei|paguei|comprovante)/.test(texto)) { await pausarRegua(un.id, 3); // segura a régua até a conciliação await filaDoFinanceiro(un.id, texto); return enviarTexto(telefone, "Obrigado. O financeiro confere a baixa e confirma por aqui."); } if (/(segunda via|boleto|2a via)/.test(texto)) return enviarSegundaVia(un); if (/(parar|nao quero|descadastr)/.test(texto)) { await marcarOptOut(un.id); return enviarTexto(telefone, "Certo, não enviaremos mais avisos por aqui."); } return filaDaAdministradora(un.id, texto); // o resto é assunto de gente });
Repare no pausarRegua: quando o morador diz que pagou, a régua para antes de a conciliação confirmar. É uma decisão deliberada — é melhor atrasar um aviso legítimo do que insistir com alguém que já pagou.
Ele vai responder isso, e no dia seguinte ao primeiro comunicado. "O portão está batendo", "o vizinho de cima arrasta móvel de madrugada", "quando conserta a bomba?". Nada disso é para a automação resolver: o papel dela é reconhecer que a conversa espera resposta e colocá-la numa fila que alguém da administradora abre todo dia. Ocorrência entre vizinhos, então, nunca deveria ser tratada por texto automático — é caso de registro formal e de conversa com o síndico.
Vai para todo mundo o que afeta todo mundo: manutenção programada, corte de água, elevador parado, dedetização, mudança de horário de área comum, edital de assembleia, prestação de contas. É da unidade — e só dela — tudo que identifica a situação de uma pessoa: taxa em atraso, valor devido, acordo, multa por descumprimento de regimento e ocorrência registrada. Misturar as duas coisas é o erro que transforma um aviso em constrangimento.
A linha é simples de aplicar: se a informação, lida por um vizinho, expuser alguém, ela não é comunicado — é assunto de unidade. Nunca cite número de apartamento inadimplente em texto coletivo, nem em lista afixada, nem em nota de prestação de contas com identificação. A posição da unidade é informação da unidade e do condomínio, não do prédio.
A API tem 18 endpoints de grupo, então tecnicamente dá. Na prática, o grupo do prédio é um canal de conversa entre vizinhos: qualquer aviso oficial cai no meio de piada, foto de cachorro perdido e discussão sobre vaga de garagem, e some. Pior: mensagem de cobrança em grupo expõe quem está em atraso na frente de todo mundo, e não existe forma elegante de consertar isso depois.
O caminho é o inverso — envio individual por unidade. É trabalhoso para uma pessoa e trivial para a API: é o mesmo laço, com uma chamada por unidade e uma pausa entre elas. Deixe o grupo para o que ele é bom: conversa. E se a administradora quiser um canal de mão única para avisos, mantenha-o separado do canal de cobrança.
Depende do assunto, e o cadastro precisa refletir isso. Comunicado de manutenção e aviso de área comum interessam a quem mora — o inquilino. Taxa, rateio de obra e convocação de assembleia costumam ser assunto do proprietário, salvo o que a convenção e o contrato de locação disserem. Guarde os dois telefones com papéis distintos e escolha o destinatário pelo tipo de mensagem, em vez de manter um campo único chamado "contato".
Quando a unidade troca de morador, o cadastro fica errado em silêncio: o antigo inquilino continua recebendo aviso do prédio onde não mora mais. Duas defesas práticas: uma rodada de /user/check antes de campanhas de envio, e um pedido explícito de atualização na primeira mensagem de cada competência — "se você não é mais o responsável por esta unidade, responda AVISO para pararmos".
Para o que é administração do condomínio, sim: quem mora ou é dono de uma unidade tem relação com o condomínio e espera receber aviso de taxa, manutenção e assembleia. O que essa relação não autoriza é qualquer outra coisa — propaganda de fornecedor parceiro, campanha de empresa amiga, pesquisa que não é do prédio. Usar a base de moradores para isso é o caminho mais curto para o número ser denunciado.
optOut do exemplo em Node fez. Vale uma ressalva honesta: convocação de assembleia e cobrança têm formalidades próprias, e sair do WhatsApp não elimina o aviso pelos meios que o condomínio já usa. Registre o pedido, pare o envio e continue avisando pelo canal formal — não force o morador a permanecer no WhatsApp.R$ 27 por mês por número conectado, sem cobrança por mensagem. A conta é por número, não por unidade nem por mensagem: um número que atende um prédio de 300 unidades custa o mesmo que um que atende um de 20. Cada número envia até 300 mensagens por dia — dá para avisar um prédio inteiro numa tacada, e o teto existe para a administradora não perder o número num comunicado disparado sem ritmo. O teste é de 14 dias sem cartão e só começa na primeira conexão — dá para criar a conta, integrar com calma e conectar o número depois.
É essa previsibilidade que torna o fluxo viável em condomínio, onde o volume é alto e concentrado em poucos dias do mês: aviso, boleto, vencimento, comunicado e edital somam facilmente cinco ou seis mensagens por unidade em uma competência. Com cobrança por mensagem, alguém acabaria cortando justamente o aviso preventivo — o mais barato e o mais útil de todos.
O painel mostra o estado de cada conexão e atualiza a cada 10 segundos enquanto a página está aberta. Para não depender de alguém olhar a tela, assine os eventos de conexão no webhook: Disconnected avisa a queda e LoggedOut avisa que o número precisa reler o QR Code. E toda falha de envio deve virar registro numa lista visível — foi o papel do registrarFalha no exemplo — com alguém da administradora conferindo essa lista todo dia. Boleto que não saiu precisa virar tarefa, não silêncio.
Funciona sempre que esse sistema conseguir fazer uma chamada HTTP ou exportar a posição das unidades. Se ele tem área de integração, chama a API direto quando gera a cobrança do mês. Se é fechado, leia os dados por fora — relatório, banco, planilha — e dispare com uma rotina própria ou uma ferramenta de automação no meio.
Não é obrigatório, é uma escolha de remetente. Um número por prédio faz o aviso chegar com a identidade daquele condomínio e separa as conversas; um número único da administradora concentra a operação e a equipe. Cada número conectado custa R$ 27 por mês, e trocar de remetente no código é trocar o header token da chamada.
Dá: o endpoint de envio de documento recebe o arquivo em base64, com nome e legenda. Use um nome de arquivo que o morador entenda meses depois, como taxa-03-2027-unidade-42B.pdf, e mande o PDF só uma vez por competência — no aviso anterior ao vencimento. Repetir o anexo em cada mensagem só pesa a conversa.
Unidade por unidade. O grupo é conversa entre vizinhos: o aviso oficial se perde no meio e, pior, qualquer assunto de cobrança exposto ali constrange quem está em atraso. O envio individual é trabalhoso para uma pessoa e trivial para a API — é o mesmo laço, com uma chamada por unidade e uma pausa entre elas.
Lendo a posição da unidade no momento do envio, dentro do laço, nunca de uma lista montada no dia anterior. Some a isso duas proteções: registrar o que já foi enviado para aquela unidade e competência, para não repetir, e pausar a régua assim que o morador responde que pagou, deixando a conferência para o financeiro.
Isso vira tarefa, não resposta automática. A regra reconhece o que é previsível — segunda via, aviso de pagamento, confirmação de presença — e manda todo o resto para uma fila que alguém da administradora abre todo dia. Ocorrência entre vizinhos precisa de registro formal e de conversa com o síndico, nunca de texto automático.
Pode — em qualquer API, inclusive na oficial da Meta. O risco não é eliminável, é gerenciável: fale só de assunto do condomínio, fracione os disparos em vez de mandar todas as unidades no mesmo minuto, responda quem responde e pare de enviar para quem pediu para sair. O que dispara bloqueio é mensagem indesejada em massa, não o uso de API.
Com papéis distintos no cadastro, e escolhendo o destinatário pelo tipo de mensagem: comunicado de manutenção e área comum interessam a quem mora, enquanto taxa, rateio e convocação costumam ser do proprietário, conforme a convenção e o contrato de locação. Quando a unidade troca de morador, o cadastro fica errado em silêncio — vale conferir os telefones periodicamente e pedir atualização na primeira mensagem de cada competência.
14 dias grátis, sem cartão — a contagem só começa quando você conectar o número. Crie a conta, leia o QR Code e mande o aviso da próxima competência com o boleto junto.