Drivers

Drivers são as integrações disponíveis na plataforma. Cada driver representa uma conexão com um provedor externo.

Listar Drivers

GET /drivers

Lista todos os drivers disponíveis para seu tenant.

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

Parâmetros de query:

Parâmetro	Tipo	Descrição
limit	integer	Itens por página (padrão: 10, max: 100)
filter[name]	string	Filtrar por nome
filter[type]	string	Filtrar por tipo (webhook)
filter[enabled]	boolean	Filtrar por status de habilitação
sort	string	Ordenar (name, slug, version, type, status, created_at)

Resposta:

{
  "data": [
    {
      "id": "01ke7rhnt6fhb6tsbbhcdpepya",
      "name": "Digital Manager Guru",
      "slug": "digital_manager_guru",
      "description": "A Digital Manager Guru é uma plataforma completa de gestão de vendas...",
      "primary_color": "#1e90ff",
      "logo": "https://api.integracoesinteligentes.com/integrations/digital_manager_guru.svg",
      "icon": "https://api.integracoesinteligentes.com/integrations/icons/digital_manager_guru.svg",
      "version": "v1",
      "type": "webhook",
      "status": "active",
      "available_settings": {},
      "supported_events": [
        "order.paid",
        "order.canceled",
        "checkout.abandoned"
      ],
      "settings": null,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    },
    {
      "id": "01ke7rhnt6fhb6tsbbhcdpepyb",
      "name": "Bling",
      "slug": "bling",
      "description": "...",
      "primary_color": "#1e90ff",
      "logo": "https://api.integracoesinteligentes.com/integrations/bling.svg",
      "icon": "https://api.integracoesinteligentes.com/integrations/icons/bling.svg",
      "version": "v1",
      "type": "webhook",
      "status": "active",
      "available_settings": {
        "oauth_settings.redirect_url": {
          "required": true,
          "type": "url",
          "translation": "URL de redirecionamento OAuth"
        },
        "oauth_settings.client_id": {
          "required": false,
          "type": "string",
          "translation": "Client ID"
        },
        "oauth_settings.client_secret": {
          "required": false,
          "type": "string",
          "translation": "Client Secret"
        }
      },
      "supported_events": ["order.paid", "order.canceled"],
      "settings": {
        "integration_driver_slug": "bling",
        "integration_driver_version": "v1",
        "enabled": true,
        "oauth_settings": {
          "redirect_url": "https://sua-app.com/oauth/callback"
        }
      },
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-15T10:00:00.000000Z"
    }
  ],
  "links": {
    "first": "https://api.integracoesinteligentes.com/drivers?page=1",
    "last": "https://api.integracoesinteligentes.com/drivers?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api.integracoesinteligentes.com/drivers",
    "per_page": 20,
    "to": 2,
    "total": 2
  }
}

Campos do driver:

Campo	Tipo	Descrição
id	string	ID único do driver
name	string	Nome de exibição do driver
slug	string	Identificador único do driver (usado em APIs)
description	string	Descrição do driver
primary_color	string	Cor principal do driver em hexadecimal
logo	string	URL do logo do driver
icon	string	URL do ícone do driver
version	string	Versão do driver
type	string	Tipo de driver (webhook ou polling)
status	string	Status do driver (active, deprecated, disabled)
available_settings	object	Configurações disponíveis para este driver
supported_events	array	Lista de eventos suportados pelo driver
settings	object|null	Configurações atuais (null se não configurado)
created_at	string	Data de criação (ISO 8601)
updated_at	string	Data de atualização (ISO 8601)

Listar Nomes dos Drivers

GET /drivers/names

Retorna apenas os nomes e slugs (para dropdowns).

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

Resposta:

{
  "data": [
    { "name": "Bling", "slug": "bling" },
    { "name": "Digital Manager Guru", "slug": "digital_manager_guru" },
    { "name": "Hotmart", "slug": "hotmart" },
    { "name": "Shopify", "slug": "shopify" }
  ]
}

Campos da resposta:

Campo	Tipo	Descrição
name	string	Nome de exibição do driver
slug	string	Identificador único do driver

Visualizar Driver

GET /drivers/{id}

Retorna detalhes de um driver específico.

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

Resposta:

{
  "data": {
    "id": "01ke7rhnt6fhb6tsbbhcdpepya",
    "name": "Digital Manager Guru",
    "slug": "digital_manager_guru",
    "description": "A Digital Manager Guru é uma plataforma completa...",
    "primary_color": "#1e90ff",
    "logo": "https://api.integracoesinteligentes.com/integrations/digital_manager_guru.svg",
    "icon": "https://api.integracoesinteligentes.com/integrations/icons/digital_manager_guru.svg",
    "version": "v1",
    "type": "webhook",
    "status": "active",
    "available_settings": {},
    "supported_events": ["order.paid", "order.canceled", "checkout.abandoned"],
    "settings": {
      "integration_driver_slug": "digital_manager_guru",
      "integration_driver_version": "v1",
      "enabled": true
    },
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2024-01-01T00:00:00.000000Z"
  }
}

Configurar Driver Settings

Alguns drivers (como Bling) precisam de configuração antes de criar uma instalação.

GET /drivers/{id}/settings

Visualiza as configurações atuais.

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

Resposta (configurado):

{
  "data": {
    "integration_driver_slug": "bling",
    "integration_driver_version": "v1",
    "enabled": true,
    "oauth_settings": {
      "redirect_url": "https://sua-app.com/oauth/callback",
      "client_id": "seu-client-id",
      "client_secret": null
    },
    "rate_limits_settings": null,
    "enabled_at": "2024-01-15T10:00:00.000000Z",
    "integration_driver": {
      "id": "01ke7rhnt6fhb6tsbbhcdpepyb",
      "name": "Bling",
      "slug": "bling"
    }
  }
}

Campos da resposta:

Campo	Tipo	Descrição
integration_driver_slug	string	Slug do driver
integration_driver_version	string	Versão do driver
enabled	boolean	Se o driver está habilitado
oauth_settings	object	Configurações OAuth (quando aplicável)
rate_limits_settings	object|null	Configurações de rate limit
enabled_at	string|null	Data de habilitação
integration_driver	object	Dados do driver
integration_driver.id	string	ID do driver
integration_driver.name	string	Nome do driver
integration_driver.slug	string	Slug do driver

Resposta (não configurado - 404):

{
  "error": "Not found"
}

PUT /drivers/{id}/settings

Cria ou atualiza as configurações do driver.

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

Validação por driver:

Cada driver define suas próprias regras de validação. Verifique available_settings no driver para campos obrigatórios.

Exemplo: Driver com OAuth (Bling)

{
  "enabled": true,
  "oauth_settings": {
    "redirect_url": "https://sua-app.com/oauth/callback",
    "client_id": "seu-client-id",
    "client_secret": "seu-client-secret"
  }
}

Importante:

oauth_settings.redirect_url é obrigatório para drivers com OAuth.

Exemplo: Driver simples

{
  "enabled": true
}

Resposta:

{
  "data": {
    "integration_driver_slug": "bling",
    "integration_driver_version": "v1",
    "enabled": true,
    "oauth_settings": {
      "redirect_url": "https://sua-app.com/oauth/callback",
      "client_id": "seu-client-id",
      "client_secret": "seu-client-secret"
    },
    "rate_limits_settings": null,
    "enabled_at": "2024-01-15T10:00:00.000000Z",
    "created_at": "2024-01-15T10:00:00.000000Z",
    "updated_at": "2024-01-15T10:00:00.000000Z"
  }
}

Status dos Drivers

Status	Descrição
active	Driver disponível para uso
deprecated	Driver será descontinuado em breve
disabled	Driver temporariamente indisponível

Tipos de Drivers

Tipo	Descrição
webhook	Recebe events via webhooks do provedor
polling	Busca events periodicamente (em desenvolvimento)

Drivers Disponíveis

Veja a lista completa em Integrações:

• Appmax
• Assiny
• Bagy
• Bling
• Cakto
• Digital Manager Guru
• Eduzz
• FindMyPack
• Hotmart
• Irroba
• Kiwify
• Monetizze
• Pagali
• Pagarme
• Shopify
• Ticto
• Troquecommerce
• WooCommerce

Enviar Evento de Teste

POST /drivers/{id}/send-test-event

Envia um evento de teste para validar o comportamento do seu sistema ao receber eventos.

curl -X POST "https://api.integracoesinteligentes.com/drivers/01ke7rhnt6fhb6tsbbhcdpepya/send-test-event" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://sua-api.com/webhooks",
    "event_name": "order.paid"
  }'

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
webhook_url	string	Sim	URL do seu webhook (precisa ser HTTPS)
event_name	string	Sim	Nome do evento de teste disponível

Resposta (200 OK):

{
  "data": {
    "success": true,
    "checks": {
      "valid_url": {
        "result": "succeeded",
        "message": "URL é válida"
      },
      "https": {
        "result": "succeeded",
        "message": "URL usa HTTPS"
      },
      "gzip": {
        "result": "succeeded",
        "message": "Servidor aceita compressão gzip"
      },
      "timeout": {
        "result": "succeeded",
        "message": "Timeout adequado"
      },
      "post_success": {
        "result": "succeeded",
        "message": "POST retornou código 2xx"
      }
    }
  }
}

Resposta (400 - URL inválida):

{
  "data": {
    "success": false,
    "checks": {
      "valid_url": {
        "result": "succeeded",
        "message": "URL é válida"
      },
      "https": {
        "result": "failed",
        "message": "URL deve usar HTTPS"
      },
      "gzip": {
        "result": "skipped",
        "message": null
      },
      "timeout": {
        "result": "skipped",
        "message": null
      },
      "post_success": {
        "result": "skipped",
        "message": null
      }
    }
  }
}

Valores possíveis para result:

Valor	Descrição
succeeded	Teste passou
failed	Teste falhou
skipped	Teste não executado

Próximos Passos

• Installations - Criar instalações
• Setup OAuth - Configurar OAuth
• Configurar Integração - Guia completo