Pular para o conteúdo principal

Webhook: item adicionado ao carrinho

Este é o único endpoint que o parceiro implementa. Quando o vendedor clica em "adicionar" na tela do Sipru, o Sipru faz um POST no seu endpoint com o item.

Para onde o Sipru envia​

O destino é resolvido nesta ordem de precedência:

  1. o cartCallbackUrl do canal, quando enviado na criação — override por cotação;
  2. o cartCallbackUrl cadastrado para a loja em /integracoes/cart-erp;
  3. erpBaseUrl + orderEndpointPath da mesma configuração — o endpoint do carrinho inteiro, usado como fallback por quem não separa os dois.

Sem nenhum dos três, o clique simplesmente não vira POST.

Em produção a URL precisa ser HTTPS. HTTP é aceito apenas no ambiente de homologação, para você conseguir apontar para um host interno durante a integração.

Autenticação​

Configurável por canal ou por loja, com credencial estática:

modeO que o Sipru envia
noneNenhum header de autenticação
bearerAuthorization: Bearer <token>
api_keyX-API-Key: <token>

OAuth client credentials não é suportado no canal ao vivo.

O payload​

{
  "idempotencyKey": "erp_cart_4f1c8b2e-...",
  "event": "cart_item_added",
  "channelId": "8f2b...",
  "tempQuoteId": "TMP-90321",
  "quoteId": null,
  "cliente": { "cnpj": "04252011000110", "razaoSocial": "…", "nomeFantasia": "…" },
  "vendedor": { "cpf": "12345678909", "email": "vendedor@loja.com.br" },
  "tenant": { "companyId": "marbel", "locationId": "07526557000100" },
  "item": {
    "productCode": "72411",
    "ean": "7891234567890",
    "name": "Argamassa AC-III 20kg",
    "quantity": 4,
    "unitPrice": 34.9,
    "coinsReward": 12,
    "source": "cross_sell"
  },
  "timestamp": "2026-08-31T18:44:02.117Z"
}

O Idempotency-Key também vai no header, com o mesmo valor.

O que o Sipru espera de volta​

Responder 2xx. Qualquer 2xx serve.

O Sipru tenta 2 vezes, com timeout de 8 segundos, e só repete em status transitório — 408, 429 e 5xx. Um 4xx não transitório recusa o item de vez, sem nova tentativa.

Deduplique

Como há retry, o mesmo item pode chegar duas vezes. Use o idempotencyKey (header ou corpo) como chave de deduplicação do seu lado.

O contrato formal está em webhooks.cartItemAdded na referência da API.