Fluxo de Provisionamento

O processo de conectar um cliente começa na sua aplicação chamando nossa API. O retorno dita o próximo passo (Webhook simples ou OAuth flow).

O “Handshake” da Integração

Este diagrama ilustra o fluxo completo desde a solicitação inicial até a ativação da instalação.

sequenceDiagram
    autonumber
    participant User as End User
    participant SaaS as Your SaaS App
    participant API as Integr. Inteligentes
    participant Provider as 3rd Party (e.g., Shopify)

    Note over SaaS, API: 1. Solicitação de Instalação
    SaaS->>API: POST /installations/create<br/>{driver_id, name, meta}
    API-->>SaaS: JSON Response<br/>{ method: "oauth", auth_url: "..." }

    Note over User, Provider: 2. Fluxo de Autorização (OAuth)
    SaaS->>User: Redirect to auth_url
    User->>Provider: Login & Approve Permissions
    Provider->>API: Callback with Auth Code
    API->>Provider: Exchange Code for Access Token

    Note over API, SaaS: 3. Confirmação
    API-->>SaaS: Webhook: installation.active<br/>(OR Redirect back to SaaS)

Nota: Para drivers baseados em API Key, o passo 2 é ignorado e a instalação é ativada imediatamente após a validação da chave.

Detalhes do Processo

1. Solicitação de Instalação (Request)

Sua aplicação envia um comando para iniciar o processo.

POST /api/v1/installations

{
  "driver_id": "shopify",
  "name": "Loja do Pedro",
  "meta": {
    "internal_id": "123456" // Seu ID interno para correlação futura
  }
}

2. Autorização (Response & Redirect)

A API responde indicando que é necessária autorização OAuth.

{
  "id": "inst_8abf9...",
  "status": "pending_auth",
  "auth_url": "https://shopify.com/oauth/authorize?client_id=...&redirect_uri=..."
}

Seu frontend deve redirecionar o usuário para auth_url.

3. Confirmação (Webhook Payload)

Após o usuário autorizar, nossa plataforma recebe o callback, troca os tokens e ativa a instalação. Enviaremos um webhook para você confirmar:

Event: installation.updated

{
  "event": "installation.updated",
  "payload": {
    "id": "inst_8abf9...",
    "status": "active",
    "meta": {
      "internal_id": "123456"
    }
  }
}