# OneSendz API

> API oficial do WhatsApp da OneSendz (parceira oficial da Meta): enviar mensagens e templates, ler contatos e conversas, receber eventos por webhook. Também há um servidor MCP em https://dev.onesendz.com/mcp com as mesmas ferramentas.

## Como chamar
- Base: https://dev.onesendz.com/api/v1
- Cada ferramenta: POST https://dev.onesendz.com/api/v1/<nome> com JSON no corpo (ou GET com os parâmetros na query).
- Autenticação: cabeçalho Authorization: Bearer <chave>.
- Resposta: {"ok": true, "dados": {...}} ou {"ok": false, "erro": {"codigo": "...", "mensagem": "..."}}. A mensagem de erro diz o que fazer.
- Especificação completa: https://dev.onesendz.com/openapi.json

## Chaves e modo teste
- Acesso liberado aos poucos, pela lista de espera em https://dev.onesendz.com. Enquanto o console do Developers não chega, as chaves são criadas no painel da OneSendz, em Configurações > Integrações > API e MCP.
- oszt_... = TESTE: ambiente separado (contatos, conversas, número fictício, cópia dos templates aprovados). Todo envio é simulado; nada chega a ninguém. Respostas trazem "modo": "teste".
- osz_... = PRODUÇÃO: envia de verdade pelo número da empresa.
- Desenvolva sempre com a chave de teste; troque pela de produção no fim. Guarde a chave numa variável de ambiente (ex.: ONESENDZ_API_KEY), nunca no código do front-end.
- Permissões por chave: leitura, escrita, envio. Tope opcional de envios por dia e por mês.

## Regras do WhatsApp que a API respeita
- Texto livre (enviar_mensagem) só para quem escreveu nas últimas 24 horas. Fora disso, use um template aprovado (enviar_template).
- Envios pedem chave_idempotencia: a mesma chave nunca envia duas vezes (pode repetir a chamada com segurança).
- Quem pediu para não receber marketing não recebe template de marketing.
- O envio entra na fila e devolve mensagem_id; o resultado (entregue, lida, falhou) chega por webhook.

## Limites
- Por chave: chamadas por minuto e por dia e envios por dia conforme o plano (Plus: 60/min, 5.000/dia, 300 envios/dia; Pro e acima, mais).
- Passou do limite: HTTP 429 com o motivo e quando volta (limite_por_minuto, limite_por_dia, limite_de_envios_por_dia, limite_de_envios_por_mes).

## Webhooks
- Cadastre com criar_webhook (url https + eventos). O segredo aparece uma vez.
- Eventos: mensagem.recebida, conversa.atribuida, conversa.pediu_atendente, conversa.encerrada, contato.criado, contato.etiqueta_adicionada, lead.qualificado, mensagem.entregue, mensagem.lida, mensagem.falhou.
- Corpo: {"id", "tipo", "criado_em", "organizacao_id", "dados": {...}}. Em mensagem.entregue / lida / falhou, dados.mensagem.id é o mensagem_id devolvido pelo envio; mensagem.falhou traz dados.erro {codigo, motivo, como_resolver}.
- Assinatura: X-OneSendz-Signature = "sha256=" + HMAC-SHA256(segredo, X-OneSendz-Timestamp + "." + corpo). Recuse assinatura errada ou com mais de 5 minutos. Use X-OneSendz-Event-Id para não processar duas vezes. Responda 2xx em até 10 s; sem 2xx, há novas tentativas.

## Ferramentas de leitura
- resumo_do_periodo: Números do negócio no período: contatos novos, conversas, quem pediu atendente, mensagens, campanhas enviadas e automações, com a evolução dia a dia. Responde perguntas como 'como foi a semana?', 'quantos contatos ontem?
- buscar_contatos: Procura contatos por nome, telefone ou e-mail, e/ou por etiqueta. Devolve no máximo 50 por página.
- ver_contato: Ficha de um contato: dados, etiquetas, campos personalizados, em que etapa de cada funil ele está e conversas (com canal, status e se a janela de 24 h daquele canal está aberta).
- listar_conversas: Conversas mais recentes. Filtros: pediram_atendente (precisam de alguém da equipe), nao_lidas, abertas ou todas.
- ver_conversa: Últimas mensagens de uma conversa (diz o canal: WhatsApp, Instagram ou Messenger), da mais antiga para a mais nova.
- listar_campanhas: Campanhas mais recentes com status e resultados (destinatários, entregues, lidas, falhas, cliques).
- listar_automacoes: Automações com status (ativa, pausada, rascunho), gatilho e quantas execuções tiveram (concluídas, esperando, com falha).
- listar_templates: Templates (modelos aprovados pela Meta) com texto, categoria e quantas variáveis pedem. Fora da janela de 24 h, só dá para mandar template.
- listar_etiquetas_e_segmentos: Etiquetas (cadastradas e em uso nos contatos), segmentos salvos e funis com suas colunas (nomes exatos, como aparecem no painel).
- listar_unidades_e_numeros: Unidades e números de WhatsApp conectados. Útil para escolher por qual número enviar um template ou uma campanha.
- buscar_na_ajuda: Procura nas guias oficiais da Central de Ajuda do OneSendz e devolve o passo a passo (com os nomes de menu e telas como aparecem no painel) e o link da guia. Serve para dúvidas de como fazer algo, onde fica uma opção ou 
- diagnosticar: Procura problemas e explica a causa em linguagem simples, com como resolver e onde fica no painel. Sem id: a conta inteira (números de WhatsApp, qualidade e limite, pagamento da Meta, falhas de envio e de automações nos 
- pedir_ajuda_ao_suporte: Abre um pedido de ajuda para a equipe de suporte do OneSendz, com o diagnóstico da conta anexado automaticamente. Para problemas que as guias e o diagnóstico não resolveram, ou quando a pessoa pede para falar com o supor
- resultados_de_campanhas: Compara as campanhas de WhatsApp enviadas no período: taxas de entrega, leitura e clique, quantas pessoas responderam até 72 h depois e quantos pedidos pagos (lojas integradas) vieram desses destinatários até 7 dias depo
- vendas_da_loja: Faturamento e pedidos da loja virtual integrada à OneSendz (Tray, Bizway e outras) num período, comparando com o período anterior: faturamento (pedidos pagos, enviados e entregues), número de pedidos, ticket médio, clien
- ver_funil: Mostra um funil (Kanban) por etapa: quantos cartões, valor somado, quantos estão parados além do prazo da etapa e quantos esperam resposta da empresa, com os 5 cartões que pedem atenção primeiro em cada etapa. Sem 'funil
- contar_publico: Conta quantos contatos salvos cumprem um conjunto de condições (etiquetas, compras, carrinho abandonado, funil, e-mail, resultado de campanha, campos personalizados...) e mostra alguns exemplos. Não salva nada: serve par
- ver_automacao: Mostra uma automação passo a passo (blocos e para onde cada saída leva) e aponta pontos frágeis, como 'aguardar resposta' sem caminho para 'outra resposta'. Serve para explicar, revisar ou diagnosticar um fluxo.
- ver_templates_email: Lista os templates de e-mail da empresa (nome, assunto, editor). Com 'nome', devolve também os blocos (conteudo) de um template do editor simples, para ajustar com criar_template_email.
- ver_agenda: Lista os agendamentos da Agenda num período (padrão: de hoje até 7 dias), com cliente, serviço, profissional, status (a confirmar, confirmado, atendido, faltou, cancelado), resposta do cliente ao lembrete e link. Filtra 
- horarios_livres: Mostra os horários livres da Agenda num dia (ou os próximos dias com horário), para um serviço e/ou profissional, respeitando o expediente, a duração do serviço, os bloqueios e os horários já marcados. Com contato, usa a
- ver_configuracao_agenda: Mostra como a Agenda está configurada: serviços (duração e quem faz), profissionais (ativos e horário próprio), horário de atendimento da unidade, regras (intervalo entre horários, antecedência, dias abertos, confirmar s
- listar_webinars: Lista os webinars perpétuos da conta com status, vídeo, horários das sessões, próxima sessão, oferta, a automação de inscrição ligada e os números dos últimos 30 dias (inscritos, entraram, chegaram à oferta, clicaram na 
- questionario_agente_ia: Primeiro passo para montar ou refazer o agente de IA que atende os clientes da empresa (o atendente virtual do WhatsApp, Instagram e Messenger). Lê o agente atual, o catálogo da loja conectada e perguntas recentes dos cl
- testar_agente_ia: Mostra como o agente responderia mensagens de cliente, usando o rascunho (ou o agente no ar, se não houver rascunho). Não envia nada a ninguém. Mostre ao dono as perguntas e as respostas como vieram.
- avisos_do_agente_ia: Lista os avisos passageiros em vigor no agente de atendimento, com id, para quem valem e até quando.
- listar_links_whatsapp: Links curtos de WhatsApp da empresa (app.onesendz.com/wa/...), com mensagem pronta, automação que iniciam, números e cliques. Use antes de criar um link novo para não duplicar, ou quando perguntarem quantos cliques um li
- ideias_de_conteudo: Plano Plus em diante. Ideias de posts e stories (imagem) para as redes sociais do negócio, tiradas do que os clientes falaram no WhatsApp no período (dúvidas, objeções, produtos mais pedidos). Cada ideia vem com gancho, 
- arte_de_conteudo: A arte pronta (imagem) de uma ideia gerada por ideias_de_conteudo, com a logo, a cor e o nome do negócio: post (4:5) ou story (9:16). Leva a assinatura 'Feito com a Sendy da OneSendz' conforme assinatura_das_artes. Carro
- planos_para_crescer: Mostra o plano atual, os planos acima com preço e o que cada um libera (contatos, números de WhatsApp, unidades, pedidos da IA por mês, recursos) e como mudar de plano nesta conta. Use quando a empresa bate num limite, p
- ver_cobrancas_pix: Mostra se a empresa já cadastrou a chave Pix (e, se não, como cadastrar) e as cobranças Pix enviadas no WhatsApp, com status: pendente (aguardando pagamento), pago, cancelado ou falhou. Filtra por status ou por contato.
- quem_sou: Mostra a conta do OneSendz desta conexão (id, nome e plano), a conexão (app, permissões, unidade) e quem autorizou.
- limites_do_plano: Mostra o plano da empresa e quanto já foi usado de cada limite: contatos guardados, usuários (com convites pendentes), unidades, números de WhatsApp conectados (com o limite do plano), pedidos da IA Sendy no mês, saldo d
- listar_atendentes: Lista as pessoas da equipe que podem atender conversas: id, nome, e-mail, papel e unidades.
- listar_webhooks: Lista os webhooks cadastrados, se estão ativos (e por que foram desligados), o último envio e as entregas das últimas 24 h.

## Ferramentas de escrita
- salvar_contato: Cria um contato pelo telefone ou atualiza o que já existe (nome, e-mail, etiquetas e campos personalizados). Etiquetas são somadas às que o contato já tem.
- etiquetar_contato: Adiciona e/ou remove etiquetas de um contato. Etiquetas podem disparar automações que dependem delas.
- criar_campanha_rascunho: Cria uma campanha de WhatsApp ou de e-mail como RASCUNHO, para alguém revisar e disparar no painel. Nunca dispara sozinha. Público por etiquetas ou por segmento salvo.
- criar_automacao_rascunho: Monta uma automação a partir de passos e salva como RASCUNHO (nunca ativa: a pessoa revisa e ativa no painel). Devolve o link do editor. Integrações e cadastros citados (loja, Hotmart, webinar, áudio, funil, campo, webho
- editar_automacao: Altera uma automação existente sem mudar a estrutura (não adiciona nem remove blocos ou caminhos): conteúdo de qualquer bloco, o gatilho e o nome. Blocos pelos rótulos B1, B2... (os da leitura da automação). Campos por t
- pausar_ou_reativar_automacao: Pausa uma automação ativa ou reativa uma pausada. Pausar interrompe quem estava no meio do fluxo. Automação em rascunho só se ativa pelo painel (lá o fluxo é conferido).
- mover_no_funil: Coloca um contato numa etapa do funil (cria o cartão se ele ainda não estiver no funil). Etapas de ganho ou perda podem enviar a conversão para os anúncios do Meta, quando essa integração está ligada.
- criar_lembrete: Lembrete para a PRÓPRIA pessoa que está falando com você (ex.: 'me avisa amanhã às 10h para ligar para a Maria'). Fica no cartão do contato no funil; na hora, a pessoa recebe um aviso no celular e no painel (e no WhatsAp
- criar_segmento: Salva um segmento dinâmico (público que se atualiza sozinho) com as condições dadas, para usar em campanhas e filtros do painel. Devolve quantos contatos ele tem agora.
- criar_template_rascunho: Salva um template de WhatsApp como RASCUNHO no OneSendz (não vai para a Meta). A pessoa revisa em Templates e toca em 'Enviar para aprovação'. Texto com variáveis {{1}}, {{2}}... e um exemplo para cada; botões opcionais 
- criar_template_email: Cria (ou ajusta) um template de E-MAIL no editor simples por blocos, com a identidade da empresa (logo, cores, rodapé). Fica em Disparos › Templates › E-mail para usar em campanhas e automações; não envia nada. Para AJUS
- configurar_email_empresa: Muda como os e-mails da empresa saem: nome do remetente, endereço de envio (só no domínio já verificado em Configurações › Email), e a identidade visual dos e-mails do editor simples (logo, cor da marca, rodapé, nome da 
- agendar: Marca um horário na Agenda para um contato: data, hora exata (ou só o período manhã/tarde/noite), serviço, profissional e observação. Confere se o horário está livre no expediente do profissional; sem profissional, escol
- alterar_agendamento: Muda um agendamento da Agenda: confirmar, cancelar, marcar como atendido ou falta, voltar para pedido, remarcar (nova data, hora ou período, conferindo se está livre) ou editar serviço, profissional, duração e observação
- salvar_servico: Cria um serviço da Agenda ou edita um existente (pelo id ou nome): nome, duração em minutos, ativo/inativo e quais profissionais fazem (substitui a lista; vazio = qualquer profissional). Desativar tira o serviço do formu
- salvar_profissional: Cria um profissional da Agenda ou edita um existente (pelo id ou nome): nome, ativo/inativo, horário próprio por dia da semana (ou usar o da unidade) e quais serviços faz (substitui a lista). Desativar tira dos horários 
- bloquear_agenda: Cria ou remove um bloqueio na Agenda (folga, feriado, almoço, manutenção): de um profissional ou da unidade inteira, com início, fim e motivo. O bloqueio tira o período dos horários livres; agendamentos que já existiam n
- configurar_agenda: Muda a configuração da Agenda: horário de atendimento da unidade por dia da semana, intervalo entre horários, antecedência mínima, quantos dias a agenda fica aberta, confirmar sozinho, cliente remarca e cancela sozinho (
- salvar_webinar: Cria um webinar perpétuo ou edita um existente (pelo id ou nome): nome interno, título na página, link do vídeo (YouTube, Vimeo, Panda, VTurb, Bunny ou Wistia), duração, quando a oferta aparece, link de compra e texto do
- criar_automacao_webinar: Cria, em rascunho, a automação completa de um webinar perpétuo (a mesma do botão do painel): quem manda a palavra-chave no WhatsApp é inscrito na próxima sessão e recebe o link pessoal, lembretes 1 dia antes, 10 minutos 
- link_de_teste_webinar: Gera um link de teste da sala do webinar que começa em poucos minutos, para ver a página, a contagem regressiva, o vídeo e a oferta como o inscrito vê. Não conta nos números e não manda mensagem a ninguém.
- salvar_agente_ia: Monta o agente de atendimento num RASCUNHO a partir das respostas do dono ao questionário (todas juntas, em qualquer ordem ou formato). Não liga nem muda o agente que está no ar. Organize a resposta do dono nos campos; u
- ativar_agente_ia: Grava o rascunho no agente de atendimento e liga (ou só grava, com ligar=false). Os clientes passam a ser atendidos por ele. Primeiro chame sem 'confirmar' para mostrar o resumo ao dono; só chame com confirmar=true depoi
- avisar_agente_ia: Dá ao agente de atendimento um aviso passageiro que ele passa a usar na hora com os clientes (horário diferente, promoção, produto em falta, feriado), sem mexer nas instruções do agente. Escreva o texto como fato, com da
- remover_aviso_agente_ia: Tira avisos do agente de atendimento antes do prazo (pelos ids de avisos_do_agente_ia, ou todos=true). O agente deixa de usá-los na hora.
- criar_link_whatsapp: Cria um link curto de WhatsApp (app.onesendz.com/wa/...) com mensagem pronta, para bio do Instagram, anúncio, site ou QR code impresso, e conta os cliques. Com 'automacao' (gatilho Mensagem WhatsApp recebida), a mensagem
- assinatura_das_artes: Liga ou tira a assinatura 'Feito com a Sendy da OneSendz' das artes de conteúdo da empresa (vale para as próximas artes). Vem ligada por padrão e dá para tirar; no teste grátis ela fica até a assinatura começar. Sem 'mos
- comprar_pedidos_ia: Gera o link de pagamento do pacote de pedidos extras da IA Sendy (pagamento único, os pedidos acumulam e não vencem). Só gera o link: quem paga é a pessoa, na página de pagamento. Mande o link como veio.
- atribuir_conversa: Define quem atende a conversa (a pessoa passa a ver a conversa como dela no Inbox) ou tira o atendente. Conversa por "conversa_id" ou pela mais recente do contato ("contato_id" ou "telefone"); atendente por "atendente_id
- criar_webhook: Cadastra um endereço https que recebe um aviso (POST JSON assinado) a cada evento escolhido. Eventos: mensagem.recebida (o cliente escreveu), conversa.atribuida (a conversa ganhou um atendente), conversa.pediu_atendente 
- testar_webhook: Manda na hora um aviso de teste (evento "teste") e devolve a resposta do endereço. Se o webhook foi desligado por falhas e o teste der certo, ele volta a funcionar.
- remover_webhook: Remove um webhook. Os avisos que ainda estavam na fila para ele são descartados.

## Ferramentas de envio
- preparar_mensagem: Prepara uma mensagem de texto para um contato que falou com a empresa nas últimas 24 h (regra do WhatsApp). NÃO envia: devolve um resumo e um confirmacao_id. Fora das 24 h o WhatsApp só aceita template.
- preparar_template: Use só um template cujo texto diga o que foi pedido; se nenhum servir, NÃO chame esta ferramenta: explique e ofereça criar um. Prepara o envio de um template aprovado para um contato (serve mesmo fora das 24 h). NÃO envi
- preparar_cobranca_pix: Prepara uma cobrança por Pix para um contato que falou com a empresa nas últimas 24 h: ele recebe no WhatsApp o resumo (o que está sendo cobrado e o valor) e um botão para copiar o Pix copia e cola. NÃO envia: devolve um
- marcar_cobranca_pix: Marca uma cobrança Pix pendente como paga ou cancelada. Com a conversa aberta (24 h), o cliente recebe no WhatsApp a atualização (pago aparece com o selo de pago). SÓ chame depois que a pessoa disser com clareza que o pa
- confirmar_envio: Envia de verdade a mensagem ou o template preparado identificado pelo confirmacao_id. Cada confirmacao_id vale uma vez, por 10 minutos.
- enviar_template: Envia um template aprovado para um contato numa chamada só, para sistemas integrados (CRM, ERP). Mesmas regras de preparar_template. "chave_idempotencia" é obrigatória: repetir o pedido com a mesma chave devolve o mesmo 
- enviar_mensagem: Envia texto livre para um contato que falou com a empresa nas últimas 24 h (regra do WhatsApp), numa chamada só, para sistemas integrados. "chave_idempotencia" é obrigatória: repetir o pedido com a mesma chave devolve o 

## Mais
- Guia: https://dev.onesendz.com/docs
- Suporte: suporte@impulsionae.com