API de Integração

📋 Visão Geral

A API do ÁlibiApp permite que você integre seu ERP ou sistema externo com nosso sistema de fidelidade, enviando pontos automaticamente para seus clientes baseado em suas vendas.

⚡

Rápido

Respostas em menos de 200ms

🔒

Seguro

Autenticação via Bearer Token

📚

Simples

Documentação completa e exemplos

Base URL da API

Use esta URL como base para todas as suas requisições

https://painel.alibi.app.br/api/integration

ℹ️

Configuração de Limites

A quantidade máxima de pontos por envio é configurável nos Parâmetros do Sistema. Acesse Configurações > Parâmetros para ajustar o limite conforme sua necessidade.

🔐 Autenticação

Nossa API usa autenticação via Bearer Token. Você precisa gerar um token de API nas configurações da sua conta.

Como obter o token:

Faça login na sua conta do ÁlibiApp
Acesse Configurações no menu superior
Na seção "Token de API para Integrações", clique em "Criar Token de Integração"
Copie o token exibido (ele só aparece uma vez!)
Salve o token em local seguro

Como usar o token:

Inclua o token no header Authorization de todas as requisições:

Authorization: Bearer SEU_TOKEN_AQUI

🚀 Endpoints

🔗

Base URL:

https://painel.alibi.app.br/api/integration

POST


                                    /points

Endpoint completo:


                                https://painel.alibi.app.br/api/integration/points

Envia pontos de fidelidade para um cliente específico.

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
phone	string	✅ Sim	Número de telefone do cliente
points	integer	❌ Não	Quantidade de pontos (padrão: 1, máximo configurável nos parâmetros do sistema)

Exemplo de Requisição:

{
  "phone": "11999999999",
  "points": 3
}

Resposta de Sucesso (200):

{
  "success": true,
  "message": "Pontos enviados com sucesso para 11999999999"
}

Resposta de Erro (400):

{
  "success": false,
  "message": "Conta não possui assinatura ativa"
}

Exemplos de Código

Selecione uma linguagem para ver um exemplo no endpoint /api/integration/points.

POST


                                    /points/from-value

Endpoint completo:


                                https://painel.alibi.app.br/api/integration/points/from-value

Envia pontos calculados a partir do valor de uma venda (baseado na regra ativa da conta).

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
phone	string	✅ Sim	Número de telefone do cliente
sale_value	number	✅ Sim	Valor da venda (ex.: 29.90)

Exemplo de Requisição:

{
  "phone": "11999999999",
  "sale_value": 123.45
}

Resposta de Sucesso (200):

{
  "success": true,
  "message": "Pontos enviados com sucesso para 11999999999"
}

Resposta de Erro (400):

{
  "success": false,
  "message": "Nenhuma regra de conversão ativa encontrada para esta conta."
}

Exemplos de Código

Selecione uma linguagem para ver um exemplo no endpoint /api/integration/points/from-value.

⚖️ Validações e Limites

Limites de Pontos

O sistema possui validações automáticas para garantir a integridade dos dados e limites de negócio:

📊

Limite Máximo de Pontos

Configurável nos Parâmetros do Sistema (Configurações > Parâmetros). O valor padrão é definido pelo parâmetro qtd-points-send.

🔒

Limite por Requisição

O máximo de pontos por requisição segue o parâmetro qtd-points-send configurado no sistema (Configurações > Parâmetros).

📱

Validação de Telefone

Número deve conter apenas dígitos e ter formato válido (mínimo 10 dígitos).

💳

Limite de Cartões Ativos

Respeitado o limite do plano de assinatura da conta.

Importante

Todas as validações retornam erro 400 (Bad Request) com mensagem descritiva quando não atendidas.

💻 Exemplos de Integração

Use os endpoints /points e /points/from-value para enviar dados e calcular os pontos pela regra ativa. Os exemplos por linguagem aparecem dentro dos cards dos endpoints acima.

1) Enviar pontos diretamente (`/points`)

Exemplo de requisição para enviar pontos no endpoint /api/integration/points.


$token = 'SEU_TOKEN_AQUI';
$baseUrl = "https://painel.alibi.app.br/api/integration";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/points');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'phone' => '11999999999',
    'points' => 3
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
if (is_array($data)) {
    echo json_encode($data, JSON_PRETTY_PRINT);
} else {
    echo $response;
}

const token = 'SEU_TOKEN_AQUI';
const baseUrl = "https://painel.alibi.app.br/api/integration";

async function sendPoints(phone, points = 1) {
  const response = await fetch(`${baseUrl}/points`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ phone, points })
  });

  const data = await response.json();
  console.log(data?.message || 'Erro na resposta da API');
}

// Exemplo
sendPoints('11999999999', 3); // envia 3 pontos

import requests

token = 'SEU_TOKEN_AQUI'
base_url = "https://painel.alibi.app.br/api/integration"

def send_points(phone, points=1):
    url = f"{base_url}/points"
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {token}'
    }
    payload = {'phone': phone, 'points': points}

    response = requests.post(url, json=payload, headers=headers)
    data = response.json()
    print(data.get('message', 'Erro na resposta da API'))

send_points('11999999999', 3)  # envia 3 pontos

require 'net/http'
require 'uri'
require 'json'

token = 'SEU_TOKEN_AQUI'
baseUrl = "https://painel.alibi.app.br/api/integration"
url = baseUrl + '/points'

uri = URI(url)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = (uri.scheme == 'https')

payload = { phone: '11999999999', points: 3 }.to_json

req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['Authorization'] = "Bearer #{token}"
req.body = payload

res = http.request(req)

begin
  puts JSON.pretty_generate(JSON.parse(res.body))
rescue
  puts res.body
end

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class SendPoints {
  public static void main(String[] args) throws Exception {
    String token = "SEU_TOKEN_AQUI";
    String baseUrl = "https://painel.alibi.app.br/api/integration";
    String url = baseUrl + "/points";

    String payload = "{\"phone\":\"11999999999\",\"points\":3}";

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create(url))
      .header("Content-Type", "application/json")
      .header("Authorization", "Bearer " + token)
      .POST(HttpRequest.BodyPublishers.ofString(payload))
      .build();

    HttpClient client = HttpClient.newHttpClient();
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }
}

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
)

type Payload struct {
  Phone  string `json:"phone"`
  Points int    `json:"points"`
}

func main() {
  token := "SEU_TOKEN_AQUI"
  baseUrl := "https://painel.alibi.app.br/api/integration"
  url := baseUrl + "/points"

  payload := Payload{Phone: "11999999999", Points: 3}
  body, err := json.Marshal(payload)
  if err != nil {
    panic(err)
  }

  req, err := http.NewRequest("POST", url, bytes.NewBuffer(body))
  if err != nil {
    panic(err)
  }
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("Authorization", "Bearer " + token)

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  raw, _ := io.ReadAll(resp.Body)
  fmt.Println(string(raw))
}

curl -X POST https://painel.alibi.app.br/api/integration/points \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "11999999999",
    "points": 3
  }'

2) Enviar por valor (`/points/from-value`)

Neste caso, a API converte o sale_value usando a regra ativa da conta (mesma lógica do Dashboard).

Exemplo de requisição para enviar sale_value no endpoint /api/integration/points/from-value.


$token = 'SEU_TOKEN_AQUI';
$baseUrl = "https://painel.alibi.app.br/api/integration";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/points/from-value');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'phone' => '11999999999',
    'sale_value' => 123.45
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
if (is_array($data)) {
    echo json_encode($data, JSON_PRETTY_PRINT);
} else {
    echo $response;
}

const token = 'SEU_TOKEN_AQUI';
const baseUrl = "https://painel.alibi.app.br/api/integration";

async function sendPointsFromValue(phone, saleValue) {
  const response = await fetch(`${baseUrl}/points/from-value`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ phone, sale_value: saleValue })
  });

  const data = await response.json();
  console.log(data?.message || 'Erro na resposta da API');
}

// Exemplo
sendPointsFromValue('11999999999', 123.45);

import requests

token = 'SEU_TOKEN_AQUI'
base_url = "https://painel.alibi.app.br/api/integration"

def send_points_from_value(phone, sale_value):
    url = f"{base_url}/points/from-value"
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {token}'
    }
    payload = {'phone': phone, 'sale_value': sale_value}

    response = requests.post(url, json=payload, headers=headers)
    data = response.json()
    print(data.get('message', 'Erro na resposta da API'))

send_points_from_value('11999999999', 123.45)

require 'net/http'
require 'uri'
require 'json'

token = 'SEU_TOKEN_AQUI'
baseUrl = "https://painel.alibi.app.br/api/integration"
url = baseUrl + '/points/from-value'

uri = URI(url)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = (uri.scheme == 'https')

payload = { phone: '11999999999', sale_value: 123.45 }.to_json

req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['Authorization'] = "Bearer #{token}"
req.body = payload

res = http.request(req)

begin
  puts JSON.pretty_generate(JSON.parse(res.body))
rescue
  puts res.body
end

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class SendPointsFromValue {
  public static void main(String[] args) throws Exception {
    String token = "SEU_TOKEN_AQUI";
    String baseUrl = "https://painel.alibi.app.br/api/integration";
    String url = baseUrl + "/points/from-value";

    String payload = "{\"phone\":\"11999999999\",\"sale_value\":123.45}";

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create(url))
      .header("Content-Type", "application/json")
      .header("Authorization", "Bearer " + token)
      .POST(HttpRequest.BodyPublishers.ofString(payload))
      .build();

    HttpClient client = HttpClient.newHttpClient();
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }
}

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
)

type Payload struct {
  Phone     string  `json:"phone"`
  SaleValue float64 `json:"sale_value"`
}

func main() {
  token := "SEU_TOKEN_AQUI"
  baseUrl := "https://painel.alibi.app.br/api/integration"
  url := baseUrl + "/points/from-value"

  payload := Payload{Phone: "11999999999", SaleValue: 123.45}
  body, err := json.Marshal(payload)
  if err != nil {
    panic(err)
  }

  req, err := http.NewRequest("POST", url, bytes.NewBuffer(body))
  if err != nil {
    panic(err)
  }
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("Authorization", "Bearer " + token)

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  raw, _ := io.ReadAll(resp.Body)
  fmt.Println(string(raw))
}

curl -X POST https://painel.alibi.app.br/api/integration/points/from-value \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "11999999999",
    "sale_value": 123.45
  }'

❌ Códigos de Erro

Código	Descrição	Possíveis Causas
400	Bad Request	Dados inválidos, conta sem assinatura, limite de cartões atingido, pontos excedem limite configurado
401	Unauthorized	Token inválido, expirado ou ausente
422	Unprocessable Entity	Dados de validação incorretos (telefone inválido, pontos inválidos)
500	Internal Server Error	Erro interno do servidor

✨ Funcionalidades

🤖

Automação Completa

Cria usuários e cartões automaticamente quando necessário

📱

Notificações

Envia SMS e push notifications automaticamente

🔒

Segurança

Validações completas e logs de auditoria

⚡

Performance

Processamento assíncrono e respostas rápidas

📊

Relatórios

Acompanhe o uso da API nas configurações

🔄

Consistência

Mesma lógica do dashboard, garantindo consistência

🆘 Suporte

💬

Precisa de ajuda?

Nossa equipe está pronta para ajudar você a integrar sua API.

📧 Enviar Email 🎫 Central de Suporte