API atual/Referência completa/Recomendações e compartilhamento

Links de compartilhamento

Cria um link curto para uma página da loja, para o botão "compartilhar", e descobre para onde um link curto aponta.

Quando o cliente toca em "compartilhar" em um produto ou página, a vitrine pede um link curto (https://sualoja.com.br/s/Ab3dEf9g). Se o cliente estiver logado, o link fica ligado a ele, e a loja pode atribuir a ele as compras feitas por quem abrir o link (programa de indicação e pontos, conforme a configuração do lojista). Para visitante anônimo, o link só serve para medir o canal.

A criação é POST /share-links. A rota GET /share-links/{code}/resolve é o que a página curta /s/{code} da vitrine chama para saber o destino e redirecionar o visitante.

POST/api/v1/storefront/share-linksPública

Criar um link curto de compartilhamento

Cabeçalhos

Authorizationstring

Opcional. Com um cliente logado, a plataforma reaproveita o mesmo link para a mesma página (um por cliente e página). Sem token, cada chamada cria um código novo.

Corpo da requisição

url_pathstringobrigatório

Caminho relativo da página, começando com uma única barra (por exemplo /produto/camiseta-lite-verde-00146-146). Endereço absoluto, // ou qualquer texto com http é recusado.

product_iduuid

Produto compartilhado, quando a página é de um produto. Usado nos relatórios do lojista.

GET/api/v1/storefront/share-links/{code}/resolvePública

Resolver um link curto

Parâmetros de caminho

codestringobrigatório

Código do link curto (o que vem depois de /s/).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/share-links" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"url_path":"/produto/camiseta-lite-verde-00146-146","product_id":"db033935-75ea-4b6f-abbb-13d0fcd6386d"}'

curl "$BASE_URL/api/v1/storefront/share-links/FIhoPna9/resolve"

Resposta

200Link criado

json

{
  "code": "FIhoPna9",
  "share_url": "https://store1.io-dev.venddor.com.br/s/FIhoPna9"
}

200Link resolvido

json

{ "url_path": "/produto/camiseta-lite-verde-00146-146" }

Campos da resposta

codestring

Código curto do link (8 caracteres).

share_urlstring

Endereço público completo para compartilhar. É montado com o domínio pelo qual a loja foi acessada; se a chamada veio por um endereço interno, usa o domínio cadastrado da loja.

url_pathstring

Em resolve: caminho de destino. Vazio ("") quando o código não existe.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid body"}`
400	`url_path` não começa com `/`, começa com `//` ou contém `http`	`{"error":"url_path must be a relative path starting with /"}`
401	A loja exige login para navegar e a chamada de criação não tem token	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
403	O lojista desligou o compartilhamento	`{"error":"sharing_disabled"}`
500	Falha ao gravar ou ler o link	`{"error":"..."}`

Um código inexistente em resolve não dá 404: a resposta é 200 com url_path vazio. A vitrine deve então mandar o visitante à página inicial.

Veja também

Links de compartilhamento

Cria um link curto para uma página da loja, para o botão "compartilhar", e descobre para onde um link curto aponta.

A criação é POST /share-links. A rota GET /share-links/{code}/resolve é o que a página curta /s/{code} da vitrine chama para saber o destino e redirecionar o visitante.

POST/api/v1/storefront/share-linksPública

Criar um link curto de compartilhamento

Cabeçalhos

Authorizationstring

Opcional. Com um cliente logado, a plataforma reaproveita o mesmo link para a mesma página (um por cliente e página). Sem token, cada chamada cria um código novo.

Corpo da requisição

url_pathstringobrigatório

Caminho relativo da página, começando com uma única barra (por exemplo /produto/camiseta-lite-verde-00146-146). Endereço absoluto, // ou qualquer texto com http é recusado.

product_iduuid

Produto compartilhado, quando a página é de um produto. Usado nos relatórios do lojista.

GET/api/v1/storefront/share-links/{code}/resolvePública

Resolver um link curto

Parâmetros de caminho

codestringobrigatório

Código do link curto (o que vem depois de /s/).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/share-links" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"url_path":"/produto/camiseta-lite-verde-00146-146","product_id":"db033935-75ea-4b6f-abbb-13d0fcd6386d"}'

curl "$BASE_URL/api/v1/storefront/share-links/FIhoPna9/resolve"

Resposta

200Link criado

json

{
  "code": "FIhoPna9",
  "share_url": "https://store1.io-dev.venddor.com.br/s/FIhoPna9"
}

200Link resolvido

json

{ "url_path": "/produto/camiseta-lite-verde-00146-146" }

Campos da resposta

codestring

Código curto do link (8 caracteres).

share_urlstring

Endereço público completo para compartilhar. É montado com o domínio pelo qual a loja foi acessada; se a chamada veio por um endereço interno, usa o domínio cadastrado da loja.

url_pathstring

Em resolve: caminho de destino. Vazio ("") quando o código não existe.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid body"}`
400	`url_path` não começa com `/`, começa com `//` ou contém `http`	`{"error":"url_path must be a relative path starting with /"}`
401	A loja exige login para navegar e a chamada de criação não tem token	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
403	O lojista desligou o compartilhamento	`{"error":"sharing_disabled"}`
500	Falha ao gravar ou ler o link	`{"error":"..."}`

Um código inexistente em resolve não dá 404: a resposta é 200 com url_path vazio. A vitrine deve então mandar o visitante à página inicial.