> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velan.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Integrações

> Endpoints para criar, listar, atualizar e remover integrações da sua empresa.

<Note>
  Todos os endpoints exigem autenticação via Bearer Token e empresa ativa (`HTTP 402` caso contrário).
</Note>

**Base URL:** `https://api.velan.app/v1`

***

## Listar integrações

<ParamField query="type" type="string">
  Filtra pelo tipo de integração (ex: `webhook`, `meta_pixel`). Ver [tipos disponíveis](/integrations/tipos).
</ParamField>

```http theme={null}
GET /integrations/
Authorization: Bearer {token}
```

**Resposta 200**

```json theme={null}
[
  {
    "id": 42,
    "type": "webhook",
    "is_active": true,
    "config": { "url": "https://seu-servidor.com/hook", "secret": "abc123" },
    "events": ["order.paid", "order.refunded"],
    "products": [],
    "send_to_all_products": true,
    "product_ids": [1, 2, 3],
    "failure_count": 0,
    "last_failure_at": null,
    "disabled_reason": "",
    "created_at": "2025-01-10T14:00:00Z",
    "updated_at": "2025-01-10T14:00:00Z"
  }
]
```

***

## Criar integração

```http theme={null}
POST /integrations/
Authorization: Bearer {token}
Content-Type: application/json
```

**Body**

<ParamField body="type" type="string" required>
  Tipo da integração. Ver [tipos disponíveis](/integrations/tipos).
</ParamField>

<ParamField body="config" type="object" required>
  Credenciais e configurações específicas do tipo. Ver [referência de config](/integrations/tipos).
</ParamField>

<ParamField body="events" type="array" required>
  Lista de eventos que ativam a integração. Ver [eventos disponíveis](/integrations/eventos).
</ParamField>

<ParamField body="is_active" type="boolean" default="true">
  Se a integração está ativa.
</ParamField>

<ParamField body="send_to_all_products" type="boolean" default="false">
  Se `true`, a integração é disparada para todos os produtos ativos da empresa. Quando ativo, o filtro de produtos é gerenciado automaticamente.
</ParamField>

**Exemplo — Webhook**

```json theme={null}
{
  "type": "webhook",
  "config": {
    "url": "https://seu-servidor.com/hook",
    "secret": "meu-segredo-hmac"
  },
  "events": ["order.paid", "order.refunded"],
  "send_to_all_products": true
}
```

**Resposta 201** — retorna o objeto criado com o mesmo schema da listagem.

<Warning>
  Só é permitida **uma** integração do tipo `mercadopago` ativa por empresa.
</Warning>

***

## Detalhe da integração

```http theme={null}
GET /integrations/{id}
Authorization: Bearer {token}
```

Retorna o mesmo schema de um item da listagem.

***

## Atualizar integração

```http theme={null}
PATCH /integrations/{id}
Authorization: Bearer {token}
Content-Type: application/json
```

Aceita os mesmos campos de criação, todos opcionais. Útil para reativar uma integração desabilitada pelo circuit breaker:

```json theme={null}
{ "is_active": true }
```

**Resposta 200** — retorna o objeto atualizado.

***

## Remover integração

```http theme={null}
DELETE /integrations/{id}
Authorization: Bearer {token}
```

**Resposta 204** — sem corpo.

***

## Alertas pendentes

Retorna se existe alguma integração MercadoPago pendente de autorização OAuth.

```http theme={null}
GET /integrations/alerts
Authorization: Bearer {token}
```

**Resposta — sem pendência**

```json theme={null}
{ "pending": false }
```

**Resposta — com pendência**

```json theme={null}
{
  "pending": true,
  "type": "mercadopago",
  "oauth_url": "https://auth.mercadopago.com/authorization?..."
}
```

***

## Listar tipos de eventos

```http theme={null}
GET /integrations/events
Authorization: Bearer {token}
```

**Resposta 200**

```json theme={null}
[
  { "value": "order.paid",      "label": "Pedido Pago" },
  { "value": "order.refunded",  "label": "Pedido Estornado" },
  { "value": "order.created",   "label": "Pedido Criado" },
  { "value": "order.expired",   "label": "Pedido Expirado" },
  { "value": "order.failed",    "label": "Pedido Falhou" },
  { "value": "order.abandoned", "label": "Carrinho Abandonado" },
  { "value": "lead.created",    "label": "Lead Criado" }
]
```

***

## Produtos vinculados

### Listar produtos da integração

```http theme={null}
GET /integrations/{id}/products
Authorization: Bearer {token}
```

```json theme={null}
[
  {
    "id": 7,
    "product": 1,
    "product_code": "550e8400-e29b-41d4-a716-446655440000",
    "product_name": "Curso de Marketing Digital",
    "is_active": true,
    "created_at": "2025-01-10T14:00:00Z"
  }
]
```

### Adicionar produto

```http theme={null}
POST /integrations/{id}/products
Authorization: Bearer {token}
Content-Type: application/json
```

```json theme={null}
{ "product_id": 1 }
```

**Resposta 201** — retorna o objeto `IntegrationProduct` criado.
**Resposta 409** — produto já vinculado.

### Atualizar produto vinculado

```http theme={null}
PATCH /integrations/{id}/products/{product_id}
Authorization: Bearer {token}
Content-Type: application/json
```

```json theme={null}
{ "is_active": false }
```

### Remover produto

```http theme={null}
DELETE /integrations/{id}/products/{product_id}
Authorization: Bearer {token}
```

**Resposta 204** — sem corpo.

***

## Schema de resposta

<ResponseField name="id" type="integer">
  Identificador da integração.
</ResponseField>

<ResponseField name="type" type="string">
  Tipo da integração (ex: `webhook`, `meta_pixel`).
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Se a integração está ativa e recebendo eventos.
</ResponseField>

<ResponseField name="config" type="object">
  Credenciais e configurações. O schema varia por tipo — ver [referência de config](/integrations/tipos).
</ResponseField>

<ResponseField name="events" type="array">
  Eventos assinados pela integração.
</ResponseField>

<ResponseField name="send_to_all_products" type="boolean">
  Quando `true`, aplica a todos os produtos da empresa.
</ResponseField>

<ResponseField name="product_ids" type="array">
  Cache dos IDs de produtos ativos vinculados. Atualizado automaticamente.
</ResponseField>

<ResponseField name="failure_count" type="integer">
  Número de falhas consecutivas. Resetado após um despacho bem-sucedido.
</ResponseField>

<ResponseField name="last_failure_at" type="string | null">
  Data/hora da última falha em ISO 8601.
</ResponseField>

<ResponseField name="disabled_reason" type="string">
  `"auto_disabled"` quando desativada pelo circuit breaker; vazio nos demais casos.
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.