Hub de Integração CourtexID

Padrões e Convenções Globais

Para garantir a previsibilidade na integração, adotamos padrões estritos em toda a nossa superfície de API e troca de arquivos.

Política de Versionamento

Estrutura de Versionamento

Utilizamos versionamento semântico com três componentes principais:

Segurança e Autenticação

A segurança é "First-Class Citizen" na CourtexID. Utilizamos Bearer Tokens opacos com alta entropia para autenticação.

Authorization: Bearer sk_live_51MxPq2LkY7hM8nJ9... [256-bit hash]
Content-Type: application/json
Accept: application/json
X-API-Version: 2024-12-27
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Arquitetura de Segurança

Nossa arquitetura de segurança implementa múltiplas camadas de proteção:

{
  "refresh_token": "rt_live_7x9y8z...",
  "grant_type": "refresh_token"
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "rt_live_n3w_r3fr3sh_t0k3n",
  "scope": "audits:read products:read"
}

Segurança de Rede (IP Whitelisting)

Para clientes Enterprise, oferecemos a funcionalidade de IP Whitelisting. Você pode restringir o uso das suas API Keys a um conjunto específico de endereços IP estáticos ou faixas CIDR.

Objeto: Audit (Varejo Físico)

Este é o objeto central da plataforma. Ele encapsula a verdade de campo ("ground truth") coletada por nossos agentes.

{
  "id": "aud_7s8x9y0z",
  "store_context": {
    "cnpj": "12.345.678/0001-90",
    "name": "Supermercado Central",
    "channel": "Hipermercado",
    "geo": {
      "lat": -23.5505,
      "lng": -46.6333
    }
  },
  "metrics": {
    "osa": 0.95,
    "sos": 0.28,
    "price_compliance": 0.98
  },
  "collected_at": "2025-12-27T14:30:00Z",
  "agent_id": "agt_12345",
  "validation": {
    "gps_delta": 12,
    "photo_match_score": 0.96
  }
}

Endpoint: Listar Auditorias

curl -G https://api.courtex.id/v1/audits \
  -d "status=completed" \
  -d "created[gte]=2025-01-01T00:00:00Z" \
  -d "expand[]=store_context" \
  -H "Authorization: Bearer sk_live_..."

import requests

headers = {
    "Authorization": "Bearer sk_live_...",
    "Accept": "application/json"
}

params = {
    "status": "completed",
    "created[gte]": "2025-01-01T00:00:00Z",
    "expand[]": ["store_context"]
}

response = requests.get(
    "https://api.courtex.id/v1/audits",
    headers=headers,
    params=params
)

const audits = await courtex.audits.list({
  status: 'completed',
  created: { gte: '2025-01-01T00:00:00Z' },
  expand: ['store_context']
});

Webhooks & Event-Driven Architecture

Nossa infraestrutura de webhooks permite que você construa reações em tempo real com latência subsegundo.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
    const hmac = crypto.createHmac('sha256', secret);
    const computedSignature = `sha256=${hmac.update(payload).digest('hex')}`;
    
    // Comparação de tempo constante para evitar timing attacks
    return crypto.timingSafeEqual(
        Buffer.from(computedSignature),
        Buffer.from(signature)
    );
}

// Exemplo de uso
const isValid = verifyWebhookSignature(
    req.rawBody,
    req.headers['x-courtex-signature'],
    process.env.WEBHOOK_SECRET
);

Engenharia de Dados: Ingestão via SFTP

Para cargas de dados massivas (Data Warehousing, ML Training), oferecemos um pipeline de dados gerenciado via SFTP.

Host: sftp.data.courtex.id
Porta: 2222
Autenticação: Chave SSH RSA 4096-bit
Protocolo: SFTP v3
Conexões Máximas: 10 simultâneas
Transferência: Até 1 Gbps dedicado
Timeout: 300 segundos
Compressão: Opcional (gzip)

/
├── inbound/                  # Seus arquivos de entrada
│   └── catalog_updates/     # Atualizações de catálogo
│       └── tenant_id=ACME/
│           └── date=2025-12-27/
│               └── products.csv
│
├── outbound/                # Nossos arquivos processados
│   ├── audits/              # Dados de auditoria
│   │   └── tenant_id=ACME/
│   │       └── year=2025/month=12/day=27/
│   │           ├── part-00000.snappy.parquet
│   │           └── _SUCCESS
│   │
│   └── digital_insights/    # Insights digitais
│       └── tenant_id=ACME/
│           └── year=2025/month=12/day=27/
│               └── pricing_data.jsonl.gz
│
└── logs/                    # Logs de processamento
    ├── success/             # Processamentos bem-sucedidos
    └── errors/              # Erros com detalhes para debug

Níveis de Serviço (SLAs) e Suporte

Clientes Enterprise possuem acesso a níveis de serviço garantidos contratualmente com suporte 24/7.