Carrinho — API Pública v1

Endpoints para manipular o carrinho de compras (cart), seus itens, serviços associados e brindes (gifts).

Base URL

https://{sua-loja}/api/v1/public/

O identificador do carrinho é um UUID retornado pelo servidor. Um carrinho é válido enquanto tiver status ∈ open, declined, budget, notified.

Todas as respostas retornam o objeto completo do pedido (OrderSerializer), útil para o cliente sincronizar o estado após cada operação.

`GET /order/` e `GET /order/{uuid}/`

Retorna o carrinho atual. Quando uuid é omitido, a API tenta resolver o carrinho pela sessão (request.cart); quando informado, carrega pelo UUID.

Exemplo

curl "https://sua-loja.com/api/v1/public/order/49b395eb-331f-4f3a-8a9d-eeb4c08548be/"

Resposta `200 OK`

O payload representa o estado completo do checkout. Os principais blocos:

Campo	Tipo	Descrição
`uuid`	`string`	UUID do carrinho.
`is_logged`	`bool`	Se existe um cliente autenticado na sessão.
`is_register`	`bool`	Se a sessão está em fluxo de cadastro.
`can_edit`	`bool`	Se o carrinho pode ser editado (`false` p.ex. em pedidos já notificados).
`trade`	`int	null`
`order_minimum_value`	`bool	number`
`messages`	`array`	Avisos (`{level, message}`).
`customer`	`object`	Dados do cliente (mascarados quando `can_edit=false`). Ver abaixo.
`address`	`object`	Endereço de entrega atualmente selecionado.
`addresses`	`array`	Todos os endereços disponíveis ao cliente. `id` pode ser `"P"` (endereço principal) ou um ID numérico.
`totalizers`	`object`	`total_price`, `total_payment`, `discount`, `payment_discount`, `interest`, `shipping_total`, `weight`, `quantity`.
`items`	`array`	Itens do carrinho. Ver abaixo.
`coupons`	`array`	Cupons aplicados.
`shipping_info`	`object`	`freights[]`, `selected`, `zipcode`.
`payment_data`	`object`	`payments[]` (métodos), `saved_cards[]`, `giftcards[]`.
`localization`	`object`	`code`, `name`, `prefix`, `language_code`, separadores.
`config`	`object`	Flags de config expostas (ex.: `customer_credit_balance`).
`seller`	`object`	Opcional. Presente apenas quando a sessão tem um seller vinculado.

`customer`

Quando can_edit=false, campos sensíveis são mascarados pelo servidor (name, document, phone). Campos típicos:

{
  "uuid": "511e9c46-9a7c-43d8-be05-1634497cc340",
  "name": "Car***** Tar****",
  "email": "[email protected]",
  "document": "***********",
  "phone": "******7676",
  "phone2": null,
  "fancy_name": null,
  "corporate_name": null,
  "corporate_document": null,
  "inscricao_estadual": null,
  "inscricao_estadual_isento": false,
  "birthdate": null,
  "gender": null,
  "newsletter": 0,
  "group_id": null,
  "is_valid": true
}

`addresses[]` / `address`

{
  "id": "P",
  "title": "",
  "receiver": "Car***** *******",
  "zipcode": "****5163",
  "address": "AL *** ******LOS",
  "number": "***",
  "complement": null,
  "neighborhood": "JD *****",
  "reference": null,
  "city": "SOR*****",
  "city_id": "****",
  "state": "SP",
  "code_ibge": "*******",
  "phone": "******7676",
  "can_edit": false,
  "is_valid": true
}

id = "P" identifica o endereço principal do cliente; os demais usam o PK numérico do Address.
Endereços temporários de sessão incluem session_key: true|false.

`items[]`

Cada item é um CartItem serializado:

{
  "id": 755030,
  "sku": 18161,
  "product": 23503,
  "sku_reference": "1034977",
  "sku_name": "Kit Medidor de Glicemia ...",
  "name": "Kit Medidor de Glicemia ...",
  "brand": "Accu-Chek",
  "image": "//io.convertiez.com.br/m/.../small/...jpg",
  "url": "/accu-chek-guide-kit/p",
  "categories": ["Saúde", "Espaço para Diabéticos", "Fita e Aparelhos de Glicemia"],
  "quantity": 1.0,
  "unit_multiplier": 1.0,
  "unit_price": 102.59,
  "sku_unit_price": 102.59,
  "sku_sale_price": null,
  "discount_unit_price": 102.59,
  "total_price": 102.59,
  "discount": 0.0,
  "unit_discount": 0.0,
  "discount_value": 102.59,
  "manual_price": null,
  "loyalty_price": null,
  "measurement_unit": null,
  "sku_options": [],
  "sku_modals": null,
  "sku_availability": null,
  "available": true,
  "is_gift": false,
  "is_subscription": false,
  "seals": ["<p class=\"seal-pix ...\">R$ 100,54</p>"],
  "services_items": [],
  "selected_services": [],
  "shipping_type": null,
  "shipping_name": null,
  "shipping_total": null,
  "delivery_time": null,
  "messages": [],
  "errors": false
}

Campos shipping_* no item só são preenchidos quando o frete é calculado por item (fulfillment split). seals pode conter HTML já renderizado com os selos promocionais.

`shipping_info`

{
  "zipcode": "18055163",
  "selected": {
    "shipping_type": "gratis",
    "shipping_name": "Grátis",
    "shipping_address": "P",
    "shipping_delivery_date": "2026-04-09",
    "shipping_scheduled_date": null,
    "scheduled_deliveries_times": null,
    "delivery_time": "1",
    "time_format": "d",
    "pickup": null,
    "pickup_store": null,
    "total": 0.0
  },
  "freights": [ /* ... */ ]
}

Cada frete em freights[] pode ter um shape ligeiramente diferente dependendo do conector (Correios, motoboy, pickup, logística interna). Campos comuns:

Campo	Descrição
`service`	Código interno (ex.: `PAC`, `Sedex`, `gratis`, `CLICK_RETIRE`, `MotoBoy`, `LetsExpress`). É esse valor que deve ser enviado em `freight` no `POST /order/{uuid}/freights/`.
`label`	Nome amigável para exibir.
`absolute_value`	Valor cobrado (string, em `pt_BR`).
`original_absolute_value`	Valor original antes de descontos.
`delivery_time`	Prazo estimado (em `time_format`: `d` = dias, `h` = horas).
`time_format`	`d` ou `h`.
`original_delivery_time`	Prazo original antes de ajustes.
`choice_auto`	Se o frete pode ser auto-selecionado.
`flag`	`D` (desconto/default), `S` (standard).
`logo`	URL (ou caminho relativo) do logo do carrier.
`pickup_store`	`true` em fretes do tipo "clique e retire".
`pickups`	Array de IDs de lojas de retirada (quando `pickup_store=true`).
`scheduled_deliveries_times`	Janelas de agendamento disponíveis (quando aplicável).
`dock` / `dock_stock`	Metadados de logística interna.
`api`	`true` quando o frete vem de integração externa síncrona.

`payment_data`

{
  "payments": [
    {
      "group": "CartaoDeCredito",
      "name": "Cartão de Crédito",
      "template": "CartaoDeCredito",
      "description": "",
      "cards": [
        {
          "id": 4,
          "name": "Visa",
          "regex": "^4",
          "code_regex": "^[0-9]{3}$",
          "mask": "0000 0000 0000 0000",
          "code_mask": "000",
          "weights": [2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2],
          "installments": [
            { "parcel": 1, "value": 102.59, "total": 102.59, "interest_rate": 0.0 },
            { "parcel": 2, "value": 51.30,  "total": 102.59, "interest_rate": 0.0 }
          ]
        }
      ]
    },
    { "group": "PIX", "id": 12, "name": "PIX", "template": "Intermediary", "description": "<div>...</div>" },
    { "group": "CartaoDeDebito", "name": "Cartão de Débito", "template": "CartaoDeDebito", "cards": [ /* ... */ ] }
  ],
  "saved_cards": [
    { "token": "45b4ba2a-...", "remote_id": null, "card_mask": "Terminado em 8429", "flag": "Mastercard" }
  ],
  "giftcards": []
}

payments[].group é o valor que deve ser enviado em POST /order/{uuid}/payment-data/ e POST /order/{uuid}/payments/.
template identifica a UI associada. Intermediary indica métodos que pedem confirmação externa (ex.: PIX, boleto).
cards[].regex / code_regex / mask / code_mask / weights permitem ao cliente validar e formatar o cartão antes do envio.
saved_cards[].token é o UUID usado em payments[].token ao processar pagamentos com cartão salvo.

`totalizers`

{
  "total_price": 102.59,
  "total_payment": 102.59,
  "shipping_total": 0.0,
  "discount": 0.0,
  "payment_discount": 0.0,
  "interest": 0.0,
  "weight": 0.31,
  "quantity": 1.0
}

`localization`

{
  "code": "BRL ",
  "name": "BRL ",
  "prefix": "R$",
  "language_code": "pt_BR",
  "thousand_separator": ".",
  "decimal_separator": ","
}

Exemplo completo (resumido)

{
  "uuid": "49b395eb-331f-4f3a-8a9d-eeb4c08548be",
  "is_logged": false,
  "is_register": false,
  "can_edit": false,
  "trade": null,
  "order_minimum_value": false,
  "messages": [],
  "customer": { "uuid": "...", "email": "[email protected]", "name": "Car***** Tar****", "...": "..." },
  "address": { "id": "P", "...": "..." },
  "addresses": [ { "id": "P", "...": "..." }, { "id": "504", "...": "..." } ],
  "items": [ { "id": 755030, "sku": 18161, "quantity": 1.0, "total_price": 102.59, "...": "..." } ],
  "coupons": [],
  "totalizers": { "total_price": 102.59, "total_payment": 102.59, "...": "..." },
  "shipping_info": { "zipcode": "18055163", "selected": { "...": "..." }, "freights": [ /* ... */ ] },
  "payment_data": { "payments": [ /* ... */ ], "saved_cards": [ /* ... */ ], "giftcards": [] },
  "localization": { "code": "BRL ", "prefix": "R$", "...": "..." },
  "config": { "customer_credit_balance": false }
}

Nota sobre mascaramento: quando can_edit=false, dados pessoais (name, document, phone, campos de endereço) vêm mascarados no servidor. Isso é esperado e serve para expor um carrinho "read-only" sem vazar PII. Para obter dados legíveis o cliente precisa estar autenticado e com permissão de edição.

`PATCH /order/{uuid}/`

Esvazia o carrinho (remove todos os itens) e retorna o objeto atualizado.

Código	Significado
`200`	Carrinho esvaziado.
`404`	Carrinho não encontrado.

`POST /order/` e `POST /order/{uuid}/`

Atualiza o carrinho: adiciona SKUs/produtos, define CEP, associa cliente, aplica política de preço (tr), vincula lista de presente (giftlist), etc.

Body

{
  "zipcode": "01310-100",
  "tr": "12",
  "profile_id": "uuid-do-customer",
  "giftlist": 45,
  "skus": [
    { "sku": 12345, "quantity": 2, "update": false, "price": 79.90 }
  ],
  "products": [
    { "product": 5678, "quantity": 1, "options": [11, 22] }
  ]
}

Campo	Tipo	Descrição
`zipcode`	`string`	CEP de entrega. Apenas dígitos ou com máscara — pontuação é removida.
`tr`	`string` (int)	ID da `TradePolitic` para recalcular tabela de preços.
`profile_id`	`string` (UUID)	Associa um `Customer` ao carrinho.
`giftlist`	`int`	Vincula uma lista de presentes publicada.
`skus[]`	`array`	Lista de SKUs a adicionar. `quantity` default `1`. `update=true` substitui a quantidade em vez de somar. `price` só é aceito quando a sessão tem um seller com `add_manual_value=true`.
`products[]`	`array`	Alternativa a `skus`: informa `product` e `options` (IDs da grade) quando o produto tem variações.

Erros possíveis

Retornos incluem messages, um array de objetos {"level": "ERROR", "message": "..."}:

O SKU informado não existe
O Produto informado não existe
Selecione uma opção. (produto com grade sem options)
Há somente {n} itens em estoque disponível.
Não é possível adicionar o produto com este valor. (quando o preço manual está abaixo do min_seller_sale_price)
Cliente não encontrado.
Lista de presente não encontrada.

`PUT /order/{uuid}/{item_pk}/`

Atualiza um item do carrinho. Usado para mudar quantidade, preço manual (quando permitido) ou anexar serviços ao item.

Body

{
  "quantity": 3,
  "unit_price": 59.90,
  "service": 12,
  "services": [
    { "service": 12, "fields": { "id": "value" } }
  ]
}

Campo	Descrição
`quantity`	Nova quantidade. Default `1`.
`unit_price`	Só é aceito quando a sessão tem `seller.add_manual_value=true`.
`service`	ID de um `SKUService` a ser adicionado ao item.
`services[]`	Lista de serviços com campos customizados.

Erros comuns

Selecione no máximo {n} unidade(s). (quando excede sku.max_buy)
A quantidade selecionada não está disponível no momento.
Alteração de valor inválida. (preço abaixo do mínimo)

`DELETE /order/{uuid}/{item_pk}/`

Remove um item do carrinho. Retorna o carrinho atualizado.

`POST /order/{uuid}/services/`

Adiciona serviços a múltiplos itens do carrinho de uma só vez.

Body

[
  {
    "id": 101,
    "service": 12,
    "fields": [
      { "id": "42", "value": "gravação personalizada" }
    ]
  }
]

id é o ID do CartItem, service é o ID do SKUService, fields são os campos customizados do serviço.

`DELETE /order/{uuid}/services/`

Remove serviços dos itens. Body com o mesmo formato ([ { "id", "service" } ]).

`PUT /order/{uuid}/{item_id}/service/{pk}/`

Atualiza um ServiceItem específico (ex.: altera os valores dos campos customizados de um serviço já vinculado).

Body

{
  "fields": {
    "field-42": { "value": "novo valor" }
  }
}

Erros

Tipo de arquivo inválido. Apenas imagens ou PDFs são permitidos.
O arquivo deve ter no máximo 4MB.

`DELETE /order/{uuid}/{item_id}/service/{pk}/`

Remove o serviço do item. Se o item ficar sem serviços e existir outro item compatível no mesmo carrinho, eles são fundidos automaticamente.

`GET /order/{uuid}/{item_id}/{offer_id}/gift/`

Lista as opções de brinde disponíveis para um item, dada uma oferta (type_offer=12).

Resposta

{
  "id": 77,
  "name": "Brinde grátis",
  "description": "...",
  "quantity": 1,
  "gifts": [
    {
      "id": 999,
      "name": "Produto X",
      "sku_name": "Produto X - P",
      "image": "https://.../media/...",
      "url": "/produto-x/p",
      "available": true,
      "selected": false
    }
  ]
}

`POST /order/{uuid}/{item_id}/{offer_id}/gift/`

Consome a oferta de brinde, adicionando o(s) SKU(s) escolhido(s) ao carrinho.

Body

{ "items": [999, 1000] }

Retorna o carrinho atualizado ou, em caso de falha, o dicionário da oferta com a mensagem de erro.

Observações gerais

Todos os endpoints de carrinho retornam o objeto completo do pedido após a operação, incluindo messages com avisos/erros de nível ERROR / SUCCESS.
O cliente deve sempre atualizar seu estado local com a resposta do servidor — regras de estoque, descontos e promoções são aplicadas do lado do servidor.
Operações financeiras (payment_discount, payment_interest) são zeradas automaticamente ao atualizar itens, cupons ou serviços — o cliente precisa recalcular pagamento depois.

Carrinho — API Pública v1

GET /order/ e GET /order/{uuid}/

Exemplo

Resposta 200 OK

customer

addresses[] / address

items[]

shipping_info

payment_data

totalizers

localization

Exemplo completo (resumido)

PATCH /order/{uuid}/

POST /order/ e POST /order/{uuid}/

Body

Erros possíveis

PUT /order/{uuid}/{item_pk}/

Body

Erros comuns

DELETE /order/{uuid}/{item_pk}/

POST /order/{uuid}/services/

Body

DELETE /order/{uuid}/services/

PUT /order/{uuid}/{item_id}/service/{pk}/

Body

Erros

DELETE /order/{uuid}/{item_id}/service/{pk}/

GET /order/{uuid}/{item_id}/{offer_id}/gift/

Resposta

POST /order/{uuid}/{item_id}/{offer_id}/gift/

Body

Observações gerais

`GET /order/` e `GET /order/{uuid}/`

Resposta `200 OK`

`customer`

`addresses[]` / `address`

`items[]`

`shipping_info`

`payment_data`

`totalizers`

`localization`

`PATCH /order/{uuid}/`

`POST /order/` e `POST /order/{uuid}/`

`PUT /order/{uuid}/{item_pk}/`

`DELETE /order/{uuid}/{item_pk}/`

`POST /order/{uuid}/services/`

`DELETE /order/{uuid}/services/`

`PUT /order/{uuid}/{item_id}/service/{pk}/`

`DELETE /order/{uuid}/{item_id}/service/{pk}/`

`GET /order/{uuid}/{item_id}/{offer_id}/gift/`

`POST /order/{uuid}/{item_id}/{offer_id}/gift/`