Basis

Appearance

Pedidos ​

Os pedidos representam as cotações de compra geradas pelos clientes da loja, com produtos, variantes, endereço de entrega e totais. O lojista acompanha tudo pelo painel administrativo, incluindo gráficos de evolução e ranking de produtos, enquanto o comprador cria e consulta seus próprios pedidos.

Todas as requisições devem incluir o header X-Shop-Id (UUID) e, por serem protegidas, o header Authorization: Bearer {token}.

Estrutura de Dados Principal ​

Um pedido contém as seguintes informações principais:

CampoTipoDescrição
hashUUIDIdentificador público único do pedido.
totalDecimalValor total do pedido.
shippingTotalDecimalValor do frete aplicado.
discountTotalDecimalValor total de descontos.
phoneStringTelefone de contato para entrega.
shippingZipcodeStringCEP de entrega.
shopCustomerObjectDados do cliente que fez o pedido.
shopQuoteProductsArrayProdutos do pedido, com unidades e preços.
shopQuoteProductVariantsArrayVariantes de produtos do pedido.

Endpoints do Comprador ​

Endpoints para o comprador criar e acompanhar seus próprios pedidos na loja.

Criar Pedido ​

Cria um novo pedido com endereço de entrega, produtos e variantes.

http
POST /v1/shop/customer/quotes

Payload (Body) ​

AtributoTipoObrigatórioDescrição
location.cityIdnumberSimID da cidade de entrega.
location.phonestringSimTelefone de contato (máx. 50 caracteres).
location.shippingZipcodestringSimCEP de entrega (máx. 50 caracteres).
location.shippingStreetstringSimRua de entrega (máx. 150 caracteres).
location.shippingNumberstringSimNúmero do endereço (máx. 100 caracteres).
location.shippingComplementstringSimComplemento (máx. 100 caracteres).
location.shippingNeighborhoodstringSimBairro (máx. 100 caracteres).
productsarraySimItens com id do produto e units (inteiro positivo).
productVariantsarrayNãoVariantes com id e units (inteiro positivo). Pode ser null.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/shop/customer/quotes" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {
      "cityId": 10,
      "shippingZipcode": "03461000",
      "shippingStreet": "Rua das Flores",
      "shippingNumber": "513",
      "shippingComplement": "Apto 101",
      "shippingNeighborhood": "Centro",
      "phone": "5511987654321"
    },
    "products": [
      { "units": 29, "id": 1 },
      { "units": 2, "id": 2 }
    ],
    "productVariants": [
      { "units": 1, "id": 1 }
    ]
  }'

Respostas ​

201 Created

Retorna o ID do pedido criado.

json
{
  "id": "4"
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

json
{
  "errors": [
    {
      "message": "Cidade não localizada",
      "rule": "database.exists",
      "field": "location.cityId"
    }
  ]
}

Listar Meus Pedidos ​

Retorna uma lista paginada dos pedidos do comprador autenticado.

http
GET /v1/shop/customer/quotes

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
pagenumberNãoNúmero da página (mín. 1).
perPagenumberNãoItens por página (máx. 100).
orderByenumNãoid, total ou createdAt.
orderDirectionenumNãoasc ou desc.
fromdateNãoData inicial no formato YYYY-MM-DD.
todateNãoData final no formato YYYY-MM-DD.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/shop/customer/quotes?page=1&perPage=25" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna um objeto de paginação contendo os pedidos e metadados.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": "1",
      "shopCustomerId": "2",
      "stateId": "3",
      "cityId": "10",
      "hash": "00000000-0000-4000-8000-000000000000",
      "total": "296.80",
      "shippingTotal": "12.00",
      "discountTotal": "0.00",
      "phone": "5511987654321",
      "shippingZipcode": "03461000",
      "createdAt": "2026-07-01T16:27:41.846+00:00",
      "updatedAt": "2026-07-01T16:27:41.846+00:00",
      "shopCustomer": {
        "id": "2",
        "firstName": "Maria",
        "lastName": "Silva",
        "email": "cliente@exemplo.com"
      },
      "city": {
        "id": "10",
        "name": "São Paulo"
      },
      "state": {
        "id": "3",
        "name": "São Paulo"
      }
    }
  ]
}

Obter Pedido ​

Recupera os detalhes completos de um pedido, incluindo endereço, produtos e variantes.

http
GET /v1/shop/customer/quotes/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimID do pedido.

Respostas ​

200 OK

Retorna os dados completos do pedido.

json
{
  "id": "1",
  "shopCustomerId": "2",
  "stateId": "3",
  "cityId": "10",
  "countryId": "1",
  "hash": "00000000-0000-4000-8000-000000000000",
  "total": "296.80",
  "shippingTotal": "12.00",
  "discountTotal": "0.00",
  "phone": "5511987654321",
  "shippingZipcode": "03461000",
  "shippingStreet": "Rua das Flores",
  "shippingNumber": "513",
  "shippingComplement": "Apto 101",
  "shippingNeighborhood": "Centro",
  "createdAt": "2026-07-01T16:27:41.846+00:00",
  "updatedAt": "2026-07-01T16:27:41.846+00:00",
  "shopQuoteProducts": [
    {
      "id": "1",
      "shopQuoteId": "1",
      "shopProductId": "1",
      "units": 29,
      "price": "0.00",
      "shopProduct": {
        "id": "1",
        "name": "Camiseta Básica",
        "sku": null,
        "price": "8.90"
      }
    }
  ],
  "shopQuoteProductVariants": [
    {
      "id": "1",
      "shopQuoteId": "1",
      "shopProductVariantId": "1",
      "units": 1,
      "price": "0.00",
      "shopProductVariant": {
        "id": "1",
        "name": "Camiseta Básica - Tamanho M",
        "sku": null,
        "price": "8.90"
      }
    }
  ]
}

404 Not Found

Ocorre quando o pedido não existe ou não pertence ao comprador autenticado.

Endpoints Administrativos ​

Endpoints protegidos para o lojista acompanhar os pedidos da loja e analisar relatórios.

Listar Pedidos ​

Retorna uma lista paginada de todos os pedidos da loja, com filtros por cliente, localização e período.

http
GET /v1/shop/user/quotes

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
pagenumberNãoNúmero da página (mín. 1).
perPagenumberNãoItens por página (máx. 100).
orderByenumNãoid, total ou createdAt.
orderDirectionenumNãoasc ou desc.
shopCustomerIdnumberNãoFiltra por cliente.
stateIdnumberNãoFiltra por estado de entrega.
cityIdnumberNãoFiltra por cidade de entrega.
fromdateNãoData inicial no formato YYYY-MM-DD.
todateNãoData final no formato YYYY-MM-DD.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/shop/user/quotes?page=1&perPage=25" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna um objeto de paginação contendo os pedidos e metadados.

json
{
  "meta": {
    "currentPage": "1",
    "perPage": "25"
  },
  "data": [
    {
      "id": "10",
      "shopCustomerId": "2",
      "stateId": "3",
      "cityId": "10",
      "hash": "00000000-0000-4000-8000-000000000000",
      "total": "296.80",
      "shippingTotal": "12.00",
      "discountTotal": "0.00",
      "phone": "5511987654321",
      "shippingZipcode": "03461000",
      "createdAt": "2026-06-02T20:21:23.215+00:00",
      "updatedAt": "2026-07-02T20:21:23.215+00:00",
      "city": {
        "id": "10",
        "name": "São Paulo"
      },
      "state": {
        "id": "3",
        "name": "São Paulo"
      },
      "shopCustomer": {
        "id": "2",
        "firstName": "Maria",
        "lastName": "Silva",
        "email": "cliente@exemplo.com"
      }
    }
  ]
}

Obter Pedido ​

Recupera os detalhes completos de um pedido, incluindo cliente, endereço e itens.

http
GET /v1/shop/user/quotes/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimID do pedido.

Respostas ​

200 OK

Retorna os dados completos do pedido, com cliente, localização e itens.

404 Not Found

Ocorre quando o pedido não existe na loja.

Gráfico de Evolução ​

Retorna a quantidade de pedidos agrupada por período, ideal para gráficos de evolução temporal.

http
GET /v1/shop/user/quotes/chart-evolution

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
groupByenumSimAgrupamento: day, week ou month.
fromdateNãoData inicial no formato YYYY-MM-DD.
todateNãoData final no formato YYYY-MM-DD.
shopCustomerIdnumberNãoFiltra por cliente.
stateIdnumberNãoFiltra por estado de entrega.
cityIdnumberNãoFiltra por cidade de entrega.

Respostas ​

200 OK

Retorna um array com a data e a quantidade de pedidos por período.

json
[
  {
    "date": "2026-05-01",
    "quotes": 3
  },
  {
    "date": "2026-06-01",
    "quotes": 2
  },
  {
    "date": "2026-07-01",
    "quotes": 4
  }
]

Gráfico de Ranking de Produtos ​

Retorna os produtos mais pedidos da loja, com contagens de pedidos, itens e unidades.

http
GET /v1/shop/user/quotes/chart-products-ranking

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
limitnumberNãoQuantidade máxima de produtos no ranking (máx. 10).
fromdateNãoData inicial no formato YYYY-MM-DD.
todateNãoData final no formato YYYY-MM-DD.

Respostas ​

200 OK

Retorna um array com o ranking de produtos.

json
[
  {
    "shopProductId": 1,
    "name": "Camiseta Básica",
    "sku": null,
    "quotesCount": 9,
    "itemsCount": 9,
    "units": 261
  },
  {
    "shopProductId": 2,
    "name": "Caneca Personalizada",
    "sku": null,
    "quotesCount": 9,
    "itemsCount": 9,
    "units": 18
  }
]

Remover Pedido ​

Exclui um pedido da loja.

http
DELETE /v1/shop/user/quotes/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.