Documentação da API v1

Visão Geral

A API do Indica Nóis permite que você automatize a gestão de indicações, sincronize dados com seu CRM de vendas e realize pagamentos em lote via PIX.

Todos os endpoints retornam JSON e seguem os padrões REST. Para requisições que enviam dados (POST), inclua sempre o header Content-Type: application/json.

Plano Necessário: A API está disponível para assinantes dos planos Plus e PRO.

Autenticação

As requisições devem ser autenticadas via header X-API-Key. Você pode gerar suas chaves no painel em Integração API → API Keys.

Exemplo de requisição

curl https://app.indicanois.com.br/api/v1/data/campaigns \
  -H "X-API-Key: in_live_sua_chave_aqui"

Escopos (Scopes)

Escopo	Acesso Permitido
`read:data`	Acesso a todos os endpoints `GET /v1/data/*`
`write:actions`	Acesso a todos os endpoints `POST /v1/actions/*`

Rate Limit

Os limites são aplicados por conta (tenant), independentemente do número de chaves utilizadas.

Tipo de Endpoint	Limite
Leitura (GET)	300 requisições / minuto
Ações (POST)	30 requisições / minuto

Caso o limite seja excedido, você receberá um erro 429 Too Many Requests. Verifique os headers X-RateLimit-Remaining e X-RateLimit-Reset para controle.

Paginação

Endpoints que retornam listas utilizam paginação baseada em cursor para garantir performance e consistência dos dados.

GET /v1/data/referrals?after=ref_01jqa...&limit=50

Parâmetro	Tipo	Default	Máximo
`after`	string	-	-
`limit`	number	50	200

O campo next_cursor na resposta deve ser passado no parâmetro after da próxima requisição até que has_more seja false.

Idempotência

Para evitar operações duplicadas (como criar duas indicações para o mesmo cliente devido a um timeout de rede), utilizamos o header Idempotency-Key.

Se você enviar a mesma chave novamente em um intervalo de 24h, retornaremos a resposta original sem processar a operação novamente.

Endpoint	Idempotency-Key
`POST /v1/actions/referrals`	Obrigatório
`POST /v1/actions/referrals/:id/convert`	Obrigatório
Outros POSTs	Opcional

Erros

Utilizamos códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição.

{
  "error": "indicação_já_existente",
  "message": "Este CPF já foi indicado para esta campanha recentemente."
}

Status	Significado
400	Bad Request — Requisição malformada
401	Unauthorized — Chave de API inválida
403	Forbidden — Sem permissão para o recurso
404	Not Found — Recurso não encontrado
422	Unprocessable — Erro de validação de dados

Endpoints de Dados (GET)

GET /v1/data/campaigns

Retorna a lista de campanhas disponíveis no seu painel.

Response (200 OK)

{
  "data": [
    {
      "id": "cp_01jqa",
      "name": "Indica Fibra 500",
      "status": "active",
      "reward_type": "pix",
      "created_at": "2026-03-20T10:00:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

GET /v1/data/referrals

Lista todas as indicações recebidas. Filtre por status para identificar quais precisam ser convertidas.

GET /v1/data/participants

Retorna os indicadores ativos. O campo custom_data contém as informações extras capturadas.

Endpoints de Ação (POST)

POST /v1/actions/referrals

Cria uma indicação vinda de um sistema externo (ex: seu site oficial ou landing page própria).

Request Body

{
  "campaign_id": "cp_01jqa",
  "referrer_id": "part_982",
  "referred_name": "Cliente Exemplo",
  "referred_email": "exemplo@email.com",
  "referred_phone": "11988887777"
}

POST /v1/actions/referrals/:id/convert

Confirma que a indicação foi concretizada. Este é o gatilho principal para a geração da recompensa.

Webhooks de Saída

Configure uma URL no painel para receber notificações em tempo real sempre que uma indicação for criada ou convertida.

Cada requisição inclui um header X-Webhook-Signature gerado via HMAC-SHA256 com sua chave secreta para verificação de integridade.

Suporte Técnico

Precisa de ajuda com a integração? Nossa equipe de engenharia está à disposição.

E-mail

suporte@indicanois.com.br

WhatsApp

Falar com Desenvolvedor