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 →TXT (texto delimitado)
Indicado para sistemas que exportam texto separado por tabulação ou barra vertical.
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: tab (recomendado), |, ponto e vírgula ou vírgula.
- Codificação UTF-8 (com ou sem BOM). Valor com o separador ou quebra de linha vai entre aspas duplas.
Content-Type: text/plain(outext/tab-separated-values) · extensão.txtou.tsvno 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).
| Campo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|
| 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 |
| nome | Sim | Nome do contato. {{primeiro_nome}} usa a primeira palavra. | Ana Lima |
| Sim | E-mail válido. | ana@exemplo.com | |
| telefone | Sim | Com DDI e DDD, só números (55 + DDD + número). | 5511999999999 |
| empresa | Não | Empresa do contato ({{empresa}}). | Loja Exemplo |
| cidade | Não | Cidade do contato ({{cidade}}). | São Paulo |
| tags | Não | Etiquetas do lead, separadas por vírgula (no JSON também aceita lista). | cliente,vip |
| link_pagamento | Não | Entra em {{campo:link_pagamento}} nas comunicações da régua. | https://seusite.com/pagar/4821 |
| preco | Não | Entra em {{campo:preco}} nas comunicações da régua. | R$ 199,90 |
Conteúdo de exemplo (contatos.txt)
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/plain)
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/plain; charset=utf-8" \ --data-binary @contatos.txt
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.txt"
- Pela tela: na régua, aba Integração → Enviar arquivo (contatos.txt).
- Busca automática: na mesma aba, cadastre a URL https do seu sistema com o formato TXT 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.
