Instalações

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

Listar Instalações

GET /installations

Lista todas as instalações do tenant.

Permissões necessárias

Permissão	Descrição
`INSTALLATIONS_VIEW`	Visualizar instalações

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

Parâmetros de query:

Parâmetro	Tipo	Descrição
`limit`	integer	Itens por página (padrão: 10)
`filter[search]`	string	Busca por ID ou descrição
`filter[driver]`	string	Filtrar por slug do driver
`sort`	string	Ordenar (`id`, `created_at`, `updated_at`, `description`)

Resposta:

{
  "data": [
    {
      "id": "0192abcd-1234-5678-9abc-def012345678",
      "driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
      "migration_id": null,
      "description": "Minha loja Digital Manager Guru",
      "connection_settings": null,
      "processing_method": "complete",
      "new_events_enabled": true,
      "new_events_enabled_at": "2024-01-15T10:45:00.000000Z",
      "out_of_sequence_enabled": false,
      "out_of_sequence_enabled_at": null,
      "ingestion_url": "https://api.integracoesinteligentes.com/ingestion/0192abcd-...",
      "created_at": "2024-01-15T10:45:00.000000Z",
      "updated_at": "2024-01-15T10:45:00.000000Z",
      "driver": {
        "id": "01ke7rhnt6fhb6tsbbhcdpepya",
        "name": "Digital Manager Guru",
        "slug": "digital_manager_guru"
      },
      "enabled_events": {
        "order.paid": true,
        "order.canceled": true,
        "checkout.abandoned": false
      }
    }
  ]
}

Campos da resposta:

Campo	Tipo	Descrição
`id`	UUID	ID único da instalação
`driver_id`	string	ID do driver
`migration_id`	UUID\|null	ID da migration (se migração)
`description`	string\|null	Nome descritivo da instalação
`connection_settings`	object\|null	Configurações de conexão
`processing_method`	string	Método de processamento (`complete` ou `real_time`)
`new_events_enabled`	boolean	Se novos eventos são habilitados automaticamente
`new_events_enabled_at`	string\|null	Data de habilitação de novos eventos
`out_of_sequence_enabled`	boolean	Se eventos fora de ordem são enviados ao tenant
`out_of_sequence_enabled_at`	string\|null	Data de habilitação de eventos fora de ordem
`ingestion_url`	string\|null	URL de ingestão do webhook
`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
`enabled_events`	object	Mapa de eventos habilitados

Criar Instalação

POST /installations

Cria uma nova instalação.

Permissões necessárias

Permissão	Descrição
`INSTALLATIONS_MANAGE`	Criar instalações

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

Parâmetros:

Campo	Tipo	Obrigatório	Padrão	Descrição
`driver_id`	UUID	Sim	—	ID do driver
`description`	string	Não	`null`	Nome descritivo
`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.

Resposta (201 Created):

{
  "data": {
    "id": "0192abcd-1234-5678-9abc-def012345678",
    "driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
    "migration_id": null,
    "description": "Minha loja",
    "connection_settings": null,
    "processing_method": "complete",
    "new_events_enabled": true,
    "new_events_enabled_at": "2024-01-15T10:45:00.000000Z",
    "out_of_sequence_enabled": false,
    "out_of_sequence_enabled_at": null,
    "ingestion_url": "https://api.integracoesinteligentes.com/ingestion/0192abcd-...",
    "created_at": "2024-01-15T10:45:00.000000Z",
    "updated_at": "2024-01-15T10:45:00.000000Z",
    "driver": {
      "id": "01ke7rhnt6fhb6tsbbhcdpepya",
      "name": "Digital Manager Guru",
      "slug": "digital_manager_guru"
    },
    "enabled_events": {
      "order.paid": false,
      "order.canceled": false,
      "checkout.abandoned": false
    }
  },
  "needs_setup": false
}

Campos da resposta:

Campo	Tipo	Descrição
`id`	UUID	ID único da instalação criada
`driver_id`	string	ID do driver
`migration_id`	UUID\|null	ID da migration (se migração)
`description`	string\|null	Nome descritivo
`connection_settings`	object\|null	Configurações de conexão
`processing_method`	string	Método de processamento
`new_events_enabled`	boolean	Se novos eventos são habilitados automaticamente
`new_events_enabled_at`	string\|null	Data de habilitação de novos eventos
`out_of_sequence_enabled`	boolean	Se eventos fora de ordem são enviados ao tenant
`out_of_sequence_enabled_at`	string\|null	Data de habilitação de eventos fora de ordem
`ingestion_url`	string\|null	URL de ingestão do webhook
`created_at`	string	Data de criação
`updated_at`	string	Data de atualização
`driver`	object	Dados do driver
`enabled_events`	object	Mapa de eventos habilitados

Campos adicionais no nível raiz:

Campo	Tipo	Descrição
`needs_setup`	boolean	Se há configuração adicional necessária
`setup_type`	string	Tipo de setup necessário (`oauth`)
`setup_data`	object	Dados necessários para o setup

Com setup OAuth necessário:

{
  "data": {
    /* ... */
  },
  "needs_setup": true,
  "setup_type": "oauth",
  "setup_data": {
    "oauth_authorization_url": "https://..."
  }
}

Visualizar Instalação

GET /installations/{id}

Retorna detalhes de uma instalação.

Permissões necessárias

Permissão	Descrição
`INSTALLATIONS_VIEW`	Visualizar instalações

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

Resposta:

{
  "data": {
    "id": "0192abcd-1234-5678-9abc-def012345678",
    "driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
    "migration_id": null,
    "description": "Minha loja",
    "connection_settings": null,
    "processing_method": "complete",
    "new_events_enabled": true,
    "new_events_enabled_at": "2024-01-15T10:45:00.000000Z",
    "out_of_sequence_enabled": false,
    "out_of_sequence_enabled_at": null,
    "ingestion_url": "https://api.integracoesinteligentes.com/ingestion/0192abcd-...",
    "created_at": "2024-01-15T10:45:00.000000Z",
    "updated_at": "2024-01-15T10:45:00.000000Z",
    "driver": {
      "id": "01ke7rhnt6fhb6tsbbhcdpepya",
      "name": "Digital Manager Guru",
      "slug": "digital_manager_guru"
    },
    "enabled_events": {
      "order.paid": true,
      "order.canceled": true
    }
  },
  "needs_setup": false
}

Campos da resposta:

Campo	Tipo	Descrição
`id`	UUID	ID único da instalação
`driver_id`	string	ID do driver
`migration_id`	UUID\|null	ID da migration (se migração)
`description`	string\|null	Nome descritivo
`connection_settings`	object\|null	Configurações de conexão
`processing_method`	string	Método de processamento
`new_events_enabled`	boolean	Se novos eventos são habilitados automaticamente
`new_events_enabled_at`	string\|null	Data de habilitação de novos eventos
`out_of_sequence_enabled`	boolean	Se eventos fora de ordem são enviados ao tenant
`out_of_sequence_enabled_at`	string\|null	Data de habilitação de eventos fora de ordem
`ingestion_url`	string\|null	URL de ingestão do webhook
`created_at`	string	Data de criação
`updated_at`	string	Data de atualização
`driver`	object	Dados do driver
`enabled_events`	object	Mapa de eventos habilitados
`needs_setup`	boolean	Se há configuração adicional necessária

Atualizar Instalação

PUT /installations/{id}

Atualiza uma instalação existente.

Permissões necessárias

Permissão	Descrição
`INSTALLATIONS_MANAGE`	Atualizar instalações

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

Campos atualizáveis:

Campo	Tipo	Descrição
`description`	string	Novo nome descritivo
`processing_method`	string	Alterar método de processamento
`new_events_enabled`	boolean	Habilitar novos eventos automaticamente
`out_of_sequence_enabled`	boolean	Habilitar envio de eventos fora de ordem
`enabled_events`	object	Mapa de eventos e status

Nota:

No enabled_events, apenas eventos existentes podem ser atualizados. Eventos inválidos retornam erro 422.

Resposta (200 OK):

{
  "data": {
    "id": "0192abcd-1234-5678-9abc-def012345678",
    "driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
    "migration_id": null,
    "description": "Loja Digital Manager Guru - Principal",
    "processing_method": "real_time",
    "new_events_enabled": true,
    "new_events_enabled_at": "2024-01-15T10:45:00.000000Z",
    "out_of_sequence_enabled": false,
    "out_of_sequence_enabled_at": null,
    "ingestion_url": "https://api.integracoesinteligentes.com/ingestion/0192abcd-...",
    "created_at": "2024-01-15T10:45:00.000000Z",
    "updated_at": "2024-01-15T11:00:00.000000Z",
    "driver": {
      "id": "01ke7rhnt6fhb6tsbbhcdpepya",
      "name": "Digital Manager Guru",
      "slug": "digital_manager_guru"
    },
    "enabled_events": {
      "order.paid": true,
      "order.canceled": true,
      "checkout.abandoned": true
    }
  }
}

Remover Instalação

DELETE /installations/{id}

Remove uma instalação (soft delete).

Permissões necessárias

Permissão	Descrição
`INSTALLATIONS_MANAGE`	Excluir instalações

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

Resposta (204 No Content):

Sem corpo na resposta.

Atenção:

Instalações removidas ficam indisponíveis imediatamente. Eventos já processados permanecem por 30 dias.

Métodos de Processamento

`complete` (padrão)

O evento só é gerado e enviado após o polyfill ter sucesso. O sistema retenta até obter todos os dados.

Vantagem: Eventos sempre com dados completos
Desvantagem: Pode haver delay até o polyfill ser bem-sucedido
Recomendado: Para a maioria dos casos

`real_time`

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

Vantagem: Entrega imediata
Desvantagem: Dados podem estar incompletos se o polyfill falhar
Use quando: Velocidade é mais importante que dados completos

Eventos Habilitados

Estrutura do enabled_events

{
  "enabled_events": {
    "order.paid": true,
    "order.canceled": true,
    "order.refunded": false,
    "checkout.abandoned": true
  }
}

Eventos são desabilitados por padrão. Você deve habilitar explicitamente cada um.

Novos Eventos Automaticamente

Valor	Comportamento
`true`	Eventos novos são criados e habilitados automaticamente
`false` (padrão)	Eventos novos são criados desabilitados

Eventos Fora de Ordem (Out of Sequence)

Quando um evento chega depois de um evento que deveria ter chegado antes (ex: order.waiting_payment chega depois de order.paid), o evento que chegou fora de ordem (order.waiting_payment neste caso) é marcado como superseded.

Campo	Descrição
`out_of_sequence_enabled`	Se eventos fora de ordem são enviados ao tenant
`out_of_sequence_enabled_at`	Data em que o envio de eventos fora de ordem foi habilitado

Por padrão, eventos fora de ordem não são enviados ao tenant. Para recebê-los, defina out_of_sequence_enabled: true na atualização da instalação.

Fluxo OAuth

Quando needs_setup: true e setup_type: "oauth":

Redirecione o usuário para oauth_authorization_url
Usuário autoriza no provedor
Provedor redireciona para callback da API
API completa setup e redireciona para seu redirect_url

Motivos de Falha OAuth

Quando o OAuth falha, o redirect inclui oauth_failed_reason:

Reason	Descrição
`invalid_oauth_code`	O código de autorização estava ausente ou vazio
`account_not_found`	Não foi possível recuperar o ID da conta do provedor
`account_connected_to_other_installation`	Já existe uma instalação conectada a esta conta do provedor
`unknown_exception`	Erro inesperado durante o setup

Veja Setup OAuth para detalhes completos.

Callback OAuth

GET /installations/oauth

Endpoint público para callback OAuth.

Nota:

Este endpoint é chamado pelo navegador durante o fluxo OAuth, não requer autenticação da API.

Query Parameters:

state - State da installation
code - Authorization code (sucesso)
error - Mensagem de erro (falha)

Redirecionamento final:

https://sua-app.com/oauth/callback?installation_id=...&oauth_succeeded=true

Ou em caso de erro:

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

Migrations

Migrations permitem migrar instalações existentes de um driver para outro.

GET /migrations

Lista todas as migrations do tenant.

Permissões necessárias

Permissão	Descrição
`INSTALLATIONS_VIEW`	Visualizar migrations

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

Resposta:

{
  "data": [
    {
      "id": "0192abcd-1234-5678-9abc-def012345678",
      "driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
      "total_count": 10,
      "pending_count": 2,
      "processing_count": 3,
      "finished_count": 4,
      "failed_count": 1,
      "created_at": "2024-01-15T10:45:00.000000Z",
      "updated_at": "2024-01-15T10:50:00.000000Z",
      "driver": {
        "id": "01ke7rhnt6fhb6tsbbhcdpepya",
        "name": "Bling",
        "slug": "bling"
      },
      "migration_installations": [
        {
          "id": "0192abcd-1234-5678-9abc-def012345679",
          "original_id": "12345",
          "description": "Loja Principal",
          "setup_data": null,
          "status": "pending"
        }
      ]
    }
  ],
  "links": {
    "first": "https://api.integracoesinteligentes.com/migrations?page=1",
    "last": "https://api.integracoesinteligentes.com/migrations?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1
  }
}

GET /migrations/{id}

Retorna detalhes de uma migration específica.

Permissões necessárias

Permissão	Descrição
`INSTALLATIONS_VIEW`	Visualizar migrations

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

Resposta:

{
  "data": {
    "id": "0192abcd-1234-5678-9abc-def012345678",
    "driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
    "total_count": 10,
    "pending_count": 2,
    "processing_count": 3,
    "finished_count": 4,
    "failed_count": 1,
    "created_at": "2024-01-15T10:45:00.000000Z",
    "updated_at": "2024-01-15T10:50:00.000000Z",
    "driver": {
      "id": "01ke7rhnt6fhb6tsbbhcdpepya",
      "name": "Bling",
      "slug": "bling"
    },
    "migration_installations": [
      {
        "id": "0192abcd-1234-5678-9abc-def012345679",
        "original_id": "12345",
        "description": "Loja Principal",
        "setup_data": null,
        "status": "pending"
      },
      {
        "id": "0192abcd-1234-5678-9abc-def012345680",
        "original_id": "67890",
        "description": "Filial SP",
        "setup_data": null,
        "status": "finished"
      }
    ]
  }
}

Campos da resposta:

Campo	Tipo	Descrição
`id`	UUID	ID único da migration
`driver_id`	string	ID do driver de destino
`total_count`	integer	Total de instalações para migrar
`pending_count`	integer	Instalações pendentes
`processing_count`	integer	Instalações em processamento
`finished_count`	integer	Instalações migradas com sucesso
`failed_count`	integer	Instalações que falharam
`created_at`	string	Data de criação
`updated_at`	string	Data de atualização
`driver`	object	Dados do driver
`migration_installations`	array	Lista de instalações sendo migradas
`migration_installations[].id`	UUID	ID da instalação de migration
`migration_installations[].original_id`	string	ID original no driver de origem
`migration_installations[].description`	string\|null	Descrição da instalação
`migration_installations[].setup_data`	object\|null	Dados de setup
`migration_installations[].status`	string	Status da migração

Status das instalações de migration:

Status	Descrição
`pending`	Aguardando processamento
`processing`	Em processamento
`finished`	Migração concluída
`failed`	Migração falhou

POST /drivers/{id}/migrations

Inicia uma migration de instalações para um driver.

Permissões necessárias

Permissão	Descrição
`INSTALLATIONS_MANAGE`	Criar migrations

curl -X POST "https://api.integracoesinteligentes.com/drivers/01ke7rhnt6fhb6tsbbhcdpepya/migrations" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "installations": [
      {
        "original_id": "12345",
        "description": "Loja Principal"
      },
      {
        "original_id": "67890",
        "description": "Filial SP"
      }
    ]
  }'

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`installations`	array	Sim	Lista de instalações para migrar
`installations[].original_id`	string	Sim	ID original no driver de origem
`installations[].description`	string	Não	Descrição da instalação
`installations[].setup_data`	object	Não	Dados de setup necessários

Resposta (201 Created):

{
  "data": {
    "id": "0192abcd-1234-5678-9abc-def012345678",
    "driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
    "total_count": 2,
    "pending_count": 2,
    "processing_count": 0,
    "finished_count": 0,
    "failed_count": 0,
    "created_at": "2024-01-15T10:45:00.000000Z",
    "updated_at": "2024-01-15T10:45:00.000000Z",
    "driver": {
      "id": "01ke7rhnt6fhb6tsbbhcdpepya",
      "name": "Bling",
      "slug": "bling"
    },
    "migration_installations": [
      {
        "id": "0192abcd-1234-5678-9abc-def012345679",
        "original_id": "12345",
        "description": "Loja Principal",
        "setup_data": null,
        "status": "pending"
      },
      {
        "id": "0192abcd-1234-5678-9abc-def012345680",
        "original_id": "67890",
        "description": "Filial SP",
        "setup_data": null,
        "status": "pending"
      }
    ]
  }
}

Erro (409 - Migration já em andamento):

{
  "message": "Uma migration já está em andamento para este driver."
}

Erros Comuns

422 - Settings não existe

{
  "message": "O driver selecionado não possui configuração.",
  "errors": {
    "driver_id": ["O driver selecionado não possui configuração."]
  }
}

Solução: Configure o driver antes de criar a instalação.

422 - Evento inválido

{
  "message": "O evento selecionado é inválido.",
  "errors": {
    "enabled_events.unknown.event": ["O evento selecionado é inválido."]
  }
}

Solução: Verifique se o evento existe para este driver.

403 - Não autorizado

{
  "message": "This action is unauthorized."
}

Solução: Esta instalação pertence a outro tenant.

Próximos Passos

Drivers - Gerenciar drivers
Processing - Consultar eventos
Setup OAuth - Fluxo OAuth completo
Configurar Integração - Guia passo a passo

Instalações

Listar Instalações

GET /installations

Permissões necessárias

Criar Instalação

POST /installations

Permissões necessárias

Visualizar Instalação

GET /installations/{id}

Permissões necessárias

Atualizar Instalação

PUT /installations/{id}

Permissões necessárias

Remover Instalação

DELETE /installations/{id}

Permissões necessárias

Métodos de Processamento

complete (padrão)

real_time

Eventos Habilitados

Estrutura do enabled_events

Novos Eventos Automaticamente

Eventos Fora de Ordem (Out of Sequence)

Fluxo OAuth

Motivos de Falha OAuth

Callback OAuth

GET /installations/oauth

Migrations

GET /migrations

Permissões necessárias

GET /migrations/{id}

Permissões necessárias

POST /drivers/{id}/migrations

Permissões necessárias

Erros Comuns

422 - Settings não existe

422 - Evento inválido

403 - Não autorizado

Próximos Passos

`complete` (padrão)

`real_time`