Painel
Menu da documentação
Zolvi APIv1 estável

zolvibot.app/api/v1

40 rotas · REST e webhooks

Referência da API

Webhooks

Gerencie os webhooks da loja pela API (até 10). Cada evento pede também a permissão de ver o que ele traz (eventos ORDER_* pedem orders:read, PRODUCT_* products:read, STOCK_* stock:read, REVIEW_CREATED reviews:read e AFFILIATE_SALE affiliates:read); sem ela, a resposta é 403. Como receber e conferir a assinatura: veja a página Webhooks.

Rotas deste grupo8

Listar webhooks

GET/api/v1/webhooks

Sem o segredo.

Permissão: webhooks:read

Exemplo

curl
curl https://zolvibot.app/api/v1/webhooks \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"
Resposta 200
{
  "data": [
    {
      "id": "cmw8ezqao002issqgbr5y6qbw",
      "url": "https://seusite.com/webhooks/zolvi",
      "description": "Liberar VIP no site",
      "events": [
        "ORDER_PAID",
        "ORDER_DELIVERED"
      ],
      "active": true,
      "disabled_reason": null,
      "failing_since": null,
      "created_at": "2026-11-08T21:50:00.000Z",
      "updated_at": "2026-11-08T21:50:00.000Z"
    }
  ]
}

Criar webhook

POST/api/v1/webhooks

A resposta traz o secret (whsec_…) para conferir a assinatura: guarde, ele só aparece aqui (ou ao trocar).

Permissão: webhooks:create

Corpo (JSON)

urlobrigatóriotextohttps e endereço público.
eventsobrigatóriolista de textosEventos assinados (veja a página Webhooks).
descriptiontexto | nullPara você lembrar do que é.
activebooleanoLigado (padrão true).

Exemplo

curl
curl -X POST https://zolvibot.app/api/v1/webhooks \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://seusite.com/webhooks/zolvi","events":["ORDER_PAID","ORDER_DELIVERED"]}'
Resposta 201
{
  "id": "cmw8ezqao002issqgbr5y6qbw",
  "url": "https://seusite.com/webhooks/zolvi",
  "description": "Liberar VIP no site",
  "events": [
    "ORDER_PAID",
    "ORDER_DELIVERED"
  ],
  "active": true,
  "disabled_reason": null,
  "failing_since": null,
  "created_at": "2026-11-08T21:50:00.000Z",
  "updated_at": "2026-11-08T21:50:00.000Z",
  "secret": "whsec_GoA_e1Baz9mqimERDXgVDqcVJv4ZYgWZ"
}

Ver um webhook

GET/api/v1/webhooks/{id}

Sem o segredo.

Permissão: webhooks:read

Exemplo

curl
curl https://zolvibot.app/api/v1/webhooks/ID \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"
Resposta 200
{
  "id": "cmw8ezqao002issqgbr5y6qbw",
  "url": "https://seusite.com/webhooks/zolvi",
  "description": "Liberar VIP no site",
  "events": [
    "ORDER_PAID",
    "ORDER_DELIVERED"
  ],
  "active": true,
  "disabled_reason": null,
  "failing_since": null,
  "created_at": "2026-11-08T21:50:00.000Z",
  "updated_at": "2026-11-08T21:50:00.000Z"
}

Editar webhook

PATCH/api/v1/webhooks/{id}

url, events, description e active. rotate_secret: true troca o segredo (o novo vem na resposta; o antigo para na hora).

Permissão: webhooks:update

Exemplo

curl
curl -X PATCH https://zolvibot.app/api/v1/webhooks/ID \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"rotate_secret":true}'
Resposta 200
{
  "id": "cmw8ezqao002issqgbr5y6qbw",
  "url": "https://seusite.com/webhooks/zolvi",
  "description": "Liberar VIP no site",
  "events": [
    "ORDER_PAID",
    "ORDER_DELIVERED"
  ],
  "active": true,
  "disabled_reason": null,
  "failing_since": null,
  "created_at": "2026-11-08T21:50:00.000Z",
  "updated_at": "2026-11-08T21:50:00.000Z",
  "secret": "whsec_Nx8mQ2vRt5LpW9cYbKd3FhJs7uZa1EoG"
}

Apagar webhook

DELETE/api/v1/webhooks/{id}

Com o histórico de entregas.

Permissão: webhooks:delete

Exemplo

curl
curl -X DELETE https://zolvibot.app/api/v1/webhooks/ID \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"
Resposta 200
{
  "deleted": true,
  "id": "cmw8ezqao002issqgbr5y6qbw"
}

Entregas

GET/api/v1/webhooks/{id}/deliveries

Dos últimos 30 dias, da mais nova.

Permissão: webhooks:read

Parâmetros da URL

statustextopending, succeeded ou failed.
pageinteiroPágina, a partir de 1. Padrão 1.
per_pageinteiroItens por página, de 1 a 100. Padrão 20.

Exemplo

curl
curl https://zolvibot.app/api/v1/webhooks/ID/deliveries \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"
Resposta 200
{
  "data": [
    {
      "id": "cmw8f3x1k002mssqg1x2y3z4a",
      "event_id": "evt_8ZcZT72Gy-jnD1xK5GTXcKIKgZQ",
      "event": "ORDER_PAID",
      "status": "succeeded",
      "attempts": 1,
      "next_attempt_at": null,
      "last_attempt_at": "2026-11-08T21:53:48.000Z",
      "last_status_code": 200,
      "last_error": null,
      "duration_ms": 182,
      "created_at": "2026-11-08T21:53:47.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

Enviar teste

POST/api/v1/webhooks/{id}/test

Manda um evento PING assinado (sai em alguns segundos).

Permissão: webhooks:update

Exemplo

curl
curl -X POST https://zolvibot.app/api/v1/webhooks/ID/test \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"
Resposta 202
{
  "event_id": "evt_8ZcZT72Gy-jnD1xK5GTXcKIKgZQ",
  "event": "PING"
}

Reenviar entrega

POST/api/v1/webhooks/{id}/deliveries/{deliveryId}/retry

Manda de novo uma entrega que falhou (ou antecipa a próxima tentativa).

Permissão: webhooks:update

Exemplo

curl
curl -X POST https://zolvibot.app/api/v1/webhooks/ID/deliveries/DELIVERY_ID/retry \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"
Resposta 200
{
  "id": "cmw8f3x1k002mssqg1x2y3z4a",
  "event_id": "evt_8ZcZT72Gy-jnD1xK5GTXcKIKgZQ",
  "event": "ORDER_PAID",
  "status": "pending",
  "attempts": 1,
  "next_attempt_at": "2026-11-08T22:01:00.000Z",
  "last_attempt_at": "2026-11-08T21:53:48.000Z",
  "last_status_code": 200,
  "last_error": null,
  "duration_ms": 182,
  "created_at": "2026-11-08T21:53:47.000Z"
}