Documentação
Integrações
Como o seu sistema envia contatos para as réguas transacionais do Sendfor, por JSON (API em tempo real), CSV ou TXT. Cada contato recebido é cadastrado na base de leads, entra no pipe e recebe a régua (WhatsApp, e-mail e SMS) na hora.
Antes de começar
Vale para os três tipos de entrada.
- No Sendfor, crie a régua em Transacional, monte as comunicações e defina no Início o tipo de entrada e o campo de cada variável.
- Gere uma chave de API em Configurações → Integração. Ela vai no cabeçalho
Authorization: Bearer sf_live_…(ouX-Api-Key) e não deve ficar em código público. - Homologue e ative a régua. Antes disso os gatilhos são aceitos e ficam aguardando.
- Envie os contatos pela API, por arquivo na tela da régua ou cadastre a busca automática (o Sendfor consulta uma URL sua).
Endereço base da API
https://sendfor.aglive.com.br/api/v1
SEU_ID_CLIENTE é o seu id_cliente e codigo-da-regua o código da régua. No JSON, cada valor entre {{ }} é uma variável: troque pelo valor da sua aplicação ({{api_id}} = id_cliente, {{campanha}} = código da régua). Dentro do Sendfor, a página Integrações mostra o seu id_cliente, o código e as variáveis de cada régua. Entrar →JSON pela API
Indicado para enviar cada evento na hora em que acontece (pedido aprovado, boleto gerado, inscrição…).
Endpoint geral (POST): a régua vem do campo “campanha”
https://sendfor.aglive.com.br/api/v1/gatilhos
Endpoint da régua (POST)
https://sendfor.aglive.com.br/api/v1/reguas/codigo-da-regua/gatilhos
Cabeçalhos
Authorization: Bearer sf_live_…(ouX-Api-Key: sf_live_…): obrigatório.Content-Type: application/json: obrigatório. Codificação UTF-8.Idempotency-Key: opcional, até 200 caracteres. Reenviar com a mesma chave não duplica o gatilho (resposta 200 comduplicado: true). Sem ela, o próprio conteúdo é usado: o mesmo JSON enviado duas vezes também não duplica.
Estrutura do corpo
Um objeto com a identificação e a lista contatos (até 50.000 por envio e 20 MB).
| Campo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|
| id_cliente | Sim | ID do cliente no SendFor. Precisa ser o mesmo da chave de API (senão 403). | SEU_ID_CLIENTE |
| campanha | Sim | Código da régua transacional (ou o ID da campanha). No endpoint da régua, precisa ser a mesma da URL. | codigo-da-regua |
| contatos | Sim | Lista de contatos. Cada item com os campos abaixo. | [ {...} ] |
| contatos[].id_lead_cliente | Sim | ID do lead no seu sistema. Fica salvo no lead do SendFor e identifica o mesmo lead nos próximos envios (atualiza os dados em vez de duplicar). | cli-4821 |
| contatos[].nome | Sim | Nome do contato. {{primeiro_nome}} usa a primeira palavra. | Ana Lima |
| contatos[].email | Sim | E-mail válido. | ana@exemplo.com |
| contatos[].telefone | Sim | Com DDI e DDD, só números (55 + DDD + número). | 5511999999999 |
| contatos[].empresa | Não | Empresa do contato ({{empresa}}). | Loja Exemplo |
| contatos[].cidade | Não | Cidade do contato ({{cidade}}). | São Paulo |
| contatos[].tags | Não | Etiquetas do lead, separadas por vírgula (no JSON também aceita lista). | cliente,vip |
| contatos[].variaveis | Não | Objeto com as variáveis das comunicações (os campos definidos no Início da régua). Objeto aninhado vira nome com _ (pedido.numero → pedido_numero). | { ... } |
Variáveis desta régua
| Campo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|
| contatos[].variaveis.link_pagamento | Não | Entra em {{campo:link_pagamento}} nas comunicações da régua. | https://seusite.com/pagar/4821 |
| contatos[].variaveis.preco | Não | Entra em {{campo:preco}} nas comunicações da régua. | R$ 199,90 |
JSON de exemplo
{
"id_cliente": "{{api_id}}",
"campanha": "{{campanha}}",
"contatos": [
{
"id_lead_cliente": "{{id_lead}}",
"nome": "{{nome}}",
"email": "{{email}}",
"telefone": "{{telefone}}",
"variaveis": {
"link_pagamento": "{{link_pagamento}}",
"preco": "{{preco}}"
}
}
]
}Exemplos de chamada
curl
curl -X POST "https://sendfor.aglive.com.br/api/v1/gatilhos" \
-H "Authorization: Bearer $SENDFOR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-4821" \
-d '{"id_cliente":"{{api_id}}","campanha":"{{campanha}}","contatos":[{"id_lead_cliente":"{{id_lead}}","nome":"{{nome}}","email":"{{email}}","telefone":"{{telefone}}","variaveis":{"link_pagamento":"{{link_pagamento}}","preco":"{{preco}}"}}]}'JavaScript (fetch)
const resposta = await fetch("https://sendfor.aglive.com.br/api/v1/gatilhos", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SENDFOR_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "pedido-4821",
},
body: JSON.stringify({
"id_cliente": "{{api_id}}",
"campanha": "{{campanha}}",
"contatos": [
{
"id_lead_cliente": "{{id_lead}}",
"nome": "{{nome}}",
"email": "{{email}}",
"telefone": "{{telefone}}",
"variaveis": {
"link_pagamento": "{{link_pagamento}}",
"preco": "{{preco}}"
}
}
]
}),
});
const gatilho = await resposta.json(); // { id, status: "PENDING", ... }Python (requests)
import os, requests
resposta = requests.post(
"https://sendfor.aglive.com.br/api/v1/gatilhos",
headers={
"Authorization": f"Bearer {os.environ['SENDFOR_API_KEY']}",
"Idempotency-Key": "pedido-4821",
},
json={
"id_cliente": "{{api_id}}",
"campanha": "{{campanha}}",
"contatos": [
{
"id_lead_cliente": "{{id_lead}}",
"nome": "{{nome}}",
"email": "{{email}}",
"telefone": "{{telefone}}",
"variaveis": {
"link_pagamento": "{{link_pagamento}}",
"preco": "{{preco}}"
}
}
]
},
timeout=30,
)
gatilho = resposta.json() # { "id", "status": "PENDING", ... }Arquivo .json (multipart, campo “arquivo”)
curl -X POST "https://sendfor.aglive.com.br/api/v1/reguas/codigo-da-regua/gatilhos" \ -H "Authorization: Bearer $SENDFOR_API_KEY" \ -F "arquivo=@contatos.json"
Respostas e acompanhamento
Iguais para JSON, CSV e TXT. Erros vêm como { "erro": "mensagem" }.
Códigos HTTP
202Gatilho recebido e na fila (corpo com o id para consultar).200Mesmo gatilho já recebido (Idempotency-Key ou conteúdo repetido): devolve o existente com duplicado: true.400Corpo vazio, JSON sem id_cliente/campanha, CSV/TXT no endpoint geral ou arquivo fora do campo “arquivo”.401Chave de API ausente, inválida ou revogada.403id_cliente ou campanha não correspondem à chave / régua.404Régua não encontrada para este cliente.409Régua finalizada: não recebe novos gatilhos.413Conteúdo acima de 20 MB.415Content-Type ou extensão não suportados.429Mais de 150 requisições por minuto com a mesma chave (respeite o Retry-After).
Status do gatilho
PENDINGAguardando: Recebido e na fila. Fica aguardando enquanto a régua estiver em homologação ou pausada.PROCESSINGProcessando: O robô está lendo o conteúdo e cadastrando os contatos (a cada 1 minuto).DONEProcessado: Contatos cadastrados na base e na régua; a primeira comunicação sai na hora para os novos.REJECTEDRejeitado: Conteúdo não pôde ser lido (formato, cabeçalho, campos obrigatórios). Corrija e envie de novo.FAILEDFalhou: Erro inesperado depois de 5 tentativas (1, 5, 15 e 60 min). Pode ser reprocessado na tela da régua.
Resposta do envio (202)
{
"id": "cmabc123…",
"regua": "pedido-aprovado",
"status": "PENDING",
"origem": "API",
"formato": "JSON",
"recebido_em": "2026-10-26T13:00:00.000Z",
"processado_em": null,
"linhas": null,
"novos": null,
"atualizados": null,
"rejeitados": null,
"erro": null
}Consultar um gatilho (GET)
curl "https://sendfor.aglive.com.br/api/v1/gatilhos/<id do gatilho>" \ -H "Authorization: Bearer $SENDFOR_API_KEY"
Contato que não entra
O gatilho é processado e o contato com problema fica de fora, com o motivo, no CSV de não adicionados (aba Integração da régua): campo obrigatório em branco, e-mail ou telefone inválido, contato repetido no envio, na lista de inválidos ou descredenciado. Mesmo id_lead_cliente atualiza o lead em vez de criar outro.
