Venda por Link

Visão geral

A Venda por Link expõe um contrato POST para criar a venda e o link, e dois contratos GET auxiliares — um para consultar o estado da venda e outro para descobrir as opções personalizadas de um produto. Todas as requisições e respostas usam application/json e exigem Authorization: Bearer {token}.

Endpoints

Resumo dos contratos disponíveis. Base URL nos exemplos: /api2. Toda chamada exige Authorization: Bearer {{token}}.

Autenticação

Use o fluxo OAuth 2.0 da API REST Yep para gerar um token e envie-o em todas as chamadas. Consulte OAuth 2.0 para o fluxo completo.

curl -X POST "{{route}}/api2/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={{client_id}}" \
  -d "client_secret={{client_secret}}" \
  -d "grant_type=client_credentials"

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

Criar venda e link

Cria a venda e todos os itens em uma única operação, retornando o link de finalização. O total é calculado pelo servidor.

curl -X POST "{{route}}/api2/vendalink" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6ec51e29-038d-4dbd-9be9-d6940935f103" \
  -d '{
    "email": "[email protected]",
    "store_id": 1,
    "coupon_code": "BEMVINDO10",
    "send_email": false,
    "expires_at": "2026-07-23T23:59:59-03:00",
    "items": [
      {
        "sku": "SKU-001",
        "qty": 2,
        "price": 149.90,
        "options": {
          "123": "456",
          "124": "Texto personalizado",
          "125": "2026-07-20",
          "126": "14:30"
        }
      }
    ]
  }'

{
  "success": true,
  "vendalink": {
    "id": 87,
    "status": "pending",
    "email": "[email protected]",
    "store_id": 1,
    "coupon_code": "BEMVINDO10",
    "total": 299.80,
    "currency": "BRL",
    "checkout_url": "https://loja.exemplo.com/vendalink/venda/index/id/TOKEN",
    "expires_at": "2026-07-24T02:59:59+00:00",
    "order_increment_id": null,
    "email_sent": false,
    "created_at": "2026-07-16T19:30:00+00:00",
    "items": [
      {
        "id": 201,
        "sku": "SKU-001",
        "qty": 2,
        "price": 149.90,
        "row_total": 299.80,
        "options": {
          "123": "456",
          "124": "Texto personalizado",
          "125": "2026-07-20",
          "126": "14:30"
        }
      }
    ]
  }
}

Idempotência

A Idempotency-Key garante que reenviar exatamente a mesma requisição não crie uma segunda venda. Gere uma nova chave para cada nova venda e preserve a chave ao repetir a mesma operação.

Consultar venda

Consulta a venda criada. A resposta usa o mesmo objeto vendalink retornado na criação.

curl "{{route}}/api2/vendalink?id={{vendalink_id}}" \
  -H "Authorization: Bearer {{token}}" \
  -H "Accept: application/json"

Opções do produto

Retorna os identificadores e formatos necessários para preencher items[].options. Consulte este endpoint antes de enviar produtos com opções personalizadas.

curl "{{route}}/api2/vendalink/options?sku={{product_sku}}&store_id={{store_id}}" \
  -H "Authorization: Bearer {{token}}" \
  -H "Accept: application/json"

{
  "success": true,
  "product": {
    "sku": "SKU-001",
    "name": "Produto de exemplo",
    "catalog_price": 159.90,
    "options": [
      {
        "option_id": 123,
        "title": "Cor",
        "type": "drop_down",
        "required": true,
        "values": [
          {
            "option_type_id": 456,
            "title": "Azul",
            "price": 0,
            "price_type": "fixed"
          }
        ]
      }
    ]
  }
}

Formatos das opções

O valor de cada chave em items[].options depende do type da opção retornado acima.

Recomendações para integração

Boas práticas consolidadas para integrações que criam vendas personalizadas com a Plataforma Yep.

Recomendado

• Gere uma nova Idempotency-Key para cada nova venda e preserve a chave ao repetir exatamente a mesma operação.
• Consulte /api2/vendalink/options antes de enviar produtos com opções personalizadas.
• Trate o checkout_url como dado sensível — não o publique em logs abertos nem em canais compartilhados.
• Deixe o servidor calcular o total; envie apenas items[].price como preço comercial de cada item.
• Valide email_sent e a lista warnings na resposta quando usar send_email=true.

Evitar

• Reutilizar a mesma Idempotency-Key com payload diferente — resulta em 409 Conflict.
• Enviar um campo de total no corpo — o total é sempre calculado pelo servidor.
• Preencher items[].options sem antes consultar o endpoint de opções do produto.
• Usar o preço de catálogo como valor da venda — o valor efetivo é o items[].price enviado.

Erros comuns

{
  "success": false,
  "error": "Descrição objetiva do erro.",
  "field": "items.0.options.123"
}