API de Integrações - Documentation

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

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

Listar integrações

string

Filtra pelo tipo de integração (ex: webhook, meta_pixel). Ver tipos disponíveis.

GET /integrations/
Authorization: Bearer {token}

Resposta 200

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

POST /integrations/
Authorization: Bearer {token}
Content-Type: application/json

Body

string

required

Tipo da integração. Ver tipos disponíveis.

object

required

Credenciais e configurações específicas do tipo. Ver referência de config.

array

required

Lista de eventos que ativam a integração. Ver eventos disponíveis.

boolean

default:"true"

Se a integração está ativa.

boolean

default:"false"

Se true, a integração é disparada para todos os produtos ativos da empresa. Quando ativo, o filtro de produtos é gerenciado automaticamente.

Exemplo — Webhook

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

Só é permitida uma integração do tipo mercadopago ativa por empresa.

Detalhe da integração

GET /integrations/{id}
Authorization: Bearer {token}

Retorna o mesmo schema de um item da listagem.

Atualizar integração

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:

{ "is_active": true }

Resposta 200 — retorna o objeto atualizado.

Remover integração

DELETE /integrations/{id}
Authorization: Bearer {token}

Resposta 204 — sem corpo.

Alertas pendentes

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

GET /integrations/alerts
Authorization: Bearer {token}

Resposta — sem pendência

{ "pending": false }

Resposta — com pendência

{
  "pending": true,
  "type": "mercadopago",
  "oauth_url": "https://auth.mercadopago.com/authorization?..."
}

Listar tipos de eventos

GET /integrations/events
Authorization: Bearer {token}

Resposta 200

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

GET /integrations/{id}/products
Authorization: Bearer {token}

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

POST /integrations/{id}/products
Authorization: Bearer {token}
Content-Type: application/json

{ "product_id": 1 }

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

Atualizar produto vinculado

PATCH /integrations/{id}/products/{product_id}
Authorization: Bearer {token}
Content-Type: application/json

{ "is_active": false }

Remover produto

DELETE /integrations/{id}/products/{product_id}
Authorization: Bearer {token}

Resposta 204 — sem corpo.

Schema de resposta

integer

Identificador da integração.

string

Tipo da integração (ex: webhook, meta_pixel).

boolean

Se a integração está ativa e recebendo eventos.

object

Credenciais e configurações. O schema varia por tipo — ver referência de config.

array

Eventos assinados pela integração.

boolean

Quando true, aplica a todos os produtos da empresa.

array

Cache dos IDs de produtos ativos vinculados. Atualizado automaticamente.

integer

Número de falhas consecutivas. Resetado após um despacho bem-sucedido.

string | null

Data/hora da última falha em ISO 8601.

string

"auto_disabled" quando desativada pelo circuit breaker; vazio nos demais casos.

​Listar integrações

​Criar integração

​Detalhe da integração

​Atualizar integração

​Remover integração

​Alertas pendentes

​Listar tipos de eventos

​Produtos vinculados

​Listar produtos da integração

​Adicionar produto

​Atualizar produto vinculado

​Remover produto

​Schema de resposta

Listar integrações

Criar integração

Detalhe da integração

Atualizar integração

Remover integração

Alertas pendentes

Listar tipos de eventos

Produtos vinculados

Listar produtos da integração

Adicionar produto

Atualizar produto vinculado

Remover produto

Schema de resposta