API de Recomendações

1. Visão geral

A API de Recomendações permite que sistemas parceiros (chatbot de WhatsApp ou CRM) enviem os dados de um cliente e uma lista de produtos para gerar um link de indicação. O cliente recebe esse link, clica, e é levado a um checkout já pré-preenchido com seus dados e produtos. Pedidos originados desse link têm a compra como visitante liberada automaticamente, mesmo quando a loja exige cadastro para clientes comuns.

Fluxo resumido

1) O parceiro envia um POST com os dados → 2) A API valida tudo → 3) Salva a recomendação e gera um código único (hash) → 4) Retorna o link pronto para enviar ao cliente.

2. Autenticação

A autenticação é feita por token, enviado no header Authorization. Cada parceiro (WhatsApp, CRM) possui um token próprio, que também determina a origem da recomendação. Não é necessário enviar o campo de origem no corpo — ele é inferido pelo token.

Authorization: API-TOKEN
Content-Type: application/json

3. Criar recomendação (POST)

3.1. Campos do corpo (JSON)

Os campos abaixo são obrigatórios, exceto coupon_code e price (dentro de cada item), que são opcionais.

3.2. Exemplo de requisição

Dados fictícios de uma cliente no body da requisição, com cupom e preço customizado no primeiro item:

{
  "group": "P",
  "first_name": "Ana",
  "last_name": "Ferreira",
  "email": "ana.ferreira@email.com",
  "phone": "11987654321",
  "cpf": "315.458.920-04",
  "postcode": "01310-100",
  "street": "Avenida Paulista",
  "street_number": "1578",
  "complement": "Apto 42",
  "district": "Bela Vista",
  "city": "São Paulo",
  "region_code": "SP",
  "coupon_code": "BLACKFRIDAY10",
  "items": [
    { "sku": "8119803", "qty": 1, "price": 89.90 },
    { "sku": "8119801", "qty": 1 }
  ]
}

3.3. Resposta de sucesso (HTTP 200)

Exemplo de retorno para o domínio www.bioageprofissional.com.br. O campo link é o que deve ser enviado ao cliente.

{
  "success": true,
  "hash": "769bbcda0540b5c0af58d0b0b0c4bd66",
  "origin": "whatsapp",
  "link": "https://www.bioageprofissional.com.br/recommendation/769bbcda0540b5c0af58d0b0b0c4bd66",
  "customer": {
    "name": "Ana Ferreira",
    "email": "ana.ferreira@email.com",
    "cpf": "31545892004"
  },
  "items_count": 6,
  "coupon_code": "BLACKFRIDAY10"
}

3.4. Regras de validação

4. Consultar status (GET)

4.1. Parâmetros

4.2. Exemplo de chamada

GET /recommendation/api/status?hash=65d50610774b3836f10b56323b7b7b1e
Authorization: 5a0a2dfe3498a0da07b00aa8d2760e8093587e50695e2417c86733c977daa69f

4.3. Resposta — convertida em venda (HTTP 200)

Quando converted é true, o objeto order traz todos os detalhes do pedido, incluindo se foi pago (is_paid), itens comprados, frete, desconto e endereço.

{
  "success": true,
  "hash": "65d50610774b3836f10b56323b7b7b1e",
  "origin": "whatsapp",
  "is_converted": true,
  "customer": {
    "first_name": "Arthur", "last_name": "Marubayashi",
    "email": "arthur@email.com", "phone": "11987654321",
    ...
  },
  "items": [ { "sku": "8119803", "qty": 1 }, ... ],
  "converted": true,
  "order": {
    "increment_id": "1000285526",
    "status": "pending", "state": "new",
    "is_paid": false, "total_paid": 0,
    "grand_total": 1169.65, "subtotal": 1207,
    "shipping_amount": 23, "discount_amount": -60.35,
    "coupon_code": "BLACKFRIDAY10", "currency": "BRL",
    "payment_method": "pagarme_pix",
    "items": [
      {
        "sku": "8119803", "name": "Bio-Acne Solution...",
        "qty": 1, "price": 131, "row_total": 131,
        "discount": 6.55
      }, ...
    ],
    "shipping_address": { ... },
    "tracking": [],
    "order_created_at": "2026-06-12 17:58:00",
    "converted_at": "2026-06-12 17:58:00"
  }
}

4.4. Resposta — não convertida (HTTP 200)

{
  "success": true,
  "hash": "769bbcda0540b5c0af58d0b0b0c4bd66",
  "origin": "whatsapp",
  "is_converted": false,
  "customer": { ... },
  "items": [ ... ],
  "converted": false,
  "order": null
}

5. Consultar produtos (POST)

Permite consultar, antes de criar a recomendação, se um ou mais SKUs existem, estão ativos e quais são seus dados de exibição (nome, descrições, preço e URL) para um determinado grupo de cliente.

5.1. Campos do corpo (JSON)

5.2. Exemplo de requisição

{
  "skus": [
    "8119704",
    "8119609"
  ],
  "group": "P"
}

5.3. Resposta de sucesso (HTTP 200)

O campo products retorna um item por SKU consultado, indicando se foi encontrado (found) e se está ativo (status), além dos dados de exibição do produto para o grupo informado.

{
  "success": true,
  "group": "P",
  "store_id": 1,
  "total": 1,
  "products": [
    {
      "sku": "8119933",
      "found": true,
      "status": true,
      "type": "simple",
      "name": "BIO.MASK CANDY GANACHE",
      "short_description": "Bio.Mask Candy Ganache máscara facial, ajuda a reduzir a aparência das linhas finas e rugas, e promove ação antioxidante, e hidrata profundamente de forma duradoura e deixa a pele iluminada e rejuvenescida.",
      "description": "Bio.Mask Candy Ganache máscara facial, desenvolvida com Niacinamide e Acido Ferulico, que juntos ajudam a reduzir a aparência das linhas finas e rugas, e promovem ação antioxidante. Pentavitin®, que hidrata profundamente de forma duradoura, e Glowcitocin, para uma pele iluminada e rejuvenescida.",
      "price": 142,
      "special_price": 99,
      "url": "http://bioagedevpro.com.br/bio-mask-candy-ganache"
    }
  ]
}

6. Códigos de status HTTP

7. Exemplos de respostas de erro

7.1. Token inválido — HTTP 401

{
  "success": false,
  "code": 401,
  "message": "Token inválido ou usuário inativo."
}

7.2. Dados inválidos — HTTP 422

O campo errors lista todos os problemas encontrados de uma só vez:

{
  "success": false,
  "code": 422,
  "message": "Dados inválidos.",
  "errors": [
    "O campo 'E-mail' está inválido.",
    "O campo 'CPF' está inválido.",
    "O campo 'CEP' deve ter 8 dígitos.",
    "Item 2: o campo 'qty' deve ser maior que zero."
  ]
}

7.3. Corpo vazio — HTTP 400

{
  "success": false,
  "code": 400,
  "message": "Body da requisição está vazio."
}