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.

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",
      "description": "Minha loja Digital Manager Guru",
      "integration_driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
      "connection_settings": null,
      "processing_method": "complete",
      "new_events_enabled": true,
      "new_events_enabled_at": "2024-01-15T10:45:00.000000Z",
      "superseded_events_enabled": false,
      "superseded_events_enabled_at": null,
      "created_at": "2024-01-15T10:45:00.000000Z",
      "updated_at": "2024-01-15T10:45:00.000000Z",
      "integration_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
`description`	string\|null	Nome descritivo da instalação
`integration_driver_id`	string	ID do driver associado
`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
`superseded_events_enabled`	boolean	Se eventos fora de ordem são enviados ao tenant
`superseded_events_enabled_at`	string\|null	Data de habilitação de eventos fora de ordem
`created_at`	string	Data de criação
`updated_at`	string	Data de atualizaçã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
`enabled_events`	object	Mapa de eventos habilitados

Criar Instalação

POST /installations

Cria uma nova instalação.

curl -X POST https://api.integracoesinteligentes.com/installations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
    "description": "Minha loja",
    "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
`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",
    "description": "Minha loja",
    "integration_driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
    "connection_settings": null,
    "processing_method": "complete",
    "new_events_enabled": true,
    "new_events_enabled_at": "2024-01-15T10:45:00.000000Z",
    "superseded_events_enabled": false,
    "superseded_events_enabled_at": null,
    "created_at": "2024-01-15T10:45:00.000000Z",
    "updated_at": "2024-01-15T10:45:00.000000Z",
    "integration_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
`description`	string\|null	Nome descritivo
`integration_driver_id`	string	ID do driver
`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
`superseded_events_enabled`	boolean	Se eventos fora de ordem são enviados ao tenant
`superseded_events_enabled_at`	string\|null	Data de habilitação de eventos fora de ordem
`created_at`	string	Data de criação
`updated_at`	string	Data de atualização
`integration_driver`	object	Dados do driver
`enabled_events`	object	Mapa de eventos habilitados
`needs_setup`	boolean	Se há configuração adicional necessária
`needs_setup` = true	object	Presente quando `needs_setup` é true
`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.

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",
    "description": "Minha loja",
    "integration_driver_id": "01ke7rhnt6fhb6tsbbhcdpepya",
    "connection_settings": null,
    "processing_method": "complete",
    "new_events_enabled": true,
    "new_events_enabled_at": "2024-01-15T10:45:00.000000Z",
    "superseded_events_enabled": false,
    "superseded_events_enabled_at": null,
    "created_at": "2024-01-15T10:45:00.000000Z",
    "updated_at": "2024-01-15T10:45:00.000000Z",
    "integration_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
`description`	string\|null	Nome descritivo
`integration_driver_id`	string	ID do driver
`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
`superseded_events_enabled`	boolean	Se eventos fora de ordem são enviados ao tenant
`superseded_events_enabled_at`	string\|null	Data de habilitação de eventos fora de ordem
`created_at`	string	Data de criação
`updated_at`	string	Data de atualização
`integration_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.

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
`superseded_events_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",
    "description": "Loja Digital Manager Guru - Principal",
    "processing_method": "real_time",
    "new_events_enabled": true,
    "new_events_enabled_at": "2024-01-15T10:45:00.000000Z",
    "superseded_events_enabled": false,
    "superseded_events_enabled_at": null,
    "enabled_events": {
      "order.paid": true,
      "order.canceled": true,
      "checkout.abandoned": true
    },
    "updated_at": "2024-01-15T11:00:00.000000Z"
  }
}

Remover Instalação

DELETE /installations/{id}

Remove uma instalação (soft delete).

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 (Superseded)

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
`superseded_events_enabled`	Se eventos fora de ordem são enviados ao tenant
`superseded_events_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 superseded_events_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

Erros Comuns

422 - Settings não existe

{
  "message": "O driver selecionado não possui configuração.",
  "errors": {
    "integration_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

Criar Instalação

POST /installations

Visualizar Instalação

GET /installations/{id}

Atualizar Instalação

PUT /installations/{id}

Remover Instalação

DELETE /installations/{id}

Métodos de Processamento

complete (padrão)

real_time

Eventos Habilitados

Estrutura do enabled_events

Novos Eventos Automaticamente

Eventos Fora de Ordem (Superseded)

Fluxo OAuth

Motivos de Falha OAuth

Callback OAuth

GET /installations/oauth

Erros Comuns

422 - Settings não existe

422 - Evento inválido

403 - Não autorizado

Próximos Passos

`complete` (padrão)

`real_time`