Configurar Integração

Uma Instalação é a conexão entre seu tenant e um Driver específico. Este guia mostra como configurar do início ao fim.

Pré-requisitos

Antes de criar uma Instalação, você precisa:

1. ✅ Criar conta e token API
2. ✅ Configurar Webhook URL
3. ✅ Conhecer o integration_driver_id do driver desejado

Fluxo de Configuração

flowchart TD
    A[Listar Drivers] --> B{Precisa de Settings?}
    B -->|Sim| C[Habilitar Driver]
    B -->|Não| D[Criar Instalação]
    C --> D
    D --> E{Precisa de Setup?}
    E -->|Sim| F[Completar Setup]
    E -->|Não| G[Pronto!]
    F --> G

1. Listar Drivers Disponíveis

Veja quais integrações estão ativas para seu tenant:

GET /drivers

curl -X GET "https://api.integracoesinteligentes.com/drivers?limit=20" \
  -H "Authorization: Bearer <seu-token>"

Para detalhes completos (parâmetros, filtros, resposta), consulte GET /drivers.

2. Verificar Driver Settings

Alguns drivers exigem configuração prévia. Verifique em:

GET /drivers/{id}/settings

curl -X GET "https://api.integracoesinteligentes.com/drivers/01ke7rhnt6fhb6tsbbhcdpepyb/settings" \
  -H "Authorization: Bearer <seu-token>"

Para detalhes completos, consulte GET /drivers/{id}/settings.

3. Configurar Driver Settings (se necessário)

Se o driver exigir configuração, use:

PUT /drivers/{id}/settings

Exemplo: Driver com OAuth (Bling)

curl -X PUT "https://api.integracoesinteligentes.com/drivers/01ke7rhnt6fhb6tsbbhcdpepyb/settings" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "oauth_settings": {
      "redirect_url": "https://sua-app.com/oauth/callback",
      "client_id": "seu-client-id-do-bling",
      "client_secret": "seu-client-secret-do-bling"
    }
  }'

Exemplo: Driver simples (sem OAuth)

curl -X PUT "https://api.integracoesinteligentes.com/drivers/01ke7rhnt6fhb6tsbbhcdpepya/settings" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

Nota:

O campo oauth_settings.redirect_url é obrigatório para drivers com OAuth. Os campos client_id e client_secret são opcionais e podem ser configurados posteriormente.

Para detalhes completos (parâmetros, resposta), consulte PUT /drivers/{id}/settings.

4. Criar Instalação

POST /installations

curl -X POST https://api.integracoesinteligentes.com/installations \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
    "description": "Minha loja Digital Manager Guru",
    "processing_method": "complete",
    "new_events_enabled": true
  }'

Parâmetros:

Campo	Tipo	Obrigatório	Padrão	Descrição
integration_driver_id	UUID	Sim	—	ID do driver
description	string	Não	null	Nome descritivo da instalação
processing_method	string	Não	"complete"	Ver nota abaixo
new_events_enabled	boolean	Não	false	Habilita automaticamente eventos novos do driver

Nota: processing_method: "complete" (padrão) aguarda o sucesso do polyfill; "real_time" entrega imediatamente, mesmo com dados incompletos se o polyfill falhar.

Para detalhes completos (parâmetros, resposta), consulte POST /installations.

Importante:

Se needs_setup for true, veja a seção Setup Adicional abaixo.

5. Gerenciar Eventos

Ao criar uma instalação, todos os eventos suportados pelo driver são habilitados automaticamente. Você pode ajustar quais deseja receber.

PUT /installations/{id}

curl -X PUT "https://api.integracoesinteligentes.com/installations/0192abcd-1234-5678-9abc-def012345678" \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled_events": {
      "order.paid": true,
      "order.canceled": true,
      "checkout.abandoned": false
    }
  }'

Nota: Somente eventos já existentes no driver podem ser atualizados. Eventos inválidos retornarão erro 422.

Para detalhes completos, consulte PUT /installations/{id}.

6. Verificar Status

GET /installations/{id}

curl -X GET "https://api.integracoesinteligentes.com/installations/0192abcd-1234-5678-9abc-def012345678" \
  -H "Authorization: Bearer <seu-token>"

Para detalhes completos, consulte GET /installations/{id}.

Configuração Adicional

Se needs_setup: true na criação da instalação, você precisa completar a configuração antes de começar a receber eventos.

Tipo: OAuth

Quando setup_type: "oauth":

{
  "data": {
    "id": "0192abcd-1234-5678-9abc-def012345678",
    ...
  },
  "needs_setup": true,
  "setup_type": "oauth",
  "setup_data": {
    "oauth_authorization_url": "https://bling.com.br/oauth/authorize?client_id=...&state=..."
  }
}

Próximos passos:

1. Redirecione o usuário para setup_data.oauth_authorization_url
2. O usuário autoriza no provedor
3. O provedor redireciona para o callback da API
4. A API redireciona para sua redirect_url configurada

Veja detalhes em Setup OAuth.

Métodos de Processamento

complete (padrão)

O evento só é gerado e enviado após o polyfill (busca de dados adicionais) ter sucesso. Se o polyfill falhar, o sistema retenta até conseguir obter todos os dados.

• Vantagem: Garante eventos com todos os dados disponíveis
• Desvantagem: Pode haver delay até o polyfill ser bem-sucedido
• Use quando: Precisa de dados completos

real_time

O evento é gerado imediatamente. Se o polyfill funcionar de primeira, o evento terá dados completos. Se o polyfill falhar, o evento é gerado mesmo assim, mas com dados incompletos.

• Vantagem: Entrega imediata, sem esperar o polyfill
• Desvantagem: Eventos podem ter dados incompletos se o polyfill falhar
• Use quando: Precisa de velocidade e pode trabalhar com dados parciais

Atenção:

No modo real_time, campos que dependeriam do polyfill podem vir nulos se a busca de dados adicionais falhar.

Gerenciar Eventos

Novos Eventos Automaticamente

• new_events_enabled: true: Quando o driver adicionar novos tipos de eventos, eles serão automaticamente criados e habilitados na sua instalação
• new_events_enabled: false (padrão): Eventos novos serão criados, mas desabilitados na sua instalação

Desabilitar Eventos

Para parar de receber um evento específico:

curl -X PUT "https://api.integracoesinteligentes.com/installations/0192abcd-..." \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled_events": {
      "checkout.abandoned": false
    }
  }'

Atualizar Instalação

PUT /installations/{id}

curl -X PUT "https://api.integracoesinteligentes.com/installations/0192abcd-..." \
  -H "Authorization: Bearer <seu-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Loja Digital Manager Guru - Principal",
    "processing_method": "real_time"
  }'

Campos atualizáveis:

• description
• processing_method
• new_events_enabled
• enabled_events

Remover Instalação

DELETE /installations/{id}

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

Resposta (204 No Content):

Sem corpo na resposta.

Atenção:

A remoção é lógica (soft delete). Os eventos já processados permanecem disponíveis por 30 dias.

Para detalhes completos, consulte DELETE /installations/{id}.

Listar Todas as Instalações

GET /installations

curl -X GET "https://api.integracoesinteligentes.com/installations?limit=20" \
  -H "Authorization: Bearer <seu-token>"

Para detalhes completos (parâmetros, filtros, resposta), consulte GET /installations.

Próximos Passos

• Setup OAuth - Para drivers que precisam de OAuth
• Receber Eventos - Como processar eventos
• Estrutura dos Eventos - Conheça todos os tipos
• API de Drivers - Documentação completa
• API de Installations - Documentação completa