REST API v2.1

API Reference

A referência completa para integrar dados, pessoas e decisões ao SYNQi³.

Nesta seção você encontra todos os endpoints, payloads, modelos, erros, limites e exemplos necessários para integrar sua aplicação ao ecossistema SYNQi³.

Base URL: https://api.synqi3.aiFormato: JSONAuth: Bearer Token

1. Conceitos Fundamentais

1.1 Base da plataforma

O SYNQi³ funciona com quatro pilares principais:

Eventos: tudo o que acontece (cliques, compras, interações)
Métricas: tudo o que importa (KPIs, trends, anomalias)
Pessoas: tudo o que muda (perfis, comportamentos, sinais)
Regras: tudo o que decide (automações, triggers, ações)

A API permite que você envie dados, consuma análises e execute decisões automatizadas.

1.2 Headers obrigatórios

Toda requisição exige:

Authorization: Bearer <api_token>
Content-Type: application/json
X-Request-ID: <optional-unique-id>

Tokens são gerados em Configurações → Integrações → API Tokens. O X-Request-ID é opcional mas recomendado para debugging.

2. Autenticação

POST/auth/token

Gera ou renova tokens de sessão

curl -X POST https://api.synqi3.ai/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-secret"
  }'

Resposta

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_abc123..."
}

Segurança

Nunca exponha client_secret no frontend. Use backend-to-backend para autenticação e apenas o access_token no cliente.

3. Eventos API

POST/api/events

Envia qualquer tipo de evento

Eventos são a base da plataforma. Cada ação, comportamento, clique, atualização ou mudança deve ser enviada para que o SYNQi³ gere insights e decisões.

curl -X POST https://api.synqi3.ai/api/events \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "purchase_completed",
    "user_id": "94821",
    "timestamp": 1698952921,
    "properties": {
      "amount": 199.90,
      "payment_method": "credit_card",
      "product_ids": ["prod_123", "prod_456"]
    }
  }'

Resposta

{
  "status": "ok",
  "event_id": "evt_abc123",
  "received_at": 1698952925
}

Campos do evento

event: Nome do evento (obrigatório)
user_id: ID do usuário
anonymous_id: ID anônimo
timestamp: Unix timestamp
properties: Dados adicionais

4. Métricas API

Consulte métricas calculadas automaticamente a partir dos eventos, incluindo tendências e detecção de anomalias.

GET/api/metrics/{metricId}

Retorna valor atual, tendência e anomalias

GET/api/metrics

Lista todas as métricas disponíveis

POST/api/metrics/query

Consulta personalizada de métricas agregadas

# Buscar métrica específica
curl -X GET "https://api.synqi3.ai/api/metrics/daily_revenue" \
  -H "Authorization: Bearer <token>"

# Query personalizada
curl -X POST "https://api.synqi3.ai/api/metrics/query" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["daily_revenue", "active_users"],
    "period": "7d",
    "granularity": "day"
  }'

Resposta

{
  "metric_id": "daily_revenue",
  "value": 19231.55,
  "trend": 0.14,
  "anomaly": false,
  "anomaly_score": 0.23,
  "compared_to": {
    "yesterday": 0.08,
    "last_week": 0.22,
    "last_month": 0.31
  },
  "time_series": [
    { "timestamp": 1698866521, "value": 17500.00 },
    { "timestamp": 1698952921, "value": 19231.55 }
  ]
}

5. Pessoas API

Acesse perfis unificados de usuários com sinais comportamentais, personas e histórico de interações.

GET/api/people/{userId}

Retorna o perfil unificado do usuário

POST/api/people/identify

Associa dados ao perfil do usuário

POST/api/people/search

Busca por critérios comportamentais

# Buscar perfil de usuário
curl -X GET "https://api.synqi3.ai/api/people/94821" \
  -H "Authorization: Bearer <token>"

# Identificar usuário com traits
curl -X POST "https://api.synqi3.ai/api/people/identify" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "94821",
    "traits": {
      "name": "João Silva",
      "email": "joao@email.com",
      "plan": "pro"
    }
  }'

Resposta

{
  "user_id": "94821",
  "traits": {
    "name": "João Silva",
    "email": "joao@email.com",
    "plan": "pro"
  },
  "personas": ["early_adopter", "high_intent"],
  "signals": {
    "risk": 0.02,
    "interest": 0.91,
    "fatigue": 0.14,
    "churn_probability": 0.05
  },
  "last_seen": 1698952921,
  "total_events": 156,
  "last_events": [...]
}

6. Regras API

Crie regras autônomas que disparam ações automaticamente com base em eventos, métricas ou comportamentos.

POST/api/rules

Cria uma regra autônoma

GET/api/rules/{ruleId}

Retorna regra com estado e histórico

PUT/api/rules/{ruleId}

Atualiza uma regra existente

POST/api/rules/dry-run

Simula regra sem executar

curl -X POST https://api.synqi3.ai/api/rules \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alertar queda de receita",
    "description": "Dispara quando receita diária cai abaixo do limite",
    "trigger": {
      "type": "metric",
      "metric": "daily_revenue",
      "condition": "drop_below",
      "value": 5000
    },
    "actions": [
      {
        "type": "webhook",
        "url": "https://myserver.com/alert"
      },
      {
        "type": "email",
        "to": "team@empresa.com"
      }
    ],
    "enabled": true
  }'

Tipos de trigger

metric

Baseado em valores de métricas

event

Quando um evento específico ocorre

signal

Quando sinais de usuário mudam

schedule

Execução em horário específico

7. Assistente API

O assistente unifica toda a inteligência do SYNQi³ em uma interface conversacional. Pergunte sobre métricas, usuários, anomalias e receba insights acionáveis.

POST/api/assistant/chat

Envia mensagem + contexto

GET/api/assistant/history

Retorna histórico de conversas

POST/api/assistant/feedback

Envia feedback sobre resposta

curl -X POST https://api.synqi3.ai/api/assistant/chat \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Quais métricas caíram hoje?",
    "context": {
      "focus": "metrics",
      "period": "today"
    },
    "conversation_id": "conv_abc123"
  }'

Resposta

{
  "reply": "A métrica 'daily_revenue' caiu 12% em relação a ontem, passando de R$ 21.850 para R$ 19.231. Isso está fora do padrão normal para esta época.",
  "conversation_id": "conv_abc123",
  "insights": [
    {
      "type": "anomaly",
      "metric": "daily_revenue",
      "severity": "medium",
      "description": "Queda de 12% detectada"
    }
  ],
  "suggested_rules": [
    {
      "name": "Alerta de queda de receita",
      "trigger": { "metric": "daily_revenue", "condition": "drop_percent", "value": 10 }
    }
  ],
  "sources": ["metrics", "anomaly_detector"]
}

8. Webhooks

Configure webhooks para receber notificações em tempo real sobre eventos importantes na sua aplicação.

Tipos de webhook

rule_executed

Regra foi disparada

anomaly_detected

Anomalia detectada em métrica

insight_generated

Novo insight gerado

user_signal_changed

Sinal de usuário alterado

Formato do payload

{
  "id": "wh_evt_abc123",
  "type": "rule_executed",
  "timestamp": 1698952921,
  "rule_id": "rule_xyz",
  "payload": {
    "metric": "daily_revenue",
    "value": 4850.00,
    "threshold": 5000,
    "affected_users": ["user_123", "user_456"]
  },
  "signature": "sha256=abc123..."
}

Verificação de assinatura

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Sempre verifique a assinatura do webhook usando o header X-Signature para garantir autenticidade.

Retry automático

Webhooks que falham (status != 2xx) são reenviados automaticamente com backoff exponencial: 1 min, 5 min, 30 min, 2 horas, 24 horas.

9. Base de Documentos (RAG)

Faça upload de documentos para criar uma base de conhecimento que alimenta o assistente de IA.

POST/api/documents

Envia PDFs e textos para indexação

GET/api/documents/{id}

Retorna status da indexação + tokens processados

DELETE/api/documents/{id}

Remove documento e suas embeddings

Formatos suportados

PDFDOCXTXTHTMLMDCSV

# 1. Obter URL de upload
curl -X POST https://api.synqi3.ai/api/documents/presign \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"filename": "manual.pdf", "content_type": "application/pdf"}'

# 2. Upload para S3
curl -X PUT "<presigned_url>" \
  -H "Content-Type: application/pdf" \
  --data-binary @manual.pdf

# 3. Iniciar processamento
curl -X POST https://api.synqi3.ai/api/documents \
  -H "Authorization: Bearer <token>" \
  -d '{"s3_key": "<key_from_presign>", "title": "Manual do Produto"}'

10. SDKs Oficiais

Use nossos SDKs para integração mais rápida e segura. Disponíveis para JavaScript/TypeScript e Python.

JavaScript SDK

npm install @synqi3/sdk

import { SYNQi3 } from '@synqi3/sdk';

const synqi3 = new SYNQi3({
  apiKey: 'your-api-key'
});

// Tracking de eventos
synqi3.track('page_view', {
  page: '/products',
  user_id: '12345'
});

Python SDK

pip install synqi3

from synqi3 import SYNQi3

client = SYNQi3(api_key='your-api-key')

# Tracking de eventos
client.track(
    event='page_view',
    user_id='12345',
    properties={'page': '/products'}
)

Recursos dos SDKs

Tipagem completa (TypeScript)
Retry automático com backoff
Batching automático de eventos
Validação de payload

11. Rate Limits

Para garantir estabilidade e performance, a API possui limites de requisições por plano.

Endpoint	Starter	Pro	Enterprise
/api/events	1.000/min	10.000/min	Ilimitado
/api/metrics	100/min	1.000/min	10.000/min
/api/assistant	20/min	100/min	500/min
/api/documents	10/hora	100/hora	1.000/hora

Headers de Rate Limit

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1698953521

Quando o limite é excedido, a API retorna 429 Too Many Requests.

12. Limites e Boas Práticas

Evitar

Enviar métricas que podem ser derivadas de eventos
Payloads maiores que 1MB por requisição
Polling frequente (use webhooks)
Expor API keys no frontend

Limites de Payload

Evento único

256 KB

Batch de eventos

1 MB

Documento

50 MB

Resposta API

10 MB

13. Mensagens de Erro

Formato padrão de erro

{
  "error": {
    "code": "invalid_payload",
    "message": "Campo 'event' é obrigatório.",
    "details": {
      "field": "event",
      "received": null,
      "expected": "string"
    },
    "request_id": "req_abc123"
  }
}

Códigos HTTP

400bad_requestPayload inválido ou campos obrigatórios ausentes

401unauthorizedToken ausente ou inválido

403forbiddenSem permissão para o recurso solicitado

404not_foundRecurso não encontrado

429rate_limit_exceededLimite de requisições excedido

500internal_errorErro interno do servidor

Tratamento recomendado

try {
  const response = await synqi3.events.track({ ... });
} catch (error) {
  if (error.code === 'rate_limit_exceeded') {
    // Aguardar e tentar novamente
    await sleep(error.retryAfter * 1000);
    return retry();
  }
  if (error.code === 'unauthorized') {
    // Renovar token
    await refreshToken();
    return retry();
  }
  // Log e notificação
  console.error(`API Error: ${error.code} - ${error.message}`);
}

14. Changelog

v2.1.0Latest14 Jan 2026

+Novo endpoint /api/assistant/chat
+SDKs oficiais para JavaScript e Python
~Melhorias na detecção de anomalias
~Webhooks com retry automático

v2.0.0Major01 Dez 2025

+Lançamento da API v2 com nova arquitetura
+Endpoints de Pessoas e Regras
+Sistema de autenticação JWT
!Breaking: Nova estrutura de payloads

v1.5.015 Set 2025

+Suporte a documentos RAG
~Performance de queries melhorada em 40%

API Reference

1. Conceitos Fundamentais

1.1 Base da plataforma

1.2 Headers obrigatórios

2. Autenticação

Resposta

Segurança

3. Eventos API

Resposta

Campos do evento

4. Métricas API

Resposta

5. Pessoas API

Resposta

6. Regras API

Tipos de trigger

7. Assistente API

Resposta

8. Webhooks

Tipos de webhook

Formato do payload

Verificação de assinatura

Retry automático

9. Base de Documentos (RAG)

Formatos suportados

10. SDKs Oficiais

JavaScript SDK

Python SDK

Recursos dos SDKs

11. Rate Limits

Headers de Rate Limit

12. Limites e Boas Práticas

Recomendado

Evitar

Limites de Payload

13. Mensagens de Erro

Formato padrão de erro

Códigos HTTP

Tratamento recomendado

14. Changelog