API legada/Referência completa/Áreas de entrega

Ler áreas de entrega

Lista e consulta as áreas de entrega (destinations) da loja na API legada.

Esta página traz as duas leituras de áreas de entrega. Para o conceito, veja a home da seção.

Listar áreas

Devolve as áreas de entrega da loja, com filtro opcional por tipo e status.

GET/api/v1.0/destinationsAdmin

Listar áreas de entrega

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de consulta

typestring

shippingtax

Filtra pelo tipo da área. Um valor desconhecido devolve lista vazia.

statusstring

ADHNP

Filtra pelo status, em letra. Uma letra desconhecida vale A.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/destinations?type=shipping&status=A"

Resposta

200Áreas devolvidas

json

{
  "destinations": [
    {
      "destination_id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
      "destination": "Norte",
      "status": "A",
      "countries": [
        "BR"
      ],
      "states": [
        {
          "state_code": "AC",
          "country_code": "BR"
        },
        {
          "state_code": "AM",
          "country_code": "BR"
        }
      ],
      "cities": [],
      "districts": [],
      "zipcodes": ""
    }
  ],
  "params": {
    "total_items": 1
  }
}

Campos da resposta

destinations[].destination_idstring

Id da área (UUID).

destinations[].destinationstring

Nome da área, por exemplo Norte ou Grande São Paulo.

destinations[].statusstring

AD

A ativa, D desativada.

destinations[].countriesarray

Códigos de país (ISO) cobertos pela área.

destinations[].statesarray

Estados cobertos. Cada item tem state_code e country_code.

destinations[].citiesarray

Cidades cobertas, cada uma como {"city_id": "..."}.

destinations[].districtsarray

Bairros cobertos, cada um como {"district_id": "..."}.

destinations[].zipcodesstring

Faixas ou padrões de CEP da área, um por linha; vazio se a área não usa CEP.

params.total_itemsinteger

Quantidade de áreas devolvidas.

Erros

Status	Quando	Corpo
401	Sem credenciais ou chave inválida	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	O usuário não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
500	Falha ao consultar	`{"error":"query rate areas: ..."}`

Consultar uma área

Devolve uma área pelo id.

GET/api/v1.0/destinations/{id}Admin

Consultar uma área de entrega

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de caminho

idstringobrigatório

Id da área (UUID).

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/destinations/7bce1201-0e92-49d1-8e25-846f35fa697e"

Resposta

200Área devolvida

json

{
  "destination_id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
  "destination": "Norte",
  "status": "A",
  "countries": [
    "BR"
  ],
  "states": [
    {
      "state_code": "AC",
      "country_code": "BR"
    },
    {
      "state_code": "AM",
      "country_code": "BR"
    }
  ],
  "cities": [],
  "districts": [],
  "zipcodes": ""
}

Os campos são os mesmos de cada item da listagem, sem o envelope destinations.

Erros

Status	Quando	Corpo
401	Sem credenciais ou chave inválida	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	O usuário não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	A área não existe	`{"error":"Destination not found"}`
500	Id que não é um UUID, ou falha ao consultar	`{"error":"query rate area ...: ..."}`

Veja também

API legada/Referência completa/Áreas de entrega

Ler áreas de entrega

Lista e consulta as áreas de entrega (destinations) da loja na API legada.

Esta página traz as duas leituras de áreas de entrega. Para o conceito, veja a home da seção.

Listar áreas

Devolve as áreas de entrega da loja, com filtro opcional por tipo e status.

GET/api/v1.0/destinationsAdmin

Listar áreas de entrega

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de consulta

typestring

shippingtax

Filtra pelo tipo da área. Um valor desconhecido devolve lista vazia.

statusstring

ADHNP

Filtra pelo status, em letra. Uma letra desconhecida vale A.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/destinations?type=shipping&status=A"

Resposta

200Áreas devolvidas

json

{
  "destinations": [
    {
      "destination_id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
      "destination": "Norte",
      "status": "A",
      "countries": [
        "BR"
      ],
      "states": [
        {
          "state_code": "AC",
          "country_code": "BR"
        },
        {
          "state_code": "AM",
          "country_code": "BR"
        }
      ],
      "cities": [],
      "districts": [],
      "zipcodes": ""
    }
  ],
  "params": {
    "total_items": 1
  }
}

Campos da resposta

destinations[].destination_idstring

Id da área (UUID).

destinations[].destinationstring

Nome da área, por exemplo Norte ou Grande São Paulo.

destinations[].statusstring

AD

A ativa, D desativada.

destinations[].countriesarray

Códigos de país (ISO) cobertos pela área.

destinations[].statesarray

Estados cobertos. Cada item tem state_code e country_code.

destinations[].citiesarray

Cidades cobertas, cada uma como {"city_id": "..."}.

destinations[].districtsarray

Bairros cobertos, cada um como {"district_id": "..."}.

destinations[].zipcodesstring

Faixas ou padrões de CEP da área, um por linha; vazio se a área não usa CEP.

params.total_itemsinteger

Quantidade de áreas devolvidas.

Erros

Status	Quando	Corpo
401	Sem credenciais ou chave inválida	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	O usuário não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
500	Falha ao consultar	`{"error":"query rate areas: ..."}`

Consultar uma área

Devolve uma área pelo id.

GET/api/v1.0/destinations/{id}Admin

Consultar uma área de entrega

Autenticação: HTTP Basic com e-mail:chave_de_api de um administrador, ou Authorization: Bearer <JWT>.

Parâmetros de caminho

idstringobrigatório

Id da área (UUID).

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/destinations/7bce1201-0e92-49d1-8e25-846f35fa697e"

Resposta

200Área devolvida

json

{
  "destination_id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
  "destination": "Norte",
  "status": "A",
  "countries": [
    "BR"
  ],
  "states": [
    {
      "state_code": "AC",
      "country_code": "BR"
    },
    {
      "state_code": "AM",
      "country_code": "BR"
    }
  ],
  "cities": [],
  "districts": [],
  "zipcodes": ""
}

Os campos são os mesmos de cada item da listagem, sem o envelope destinations.

Erros

Status	Quando	Corpo
401	Sem credenciais ou chave inválida	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	O usuário não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	A área não existe	`{"error":"Destination not found"}`
500	Id que não é um UUID, ou falha ao consultar	`{"error":"query rate area ...: ..."}`