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.

  1. 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.
  2. Gere uma chave de API em Configurações → Integração. Ela vai no cabeçalho Authorization: Bearer sf_live_… (ou X-Api-Key) e não deve ficar em código público.
  3. Homologue e ative a régua. Antes disso os gatilhos são aceitos e ficam aguardando.
  4. 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
Nos exemplos abaixo, 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 →

CSV (planilha com cabeçalho)

Indicado para cargas em lote exportadas de planilhas ou relatórios do seu sistema.

Baixar modelo

Endpoint da régua (POST)

https://sendfor.aglive.com.br/api/v1/reguas/codigo-da-regua/gatilhos

Regras do arquivo

  • Só pelo endpoint da régua (o código vai na URL; não há id_cliente/campanha no arquivo).
  • Primeira linha = cabeçalho com o nome das colunas; uma linha por contato.
  • Separador detectado sozinho: vírgula, ponto e vírgula (recomendado), tab ou |.
  • Codificação UTF-8 (com ou sem BOM). Valor com o separador ou quebra de linha vai entre aspas duplas.
  • Content-Type: text/csv · extensão .csv no envio de arquivo.
  • Até 50.000 linhas e 20 MB por envio; linhas em branco são ignoradas.

Colunas

O nome da coluna é o mesmo campo do JSON (maiúsculas e acentos não importam nos campos do contato).

CampoObrigatórioDescriçãoExemplo
id_lead_clienteSimID 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
nomeSimNome do contato. {{primeiro_nome}} usa a primeira palavra.Ana Lima
emailSimE-mail válido.ana@exemplo.com
telefoneSimCom DDI e DDD, só números (55 + DDD + número).5511999999999
empresaNãoEmpresa do contato ({{empresa}}).Loja Exemplo
cidadeNãoCidade do contato ({{cidade}}).São Paulo
tagsNãoEtiquetas do lead, separadas por vírgula (no JSON também aceita lista).cliente,vip
link_pagamentoNãoEntra em {{campo:link_pagamento}} nas comunicações da régua.https://seusite.com/pagar/4821
precoNãoEntra em {{campo:preco}} nas comunicações da régua.R$ 199,90

Conteúdo de exemplo (contatos.csv)

id_lead_cliente;nome;email;telefone;link_pagamento;preco
cli-4821;Ana Lima;ana@exemplo.com;5511999999999;https://seusite.com/pagar/4821;R$ 199,90

Como enviar

curl com o conteúdo no corpo (text/csv)

curl -X POST "https://sendfor.aglive.com.br/api/v1/reguas/codigo-da-regua/gatilhos" \
  -H "Authorization: Bearer $SENDFOR_API_KEY" \
  -H "Content-Type: text/csv; charset=utf-8" \
  --data-binary @contatos.csv

curl com arquivo (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.csv"
  • Pela tela: na régua, aba Integração → Enviar arquivo (contatos.csv).
  • Busca automática: na mesma aba, cadastre a URL https do seu sistema com o formato CSV e o intervalo (a partir de 5 min). Opcional: cabeçalho de autenticação e o parâmetro “desde” (o SendFor envia a data da última busca, em ISO). Conteúdo igual ao da última busca não gera gatilho.

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.