API de integração

Antes de começar

Você precisa de uma chave de integração. Quem gera e ativa a chave é a RD360, em Configurações › API e webhooks; a clínica vê ali o estado de cada chave. Cada chave pertence a uma clínica e só enxerga os dados dela.

A chave vai no cabeçalho x-api-key de toda chamada (também aceitamos Authorization: Bearer SUA_CHAVE). Nunca mande a chave na URL. Todas as requisições são POST com corpo JSON.

Cada chave tem duas permissões, ligadas pela RD360: enviar conversão de verdade (ver Modo de teste, abaixo) e registrar venda. Sem a segunda, a chave cria e move paciente, mas fechar venda e buscar por telefone voltam 403.

Limite: 60 chamadas por minuto, por IP. Acima disso a resposta é 429.

Modo de teste

Uma chave pode estar em teste ou ativa. Em teste ela funciona por inteiro (cria paciente, move o funil, registra a venda), mas não envia conversão para o Meta nem para o Google.

É assim que se constrói a integração sem sujar a conta de anúncio da clínica. A resposta continua mostrando o que teria sido enviado, dentro de skipped, com o motivo chave em modo de teste: conversão não enviada.

Quando os dados estiverem chegando certos, peça à RD360 para ativar a chave. Do lado do código não muda nada.

1. Criar o paciente

POST https://track.rd360.com.br/api/webhook/lead

Corpo

Um objeto, ou um array de até 100 objetos para enviar vários de uma vez.

• name: obrigatório. Até 120 caracteres.
• phone: obrigatório. Telefone brasileiro, com DDD.
• email: opcional.
• origin: de onde o paciente veio. Um de facebook, instagram, google_ads, tiktok_ads, indicacao, organico, ligacao, fachada, outro. Texto diferente disso é normalizado; sem nada reconhecido, vira outro.
• campaign: legado. Continua sendo aceito para não quebrar integração existente, mas não aparece mais em nenhuma tela: a campanha passou a vir de utm_campaign e dos identificadores de clique.
• tratamento: texto livre, até 120 caracteres. Que tratamento o paciente procura.
• gclid, fbclid: o identificador do clique, quando a sua landing capturar. É o que permite creditar a venda ao anúncio certo, então mande sempre que tiver.
• utm_source, utm_medium, utm_campaign, utm_content, utm_term: opcionais.
• value: opcional. Só use se já souber o valor no momento da entrada.
• created_at: opcional. A data em que o paciente entrou no seu sistema, para ele não aparecer como novo de hoje. AAAA-MM-DD (lida como meio-dia de Brasília) ou data e hora ISO com fuso (ex.: 2026-09-30T14:00:00-03:00); data e hora sem fuso é recusada. Não pode ser futura nem anterior a 2000. Só vale na criação: paciente que já existe não tem a data reescrita. Não dispara conversão.
• reativar: opcional, padrão true. Com false, o paciente que já existe é só encontrado, sem mudar nada (ver abaixo).
• match: opcional. O único valor aceito é "phone"(ver Busca por telefone, abaixo).
• somente_buscar: opcional. Só vale como true, junto com match: "phone": busca e nunca cria.

Paciente que já existe

O Pomelo casa por telefone + nome. Se já houver um cartão para essa pessoa, ele não cria outro: atualiza os identificadores de clique e, se o cartão estava arquivado ou numa etapa final (fechado, desmarcou, não compareceu), devolve ele ao início do funil, preservando o histórico.

Com reativar: false, o cartão encontrado fica como está, e o id dele volta em existing_ids (com a contagem em existing). Serve para carga de vendas: você pega o id e decide o resto em /api/webhook/stage.

Busca por telefone

Com match: "phone", o Pomelo procura os cartões da clínica só pelo telefone, ignorando o nome. Se achar um ou mais, não cria nem muda nada e devolve todos; se não achar, cria como sempre. Com somente_buscar: true, nunca cria.

Como a resposta traz nome, etapa e vendas do paciente, a busca por telefone exige uma chave com permissão de registrar venda. Sem ela, a chamada inteira volta 403 e nada é gravado.

Isso é proposital. Dois cartões para o mesmo paciente fariam a mesma venda subir duas vezes para o Meta e para o Google. Não tente resolver duplicidade do seu lado: mande e deixe o Pomelo decidir.

Resposta

200 com ok: true, mais inserted (quantos criou), lead_ids (os ids criados) e, quando houver, reactivated, duplicates (repetidos no próprio lote) e errors.

• Com reativar: false: existing (quantos achou) e existing_ids.
• Com match: "phone": existing vira a lista dos cartões achados, cada um com id, name, stage_id, archived, closed_at e vendas (valor, fechada_em, external_id); existing_ids traz os ids; e por_telefone diz, para cada item do lote, index, phone, lead_id (o id criado, ou null) e os cartões achados em existing.

Atenção: um lote pode voltar 200 com errors preenchido. Sempre leia esse campo: ele diz qual item do lote falhou e por quê.

2. Mover no funil e registrar a venda

POST https://track.rd360.com.br/api/webhook/stage

É esta chamada que dispara a conversão para o Meta e para o Google.

Corpo

• leadId: o id devolvido na criação. Prefira sempre ele.
• phone + name: alternativa, quando você não guardou o id. Se não achar o paciente, responde 404 pedindo para criar primeiro.
• stage: obrigatório. Um de new, contacted, scheduled, completed, closed, desmarcou, no_show.
• value: o valor da venda, em reais, de 0 a 10.000.000. Só faz sentido com stage: "closed".
• external_id: opcional, até 120 caracteres. O id da venda no seu sistema. Ver Segunda venda, abaixo.
• occurred_at, scheduled_at, attended_at, closed_at: opcionais. As datas reais, para carga retroativa (ver Datas, abaixo).
• sem_conversao: opcional, true ou false. Com true, registra a etapa e a venda com a data real e não envia nada ao Meta nem ao Google. Exige a data da etapa.
• so_avancar: opcional, true ou false. Com true, o cartão só anda para a frente (ver abaixo).

Datas

Sem datas, tudo é registrado com o horário da chamada. Para lançar o que já aconteceu, mande AAAA-MM-DD (lida como meio-dia de Brasília) ou data e hora ISO com fuso; data e hora sem fuso é recusada. Nenhuma data pode ser futura.

• A data do evento da etapa pedida (scheduled_at em scheduled, attended_at em completed, closed_at em closed, ou occurred_at) pode ter no máximo 62 dias, o limite das plataformas para conversão. Mais antiga volta 400 e nada é registrado, a não ser com sem_conversao: true.
• As datas das etapas anteriores podem ser de qualquer dia desde 2000. A conversão delas só sai se tiver data e couber nos 62 dias; senão vem em skipped, com o motivo.
• Cada data só vale nas etapas que a registram: closed_at só com closed; attended_at com completed ou closed; scheduled_at com scheduled, completed, closed, desmarcou ou no_show. Fora disso, 400.

Só para a frente

Com so_avancar: true, uma etapa anterior à atual (ou no mesmo nível, como desmarcou para quem está em scheduled) não muda nada e volta 200 com unchanged: true, motivo: "etapa_a_frente" e etapa_atual. A ordem é new, contacted, scheduled (junto com desmarcou e no_show), completed, closed.

Segunda venda

Nas clínicas que usam orçamentos, closed com value registra a venda no painel. Se o paciente já está fechado, uma nova chamada sem external_id é tratada como reenvio e volta unchanged, com motivo: "venda_ja_registrada". Para registrar uma venda adicional, mande external_id com o id da venda no seu sistema: id novo registra, id repetido volta unchanged.

Quais etapas disparam conversão

Esta é a parte que mais gera erro. Só três disparam:

• scheduled → evento de agendamento
• completed → evento de comparecimento
• closed com value → evento de venda, com o valor

new, contacted, desmarcou e no_show movem o cartão e não disparam nada.

Pular etapa é seguro: mandar closed direto faz o Pomelo preencher agendamento e comparecimento sozinho, para o funil não ficar com buraco.

Reenviar a mesma coisa não duplica

Cada evento tem uma chave determinística. Se a sua automação reenviar por retentativa ou por um bug, a conversão não sobe duas vezes. Você pode reenviar com segurança.

Resposta

200 com ok: true, leadId, stage, sale_cycle, quote_id, sem_conversao: true quando for o caso, e três listas: dispatched (o que subiu), skipped (o que foi pulado, com o motivo) e failed (o que falhou).

Quando nada muda, a resposta é 200 com ok: true, unchanged: true, leadId e stage, e, conforme o caso, motivo (etapa_a_frente ou venda_ja_registrada) e etapa_atual.

Leia as três. Um 200 não significa que a conversão subiu: significa que a chamada foi aceita. O que subiu está em dispatched.

Erros

• 401: chave ausente, inválida ou revogada.
• 403: a chave é válida, mas não tem permissão de registrar venda (fechar com closed ou buscar com match: "phone"). Peça à RD360 para liberar na chave.
• 400: corpo inválido, etapa desconhecida, valor inválido, data inválida ou fora do limite.
• 404: paciente não encontrado nesta clínica.
• 409: o paciente está arquivado e a etapa é closed. Reenvie por /api/webhook/lead para reativar, e então feche.
• 429: passou de 60 chamadas por minuto.
• 500: falha nossa. Pode reenviar.
• 503: não deu para validar a chave agora (falha nossa, temporária). Não é a chave. Reenvie em alguns instantes.

Exemplo

Criar o paciente:

curl -X POST https://track.rd360.com.br/api/webhook/lead \
  -H "x-api-key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Oliveira",
    "phone": "11999990000",
    "origin": "google_ads",
    "gclid": "Cj0KCQ..."
  }'

Registrar a venda:

curl -X POST https://track.rd360.com.br/api/webhook/stage \
  -H "x-api-key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "o-id-devolvido-acima",
    "stage": "closed",
    "value": 4200
  }'

Recomendações

• Guarde o leadId devolvido na criação e use ele nas etapas. Casar por telefone + nome funciona, mas falha quando a secretária corrige a grafia do nome no Pomelo.
• Mande o gclid e o fbclid sempre que a landing capturar. Sem eles a conversão ainda sobe, mas casa por telefone, o que acerta bem menos.
• Não invente valor. Venda sem valor conhecido é melhor sem o campo do que com um número aproximado: valor errado ensina a plataforma a perseguir dinheiro que não existe.
• Comece em modo de teste e peça a ativação à RD360 só depois de ver os dados certos no Pomelo.

Dúvidas

Fale com a RD360. Todo envio fica registrado, então dá para conferir exatamente o que a sua integração mandou e o que aconteceu com cada conversão.