Documentação técnica

Integração com o Indicae

Referência completa para conectar seu ERP ou sistema ao Indicae — criar afiliados, atualizar status de leads e receber webhooks de conversão.

Como funciona

A integração tem dois sentidos: seu ERP envia eventos ao Indicae (inbound) e o Indicae notifica seu ERP sobre novos leads e conversões (outbound webhooks).

1Cliente fecha pedido no ERP da empresa.
2ERP chama POST erp-order-confirmed → Indicae cria o afiliado e devolve um welcome_url (magic-link).
3Empresa entrega o welcome_url ao cliente (WhatsApp, e-mail ou SMS). O Indicae já envia via WhatsApp por padrão — você pode desativar se quiser controlar o envio.
4Cliente acessa o link e cai direto no painel dele, com o código de indicação pronto para copiar.
5Indicado preenche o formulário na LP do afiliado → lead é criado no Indicae.
6Indicae dispara o webhook referral.created para a URL configurada no painel da empresa.
7Conforme o lead avança no funil, o ERP chama erp-referral-status para atualizar o estágio. Quando converter, inclua o bloco contract para liberar a comissão.

Autenticação

Toda requisição inbound (seu ERP → Indicae) deve ser assinada com HMAC-SHA256. O Indicae rejeita requisições com assinatura inválida ou timestamp fora da janela de ±5 minutos (proteção anti-replay).

Encontre suas credenciais em Painel admin → Configurações → Integração: o slug da empresa e a referência do segredo HMAC no Vault.

Headers obrigatórios em toda requisição

Content-Type: application/json
X-Indicaai-Company: seu slug (ex.: acme-financas)
X-Indicaai-Timestamp: epoch em segundos (Unix timestamp inteiro)
X-Indicaai-Signature: sha256=hex(HMAC_SHA256(segredo, "{timestamp}.{rawBody}"))

Gerar a assinatura — Node.js

import crypto from "crypto";

const secret = process.env.INDICAAI_HMAC_SECRET; // busque do seu vault/env
const timestamp = Math.floor(Date.now() / 1000).toString();
const rawBody = JSON.stringify(payload);

const signature = crypto
  .createHmac("sha256", secret)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");

// Headers para adicionar na requisição:
// X-Indicaai-Company: {SEU_SLUG}
// X-Indicaai-Timestamp: <timestamp>
// X-Indicaai-Signature: sha256=<signature>

Gerar a assinatura — Python

import hmac, hashlib, time, json

secret = os.environ["INDICAAI_HMAC_SECRET"]  # busque do seu vault/env
timestamp = str(int(time.time()))
raw_body = json.dumps(payload, separators=(",", ":"))

signature = hmac.new(
    secret.encode(),
    f"{timestamp}.{raw_body}".encode(),
    hashlib.sha256,
).hexdigest()

# Headers para adicionar na requisição:
# X-Indicaai-Company: {SEU_SLUG}
# X-Indicaai-Timestamp: <timestamp>
# X-Indicaai-Signature: sha256=<signature>

Criar afiliado POST

Dispare quando um cliente fechar um pedido no seu ERP. O Indicae registra o afiliado, gera o código de indicação e devolve um welcome_url (magic-link). Se o afiliado já existir pelo CPF, o endpoint é idempotente — retorna o afiliado existente sem duplicar.

URL do endpoint

https://fwenhjalbnlphpkdsszy.supabase.co/functions/v1/erp-order-confirmed

affiliate_scope

Valor	Comportamento
`hub`	Afiliado pode indicar para todas as empresas ativas no hub.
`specific_products`	Afiliado só indica os produtos definidos no campo `product_ids` (array de UUIDs).

Payload de exemplo

{
  "order_id": "ORD-12345",
  "customer": {
    "cpf": "12345678900",
    "first_name": "Daniel",
    "last_name": "Almeida",
    "phone": "+5511999998888",
    "email": "daniel@example.com"
  },
  "product_type": "credito",
  "amount": 5000,
  "confirmed_at": "2026-05-14T15:32:11Z",
  "affiliate_scope": "hub"
}

Resposta esperada (200)

{
  "status": "ok",
  "affiliate_id": "8e6f0c8c-...",
  "referral_code": "Dn7K2aZx",
  "welcome_url": "https://<sub>.indicae.club/auto/<token>",
  "welcome_sent_to": "+5511****8888"
}

Exemplo curl

TIMESTAMP=$(date +%s)
BODY='{
  "order_id": "ORD-12345",
  "customer": {
    "cpf": "12345678900",
    "first_name": "Daniel",
    "last_name": "Almeida",
    "phone": "+5511999998888",
    "email": "daniel@example.com"
  },
  "product_type": "credito",
  "amount": 5000,
  "confirmed_at": "2026-05-14T15:32:11Z",
  "affiliate_scope": "hub"
}'
SIGNATURE=$(echo -n "$TIMESTAMP.$BODY" | openssl dgst -sha256 -hmac "$INDICAAI_HMAC_SECRET" | awk '{print $2}')

curl -X POST 'https://fwenhjalbnlphpkdsszy.supabase.co/functions/v1/erp-order-confirmed' \
  -H 'Content-Type: application/json' \
  -H 'X-Indicaai-Company: {SEU_SLUG}' \
  -H "X-Indicaai-Timestamp: $TIMESTAMP" \
  -H "X-Indicaai-Signature: sha256=$SIGNATURE" \
  --data-raw "$BODY"

O welcome_url é o magic-link que você entrega ao cliente (Indicae já envia via WhatsApp por padrão). Ao abrir, o cliente cai direto na área dele dentro do /app com o link de indicação pronto para copiar.

Atualizar status do lead POST

Dispare a cada mudança de estágio do lead no funil da empresa. O referral_id é o UUID devolvido pelo webhook referral.created quando o lead foi criado.

URL do endpoint

https://fwenhjalbnlphpkdsszy.supabase.co/functions/v1/erp-referral-status

Estágios disponíveis

to_status	Significado	Campos extras
`in_service`	Lead em atendimento pela equipe comercial	—
`in_analysis`	Lead em análise / proposta enviada	—
`converted`	Negócio fechado — comissão liberada na carência	contract.external_contract_id, contract.sale_amount
`lost`	Lead perdido / descartado	—

Payload — atualização simples (in_service)

{
  "referral_id": "uuid-do-indicae",
  "external_id": "LEAD-789",
  "to_status": "in_service",
  "occurred_at": "2026-05-14T16:00:00Z",
  "notes": "Cliente respondeu o primeiro contato"
}

Payload — conversão (converted com bloco contract)

{
  "referral_id": "uuid-do-indicae",
  "external_id": "LEAD-789",
  "to_status": "converted",
  "occurred_at": "2026-05-14T18:00:00Z",
  "contract": {
    "external_contract_id": "CTR-001",
    "sale_amount": 5000
  }
}

Resposta esperada (200)

{
  "status": "ok",
  "referral_id": "8e6f0c8c-...",
  "stage": "in_service"
}

Exemplo curl

TIMESTAMP=$(date +%s)
BODY='{
  "referral_id": "uuid-do-indicae",
  "external_id": "LEAD-789",
  "to_status": "in_service",
  "occurred_at": "2026-05-14T16:00:00Z",
  "notes": "Cliente respondeu o primeiro contato"
}'
SIGNATURE=$(echo -n "$TIMESTAMP.$BODY" | openssl dgst -sha256 -hmac "$INDICAAI_HMAC_SECRET" | awk '{print $2}')

curl -X POST 'https://fwenhjalbnlphpkdsszy.supabase.co/functions/v1/erp-referral-status' \
  -H 'Content-Type: application/json' \
  -H 'X-Indicaai-Company: {SEU_SLUG}' \
  -H "X-Indicaai-Timestamp: $TIMESTAMP" \
  -H "X-Indicaai-Signature: sha256=$SIGNATURE" \
  --data-raw "$BODY"

Webhooks de saída

O Indicae envia eventos para a URL configurada no painel (Configurações → Integração → URL de webhook). Configure quais eventos deseja receber ou deixe em branco para receber todos.

Eventos disponíveis

Evento	Quando é disparado
`referral.created`	Novo lead criado a partir de uma indicação.
`referral.stage_changed`	Estágio do lead atualizado via erp-referral-status.
`referral.converted`	Lead convertido — inclui sale_amount e snapshot de comissão.
`withdrawal.paid`	Saque de comissão pago ao afiliado.

Validar a assinatura recebida

O Indicae assina cada webhook enviado com o mesmo algoritmo HMAC-SHA256. Valide o cabeçalho X-Indicaai-Signature antes de processar o payload.

Leia X-Indicaai-Timestamp e X-Indicaai-Signature dos headers.
Recalcule: sha256=hex(HMAC_SHA256(segredo, "{timestamp}.{rawBody}"))
Compare com o valor recebido (use comparação segura contra timing attacks).
Rejeite se o timestamp estiver fora de ±5 minutos.

Payload de exemplo — referral.created

{
  "event": "referral.created",
  "delivery_id": "uuid",
  "occurred_at": "2026-05-14T15:35:00Z",
  "data": {
    "referral_id": "uuid-do-indicae",
    "affiliate_id": "uuid-do-afiliado",
    "referral_code": "Dn7K2aZx",
    "lead_name": "Maria Souza",
    "lead_phone": "+5511****8888",
    "product_type": "credito",
    "stage": "received"
  }
}

O Indicae faz até 5 tentativas com backoff exponencial em caso de falha (timeout ou status ≥ 500). Retorne 200 imediatamente e processe de forma assíncrona para evitar timeouts.

Códigos de erro

Status	Nome	Descrição
200	`OK`	Requisição processada com sucesso.
400	`Bad Request`	Payload inválido ou campos obrigatórios ausentes.
401	`Unauthorized`	Assinatura HMAC inválida ou timestamp fora do intervalo.
409	`Conflict`	order_id ou external_id já processado (idempotência).
429	`Too Many Requests`	Rate limit atingido. Aguarde e tente novamente.
500	`Internal Server Error`	Erro interno no Indicae. Contate o suporte se persistir.

O corpo de erro segue o formato { error: "mensagem", code: "SNAKE_CASE" }.

Checklist de go-live

Slug da empresa e segredo HMAC configurados no painel (Configurações → Integração).
URL de webhook de saída cadastrada no painel (para receber eventos do Indicae).
Testar erp-order-confirmed com um order_id fictício e verificar retorno do welcome_url.
Confirmar recebimento do webhook referral.created ao submeter um formulário de teste.
Testar ciclo completo: erp-referral-status com to_status=converted incluindo o bloco contract.
Validar que a assinatura dos webhooks recebidos está sendo verificada no seu sistema.

Dúvidas? integracoes@indicae.club

indicae

Documentação técnica

Integração com o Indicae

Referência completa para conectar seu ERP ou sistema ao Indicae — criar afiliados, atualizar status de leads e receber webhooks de conversão.

Como funciona

A integração tem dois sentidos: seu ERP envia eventos ao Indicae (inbound) e o Indicae notifica seu ERP sobre novos leads e conversões (outbound webhooks).

1Cliente fecha pedido no ERP da empresa.
2ERP chama POST erp-order-confirmed → Indicae cria o afiliado e devolve um welcome_url (magic-link).
3Empresa entrega o welcome_url ao cliente (WhatsApp, e-mail ou SMS). O Indicae já envia via WhatsApp por padrão — você pode desativar se quiser controlar o envio.
4Cliente acessa o link e cai direto no painel dele, com o código de indicação pronto para copiar.
5Indicado preenche o formulário na LP do afiliado → lead é criado no Indicae.
6Indicae dispara o webhook referral.created para a URL configurada no painel da empresa.
7Conforme o lead avança no funil, o ERP chama erp-referral-status para atualizar o estágio. Quando converter, inclua o bloco contract para liberar a comissão.

Autenticação

Encontre suas credenciais em Painel admin → Configurações → Integração: o slug da empresa e a referência do segredo HMAC no Vault.

Headers obrigatórios em toda requisição

Content-Type: application/json
X-Indicaai-Company: seu slug (ex.: acme-financas)
X-Indicaai-Timestamp: epoch em segundos (Unix timestamp inteiro)
X-Indicaai-Signature: sha256=hex(HMAC_SHA256(segredo, "{timestamp}.{rawBody}"))

Gerar a assinatura — Node.js

import crypto from "crypto";

const secret = process.env.INDICAAI_HMAC_SECRET; // busque do seu vault/env
const timestamp = Math.floor(Date.now() / 1000).toString();
const rawBody = JSON.stringify(payload);

const signature = crypto
  .createHmac("sha256", secret)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");

// Headers para adicionar na requisição:
// X-Indicaai-Company: {SEU_SLUG}
// X-Indicaai-Timestamp: <timestamp>
// X-Indicaai-Signature: sha256=<signature>

Gerar a assinatura — Python

import hmac, hashlib, time, json

secret = os.environ["INDICAAI_HMAC_SECRET"]  # busque do seu vault/env
timestamp = str(int(time.time()))
raw_body = json.dumps(payload, separators=(",", ":"))

signature = hmac.new(
    secret.encode(),
    f"{timestamp}.{raw_body}".encode(),
    hashlib.sha256,
).hexdigest()

# Headers para adicionar na requisição:
# X-Indicaai-Company: {SEU_SLUG}
# X-Indicaai-Timestamp: <timestamp>
# X-Indicaai-Signature: sha256=<signature>

Criar afiliado POST

URL do endpoint

https://fwenhjalbnlphpkdsszy.supabase.co/functions/v1/erp-order-confirmed

affiliate_scope

Valor	Comportamento
`hub`	Afiliado pode indicar para todas as empresas ativas no hub.
`specific_products`	Afiliado só indica os produtos definidos no campo `product_ids` (array de UUIDs).

Payload de exemplo

{
  "order_id": "ORD-12345",
  "customer": {
    "cpf": "12345678900",
    "first_name": "Daniel",
    "last_name": "Almeida",
    "phone": "+5511999998888",
    "email": "daniel@example.com"
  },
  "product_type": "credito",
  "amount": 5000,
  "confirmed_at": "2026-05-14T15:32:11Z",
  "affiliate_scope": "hub"
}

Resposta esperada (200)

{
  "status": "ok",
  "affiliate_id": "8e6f0c8c-...",
  "referral_code": "Dn7K2aZx",
  "welcome_url": "https://<sub>.indicae.club/auto/<token>",
  "welcome_sent_to": "+5511****8888"
}

Exemplo curl

TIMESTAMP=$(date +%s)
BODY='{
  "order_id": "ORD-12345",
  "customer": {
    "cpf": "12345678900",
    "first_name": "Daniel",
    "last_name": "Almeida",
    "phone": "+5511999998888",
    "email": "daniel@example.com"
  },
  "product_type": "credito",
  "amount": 5000,
  "confirmed_at": "2026-05-14T15:32:11Z",
  "affiliate_scope": "hub"
}'
SIGNATURE=$(echo -n "$TIMESTAMP.$BODY" | openssl dgst -sha256 -hmac "$INDICAAI_HMAC_SECRET" | awk '{print $2}')

curl -X POST 'https://fwenhjalbnlphpkdsszy.supabase.co/functions/v1/erp-order-confirmed' \
  -H 'Content-Type: application/json' \
  -H 'X-Indicaai-Company: {SEU_SLUG}' \
  -H "X-Indicaai-Timestamp: $TIMESTAMP" \
  -H "X-Indicaai-Signature: sha256=$SIGNATURE" \
  --data-raw "$BODY"

Atualizar status do lead POST

Dispare a cada mudança de estágio do lead no funil da empresa. O referral_id é o UUID devolvido pelo webhook referral.created quando o lead foi criado.

URL do endpoint

https://fwenhjalbnlphpkdsszy.supabase.co/functions/v1/erp-referral-status

Estágios disponíveis

to_status	Significado	Campos extras
`in_service`	Lead em atendimento pela equipe comercial	—
`in_analysis`	Lead em análise / proposta enviada	—
`converted`	Negócio fechado — comissão liberada na carência	contract.external_contract_id, contract.sale_amount
`lost`	Lead perdido / descartado	—

Payload — atualização simples (in_service)

{
  "referral_id": "uuid-do-indicae",
  "external_id": "LEAD-789",
  "to_status": "in_service",
  "occurred_at": "2026-05-14T16:00:00Z",
  "notes": "Cliente respondeu o primeiro contato"
}

Payload — conversão (converted com bloco contract)

{
  "referral_id": "uuid-do-indicae",
  "external_id": "LEAD-789",
  "to_status": "converted",
  "occurred_at": "2026-05-14T18:00:00Z",
  "contract": {
    "external_contract_id": "CTR-001",
    "sale_amount": 5000
  }
}

Resposta esperada (200)

{
  "status": "ok",
  "referral_id": "8e6f0c8c-...",
  "stage": "in_service"
}

Exemplo curl

TIMESTAMP=$(date +%s)
BODY='{
  "referral_id": "uuid-do-indicae",
  "external_id": "LEAD-789",
  "to_status": "in_service",
  "occurred_at": "2026-05-14T16:00:00Z",
  "notes": "Cliente respondeu o primeiro contato"
}'
SIGNATURE=$(echo -n "$TIMESTAMP.$BODY" | openssl dgst -sha256 -hmac "$INDICAAI_HMAC_SECRET" | awk '{print $2}')

curl -X POST 'https://fwenhjalbnlphpkdsszy.supabase.co/functions/v1/erp-referral-status' \
  -H 'Content-Type: application/json' \
  -H 'X-Indicaai-Company: {SEU_SLUG}' \
  -H "X-Indicaai-Timestamp: $TIMESTAMP" \
  -H "X-Indicaai-Signature: sha256=$SIGNATURE" \
  --data-raw "$BODY"

Webhooks de saída

O Indicae envia eventos para a URL configurada no painel (Configurações → Integração → URL de webhook). Configure quais eventos deseja receber ou deixe em branco para receber todos.

Eventos disponíveis

Evento	Quando é disparado
`referral.created`	Novo lead criado a partir de uma indicação.
`referral.stage_changed`	Estágio do lead atualizado via erp-referral-status.
`referral.converted`	Lead convertido — inclui sale_amount e snapshot de comissão.
`withdrawal.paid`	Saque de comissão pago ao afiliado.

Validar a assinatura recebida

O Indicae assina cada webhook enviado com o mesmo algoritmo HMAC-SHA256. Valide o cabeçalho X-Indicaai-Signature antes de processar o payload.

Leia X-Indicaai-Timestamp e X-Indicaai-Signature dos headers.
Recalcule: sha256=hex(HMAC_SHA256(segredo, "{timestamp}.{rawBody}"))
Compare com o valor recebido (use comparação segura contra timing attacks).
Rejeite se o timestamp estiver fora de ±5 minutos.

Payload de exemplo — referral.created

{
  "event": "referral.created",
  "delivery_id": "uuid",
  "occurred_at": "2026-05-14T15:35:00Z",
  "data": {
    "referral_id": "uuid-do-indicae",
    "affiliate_id": "uuid-do-afiliado",
    "referral_code": "Dn7K2aZx",
    "lead_name": "Maria Souza",
    "lead_phone": "+5511****8888",
    "product_type": "credito",
    "stage": "received"
  }
}

O Indicae faz até 5 tentativas com backoff exponencial em caso de falha (timeout ou status ≥ 500). Retorne 200 imediatamente e processe de forma assíncrona para evitar timeouts.

Códigos de erro

Status	Nome	Descrição
200	`OK`	Requisição processada com sucesso.
400	`Bad Request`	Payload inválido ou campos obrigatórios ausentes.
401	`Unauthorized`	Assinatura HMAC inválida ou timestamp fora do intervalo.
409	`Conflict`	order_id ou external_id já processado (idempotência).
429	`Too Many Requests`	Rate limit atingido. Aguarde e tente novamente.
500	`Internal Server Error`	Erro interno no Indicae. Contate o suporte se persistir.

O corpo de erro segue o formato { error: "mensagem", code: "SNAKE_CASE" }.

Checklist de go-live

Slug da empresa e segredo HMAC configurados no painel (Configurações → Integração).
URL de webhook de saída cadastrada no painel (para receber eventos do Indicae).
Testar erp-order-confirmed com um order_id fictício e verificar retorno do welcome_url.
Confirmar recebimento do webhook referral.created ao submeter um formulário de teste.
Testar ciclo completo: erp-referral-status com to_status=converted incluindo o bloco contract.
Validar que a assinatura dos webhooks recebidos está sendo verificada no seu sistema.

Dúvidas? integracoes@indicae.club