Uma série de endpoints são disponibilizados para manipular o carrinho de compras da sessão ativa.

Alguns plugins foram criados (como o canopus.js - clique aqui para ver mais detalhes) para facilitar a chamada desses endpoints e poupar algum trabalho de quem está implementando os layouts. Entretanto, eles não são obrigatórios e projetos específicos podem requerer algum outro nível de implementação. Para isso, os endpoints a seguir podem ser chamados:

• Adicionando itens ao carrinho
• Removendo itens do carrinho
• Limpando o carrinho
• Atualizando itens do carrinho
• Adicionando campos extras relacionados à venda e assinatura
• Removendo campos extras relacionados à venda e assinatura
• Editando campos extras relacionados à venda e assinatura
• Manipulando modelos de recorrência do carrinho

Adicionando itens ao carrinho

[GET] /checkout/cart/{type}/add/{id}

Onde:

• {type} é o tipo do objeto a ser incluído no carrinho, sendo os seguintes valores possíveis:
  • item quando o objeto for um item vendável do tipo produto ou serviço;
  • plan quando o objeto for um plano de assinatura;
• {id} é o número de identificação do objeto a ser incluído no carrinho. Ele deverá ser um inteiro válido e existente;

Os parâmetros a seguir podem ser passados para a requisição como parte do endpoint (query string):

• quantity valor numérico, mínimo 1 e que deve ser preenchido se informado. Caso omitido, recebe o valor 1 por padrão e indica a quantidade do objeto informado no parâmetro {id} deverá ser incluída no carrinho.
• extra_fields array com N representações de objeto de campos extras e valores para os mesmos a serem incluídos no item no carrinho de compras. Os mesmos serão associados aos itens da venda no momento da finalização da compra.
  O seguinte formato para cada representação de objeto deve ser respeitado:
  • slug indicando qual o campo extra a ser incluído;
  • value indicando qual o campo extra deverá receber;
• components array com N representações de objeto de componentes para o item a ser adicionado ao carrinho de compras.
  O seguinte formato para cada representação de objeto deve ser respeitado:
  • componentization_group_id deverá ser um inteiro válido e existente, indicando qual o grupo de componentização corresponde o componente a ser informado a seguir em component_id;
  • component_id deverá ser um inteiro válido e existente, indicando qual o componente do grupo de componentização informado no parâmetro componentization_group_id;
  • quantity valor numérico, mínimo 1 e que deve ser preenchido se informado, indicando qual a quantidade do componente informado em component_id deve ser incluída;
• redirect_to URL para redirecionar o usuário após o término do processamento (não é válido para chamadas via AJAX)

Removendo itens do carrinho

[GET] /checkout/cart/{type}/remove/{id}

Onde:

• {type} é o tipo do objeto a ser removido do carrinho, sendo os seguintes valores possíveis:
  • item quando o objeto for um item vendável do tipo produto ou serviço;
  • plan quando o objeto for um plano de assinatura;
• {id} é o número de identificação do objeto a ser removido do carrinho. Ele deverá ser um inteiro válido e existente;

Caso o mesmo ID/tipo conste em mais de um item no carrinho (por exemplo no caso de ter o mesmo produto com variações ou campos extras diferentes), o parâmetro row_id poderá ser informado para especificar qual item deverá ser manipulado. Exemplo:

[GET] /checkout/cart/{type}/remove/{id}?row_id={row id}

Limpando o carrinho

[GET|DELETE] /checkout/cart/remove

Este endpoint poderá ser chamado através dos verbos GET ou DELETE, via ajax ou redirecionamento e então removerá todos os itens do carrinho, independente do tipo.

Atualizando itens do carrinho

[GET] /checkout/cart/{type}/update/{id}?quantity=1234

Onde:

• {type} é o tipo do objeto a ser removido do carrinho, sendo os seguintes valores possíveis:
  • item quando o objeto for um item vendável do tipo produto ou serviço;
  • plan quando o objeto for um plano de assinatura;
• {id} é o número de identificação do objeto a ser removido do carrinho. Ele deverá ser um inteiro válido e existente;
• quantity deve ter como valor a quantidade desejada para atualizar o item do carrinho.

Caso o mesmo ID/tipo conste em mais de um item no carrinho (por exemplo no caso de ter o mesmo produto com variações ou campos extras diferentes), o parâmetro row_id poderá ser informado para especificar qual item deverá ser manipulado. Exemplo:

[GET] /checkout/cart/{type}/update/{id}?quantity=1234&row_id={row id}

Adicionando campos extras relacionados à venda e assinatura

Alguns projetos pedem que os clientes informem dados adicionais à venda para complementar informações da mesma. Para isso, a partir da existência de um (ou mais) campo extra relacionado a um formulário da entidade de Vendas, pode-se adicionar os valores diretamente ao carrinho.

[POST] /checkout/cart/properties

Para isso, uma requisição do tipo POST deverá ser feita para o endpoint acima e com os dados do campo extra e seu valor, como no formato do exemplo a seguir, feito com jQuery:

$.post(
    '/checkout/cart/properties',
    {
        extra_fields: [
            {slug: 'slug-do-campo-extra-1', value: 'valor do campo extra'},
            {slug: 'slug-do-campo-extra-2', value: 29.99}
        ]
    }
);

Dessa forma, ao finalizar a venda a plataforma se encarregará de associar o(s) valor(s) ao(s) campo(s) extra da venda assim que a mesma for finalizada.

Removendo campos extras relacionados à venda e assinatura

[DELETE] /checkout/cart/properties

Para remover algum valor de campo extra previamente enviado às propriedades do carrinho, uma requisição do tipo DELETE deverá ser enviada para o endpoint acima passando como parâmetro os slugs de cada campo extra a ser removido. A seguir um exemplo feito com jQuery:

$.ajax({
    url: '/checkout/cart/properties',
    method: 'DELETE',
    data: {
        extra_fields: [
            {slug: 'slug-do-campo-extra-1'},
            {slug: 'slug-do-campo-extra-2'}
        ]
    }
});

Editando campos extras relacionados à venda e assinatura

Os valores não podem ser editados. Faz-se necessário que os mesmos sejam removidos e adicionados novamente.

Manipulando modelos de recorrência do carrinho

É possível transformar carrinhos em vendas recorrentes. Essas vendas darão origem a um plano que obrigatoriamente deverá ser "filho" de algum modelo de recorrência previamente cadastrado (veja como cadastrar modelos de recorrência aqui).

[POST] /checkout/cart/properties

Para adicionar a propriedade de modelo de recorrência a um carrinho, enviar uma requisição do tipo POST para o endpoint acima passando o id do plano (modelo de recorrência) na propriedade recurent_as. Abaixo um exemplo criado com jQuery:

$.post(
    '/checkout/cart/properties',
    {
        recurrent_as: 123456 // recurrency model id
    }
);

Para editar o modelo de recorrência o mesmo endpoint pode ser utilizado e, respeitando o mesmo padrão do body, podem ser enviados (1) o id de outro modelo de recorrência ou (2) o valor null indicando que nenhum modelo de recorrência deverá ser utilizado.