API atual/Referência completa/Mini-loja WhatsApp: sacola e checkout

Endereços do cliente

Lista, salva e apaga os endereços de entrega da conta do cliente, a mesma agenda usada na loja e no checkout.

A agenda de endereços fica na conta do cliente (a mesma tabela da loja online): salvar no WhatsApp faz o endereço aparecer no site e o contrário também. Por isso só existe agenda para cliente identificado. Um visitante recebe 200 com account_required: true e uma lista vazia, para o front-end seguir com um endereço digitado na hora em vez de mostrar erro.

No checkout, o cliente pode mandar o endereço completo no corpo ou apenas o saved_address_id de um item desta agenda. Veja Fechar o pedido.

Listar os endereços

GET/api/v1/storefront/wa-coex/addresses/{token}Pública

Lista a agenda de endereços do cliente, o principal primeiro

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/addresses/$TOKEN"

Resposta

200Cliente identificado com um endereço

json

{
  "addresses": [
    {
      "id": "5a0e8c2c-3f3b-4f5e-9d62-0c1f3b7a9a10",
      "label": "Casa",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Apto 52",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zip": "01310100",
      "reference": "Portão azul",
      "is_default": true
    }
  ],
  "edit_locked": false,
  "account_type": "pf"
}

200Visitante sem conta

json

{ "account_required": true, "addresses": [] }

Campos da resposta

addressesarray

Endereços da conta, o principal primeiro e depois os mais recentes. [] quando não há ou quando falta conta.

account_requiredboolean

true só quando o token não tem conta identificada (nesse caso as outras chaves não vêm).

edit_lockedboolean

true quando a regra da loja para este tipo de conta proíbe criar, editar e apagar endereços. O cliente ainda pode escolher um endereço já cadastrado.

account_typestring

pfpj

Tipo da conta: pessoa física ou jurídica. É o que decide a trava de edição.

Campos de cada endereço

iduuid

Id do endereço.

labelstring

Apelido dado pelo cliente (Casa, Trabalho). Vazio quando o cliente não deu um; os rótulos automáticos antigos (shipping, home, Endereço Padrão) são devolvidos vazios.

streetstring

Logradouro.

numberstring

Número.

complementstring

Complemento.

districtstring

Bairro.

citystring

Cidade.

statestring

UF, 2 letras.

zipstring

CEP, 8 dígitos, sem hífen.

referencestring

Ponto de referência.

is_defaultboolean

É o endereço principal da conta.

Erros

Status	Quando	Corpo
503	Não foi possível ler a agenda.	`{"error":"addresses_unavailable"}`

Salvar um endereço

POST/api/v1/storefront/wa-coex/addresses/{token}Pública

Cria ou atualiza um endereço da agenda

Serve para criar e para editar. Mandou id de um endereço da conta: atualiza. Sem id (ou com um id que não é UUID ou é de outra conta): cria e devolve o id definitivo. O front-end deve adotar o id devolvido.

Regras que surpreendem:

O primeiro endereço da conta vira principal sozinho. A conta nunca fica sem principal.
Mandar o mesmo CEP, número e complemento de um endereço que a conta já tem reaproveita a linha existente, sem criar cópia, e mantém o apelido e a referência que ela já tinha se você não enviou outros.
Cidade e bairro são normalizados para a grafia oficial do catálogo da plataforma.
Um id que o cliente já apagou não volta: a resposta é {"deleted": true}.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

iduuid

Id do endereço a atualizar. Ausente cria.

labelstring

Apelido (Casa, Trabalho).

streetstringobrigatório

Logradouro.

numberstring

Número. S/N ou sem número valem como sem número.

complementstring

Complemento.

districtstring

Bairro.

citystringobrigatório

Cidade.

statestringobrigatório

UF. Em minúsculas é convertida; mais de 2 letras é cortada em 2.

zipstringobrigatório

CEP com 8 dígitos. Hífen e outros símbolos são removidos.

referencestring

Ponto de referência.

is_defaultbooleanpadrão: false

Tornar este o endereço principal.

O corpo aceita no máximo 8 KB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/addresses/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Casa","street":"Avenida Paulista","number":"1000","complement":"Apto 52","district":"Bela Vista","city":"São Paulo","state":"SP","zip":"01310-100"}'

Resposta

200Endereço salvo

json

{
  "address": {
    "id": "5a0e8c2c-3f3b-4f5e-9d62-0c1f3b7a9a10",
    "label": "Casa",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Apto 52",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zip": "01310100",
    "is_default": true
  }
}

200Sem conta ou endereço já apagado

json

{ "account_required": true }

Quando o endereço já foi apagado, a resposta é {"deleted": true}. O objeto address tem os campos de Listar os endereços.

Erros

Status	Quando	Corpo
400	Corpo ilegível ou maior que 8 KB.	`{"error":"invalid_body"}`
403	A regra da loja para este tipo de conta proíbe criar ou editar endereço e o enviado não é um dos já cadastrados.	`{"error":"address_edit_blocked","message":"...","account_type":"pj"}`
422	Falta `street`, `city` ou `state`, ou o CEP não tem 8 dígitos.	`{"error":"invalid_address"}`
503	Falha ao gravar.	`{"error":"addresses_unavailable"}`

Apagar um endereço

DELETE/api/v1/storefront/wa-coex/addresses/{token}/{addressID}Pública

Apaga um endereço da agenda

Quando o apagado era o principal e sobra outro endereço, o mais recente é promovido a principal. O id apagado não volta: uma cópia velha no aparelho do cliente que o salvar de novo é ignorada. Apagar um endereço que já não existe, ou um id que não é UUID, responde 200 do mesmo jeito.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

addressIDstringobrigatório

Id do endereço (UUID).

Resposta

200Endereço apagado

json

{ "deleted": true }

Sem conta identificada a resposta é {"account_required": true}.

Erros

Status	Quando	Corpo
403	A regra da loja para este tipo de conta proíbe apagar endereço.	`{"error":"address_edit_blocked","message":"...","account_type":"pj"}`
503	Falha ao apagar.	`{"error":"addresses_unavailable"}`

Veja também

API atual/Referência completa/Mini-loja WhatsApp: sacola e checkout

Endereços do cliente

Lista, salva e apaga os endereços de entrega da conta do cliente, a mesma agenda usada na loja e no checkout.

No checkout, o cliente pode mandar o endereço completo no corpo ou apenas o saved_address_id de um item desta agenda. Veja Fechar o pedido.

Listar os endereços

GET/api/v1/storefront/wa-coex/addresses/{token}Pública

Lista a agenda de endereços do cliente, o principal primeiro

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/addresses/$TOKEN"

Resposta

200Cliente identificado com um endereço

json

{
  "addresses": [
    {
      "id": "5a0e8c2c-3f3b-4f5e-9d62-0c1f3b7a9a10",
      "label": "Casa",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Apto 52",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zip": "01310100",
      "reference": "Portão azul",
      "is_default": true
    }
  ],
  "edit_locked": false,
  "account_type": "pf"
}

200Visitante sem conta

json

{ "account_required": true, "addresses": [] }

Campos da resposta

addressesarray

Endereços da conta, o principal primeiro e depois os mais recentes. [] quando não há ou quando falta conta.

account_requiredboolean

true só quando o token não tem conta identificada (nesse caso as outras chaves não vêm).

edit_lockedboolean

true quando a regra da loja para este tipo de conta proíbe criar, editar e apagar endereços. O cliente ainda pode escolher um endereço já cadastrado.

account_typestring

pfpj

Tipo da conta: pessoa física ou jurídica. É o que decide a trava de edição.

Campos de cada endereço

iduuid

Id do endereço.

labelstring

Apelido dado pelo cliente (Casa, Trabalho). Vazio quando o cliente não deu um; os rótulos automáticos antigos (shipping, home, Endereço Padrão) são devolvidos vazios.

streetstring

Logradouro.

numberstring

Número.

complementstring

Complemento.

districtstring

Bairro.

citystring

Cidade.

statestring

UF, 2 letras.

zipstring

CEP, 8 dígitos, sem hífen.

referencestring

Ponto de referência.

is_defaultboolean

É o endereço principal da conta.

Erros

Status	Quando	Corpo
503	Não foi possível ler a agenda.	`{"error":"addresses_unavailable"}`

Salvar um endereço

POST/api/v1/storefront/wa-coex/addresses/{token}Pública

Cria ou atualiza um endereço da agenda

Regras que surpreendem:

O primeiro endereço da conta vira principal sozinho. A conta nunca fica sem principal.
Mandar o mesmo CEP, número e complemento de um endereço que a conta já tem reaproveita a linha existente, sem criar cópia, e mantém o apelido e a referência que ela já tinha se você não enviou outros.
Cidade e bairro são normalizados para a grafia oficial do catálogo da plataforma.
Um id que o cliente já apagou não volta: a resposta é {"deleted": true}.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

iduuid

Id do endereço a atualizar. Ausente cria.

labelstring

Apelido (Casa, Trabalho).

streetstringobrigatório

Logradouro.

numberstring

Número. S/N ou sem número valem como sem número.

complementstring

Complemento.

districtstring

Bairro.

citystringobrigatório

Cidade.

statestringobrigatório

UF. Em minúsculas é convertida; mais de 2 letras é cortada em 2.

zipstringobrigatório

CEP com 8 dígitos. Hífen e outros símbolos são removidos.

referencestring

Ponto de referência.

is_defaultbooleanpadrão: false

Tornar este o endereço principal.

O corpo aceita no máximo 8 KB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/addresses/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Casa","street":"Avenida Paulista","number":"1000","complement":"Apto 52","district":"Bela Vista","city":"São Paulo","state":"SP","zip":"01310-100"}'

Resposta

200Endereço salvo

json

{
  "address": {
    "id": "5a0e8c2c-3f3b-4f5e-9d62-0c1f3b7a9a10",
    "label": "Casa",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Apto 52",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zip": "01310100",
    "is_default": true
  }
}

200Sem conta ou endereço já apagado

json

{ "account_required": true }

Quando o endereço já foi apagado, a resposta é {"deleted": true}. O objeto address tem os campos de Listar os endereços.

Erros

Status	Quando	Corpo
400	Corpo ilegível ou maior que 8 KB.	`{"error":"invalid_body"}`
403	A regra da loja para este tipo de conta proíbe criar ou editar endereço e o enviado não é um dos já cadastrados.	`{"error":"address_edit_blocked","message":"...","account_type":"pj"}`
422	Falta `street`, `city` ou `state`, ou o CEP não tem 8 dígitos.	`{"error":"invalid_address"}`
503	Falha ao gravar.	`{"error":"addresses_unavailable"}`

Apagar um endereço

DELETE/api/v1/storefront/wa-coex/addresses/{token}/{addressID}Pública

Apaga um endereço da agenda

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

addressIDstringobrigatório

Id do endereço (UUID).

Resposta

200Endereço apagado

json

{ "deleted": true }

Sem conta identificada a resposta é {"account_required": true}.

Erros

Status	Quando	Corpo
403	A regra da loja para este tipo de conta proíbe apagar endereço.	`{"error":"address_edit_blocked","message":"...","account_type":"pj"}`
503	Falha ao apagar.	`{"error":"addresses_unavailable"}`