REDA Data Service: conecte seus formulários

Todo formulário que você mantém fora da REDA — um formulário de contato no site de marketing, uma landing page de campanha, um microsite no Webflow — pode criar ou atualizar um registro da REDA no instante em que é enviado, com toda a atribuição de campanha incluída, sem escrever uma linha de código. O Data Service é o motor empacotado de captação web de entrada da REDA: seu formulário envia uma pequena requisição web, a REDA a confere contra uma linha de permissão que você controla, e um mapeamento que você configura transforma os valores recebidos em um registro real. Este artigo foi escrito para o administrador ou o desenvolvedor web que monta essa conexão. Ele mostra como construir o endereço para o qual seu formulário envia os dados, como autenticar a requisição, como formatar o corpo, o conjunto pronto de campos que alimenta um Lead web e para onde vai um envio com falha, para que você possa encontrá-lo e corrigi-lo. Este é um conteúdo voltado a desenvolvedores, então — diferentemente do restante do Centro de ajuda — ele mostra os endereços web e os campos de requisição literais de que você vai precisar.

Como funciona

O Data Service aceita uma requisição web do seu formulário, confirma que ela é permitida e a encaminha para ser transformada em um registro. O ponto central do design é que a aceitação e a criação do registro são dois momentos separados:

Como a aceitação e a criação são desacopladas, uma resposta de sucesso significa "sua requisição foi aceita", e não "o registro já existe". Quase todo envio de fato vira um registro; as raras falhas durante essa etapa em segundo plano ficam registradas no Log Assíncrono em vez de se perderem, e é por isso que o log é a sua rede de segurança (veja Quando algo falha).

A etapa em segundo plano é quase instantânea para um envio isolado e processa um envio por vez quando muitos chegam ao mesmo tempo; assim, em um pico — um disparo de e-mail de campanha, por exemplo — os registros podem aparecer um instante depois das respostas de sucesso, e não todos de uma vez. Isso é normal e não descarta nada: toda requisição aceita é gravada ou registrada no log.

Ativação e controles de entrada

Antes que qualquer formulário possa criar registros, quatro coisas precisam estar alinhadas. Toda requisição — seja uma requisição de leitura no estilo do navegador, seja um envio de formulário — passa pelo mesmo controle:

De fábrica, um tipo de registro já vem conectado e pronto para uso: o Lead — o registro da REDA para um prospect que entrou em contato — com leitura, envio, criação e edição habilitados e uma chave de autenticação definida. Um segundo tipo de registro, a Solicitação de serviço, vem parado: a linha de Setup dele existe, mas todas as chaves estão desligadas, então ele não aceita nada até que um administrador o ative. Adicionar seus próprios tipos de registro segue o mesmo padrão, descrito em Adicionando objetos e fontes ao Data Service.

O endpoint

Seu formulário envia os dados para um endereço web que nomeia o tipo de registro que você está criando e a fonte de dados — um rótulo que agrupa uma família de formulários para que os mapeamentos dela fiquem separados dos de outra. O endereço segue este formato:

<Your Site URL>/services/apexrest/reda1/dataservice/<Record Type>/<Data Source>

Para a captação de Leads web que já vem pronta, o tipo de registro é o Lead e a fonte de dados é Web, resultando em um endereço que termina assim:

.../dataservice/reda1__Inquiry__c/Web

A primeira parte — a URL do seu site — é o endereço web público que seu administrador configurou para expor o serviço; peça-o a ele. Uma requisição bem-sucedida retorna imediatamente uma resposta 200 com {"success": true}. Se uma verificação de entrada falhar, você recebe uma resposta 400 com uma mensagem curta explicando o motivo e, se a chave geral estiver desligada, você recebe um 400 com uma mensagem informando que o serviço está desativado.

A requisição

Um envio de formulário é uma requisição POST. Seu corpo é uma pequena lista de pares chave/valor — uma entrada por campo enviado — escrita em JSON:

[
  {"key": "FirstName", "value": "Aisha"},
  {"key": "LastName",  "value": "Rahman"},
  {"key": "Email",     "value": "aisha@example.com"}
]

Quando a linha de Setup exige autenticação, a requisição também leva a chave em um cabeçalho chamado x-api-key. (Uma requisição de leitura do tipo GET funciona da mesma forma, com os valores passados como parâmetros do endereço em vez de um corpo; formulários devem usar POST.)

Se uma requisição cria um novo registro ou atualiza um já existente é decidido por um único campo: recordId.

Envie um recordId com Edit Record desligado (ou crie um registro com Create Record desligado) e a REDA responde "DML Operation not supported." — ela está dizendo que a operação solicitada não está habilitada naquela linha de Setup.

A integração de site que já vem pronta

Um mapeamento é a tabela de tradução entre as chaves que seu formulário envia e os campos do registro da REDA. A REDA entrega um mapeamento completo para Leads web: 21 parâmetros que cobrem os dados do visitante, de onde ele veio e todo o conjunto de atribuição de marketing. Envie qualquer uma dessas chaves na sua requisição e elas caem no campo certo do Lead. Duas delas trazem um valor padrão, aplicado quando seu formulário omite o valor:

Você não precisa enviar as 21 — envie as que seu formulário tiver. A fonte de dados Web mantém esse grupo de mapeamentos junto, de modo que outra família de formulários pode usar a própria fonte de dados com um conjunto diferente de chaves, sem nenhuma sobreposição.

Quando algo falha: o Log Assíncrono

Como o registro é criado um instante depois de seu formulário receber a resposta de sucesso, o lugar para confirmar o que realmente aconteceu é o Log Assíncrono — o registro que a REDA mantém do processamento em segundo plano. Quando um envio não pode ser transformado em registro — um campo obrigatório ausente, um valor que não passa em uma regra — a REDA desfaz a gravação e, em vez disso, cria uma entrada no Log Assíncrono. Nada é descartado em silêncio.

Cada entrada de um envio com falha traz a origem de onde ele veio, uma contagem de falhas e — o mais útil de tudo — a requisição completa em seus detalhes, para que você veja exatamente o que o formulário enviou e por que foi rejeitado. Para corrigir um envio com problema, ajuste o formulário (ou os dados) e envie novamente; não há nova tentativa automática. Para conhecer a anatomia do log em si, o indicador Attention Needed e os alertas por e-mail ao administrador, consulte Registros assíncronos do REDA.

Exemplo prático: uma landing page de campanha

A Meridian Properties mantém uma landing page de locação de verão. Quando um prospect envia o formulário de contato, a página envia esta requisição para .../dataservice/reda1__Inquiry__c/Web com um cabeçalho x-api-key contendo a chave da Meridian:

[
  {"key": "FirstName",    "value": "Aisha"},
  {"key": "LastName",     "value": "Rahman"},
  {"key": "Email",        "value": "aisha@example.com"},
  {"key": "utm_source",   "value": "google"},
  {"key": "utm_campaign", "value": "summer-lease"},
  {"key": "gclid",        "value": "..."}
]

A REDA responde 200 {"success": true} e, momentos depois, aparece um Lead chamado Aisha Rahman — com Inquiry Source Web e com a campanha e o ID de clique do Google registrados para os relatórios de marketing.

Atualizando em vez de criar. Se mais tarde Aisha enviar o formulário de novo com o telefone dela, a mesma requisição acrescida de {"key": "recordId", "value": "<id do Lead dela>"} atualiza o Lead existente em vez de criar um duplicado.

Quando falha. Se um envio chegar com um campo obrigatório ausente, nenhum registro é criado — mas aparece uma entrada no Log Assíncrono com o payload completo, para que você veja o que foi enviado e corrija o formulário.

O que vem a seguir

1. Adicionando objetos e fontes ao Data Service — conecte o mesmo motor a um novo tipo de registro ou divida os formulários em fontes separadas.
2. Leads web e solicitações de visita — o caminho de captação irmão, em que as páginas de anúncios da REDA gravam Leads diretamente.
3. Registros assíncronos do REDA — a anatomia completa do log de falhas para o qual este artigo aponta.
4. Lendo dados da REDA pelas APIs do Salesforce — o lado de saída, de leitura e gravação, por contraste.
5. Encontrando e mesclando Leads duplicados — faça a limpeza quando o mesmo prospect envia o formulário duas vezes.

Perguntas frequentes