Pular para o conteúdo
Integrações Inteligentes

Configuração OAuth

Alguns drivers (como Bling) requerem autorização OAuth 2.0 antes de começar a receber events. Este guia explica o fluxo completo.

Quando é Necessário OAuth?

O OAuth é necessário quando a resposta de criação da instalação retorna:

{
  "data": {
    "id": "0192abcd-1234-5678-9abc-def012345678",
    ...
  },
  "needs_setup": true,
  "setup_type": "oauth",
  "setup_data": {
    "oauth_authorization_url": "https://..."
  }
}

Visão Geral do Fluxo

sequenceDiagram
    participant User as Usuário
    participant YourApp as Sua Aplicação
    participant II as Integrações Inteligentes
    participant Provider as Provedor (ex: Bling)

    User->>YourApp: Clicar em "Conectar"
    YourApp->>II: POST /installations
    II-->>YourApp: needs_setup: true<br>oauth_authorization_url
    YourApp->>User: Redirecionar para oauth_authorization_url
    User->>Provider: Login & Autorização
    Provider->>II: Callback com Authorization Code
    II->>Provider: Exchange Code → Access Token
    II-->>YourApp: Redirect para redirect_url
    YourApp->>II: GET /installations/{id}
    II-->>YourApp: needs_setup: false ✓

Configuração Inicial

1. Configurar Driver Settings

Antes de criar a instalação, configure o redirect_url:

Terminal window
curl -X PUT "https://api.integracoesinteligentes.com/drivers/{driver_id}/settings" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "oauth_settings": {
      "redirect_url": "https://sua-app.com/oauth/callback"
    }
  }'

Importante:

O redirect_url é obrigatório para drivers OAuth. A API redirecionará o navegador para esta URL após completar o OAuth.

2. Criar instalação

Terminal window
curl -X POST https://api.integracoesinteligentes.com/installations \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_driver_id": "01ke7rhnt6fhb6tsbbhcdpepyb",
    "description": "Minha conta Bling",
    "processing_method": "complete"
  }'

Resposta:

{
  "data": {
    "id": "0192abcd-1234-5678-9abc-def012345678",
    "description": "Minha conta Bling",
    "integration_driver_id": "01ke7rhnt6fhb6tsbbhcdpepyb",
    ...
  },
  "needs_setup": true,
  "setup_type": "oauth",
  "setup_data": {
    "oauth_authorization_url": "https://bling.com.br/Api/v3/oauth/authorize?client_id=...&state=...&redirect_uri=..."
  }
}

Fluxo de Autorização

3. Redirecionar Usuário

Abra oauth_authorization_url no navegador do usuário:

// Frontend JavaScript
const response = await fetch("/api/create-installation", { method: "POST" });
const data = await response.json();


if (data.needs_setup && data.setup_type === "oauth") {
  // Abre popup ou redireciona
  window.location.href = data.setup_data.oauth_authorization_url;
}

Ou para popup:

const popup = window.open(
  data.setup_data.oauth_authorization_url,
  "oauth",
  "width=600,height=700",
);

4. Callback e Redirecionamento

Após o usuário autorizar no provedor:

  1. O provedor redireciona para a API: GET /installations/oauth?state=...&code=...
  2. A API troca o code por access token
  3. A API redireciona o navegador para sua URL configurada:
https://sua-app.com/oauth/callback?installation_id=0192abcd-...&oauth_succeeded=true

Ou em caso de erro:

https://sua-app.com/oauth/callback?installation_id=0192abcd-...&oauth_succeeded=false&oauth_failed_reason=<reason>

Motivos de Falha OAuth

Quando oauth_succeeded=false, um parâmetro oauth_failed_reason pode estar presente:

ReasonDescrição
invalid_oauth_codeO código de autorização estava ausente ou vazio
account_not_foundNão foi possível recuperar o ID da conta do provedor
account_connected_to_other_installationJá existe uma instalação conectada a esta conta do provedor
unknown_exceptionErro inesperado durante o setup

Exemplo de redirect com falha:

https://sua-app.com/oauth/callback?installation_id=0192abcd-...&oauth_succeeded=false&oauth_failed_reason=account_not_found

5. Verificar Status

Após o callback, verifique se o setup foi concluído:

Terminal window
curl -X GET "https://api.integracoesinteligentes.com/installations/0192abcd-..." \
  -H "Authorization: Bearer <seu-token>"

Resposta de sucesso:

{
  "data": {
    "id": "0192abcd-1234-5678-9abc-def012345678",
    ...
  },
  "needs_setup": false
}

Implementação Completa (Exemplo)

Backend (Node.js/Express)

// Criar installation
app.post("/api/installations", async (req, res) => {
  const response = await fetch(
    "https://api.integracoesinteligentes.com/installations",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${req.session.apiToken}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        integration_driver_id: req.body.driverId,
        description: req.body.description,
        processing_method: "complete",
      }),
    },
  );


  const data = await response.json();


  if (data.needs_setup && data.setup_type === "oauth") {
    // Armazena installation_id na sessão
    req.session.pendingInstallationId = data.data.id;


    return res.json({
      needsSetup: true,
      authorizationUrl: data.setup_data.oauth_authorization_url,
    });
  }


  res.json({ installation: data.data });
});


// Callback OAuth
app.get("/oauth/callback", (req, res) => {
  const { installation_id, oauth_succeeded } = req.query;


  if (oauth_succeeded === "true") {
    // Limpa sessão
    delete req.session.pendingInstallationId;


    // Redireciona para sucesso
    res.redirect("/integrations?status=connected");
  } else {
    res.redirect("/integrations?status=error");
  }
});

Frontend (React)

function ConnectIntegration({ driverId }) {
  const [loading, setLoading] = useState(false);


  const handleConnect = async () => {
    setLoading(true);


    try {
      const response = await fetch("/api/installations", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ driverId, description: "Minha conta" }),
      });


      const data = await response.json();


      if (data.needsSetup) {
        // Abre popup para OAuth
        const popup = window.open(
          data.authorizationUrl,
          "oauth",
          "width=600,height=700",
        );


        // Monitora quando o popup fecha
        const checkClosed = setInterval(() => {
          if (popup.closed) {
            clearInterval(checkClosed);
            // Recarrega lista de installations
            window.location.reload();
          }
        }, 500);
      } else {
        // Conectado sem OAuth
        window.location.reload();
      }
    } catch (error) {
      console.error("Erro:", error);
    } finally {
      setLoading(false);
    }
  };


  return (
    <button onClick={handleConnect} disabled={loading}>
      {loading ? "Conectando..." : "Conectar"}
    </button>
  );
}

Scopes de Permissão

Cada provedor define seus próprios scopes. Geralmente você precisa de:

  • Bling: produtos, pedidos, estoques, vendas
  • Verifique a documentação específica de cada provedor

Tokens e Renovação

Access Token

  • Obtido automaticamente após o OAuth
  • Armazenado de forma segura pela plataforma
  • Nunca exposto na API

Refresh Token

  • Usado para renovar access tokens expirados
  • Processo automático (agendado a cada 5 minutos)
  • Você não precisa gerenciar manualmente

Drivers que Usam OAuth

Atualmente, os seguintes drivers requerem OAuth:

DriverURL de Autorização
BlingBling OAuth 2.0

Verifique sempre a resposta da API (needs_setup) para saber se é necessário.

Próximos Passos