Basis

Appearance

Localização ​

Endpoints públicos e somente-leitura para consulta de países, estados e cidades. Eles são usados para montar seletores de endereço no cadastro de clientes e no cálculo de frete.

Todos os endpoints retornam listas no formato value / label, prontas para alimentar componentes de seleção (selects) no frontend.

Formato da Resposta

Cada item da lista possui value (o ID do registro, como string) e label (o nome legível). Use o value como countryId e stateId nas consultas seguintes.

Listar Países [public] ​

Retorna a lista de todos os países disponíveis.

http
GET /v1/shop/countries/public

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
searchstringNãoFiltra países pelo nome (máx. 100 caracteres).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/shop/countries/public?search=Brazil" \
  -H "X-Shop-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna a lista de países no formato value / label.

json
[
  {
    "value": "1",
    "label": "Afghanistan"
  },
  {
    "value": "31",
    "label": "Brazil"
  },
  {
    "value": "236",
    "label": "United States"
  }
]

Listar Estados [public] ​

Retorna a lista de estados, opcionalmente filtrada por país.

http
GET /v1/shop/states/public

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
countryIdnumberNãoFiltra estados pelo ID do país.
searchstringNãoFiltra estados pelo nome (máx. 100 caracteres).

Exemplo de Requisição ​

javascript
fetch('https://api.us.basis.tavares.in/v1/shop/states/public?countryId=31', {
  headers: {
    'X-Shop-Id': '123e4567-e89b-12d3-a456-426614174000',
    'Accept': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Respostas ​

200 OK

Retorna a lista de estados no formato value / label.

json
[
  {
    "value": "230",
    "label": "São Paulo"
  },
  {
    "value": "231",
    "label": "Rio de Janeiro"
  },
  {
    "value": "232",
    "label": "Minas Gerais"
  }
]

422 Unprocessable Entity

Erro de validação nos parâmetros enviados.

json
{
  "errors": [
    {
      "message": "Identificador do país é inválido",
      "rule": "number",
      "field": "countryId"
    }
  ]
}

Listar Cidades [public] ​

Retorna a lista de cidades, com filtros opcionais por país e estado.

http
GET /v1/shop/cities/public

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
countryIdnumberNãoFiltra cidades pelo ID do país.
stateIdnumberNãoFiltra cidades pelo ID do estado.
searchstringNãoFiltra cidades pelo nome (máx. 100 caracteres).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/shop/cities/public?countryId=31&stateId=230" \
  -H "X-Shop-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna a lista de cidades no formato value / label.

json
[
  {
    "value": "23",
    "label": "São Paulo"
  },
  {
    "value": "54",
    "label": "Campinas"
  },
  {
    "value": "79",
    "label": "Santos"
  }
]