API Partner Billing Webhook (v1) - SADI Online¶

Ultima atualizacao: 24/02/2026

Este documento define o contrato oficial para consumo da integracao financeira do parceiro com a plataforma SADI Online.

1. Objetivo¶

A integracao funciona como webhook com payload fixo.

• o parceiro envia eventos financeiros para a SADI;
• a SADI processa de forma assincrona e aplica regras de acesso;
• o parceiro nao precisa aguardar resultado de negocio na resposta HTTP.

2. Endpoint unico¶

POST /v1/partner/accesses/
Content-Type: application/json
Authorization: PartnerKey <SUA_CHAVE>

3. Autenticacao e autorizacao¶

Todas as requisicoes exigem:

• Authorization: PartnerKey <SUA_CHAVE>
• escopo: partner.access.webhook

Regras:

• chave invalida, inativa ou expirada: 401 Unauthorized
• IP fora da lista permitida do parceiro: 401 Unauthorized
• escopo ausente: 403 Forbidden

4. Payload aceito¶

O payload deve seguir este formato:

{
  "name": "Joao Silva",
  "email": "joao.silva@exemplo.com",
  "phone": "5511998765432",
  "productId": "PROD-123",
  "linkId": "LNK-456",
  "productName": "Curso Mestre do CRM",
  "amount": 197.90,
  "isOrderBump": false,
  "paymentType": "credit_card",
  "orderId": "ORD-7890",
  "source": null,
  "quantity": 1,
  "document": "12345678900",
  "timestamp": "2026-02-23T14:30:00.000Z",
  "capturedDate": "2026-02-23T14:25:00.000Z",
  "createdDate": "2026-02-23T14:20:00.000Z",
  "status": "PaymentApproved",
  "leadId": "00Q5e00000ABCD123",
  "indicatorId": "a015e00000WXYZ456",
  "package": "Pacote Premium",
  "utm_source": "instagram",
  "utm_medium": "social",
  "utm_campaign": "lancamento_fev",
  "src": "bio_link"
}

Valores aceitos para status:

• PaymentApproved
• Canceled

Campos opcionais no payload:

• indicatorId
• package
• utm_source
• utm_medium
• utm_campaign
• src

5. Regras de negocio por status¶

5.1 status = PaymentApproved¶

O sistema aplica a regra em cascata:

1. se nao existe acesso para o email no parceiro:
2. cria usuario (se necessario), organizacao, membership e subscription

3. concede acesso por 12 meses

4. se existe acesso e esta bloqueado:

5. apenas reativa o acesso

6. se existe acesso, nao esta bloqueado e ja expirou:

7. renova por mais 12 meses

8. se existe acesso ativo e nao expirado:

9. mantem acesso sem estender periodo

5.2 status = Canceled¶

• bloqueia o(s) acesso(s) do usuario para o parceiro
• cancela a subscription vinculada
• desativa o usuario (is_active = false)

6. Idempotencia¶

O processamento usa idempotencia por evento:

• event_id interno: webhook:<orderId>:<status>
• repeticoes com mesmo payload e mesmo orderId/status sao deduplicadas
• reutilizacao do mesmo orderId/status com payload diferente e rejeitada no processamento

7. Resposta da API¶

A API sempre responde imediatamente com 202 Accepted quando a requisicao for aceita para fila assincrona:

{
  "success": true,
  "message": "Webhook accepted. Processing asynchronously.",
  "data": {
    "queued": true,
    "task_id": "uuid-da-task",
    "event_id": "webhook:ORD-7890:approved"
  }
}

8. Erros HTTP¶

• 400 Bad Request: payload invalido
• 401 Unauthorized: autenticacao invalida
• 403 Forbidden: escopo insuficiente
• 429 Too Many Requests: limite de taxa excedido
• 500 Internal Server Error: erro interno

9. Exemplo de envio¶

curl -X POST "https://api.sadionline.com.br/v1/partner/accesses/" \
  -H "Authorization: PartnerKey SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Joao Silva",
    "email": "joao.silva@exemplo.com",
    "phone": "5511998765432",
    "productId": "PROD-123",
    "linkId": "LNK-456",
    "productName": "Curso Mestre do CRM",
    "amount": 197.90,
    "isOrderBump": false,
    "paymentType": "credit_card",
    "orderId": "ORD-7890",
    "source": null,
    "quantity": 1,
    "document": "12345678900",
    "timestamp": "2026-02-23T14:30:00.000Z",
    "capturedDate": "2026-02-23T14:25:00.000Z",
    "createdDate": "2026-02-23T14:20:00.000Z",
    "status": "PaymentApproved",
    "leadId": "00Q5e00000ABCD123",
    "indicatorId": "a015e00000WXYZ456",
    "package": "Pacote Premium",
    "utm_source": "instagram",
    "utm_medium": "social",
    "utm_campaign": "lancamento_fev",
    "src": "bio_link"
  }'