API atual/Referência completa/Catálogo: kits, mix e compartilhamento

Compartilhamento

Configura a recompensa em pontos por pedidos vindos de links compartilhados e consulta o relatório de cliques, pedidos e receita da indicação.

Com o compartilhamento ligado, o botão "Compartilhar" da vitrine gera um link rastreado para a página (ou produto). Cada clique é contado. Se alguém compra pelo link, o pedido é atribuído ao cliente que compartilhou, e ele ganha pontos de recompensa.

Três regras definem se os pontos saem: o compartilhamento deve estar ligado (enabled), o pedido deve ter total igual ou acima do mínimo (min_order_cents) e o comprador não pode ser o próprio autor do link. Se o pedido for depois cancelado ou devolvido, os pontos são estornados, uma única vez.

As três rotas exigem o privilégio manage_settings.

Ler a configuração

GET/api/v1/admin/sharing/settingsAdmin

Ler a recompensa do compartilhamento

bash

curl "$BASE_URL/api/v1/admin/sharing/settings" \
  -H "Authorization: Bearer $TOKEN"

200Configuração

json

{ "enabled": true, "points_per_order": 10, "min_order_cents": 5000 }

Campos da resposta

enabledboolean

Se o compartilhamento está ligado. Desligado, a vitrine não gera links rastreados.

points_per_orderinteger

Pontos dados ao autor do link por pedido atribuído. 0 não dá pontos, mas o pedido ainda é contado no relatório.

min_order_centsinteger

Total mínimo do pedido, em centavos, para dar pontos (5000 = R$ 50,00).

Alterar a configuração

PUT/api/v1/admin/sharing/settingsAdmin

Salvar a recompensa do compartilhamento

Grava os três campos de uma vez. Valores negativos viram 0. Envie sempre os três: os omitidos são gravados como false ou 0.

Corpo da requisição

enabledbooleanobrigatório

Liga ou desliga o compartilhamento.

points_per_orderintegerobrigatório

Pontos por pedido atribuído. Não negativo.

min_order_centsintegerobrigatório

Total mínimo do pedido, em centavos. Não negativo.

bash

curl -X PUT "$BASE_URL/api/v1/admin/sharing/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"points_per_order":15,"min_order_cents":8000}'

200Configuração salva

A resposta repete os valores gravados (já com os negativos trocados por 0).

json

{ "enabled": true, "points_per_order": 15, "min_order_cents": 8000 }

Relatório de indicações

GET/api/v1/admin/sharing/reportAdmin

Totais de links, cliques, pedidos e receita do compartilhamento

Soma o desempenho do canal numa janela de datas e lista os 50 clientes que mais geraram receita.

Parâmetros de consulta

fromstringpadrão: 30 dias atrás

Início da janela, RFC 3339 ou YYYY-MM-DD. Valor inválido é ignorado e vale o padrão.

tostringpadrão: agora

Fim da janela, RFC 3339 ou YYYY-MM-DD. Com YYYY-MM-DD, o dia entra por inteiro. Valor inválido é ignorado.

bash

curl "$BASE_URL/api/v1/admin/sharing/report?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $TOKEN"

200Relatório

json

{
  "totals": { "links": 18, "clicks": 104, "orders": 3, "revenue_cents": 45900, "points_awarded": 30 },
  "top_sharers": [
    {
      "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "name": "Priscila Gomes",
      "clicks": 41,
      "orders": 2,
      "revenue_cents": 31900,
      "points_awarded": 20
    }
  ]
}

Campos da resposta

totals.linksinteger

Links de compartilhamento criados.

totals.clicksinteger

Cliques registrados nos links.

totals.ordersinteger

Pedidos atribuídos a um link.

totals.revenue_centsinteger

Soma dos totais desses pedidos, em centavos.

totals.points_awardedinteger

Pontos concedidos (já descontados os estornos).

top_sharersarray

Até 50 clientes, do que mais gerou receita para o que menos.

top_sharers[].user_iduuid

Cliente que compartilhou.

top_sharers[].namestring

Nome do cliente.

top_sharers[].clicksinteger

Cliques nos links dele.

top_sharers[].ordersinteger

Pedidos atribuídos a ele.

top_sharers[].revenue_centsinteger

Receita desses pedidos, em centavos.

top_sharers[].points_awardedinteger

Pontos concedidos a ele.

Erros

Status	Quando	Corpo de exemplo
400	`PUT` com corpo que não é JSON.	`{"error":"invalid body"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
500	Falha ao ler ou gravar.	`{"error":"..."}`

Veja também

API atual/Referência completa/Catálogo: kits, mix e compartilhamento

Compartilhamento

Configura a recompensa em pontos por pedidos vindos de links compartilhados e consulta o relatório de cliques, pedidos e receita da indicação.

As três rotas exigem o privilégio manage_settings.

Ler a configuração

GET/api/v1/admin/sharing/settingsAdmin

Ler a recompensa do compartilhamento

bash

curl "$BASE_URL/api/v1/admin/sharing/settings" \
  -H "Authorization: Bearer $TOKEN"

200Configuração

json

{ "enabled": true, "points_per_order": 10, "min_order_cents": 5000 }

Campos da resposta

enabledboolean

Se o compartilhamento está ligado. Desligado, a vitrine não gera links rastreados.

points_per_orderinteger

Pontos dados ao autor do link por pedido atribuído. 0 não dá pontos, mas o pedido ainda é contado no relatório.

min_order_centsinteger

Total mínimo do pedido, em centavos, para dar pontos (5000 = R$ 50,00).

Alterar a configuração

PUT/api/v1/admin/sharing/settingsAdmin

Salvar a recompensa do compartilhamento

Grava os três campos de uma vez. Valores negativos viram 0. Envie sempre os três: os omitidos são gravados como false ou 0.

Corpo da requisição

enabledbooleanobrigatório

Liga ou desliga o compartilhamento.

points_per_orderintegerobrigatório

Pontos por pedido atribuído. Não negativo.

min_order_centsintegerobrigatório

Total mínimo do pedido, em centavos. Não negativo.

bash

curl -X PUT "$BASE_URL/api/v1/admin/sharing/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"points_per_order":15,"min_order_cents":8000}'

200Configuração salva

A resposta repete os valores gravados (já com os negativos trocados por 0).

json

{ "enabled": true, "points_per_order": 15, "min_order_cents": 8000 }

Relatório de indicações

GET/api/v1/admin/sharing/reportAdmin

Totais de links, cliques, pedidos e receita do compartilhamento

Soma o desempenho do canal numa janela de datas e lista os 50 clientes que mais geraram receita.

Parâmetros de consulta

fromstringpadrão: 30 dias atrás

Início da janela, RFC 3339 ou YYYY-MM-DD. Valor inválido é ignorado e vale o padrão.

tostringpadrão: agora

Fim da janela, RFC 3339 ou YYYY-MM-DD. Com YYYY-MM-DD, o dia entra por inteiro. Valor inválido é ignorado.

bash

curl "$BASE_URL/api/v1/admin/sharing/report?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $TOKEN"

200Relatório

json

{
  "totals": { "links": 18, "clicks": 104, "orders": 3, "revenue_cents": 45900, "points_awarded": 30 },
  "top_sharers": [
    {
      "user_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "name": "Priscila Gomes",
      "clicks": 41,
      "orders": 2,
      "revenue_cents": 31900,
      "points_awarded": 20
    }
  ]
}

Campos da resposta

totals.linksinteger

Links de compartilhamento criados.

totals.clicksinteger

Cliques registrados nos links.

totals.ordersinteger

Pedidos atribuídos a um link.

totals.revenue_centsinteger

Soma dos totais desses pedidos, em centavos.

totals.points_awardedinteger

Pontos concedidos (já descontados os estornos).

top_sharersarray

Até 50 clientes, do que mais gerou receita para o que menos.

top_sharers[].user_iduuid

Cliente que compartilhou.

top_sharers[].namestring

Nome do cliente.

top_sharers[].clicksinteger

Cliques nos links dele.

top_sharers[].ordersinteger

Pedidos atribuídos a ele.

top_sharers[].revenue_centsinteger

Receita desses pedidos, em centavos.

top_sharers[].points_awardedinteger

Pontos concedidos a ele.

Erros

Status	Quando	Corpo de exemplo
400	`PUT` com corpo que não é JSON.	`{"error":"invalid body"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem `manage_settings`.	`{"error":"insufficient privileges","required":"manage_settings"}`
500	Falha ao ler ou gravar.	`{"error":"..."}`