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.

Nota: Este endpoint não requer permissões específicas.

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...",
      "version": "v1",
      "type": "webhook",
      "available_settings": {},
      "supported_events": [
        "order.paid",
        "order.canceled",
        "checkout.abandoned"
      ],
      "enabled": false,
      "enabled_at": null,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    },
    {
      "id": "01ke7rhnt6fhb6tsbbhcdpepyb",
      "name": "Bling",
      "slug": "bling",
      "description": "Integração com a plataforma Bling para gestão de vendas.",
      "version": "v1",
      "type": "webhook",
      "available_settings": {
        "custom_oauth_enabled": {
          "required": false,
          "type": "boolean"
        },
        "oauth_settings.redirect_url": {
          "required": true,
          "type": "url"
        },
        "oauth_settings.custom_oauth.client_id": {
          "required_if": "custom_oauth_enabled,true",
          "type": "string"
        },
        "oauth_settings.custom_oauth.client_secret": {
          "required_if": "custom_oauth_enabled,true",
          "type": "string"
        }
      },
      "supported_events": ["order.paid", "order.canceled"],
      "enabled": true,
      "enabled_at": "2024-01-15T10:00:00.000000Z",
      "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
version	string	Versão do driver
type	string	Tipo de driver (webhook ou polling)
available_settings	object	Configurações disponíveis para este driver
supported_events	array	Lista de eventos suportados pelo driver
enabled	boolean	Se o driver está habilitado para este tenant
enabled_at	string|null	Data de habilitação do driver
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).

Nota: Este endpoint não requer permissões específicas.

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.

Nota: Este endpoint não requer permissões específicas.

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 de gestão de vendas...",
    "version": "v1",
    "type": "webhook",
    "available_settings": {},
    "supported_events": ["order.paid", "order.canceled", "checkout.abandoned"],
    "enabled": false,
    "enabled_at": null,
    "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.

Permissões necessárias

Permissão	Descrição
DRIVERS_MANAGE	Visualizar configurações de drivers

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

Resposta (configurado):

{
  "data": {
    "enabled": true,
    "custom_oauth_enabled": false,
    "custom_oauth_enabled_at": null,
    "custom_oauth_can_be_edited": true,
    "oauth_settings": {
      "redirect_url": "https://sua-app.com/oauth/callback",
      "custom_oauth": []
    },
    "enabled_at": "2024-01-15T10:00:00.000000Z",
    "created_at": "2024-01-15T10:00:00.000000Z",
    "updated_at": "2024-01-15T10:00:00.000000Z",
    "driver": {
      "id": "01ke7rhnt6fhb6tsbbhcdpepyb",
      "name": "Bling",
      "slug": "bling"
    }
  }
}

Campos da resposta:

Campo	Tipo	Descrição
enabled	boolean	Se o driver está habilitado
custom_oauth_enabled	boolean	Se OAuth customizado está habilitado para este driver
custom_oauth_enabled_at	string|null	Data de habilitação do OAuth customizado
custom_oauth_can_be_edited	boolean	Se o OAuth customizado pode ser editado
oauth_settings	object	Configurações OAuth (quando aplicável)
oauth_settings.redirect_url	string	URL de redirecionamento OAuth
oauth_settings.custom_oauth	array	Configurações de OAuth customizado (quando custom_oauth_enabled=true)
oauth_settings.custom_oauth.client_id	string	Client ID customizado (quando custom_oauth_enabled=true)
oauth_settings.custom_oauth.client_secret	string	Client Secret customizado (quando custom_oauth_enabled=true)
enabled_at	string|null	Data de habilitação
created_at	string	Data de criação
updated_at	string	Data de atualização
driver	object	Dados do driver
driver.id	string	ID do driver
driver.name	string	Nome do driver
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.

Permissões necessárias

Permissão	Descrição
DRIVERS_MANAGE	Gerenciar configurações de drivers

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"
    }
  }'

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
enabled	boolean	Não	Se o driver está habilitado
custom_oauth_enabled	boolean	Não	Habilita OAuth customizado para este driver

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"
  }
}

Driver com OAuth customizado:

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

Importante:

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

custom_oauth_enabled só está disponível para drivers específicos que suportam OAuth customizado.

Uma vez que uma instalação é criada usando o driver, custom_oauth_enabled e oauth_settings.custom_oauth não podem mais ser alterados.

Exemplo: Driver simples

{
  "enabled": true
}

Resposta:

{
  "data": {
    "enabled": true,
    "custom_oauth_enabled": false,
    "custom_oauth_enabled_at": null,
    "custom_oauth_can_be_edited": true,
    "oauth_settings": {
      "redirect_url": "https://sua-app.com/oauth/callback",
      "custom_oauth": []
    },
    "enabled_at": "2024-01-15T10:00:00.000000Z",
    "created_at": "2024-01-15T10:00:00.000000Z",
    "updated_at": "2024-01-15T10:00:00.000000Z",
    "driver": {
      "id": "01ke7rhnt6fhb6tsbbhcdpepyb",
      "name": "Bling",
      "slug": "bling"
    }
  }
}

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.

Permissões necessárias

Permissão	Descrição
DRIVERS_MANAGE	Enviar eventos de teste

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