Basis

Appearance

Fretes ​

As taxas de frete definem quanto custa entregar os produtos da loja em cada região. O lojista configura taxas por país, estado ou cidade — do mais genérico ao mais específico — e o comprador consulta se há frete disponível para o endereço dele.

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

Endpoints do Comprador ​

Endpoints voltados para o checkout da loja, onde o comprador verifica a disponibilidade de entrega.

Consultar Frete por Cidade ​

Verifica se existe uma taxa de frete ativa para a cidade informada, considerando taxas específicas de cidade, estado, país ou globais (sem localização definida).

http
GET /v1/shop/customer/shipping-rates/has

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
cityIdnumberSimID da cidade de entrega.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/shop/customer/shipping-rates/has?cityId=10" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna a taxa de frete aplicável ao endereço.

json
{
  "id": "9",
  "countryId": "1",
  "stateId": null,
  "cityId": null,
  "price": "12.00",
  "isActive": true,
  "createdAt": "2026-06-24T22:22:06.190+00:00",
  "updatedAt": "2026-06-24T22:22:06.190+00:00",
  "country": {
    "id": "1",
    "name": "Brasil",
    "coordinates": {
      "x": -51.92528,
      "y": -14.235004
    }
  },
  "state": null,
  "city": null
}

404 Not Found

Ocorre quando não há frete disponível para o endereço informado.

json
{
  "errors": [
    {
      "message": "Not available for this address"
    }
  ]
}

Endpoints Administrativos ​

Endpoints protegidos para o lojista configurar as taxas de frete da loja.

Listar Taxas de Frete ​

Retorna uma lista paginada das taxas de frete configuradas.

http
GET /v1/shop/user/shipping-rates

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, cityId, stateId, price ou createdAt.
orderDirectionenumNãoasc ou desc.
countryIdnumberNãoFiltra por país.
stateIdnumberNãoFiltra por estado.
cityIdnumberNãoFiltra por cidade.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/shop/user/shipping-rates?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 as taxas e metadados.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": "2",
      "countryId": null,
      "stateId": null,
      "cityId": null,
      "price": "15.00",
      "isActive": true,
      "createdAt": "2026-06-24T20:07:08.022+00:00",
      "updatedAt": "2026-06-24T20:07:08.022+00:00",
      "city": null
    },
    {
      "id": "1",
      "countryId": null,
      "stateId": null,
      "cityId": "40",
      "price": "8.80",
      "isActive": true,
      "createdAt": "2026-06-24T20:05:29.574+00:00",
      "updatedAt": "2026-06-24T20:05:29.574+00:00",
      "city": {
        "id": "40",
        "name": "São Paulo",
        "coordinates": {
          "x": -46.633309,
          "y": -23.55052
        }
      }
    }
  ]
}

Criar Taxa de Frete ​

Cria uma nova taxa de frete. Os campos de localização são opcionais — uma taxa sem localização funciona como frete global (padrão) da loja. Não é permitido cadastrar duas taxas para a mesma configuração de localização.

http
POST /v1/shop/user/shipping-rates

Payload (Body) ​

AtributoTipoObrigatórioDescrição
countryIdnumberNãoID do país. Pode ser null.
stateIdnumberNãoID do estado (deve pertencer ao país informado). Pode ser null.
cityIdnumberNãoID da cidade (deve pertencer ao estado/país informado). Pode ser null.
pricenumberSimValor do frete (positivo).
isActivebooleanSimIndica se a taxa está ativa.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/shop/user/shipping-rates" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "countryId": 1,
    "stateId": null,
    "cityId": null,
    "price": 12,
    "isActive": true
  }'

Respostas ​

201 Created

Retorna o ID da taxa criada.

json
{
  "id": "2"
}

422 Unprocessable Entity

Ocorre quando já existe uma taxa de frete para a mesma configuração de localização.

json
{
  "errors": [
    {
      "message": "Já existe uma taxa de frete para essa configuração"
    }
  ]
}

Obter Taxa de Frete ​

Recupera os detalhes de uma taxa de frete, incluindo país, estado e cidade.

http
GET /v1/shop/user/shipping-rates/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimID da taxa de frete.

Respostas ​

200 OK

Retorna os dados da taxa de frete.

json
{
  "id": "7",
  "countryId": "1",
  "stateId": "12",
  "cityId": "37",
  "price": "15.00",
  "isActive": true,
  "createdAt": "2026-06-24T22:10:11.020+00:00",
  "updatedAt": "2026-06-24T22:10:11.020+00:00",
  "country": {
    "id": "1",
    "name": "Brasil",
    "coordinates": {
      "x": -51.92528,
      "y": -14.235004
    }
  },
  "city": {
    "id": "37",
    "name": "São Paulo",
    "coordinates": {
      "x": -46.633309,
      "y": -23.55052
    }
  },
  "state": {
    "id": "12",
    "name": "São Paulo",
    "coordinates": {
      "x": -46.633309,
      "y": -23.55052
    }
  }
}

404 Not Found

Ocorre quando a taxa de frete não existe na loja.

Buscar por Localização ​

Localiza a taxa de frete correspondente a uma combinação de país, estado e cidade.

http
GET /v1/shop/user/shipping-rates/find-by-location

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
countryIdnumberNãoID do país.
stateIdnumberNãoID do estado.
cityIdnumberNãoID da cidade.

Exemplo de Requisição ​

javascript
fetch('https://api.us.basis.tavares.in/v1/shop/user/shipping-rates/find-by-location?countryId=1&stateId=12&cityId=34', {
  headers: {
    'Authorization': 'Bearer {token}',
    'X-Shop-Id': '00000000-0000-4000-8000-000000000000'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Respostas ​

200 OK

Retorna a taxa de frete encontrada para a localização.

json
{
  "id": "4",
  "countryId": "1",
  "stateId": "12",
  "cityId": null,
  "price": "15.00",
  "isActive": true,
  "createdAt": "2026-06-24T22:04:17.344+00:00",
  "updatedAt": "2026-06-24T22:04:17.344+00:00",
  "city": null,
  "country": {
    "id": "1",
    "name": "Brasil",
    "coordinates": {
      "x": -51.92528,
      "y": -14.235004
    }
  },
  "state": {
    "id": "12",
    "name": "São Paulo",
    "coordinates": {
      "x": -46.633309,
      "y": -23.55052
    }
  }
}

Atualizar Taxa de Frete ​

Atualiza uma taxa de frete existente.

http
PUT /v1/shop/user/shipping-rates/:id

Payload (Body) ​

AtributoTipoObrigatórioDescrição
countryIdnumberNãoID do país. Pode ser null.
stateIdnumberNãoID do estado. Pode ser null.
cityIdnumberNãoID da cidade. Pode ser null.
pricenumberSimValor do frete (positivo).
isActivebooleanSimIndica se a taxa está ativa.

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/shop/user/shipping-rates/2" \
  -H "Authorization: Bearer {token}" \
  -H "X-Shop-Id: 00000000-0000-4000-8000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "countryId": 7,
    "stateId": null,
    "cityId": null,
    "price": 15,
    "isActive": true
  }'

Respostas ​

204 No Content

Taxa de frete atualizada com sucesso.

Remover Taxa de Frete ​

Exclui uma taxa de frete da loja.

http
DELETE /v1/shop/user/shipping-rates/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.