Pular para o conteúdo principal

Integração do Carrinho

Visão Geral​

Toda a integração de carrinho da Widde Pro roda no front-end da loja.
Esse desenho foi pensado para:

  • Aproveitar cookies e sessão já existentes do e-commerce (login, carrinho, antifraude, preferências);
  • Evitar trafegar cookies do usuário por servidores da Widde (privacidade e compliance);
  • Executar tudo no navegador do próprio cliente, chamando diretamente a API do seu e-commerce (sem proxy/servidor Widde).

Quando a Widde está integrada, o browser do comprador aciona os endpoints da sua plataforma para ler e alterar o carrinho. A Widde apenas orquestra essas chamadas no front-end (Web Components/JS), sem passar por nenhum servidor nosso.

Requisitos gerais dos seus endpoints

  • Acessíveis pelo navegador (mesma origem ou CORS restrito ao domínio da loja);
  • Autenticação por cookie/sessão já usada pela sua loja;
  • Suporte a CSRF quando aplicável (token via meta/header/endpoint público);
  • Respostas em JSON, com status HTTP semânticos (2xx/4xx/5xx).

Contratos (Tipos de apoio)​

export interface ICartItem {
  readonly id: string;
  readonly name: string;
  readonly price: Price;
  quantity: number;
  readonly productId: string;
  readonly mainImage: string;
  readonly cartItemId?: string;
}

export interface ICart extends DomainEntity {
  readonly total: Price;
  readonly totalItems: number;
  readonly items: ICartItem[];
}

export interface ICartAddResult {
  success: boolean;
  refetch?: boolean;
  error?: {
    causes: string[];
  };
}

export namespace CartInputs {
  export interface Add {
    product: Product;
    quantity: number;
    cartId?: string;
    variantSelecteds?: Array<string>;
  }
  export interface ProductInfo {
    externalId: string;
    url: string;
  }
}

export interface ICart {
  getCartInfo(): Promise<Cart>;
  addItem(data: CartInputs.Add): Promise<ICartAddResult>;
  removeAllOfItem(item: CartItem): Promise<boolean>;
  getProductInfo(product: CartInputs.ProductInfo): Promise<Product>;
}

Observação: Os tipos Cart, CartItem e Product devem refletir os objetos da sua plataforma. Mínimos recomendados

  • Cart: id, items: CartItem[], totals (itemsSubtotal, discountTotal, shippingTotal, taxTotal, grandTotal), currency, coupon?, checkoutUrl?.
  • CartItem: lineId, externalId/sku/variantId, title, image, url, quantity, price, subtotal.
  • Product: externalId, title, url, mainImage, price, comparePrice?, variants?[] (id, label, inStock).

Métodos (o que cada um precisa expor)​

1) getCartInfo(): Cart​

O que é: Endpoint que retorna o estado atual do carrinho do cliente (associado à sessão/cookies). Quando chamamos:

  • Na montagem dos blocos de compra;
  • Após operações que pedirem refetch;
  • Para reidratar UI (quantidades, totais, cupom, frete).

Requisitos do seu lado:

  • Retornar Cart completo e consistente com o estado do servidor;
  • Operação idempotente e rápida (cache local/edge é bem-vindo).

Sugerido (REST):

GET / cart;
// Response: Cart

2) addItem(data: CartInputs.Add): ICartAddResult​

O que é: Endpoint para adicionar um item ao carrinho. Entrada mínima:

  • product.externalId ou product.sku/variantId (conforme sua chave canônica);
  • quantity;
  • variantSelecteds?[] (ex.: ["tamanho:M","cor:Azul"]) quando aplicável;
  • cartId? caso sua plataforma exija.

Retorno: ICartAddResult

  • success: boolean — operação concluída;
  • refetch?: boolean — true sinaliza que devemos chamar getCartInfo() para recalcular UI/totais;
  • error?.causes: string[] — lista de erros legíveis e/ou códigos (ex.: "OUT_OF_STOCK", "INVALID_VARIANT").

Boas práticas do seu lado:

  • Mesclar somas quando o mesmo produto/variante já existir na mesma linha (regra comum de carrinhos);
  • Validar estoque e regras de quantidade mínima/máxima;
  • Retornar mensagens claras em error.causes.

Sugerido (REST):

POST /cart/items
Body: {
externalId: "prod_123",
variantId: "var_M",
quantity: 2,
properties: { color: "Blue" }
}
// Response: { success: true, refetch: true }

3) removeAllOfItem(item: CartItem) ​

O que é: Endpoint para remover completamente uma linha do carrinho. Entrada mínima: item.lineId (ou chave equivalente para identificar a linha). Retorno: true para sucesso; false em caso de falha.

Boas práticas do seu lado:

  • Operação idempotente (remover duas vezes não deve quebrar);
  • Recalcular totais/cupom após remoção.

Sugerido (REST):

DELETE / cart / items /:itemId;
// Response: 200 OK (pode retornar { success: true } em JSON)

4) getProductInfo(product: CartInputs.ProductInfo) ​

O que é: Endpoint para consultar informações do produto (preço vigente, disponibilidade, variações) antes do addItem. Entrada mínima: externalId ou url do produto. Retorno: Product com campos suficientes para UI (nome, preço, imagem, variantes, disponibilidade).

Boas práticas do seu lado:

  • Garantir retorno atualizado com estoque/variações;
  • Incluir comparePrice? quando existir preço “de/por”.

Sugerido (REST):

GET /products/:externalId
// Response: Product

Tabela-resumo dos endpoints esperados​

AçãoMétodoCaminho sugeridoEntradaSaída
Ler carrinhoGET/cart—Cart
Adicionar itemPOST/cart/itemsexternalId/sku/variantId, quantityICartAddResult
Remover item (linha)DELETE/cart/items/:lineIdlineIdboolean | success
Info de produtoGET/products/:externalIdexternalId (ou via query por url)Product

Observação: Os caminhos são sugestões; nomes/rotas podem variar. O essencial é manter a semântica e os campos.

Erros e Status HTTP​

  • 422 Unprocessable Entity: validação (ex.: quantidade inválida, variante inexistente);
  • 409 Conflict: conflito de estoque/regra;
  • 401/403: autenticação/CSRF;
  • 5xx: falhas internas.

Padronize error.causes em ICartAddResult, por exemplo:

  • "OUT_OF_STOCK", "INVALID_VARIANT", "INVALID_QUANTITY", "PRODUCT_NOT_FOUND",
  • "MIN_QTY_NOT_MET", "MAX_QTY_EXCEEDED", "CART_CLOSED".

Segurança & Navegador​

  • Cookies/Sessão: toda auth vem do domínio da loja (não da Widde);
  • CSRF: exponha forma de obter token pelo navegador (meta tag, endpoint público, etc.);
  • CORS: se necessário, habilite apenas para o domínio da loja;
  • Rate limiting: aplique por sessão/IP conforme suas políticas.

Checklist de Homologação​

  • getCartInfo retorna Cart completo de forma estável e rápida;
  • addItem respeita estoque/regras e retorna ICartAddResult (com refetch quando necessário);
  • removeAllOfItem remove por lineId de forma idempotente;
  • getProductInfo reflete preço/estoque/variantes atuais;
  • Endpoints acessíveis via navegador com cookies da loja;
  • CSRF/CORS documentados;
  • Respostas em JSON com status HTTP semânticos.

Suporte​

Dúvidas técnicas e homologação: 📧 [email protected]