# Carrinhos

> Carrinhos compartilháveis que fecham no WhatsApp

- Página: https://tbit.app/pt/docs/api/carts
- URL base: `https://rest-api.tbit.app/v1`
- Autenticação: cabeçalho `X-API-Key` com a sua chave em cada requisição (os exemplos a leem da variável de ambiente `TBIT_API_KEY`)

## Visão geral

Os carrinhos permitem que um visitante da sua loja monte uma lista de produtos e a leve para uma conversa no WhatsApp com todo o contexto. Um carrinho é um retrato de curta duração: recebe um código de 7 caracteres, vale por 90 dias e é imutável: para mudá-lo, crie um novo.

## Como o fluxo funciona

1. Um visitante da sua loja monta uma lista de produtos.
2. A sua loja cria um carrinho com POST /v1/carts e recebe um código curto.
3. Você envia ao visitante um link como https://<sua-loja>/c/<código> pelo WhatsApp.
4. Quando a conversa começa, o seu agente já tem todo o contexto do que o visitante escolheu.

## Endpoints

| Método | Rota | Descrição |
| --- | --- | --- |
| `POST` | `/v1/carts` | Criar um carrinho compartilhável |
| `GET` | `/v1/carts/:code` | Resolver um carrinho pelo código |

## Criar um carrinho

Envie de 1 a 50 itens, cada um referenciando um id de produto com um qty entre 1 e 99. A resposta é o código curto do carrinho:

`POST /v1/carts`

```bash
curl -X POST "https://rest-api.tbit.app/v1/carts" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "prod_id_1",
        "qty": 2
      },
      {
        "id": "prod_id_2",
        "qty": 1
      }
    ]
  }'
```

Resposta:

```json
{
  "data": {
    "code": "K3F9X2A"
  }
}
```

## Obter um carrinho

Resolve um código de volta para os seus itens, cada um com o objeto produto completo mais qty. Os carrinhos são isolados por conta: uma chave só resolve carrinhos criados para o seu próprio agente; qualquer outro caso retorna 404:

`GET /v1/carts/K3F9X2A`

```bash
curl "https://rest-api.tbit.app/v1/carts/K3F9X2A" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Resposta:

```json
{
  "data": {
    "code": "K3F9X2A",
    "created_at": "2024-09-01T12:00:00Z",
    "items": [
      {
        "_id": "prod_id_1",
        "kind": "product",
        "title": "Kit fiesta dinosaurios",
        "currency": "COP",
        "base_price": 95000,
        "qty": 2
      },
      {
        "_id": "prod_id_2",
        "kind": "product",
        "title": "Piñata dinosaurio",
        "currency": "COP",
        "base_price": 45000,
        "qty": 1
      }
    ]
  }
}
```

## Notas

- Os códigos têm 7 caracteres.
- Os carrinhos valem por 90 dias.
- Os carrinhos são imutáveis: crie um novo para mudar os itens.
- Carrinhos de outros agentes (ou códigos desconhecidos) retornam 404.