Atualizar um endereço

Visão Geral

Este endpoint permite atualizar os dados de um endereço existente a partir do seu identificador único (addr_*). É útil para corrigir informações de logradouro, complementar dados parciais e manter os endereços de entrega/faturamento sempre atualizados.

Precauções

ATENÇÃO! Por favor, leia estas informações importantes antes de usar este endpoint.

• ID do Endereço: Confirme que o addressId no path corresponde ao endereço correto — atualizar o registro errado pode afetar entregas e faturamento.
• Atualização parcial: Na rota standalone (PUT /v1/addresses/{addressId}), todos os campos do corpo são opcionais — envie apenas os que deseja alterar; os omitidos permanecem inalterados.
• Formato do CEP: Quando postcode é enviado, é validado no formato brasileiro (CEP) e armazenado apenas com os dígitos.
• Escopo multi-tenant: Só é possível atualizar endereços que pertencem à sua conta (merchant).

Descrição

O endpoint Atualizar Endereço modifica os dados de um endereço já cadastrado. A identificação do endereço vem do path (addressId) e os novos valores vão no corpo da requisição. A resposta retorna o objeto de endereço completo, no nível raiz, acompanhado de merchant e _links (HATEOAS), no mesmo formato de Consultar e Criar.

Requisição

PUT /v1/addresses/{addressId}

Parâmetros de Caminho (Path)

Corpo da Requisição (Body)

{
  "street": "Avenida Paulista",
  "number": "1000",
  "complement": "Apto 123",
  "district": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "BR",
  "postcode": "01310-100"
}

Atributos do Corpo da Requisição

Todos os campos são opcionais (atualização parcial). As mesmas regras de validação do Criar Endereço aplicam-se a cada campo enviado.

Nota: Este endpoint não altera o vínculo do proprietário (ownerType/ownerId).

Resposta - 200 OK

Se a requisição for bem-sucedida, o servidor retornará um código de status HTTP 200 OK e o objeto de endereço atualizado, no nível raiz, com merchant e _links.

Exemplo de Resposta

{
  "id": "addr_01hqzvabc",
  "ownerType": "customer",
  "ownerId": "cus_01hqzvabc",
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Apto 123",
  "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": {
    "source": "checkout"
  },
  "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."
    }
  }
}

Atributos da Resposta

A resposta é o objeto completo no nível raiz + merchant e _links (mesmo formato de Consultar/Criar).

Respostas de Erro

400 Bad Request

Ocorre quando há erros de validação na requisição, como valores fora do formato esperado.

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      {
        "postcode": "must be a Brazilian postal code"
      }
    ]
  }
}

404 Not Found

Ocorre quando o addressId informado não existe ou não pertence à sua conta (addressIdNotFound).

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "resource",
    "message": "Address not found."
  }
}

Casos de Uso

1. Correção de Endereço: Ajustar logradouro, número ou CEP digitados incorretamente
2. Atualização Pós-Mudança: Atualizar o endereço quando o cliente muda de local
3. Enriquecimento de Dados: Complementar um endereço cadastrado parcialmente (ex.: adicionar bairro e complemento)
4. Padronização: Normalizar dados de endereço após validação de CEP

Melhores Práticas

1. Consultar Antes de Atualizar: Use Consultar Endereço para obter os dados atuais antes de enviar a atualização
2. Validação de CEP: Quando atualizar o postcode, garanta um valor válido para evitar falhas de validação e inconsistências de entrega
3. Enviar Apenas o Necessário: Como é uma atualização parcial, envie somente os campos que deseja alterar
4. Tratamento de Erros: Trate explicitamente 400 (validação) e 404 (endereço inexistente)

Integração com Outros Endpoints

• Use Consultar Endereço para verificar os dados antes e depois da atualização
• Veja Endereços - Visão Geral para o ciclo de vida completo do recurso
• Use Criar Endereço para cadastrar novos endereços