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 →

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_… (ou X-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 com duplicado: 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).

CampoObrigatórioDescriçãoExemplo
id_clienteSimID do cliente no SendFor. Precisa ser o mesmo da chave de API (senão 403).SEU_ID_CLIENTE
campanhaSimCódigo da régua transacional (ou o ID da campanha). No endpoint da régua, precisa ser a mesma da URL.codigo-da-regua
contatosSimLista de contatos. Cada item com os campos abaixo.[ {...} ]
contatos[].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
contatos[].nomeSimNome do contato. {{primeiro_nome}} usa a primeira palavra.Ana Lima
contatos[].emailSimE-mail válido.ana@exemplo.com
contatos[].telefoneSimCom DDI e DDD, só números (55 + DDD + número).5511999999999
contatos[].empresaNãoEmpresa do contato ({{empresa}}).Loja Exemplo
contatos[].cidadeNãoCidade do contato ({{cidade}}).São Paulo
contatos[].tagsNãoEtiquetas do lead, separadas por vírgula (no JSON também aceita lista).cliente,vip
contatos[].variaveisNãoObjeto 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

CampoObrigatórioDescriçãoExemplo
contatos[].variaveis.link_pagamentoNãoEntra em {{campo:link_pagamento}} nas comunicações da régua.https://seusite.com/pagar/4821
contatos[].variaveis.precoNãoEntra 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"
Dica: envie um gatilho por evento (um ou poucos contatos) para a comunicação sair em até 1 minuto. Para cargas grandes, prefira um arquivo CSV ou TXT.

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.