Com o Connectif, você pode registrar as compras que seus clientes realizam em suas lojas físicas para registrá-las em seu cadastro de contato e dispor de um histórico unificado entre suas ações online e offline. Dessa forma, você poderá utilizar essas informações para personalizar suas estratégias usando o histórico completo de compras de cada cliente, independentemente do canal em que foram realizadas.
Neste artigo, você aprenderá como integrar compras de lojas físicas por meio da API do Connectif para que elas fiquem registradas no cadastro de cada contato.
Para usar a integração por API, você precisará de um especialista com conhecimentos em programação. Se precisar de mais informações, consulte a documentação da API do Connectif.
Antes de começar
Para realizar essa integração, você deve ter os seguintes aspectos cobertos:
- Email como chave primária: o contato deve existir na sua base de Contatos do Connectif, com um email associado como chave primária. Embora a API aceite outros identificadores (como CPF ou telefone), usá-los como identificador principal pode causar a criação de contatos duplicados.
- Catálogo e produtos sincronizados: todos os produtos incluídos na compra offline devem existir no seu catálogo do Connectif. Se um item for vendido exclusivamente em lojas físicas e não fizer parte do site, você deve criá-lo no Connectif com o status Descontinuado para poder vincular a venda offline.
- Informações dos produtos: é recomendável enviar as informações completas dos produtos incluídos na compra, especialmente o atributo categories. Com isso, você poderá criar segmentos de produto e usar essas informações em suas estratégias automatizadas.
- Estrutura rígida da requisição: a requisição só pode incluir os atributos aceitos pelo modelo da API. Não é possível enviar campos personalizados ou atributos adicionais dentro do JSON.
Aprenda como funciona a API do Connectif em este artigo.
PASSO 1. Preparação dos contatos no Connectif
(Nesta seção, explica-se como preparar seus contatos no Connectif para que possam ser relacionados corretamente à compra offline).
Você pode adicionar os contatos ao Connectif por meio da importação de arquivo ou via API.
Ao registrar uma compra offline via API, o Connectif associará as informações enviadas aos contatos e produtos existentes. A API não os criará durante o processo, por isso você deve verificar previamente se eles já estão criados no Connectif.
1. Verifique se o contato já existe no Connectif com seu email registrado. Caso não exista, crie-o antes para poder vincular a atividade corretamente.
2. No campo de busca, insira o email do contato para verificar sua existência. Se o contato não existir, será necessário criá-lo para associar a compra ao seu histórico.
Aprenda como importar contatos em este artigo.
PASSO 2. Preparação dos produtos no Connectif
(Nesta seção, explica-se como preparar seus produtos no Connectif para que possam ser relacionados corretamente à compra offline).
Você pode adicionar os produtos ao Connectif por meio da importação de arquivo ou via API.
3. Acesse "E-commerce > Catálogo" e clique no botão de opções .
4. Se algum dos itens associados à compra offline não existir no Connectif, crie-o antes de importar a compra, para isso:
-
Clique em Criar produto.
-
Preencha, no mínimo, os campos obrigatórios do produto (nome, ID, URL de detalhe e preço).
- Se o produto for vendido somente em lojas físicas, atribua o status Descontinuado, para que a compra offline possa ser registrada, mas o produto não apareça na loja online.
A URL de detalhe é obrigatória, mesmo que o produto não exista no site ou esteja marcado como Descontinuado. Nestes casos, inclua uma URL que utilize o mesmo domínio registrado na sua loja do Connectif para evitar erros de validação. Por exemplo, se o domínio da sua loja for https://www.meudominio.com, você pode usar como URL de detalhe: https://www.meudominio.com/produtos/SKU-12345.
PASSO 3. Criação da chave API
5. Acesse a Configuração da loja no menu lateral esquerdo do Connectif.
6. Na seleção de abas, vá para "API e acessos IP" e clique em API Keys.
7. Clique no botão Criar nova API Key.
8. Na seção Compras do painel de criação, habilite as permissões para Ler, Escrever e Excluir em massa.
Se também for gerenciar contatos e produtos via API, habilite as permissões correspondentes nas seções Contatos e Produtos.
9. Salve a chave API e copie-a para usar posteriormente no seu script de automação.
PASSO 4. Registro da compra via API
(Nesta seção, explica-se como preparar o envio das informações da compra para o Connectif via API).
Para registrar uma compra offline, você deve fazer uma requisição HTTP POST que enviará as informações da compra para o Connectif em formato JSON.
10. Crie o script de automação a partir do seu sistema e inclua nele a API Key gerada no passo anterior.
11. Configure no script uma requisição HTTP POST para registrar a compra no Connectif: https://api.connectif.cloud/purchases/
Na requisição, indique:
- A API Key para autenticar a chamada.
- O tipo de conteúdo application/json.
- As informações da compra no corpo da requisição.
12. Crie as informações da compra a serem enviadas e verifique se atendem às seguintes condições:
- Inclua os atributos obrigatórios da compra: cartId, products, purchaseDate, purchaseId, totalPrice e totalQuantity.
- Identifique o contato por meio do contactEmail.
- Para cada produto incluído em products, preencha os atributos obrigatórios: name, price, productDetailUrl, productId, quantity e unitPrice.
- Para registrar a compra como proveniente de uma loja física, configure sourceType com o valor point-of-sale e indique a loja ou filial em sourceName.
- Certifique-se de que purchaseId está como identificador único da compra.
Aprenda como elaborar a estrutura completa da requisição na documentação da API.
Exemplo
Uma vez criada, a requisição terá uma aparência semelhante a esta:
const apiKey = "SUA_API_KEY";
const url = "https://api.connectif.cloud/purchases/";
const purchase = {
contactEmail: "cliente@exemplo.com",
purchaseId: "POS-20260804-001",
cartId: "POS-20260804-001",
purchaseDate: "2026-08-04T15:30:00Z",
sourceType: "point-of-sale",
sourceName: "Loja Centro",
products: [
{
productId: "SKU-12345",
name: "Tênis Running",
categories: ["Calçados/Running"],
quantity: 2,
unitPrice: 39.95,
price: 79.90,
productDetailUrl: "https://www.meudominio.com/produtos/SKU-12345"
}
],
totalQuantity: 2,
totalPrice: 79.90
};
async function main() {
const response = await fetch(url, {
method: "POST",
headers: {
"Authorization": `apiKey ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify(purchase)
});
const result = await response.json();
console.log(result);
}
main();
O script registra uma compra realizada em uma loja física e a associa ao contato indicado no atributo contactEmail. Os atributos sourceType e sourceName identificam o ponto de venda físico e o nome de origem onde foi realizada.
Sucesso!
A importação de compras das lojas físicas já está pronta.
Continue aprendendo!
Para aproveitar todo o potencial da sua conta no Connectif, recomendamos continuar com os seguintes artigos:
- Integrações via API, para administrar eventos como registros de compras ou cadastros de contatos.
- Integração personalizada para enviar dados do Connectif, para enviar informações em tempo real por meio de Webhooks.
- Importação de contatos, para importar contatos manualmente para o Connectif.
- Exportação de contatos e atividades, para exportar contatos e eventos do Connectif.