Atualizar um endereço

Atualize os dados de um endereço já cadastrado a partir do seu identificador único (addr_*). Use para corrigir um logradouro digitado errado, completar um cadastro parcial ou normalizar o CEP depois de validar a entrega. Esta operação substitui o endereço completo, então envie todos os campos que devem permanecer.

PUT /v1/addresses/{addressId}

Como funciona

Este endpoint usa semântica de PUT (substituição total), não de patch parcial. Na prática:

• Você identifica o endereço pelo addressId no caminho da URL.
• O corpo da requisição descreve o estado final do endereço.
• Campos opcionais que você não enviar voltam ao valor padrão/vazio — não há mesclagem com o que estava salvo antes. Por isso, antes de atualizar, busque o registro atual com Consultar endereço e reenvie todos os campos que precisam continuar existindo.

O servidor valida o corpo (em especial country e postcode), grava as alterações e atualiza o updatedAt para o momento da operação. O createdAt permanece inalterado. A resposta é o objeto de endereço completo no nível raiz, acompanhado de merchant e dos links HATEOAS (_links) — exatamente o mesmo formato de Consultar e Criar.

Algumas observações importantes sobre o que não muda por aqui:

• O proprietário do endereço (ownerType/ownerId) e a flag de principal (primary) não são alterados por este contrato público. Para trocar o endereço principal de um cliente, gerencie pelo recurso do proprietário.
• O escopo é multi-tenant: você só consegue atualizar endereços que pertencem à sua conta (merchant). Um addressId de outra conta responde como inexistente (404).

Quando usar

Use a atualização quando o endereço já existe e você só precisa ajustar os dados:

• Correção de logradouro, número ou CEP digitados errado.
• Mudança de endereço do cliente para um novo local.
• Enriquecimento de um cadastro parcial (ex.: adicionar bairro e complemento).
• Padronização após validar o CEP junto a um serviço de consulta.

Quando não usar:

• Para cadastrar um endereço novo, use Criar endereço (POST).
• Para remover definitivamente, use Excluir endereço (DELETE).
• Para apenas conferir os dados, use Consultar endereço (GET).

Requisição

Headers

Parâmetros de caminho

Corpo da requisição

Exemplo de requisição:

curl -X PUT "https://api.selectwin.io/v1/addresses/addr_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 6f9c2a1e-7b3d-4e2a-9c11-2f0a1b8c4d55" \
  -d '{
    "street": "Av. Paulista",
    "number": "1000",
    "complement": "Apt 42",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR",
    "postcode": "01310-100"
  }'

Resposta

Em caso de sucesso, o servidor responde com 200 OK e o objeto de endereço atualizado no nível raiz, com merchant e _links. O updatedAt reflete o momento da atualização.

{
  "id": "addr_01hqzvabc",
  "ownerType": "customer",
  "ownerId": "cus_01hqzvabc",
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Apt 42",
  "district": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "BR",
  "postcode": "01310100",
  "latitude": null,
  "longitude": null,
  "primary": true,
  "line": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP, 01310100",
  "line1": "Av. Paulista",
  "line2": "1000",
  "line3": "Bela Vista",
  "metadata": null,
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/addresses/addr_01hqzvabc",
      "method": "GET",
      "description": "Read a address."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/addresses",
      "method": "POST",
      "description": "Create a new address."
    },
    "update": {
      "href": "https://api.selectwin.io/v1/addresses/addr_01hqzvabc",
      "method": "PUT",
      "description": "Update the address."
    },
    "delete": {
      "href": "https://api.selectwin.io/v1/addresses/addr_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the address."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/addresses",
      "method": "GET",
      "description": "List all addresses."
    }
  }
}

Campos da resposta

Diferente das listagens, que devolvem projeções leves de cada item, a resposta de atualização traz o objeto completo — o mesmo formato de Consultar e Criar.

Erros

A API responde com o envelope padrão de erro e um error.code estável. Trate sempre pelo error.code, não pela message. Veja Tratamento de erros e o Catálogo de códigos.

Exemplo de validação (400), com detalhamento por campo em error.params:

{
  "error": {
    "code": "invalidParameters",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      { "country": "This field is required." },
      { "postcode": "This field is required." }
    ]
  }
}

Exemplo de endereço inexistente (404):

{
  "error": {
    "code": "addressIdNotFound",
    "statusCode": 404,
    "category": "client",
    "message": "Address not found."
  }
}

Boas práticas

• Consulte antes de atualizar. Como o PUT substitui o objeto, busque o estado atual com Consultar endereço e reenvie todos os campos que devem permanecer — evita apagar complement, district e afins por omissão.
• Sempre envie os obrigatórios. Inclua country e postcode em toda atualização, mesmo que não tenham mudado, ou a requisição falhará com invalidParameters.
• Valide o CEP localmente contra ^\d{5}-?\d{3}$ antes de enviar; aceite com ou sem hífen e normalize. Isso reduz idas e vindas com 400.
• Use X-Idempotency-Key para que repetições por timeout/retry não causem efeito duplicado. Veja Idempotência.
• Trate addressIdNotFound e invalidParameters explicitamente na sua integração; faça fallback por error.statusCode para 429/5xx com backoff.
• Não tente trocar o proprietário ou a flag primary por aqui — esses campos não são alterados por este contrato.

Veja também

• Endereços - Visão geral — modelo do objeto e ciclo de vida.
• Consultar endereço — busque o estado atual antes de atualizar.
• Criar endereço — cadastre um endereço novo.
• Excluir endereço — remova um endereço.
• Listar endereços — filtros e paginação.
• Convenções da API · Idempotência · Catálogo de códigos de erro