Primeiros Passos

Versão: 1.0
Owner: Engenharia SOFIA
Última revisão: 2026
Aplicável a: Dev Integradores, Parceiros

Este guia cobre o fluxo mínimo para colocar uma integração em funcionamento.

1. Criar Conta de Parceiro

Admin:

https://admin.v1sofia.com

Checklist

• Criar conta com email e senha
• Completar cadastro PJ
• Definir partner_slug
• Confirmar que o status do parceiro está ativo

partner_slug

Define o contexto público do parceiro:

https://app.v1sofia.com/@<partner_slug>

Regras:

• minúsculas
• números e hífen permitidos
• 3–30 caracteres
• não usar nomes ambíguos

O slug é utilizado para:

• resolver links por mesa
• resolver integrações públicas
• definir contexto da UI

2. Gerar Credenciais

Existem duas camadas de credencial:

1. JWT (Bearer) – acesso à API
2. Segredos de Integração – assinatura HMAC (quando aplicável)

2.1 Login e Token

curl -X POST "https://api.v1sofia.com/api/partners/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "seu-email@dominio.com",
    "password": "SUA_SENHA"
  }'

Resposta:

{
  "token": "SUPABASE_JWT"
}

Validar sessão:

curl "https://api.v1sofia.com/api/partners/me" \
  -H "Authorization: Bearer <JWT>"

Nunca usar JWT diretamente no frontend público.

2.2 Segredos de Integração

Dependendo do modelo:

• postMessage → segredo HMAC
• Webhook → segredo de assinatura
• API Pull → JWT válido

Regras:

• armazenar em secret manager
• nunca logar
• rotacionar quando necessário

3. Ambientes

Produção:

App:    https://app.v1sofia.com
Admin:  https://admin.v1sofia.com
API:    https://api.v1sofia.com/api
WS:     https://ws.v1sofia.com

Regras:

• Não misturar sandbox com produção
• Não reutilizar tokens entre ambientes
• Manter slugs separados para teste

4. Ordem Recomendada de Teste

Etapa 1 — Validar parceiro

• Login
• /partners/me

Se falhar aqui, não avance.

Etapa 2 — Testar Iframe

1. Configurar iframe_url por mesa
2. Validar endpoint público
3. Abrir:

https://app.v1sofia.com/@<partner_slug>

Etapa 3 — Testar postMessage (Opcional)

• Habilitar no Admin
• Validar origin
• Testar evento BALANCE_UPDATE

Etapa 4 — Testar API Pull

Endpoint público:

curl "https://api.v1sofia.com/api/available-options"

Endpoint protegido:

curl "https://api.v1sofia.com/api/signals/recent?limit=20" \
  -H "Authorization: Bearer <JWT>"

Etapa 5 — Testar Webhook

• Configurar URL no Admin
• Definir segredo
• Enviar evento de teste
• Validar idempotência

5. Requisitos para Ir para Produção

Antes de considerar integração pronta:

• Validar idempotência
• Validar assinatura (quando aplicável)
• Monitorar 4xx/5xx
• Testar falha simulada
• Separar ambientes
• Documentar retenção de dados

6. Fluxo Mental Correto

Integração madura normalmente segue:

Iframe (experiência)
+
Webhook (robustez)

Ou

API Pull (enterprise)
+
Cache local

Nunca depender apenas de browser para operação crítica.