Pular para o conteúdo principal

Primeira requisição

Três chamadas para conferir que a chave funciona e entender o padrão das rotas. Os exemplos usam homologação (https://api.plus.qa.leadsim.com.br); troque pelo endereço de produção quando a integração estiver pronta. Veja Ambientes.

Antes de começar​

  • Tenha a chave em mãos: Sua chave de API.
  • Guarde a chave numa variável de ambiente em vez de colar no comando:
export LEADSIM_KEY="lsk_api_SUA_CHAVE"

1. Listar os funis​

Rota: GET /companie/funnel

curl "https://api.plus.qa.leadsim.com.br/companie/funnel" \
  -H "Authorization: Bearer $LEADSIM_KEY"

A resposta é um array com os funis que o dono da chave enxerga, cada um com as etapas em funnel_step[]. Guarde os funnel_step[].id: eles são o funnel_step_id usado para criar oportunidades e movê-las de etapa.

[
  {
    "id": 7,
    "title": "Comercial",
    "funnel_step": [
      { "id": 41, "funnel_id": 7, "title": "Novo lead", "order": 1 },
      { "id": 42, "funnel_id": 7, "title": "Em contato", "order": 2 }
    ]
  }
]

Se vier 401 ou 403 com um código error_api_key_*, confira Problemas comuns.

2. Criar um lead​

Rota: POST /companie/captured/lead/api

É a rota pensada para sites e sistemas externos: cria o contato (ou reaproveita um existente com o mesmo e-mail ou WhatsApp) e abre a oportunidade numa chamada só.

curl -X POST "https://api.plus.qa.leadsim.com.br/companie/captured/lead/api" \
  -H "Authorization: Bearer $LEADSIM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "email": "maria.souza@exemplo.com.br",
    "whatsapp": "11999990000",
    "obs": "Pediu orçamento pelo formulário do site",
    "campaign_utm_source": "google",
    "campaign_utm_medium": "cpc",
    "campaign_utm_campaign": "lancamento-outubro"
  }'

Só name é obrigatório. email precisa ser um e-mail válido quando enviado; date_expectation é YYYY-MM-DD; campaign_state tem 2 letras (UF). Os campos campaign_* registram a origem do lead (UTM) e aparecem na oportunidade.

A resposta é o id da oportunidade criada, como número:

1234

Se o contato já tem oportunidade aberta, a rota devolve o id dela em vez de criar outra.

Automação de entrada do tipo API

Sem funnel_step_id no corpo, a oportunidade entra na etapa definida na automação de entrada do tipo API (Configurações › Automações). Se ela não existir, a resposta é 409 error_settings_form_not_exist. Ou configure a automação no LeadSim, ou envie funnel_step_id com um id obtido no passo 1.

3. Listar contatos com paginação​

Rota: GET /companie/person/list/:skip/:take

curl "https://api.plus.qa.leadsim.com.br/companie/person/list/0/20?order=created_at_desc" \
  -H "Authorization: Bearer $LEADSIM_KEY"

skip é quantos registros pular e take quantos trazer: 0/20 é a primeira página de 20, 20/20 a segunda. order aceita name_asc (padrão), name_desc, whatsapp_*, document_* e created_at_*; blackList=true ou false filtra pela blacklist.

Cada contato vem com tags, anotações, atividades e oportunidades vinculadas. Para filtrar por tag, origem, cidade ou situação financeira, use POST /companie/person/filterAdvanced/..., que segue o padrão descrito em Listagens com filtro.

Próximos passos​

  • Fluxos comuns: lead até ganho, proposta até nota fiscal, baixa de cobranças e assinatura digital.
  • Referência de rotas: parâmetros, corpo e respostas de cada rota, com link para testar no Swagger.