Pular para o conteúdo
Integrações Inteligentes

Primeiros Passos

Bem-vindo à plataforma Integrações Inteligentes. Este guia vai te ajudar a começar em minutos até o recebimento do primeiro evento.

Visão Geral do Fluxo

flowchart LR
    A[Token API] --> B[Webhook URL]
    B --> C[Driver Settings]
    C --> D[Criar instalação]
    D --> E[Habilitar Events]
    E --> F[Receber Webhooks]

1. Pré-requisitos

Antes de começar, você precisa:

Obter Token de API

Acesse o Dashboard e gere um token de API para autenticação.

Nota:

Tokens de API não expiram e são ideais para integrações de produção. Guarde-o em segurança.

Autenticação

A API usa autenticação Bearer Token. Inclua o token no header de todas as requisições:

Authorization: Bearer <seu-token>

2. Configurar Webhook URL

Antes de criar instalações, você precisa configurar o endpoint que vai receber os eventos.

PUT /me/tenant/webhook_url

Terminal window
curl -X PUT https://api.integracoesinteligentes.com/me/tenant/webhook_url \
  -H "Authorization: Bearer <token-api>" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://sua-api.com/webhooks/integracoes"
  }'

Importante:

A URL deve:

  • Usar HTTPS
  • Não ser localhost ou IPs privados
  • Aceitar requisições com Content-Encoding: gzip
  • Responder em até 10 segundos
  • Retornar HTTP 2xx para sucesso

Veja mais detalhes em Configurar Webhook URL.

3. Listar Drivers Disponíveis

Veja quais integrações estão disponíveis:

GET /drivers

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

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": 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"
        }
      },
      "supported_events": ["order.paid", "order.canceled"],
      "settings": null,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-15T10:00:00.000000Z"
    }
  ]
}

Para detalhes dos campos, consulte GET /drivers.

4. Habilitar Driver

Antes de criar uma instalação, você precisa habilitar o driver. Todos os drivers requerem habilitação, mas alguns precisam de configurações adicionais.

Quando você consulta um driver (no passo anterior), o campo available_settings mostra quais configurações estão disponíveis e quais são obrigatórias:

Exemplo - Driver sem configurações extras (Digital Manager Guru):

{
  "available_settings": {}
}

Neste caso, basta habilitar com:

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

Exemplo - Driver com configurações obrigatórias (Bling):

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

Quando há campos required: true, você deve configurá-los:

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

Importante:

Se você tentar criar uma instalação sem habilitar o driver primeiro, receberá um erro 422 informando que o driver não possui configuração.

5. Criar Instalação

Uma Instalação é a conexão entre seu tenant e um driver específico.

POST /installations

Terminal window
curl -X POST https://api.integracoesinteligentes.com/installations \
  -H "Authorization: Bearer <token-api>" \
  -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:

CampoTipoObrigatórioPadrãoDescrição
integration_driver_idUUIDSim—ID do driver
descriptionstringNãonullNome descritivo
processing_methodenumNão"complete"Ver nota abaixo
new_events_enabledbooleanNãofalseHabilita 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.

Resposta (201 Created):

{
  "data": {
    "id": "0192abcd-1234-5678-9abc-def012345678",
    "description": "Minha loja Digital Manager Guru",
    "integration_driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
    "processing_method": "complete",
    "new_events_enabled": true,
    "enabled_events": {
      "order.paid": true,
      "order.canceled": true,
      "checkout.abandoned": true
    },
    "created_at": "2024-01-15T10:45:00.000000Z"
  },
  "needs_setup": false
}

Para detalhes dos campos, consulte POST /installations.

Nota:

Se needs_setup for true e setup_type for oauth, você precisará completar o fluxo OAuth. Veja Setup OAuth.

6. Configurar Eventos

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

Desabilitar Eventos Específicos

Para parar de receber um evento específico:

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

7. Receber Seu Primeiro Evento

Agora é só aguardar! Quando um evento ocorrer na plataforma integrada, você receberá um webhook no endpoint configurado.

Estrutura do payload recebido:

CampoDescrição
idID único do evento
installation_idID da instalação que recebeu o evento
integration_driver_slugDriver que gerou o evento
nameNome do evento (ex: order.paid)
created_atTimestamp de criação
payloadDados do evento (varia por driver)
supersededSe foi substituído por evento de maior peso
webhook_dispatched_atTimestamp de envio

Para exemplos detalhados de payloads por driver, consulte Estrutura dos Eventos.

Próximos Passos

Dicas Importantes

  1. Idempotência: Processe eventos baseado no campo id. Eventos podem ser enviados múltiplas vezes em caso de falhas.

  2. Sequência de Eventos: O campo superseded indica quando eventos chegam fora de ordem (ex: order.paid antes de order.waiting_payment). Isso sinaliza inconsistência na sequência, não substituição do evento.

  3. Timeout: Responda aos webhooks em até 10 segundos com HTTP 2xx.

  4. Compressão: O body é enviado comprimido com gzip (Content-Encoding: gzip).

  5. Retry: Falhas são re-tentadas automaticamente com backoff: 5s, 15s, 30s, 60s, 120s.