Excluir um endereço

Remove permanentemente um endereço da sua conta, identificado pelo ID público (addr_...). Use quando o registro não for mais necessário — por exemplo, ao limpar cadastros duplicados, remover um endereço obsoleto após uma mudança ou atender a um pedido de exclusão de dados do cliente. A operação é irreversível: depois de confirmada, os dados do endereço não podem ser recuperados.

DELETE /v1/addresses/{addressId}

Como funciona

Você envia uma requisição DELETE para o endereço, identificando-o pelo addressId na URL. O servidor localiza o registro, remove-o e responde com um corpo de confirmação — em vez de um 204 No Content vazio.

Pontos importantes do ciclo de vida:

• Síncrona e imediata. Quando a resposta 200 chega, o endereço já não existe mais. Não há etapa assíncrona nem evento de webhook posterior para esta operação.
• Confirmação no corpo. A resposta traz deleted: true junto com o id e o resource removidos, para que seu código possa registrar o resultado sem precisar de uma nova consulta.
• Irreversível. Não há "lixeira" nem desfazer. Se o cliente puder precisar do endereço de novo, guarde os dados do seu lado antes de excluir (veja Boas práticas).
• Idempotência natural. Uma segunda chamada DELETE para o mesmo ID, depois de já excluído, retorna 404 com addressIdNotFound — o endereço simplesmente não existe mais.

Quando usar (e quando não usar)

Use quando:

• O endereço está incorreto, duplicado ou obsoleto e não será reaproveitado.
• Você precisa remover dados pessoais a pedido do titular.

Prefira alternativas quando:

• Você só quer corrigir os dados de um endereço — use Atualizar endereço (PUT) em vez de excluir e recriar. Atualizar preserva o mesmo id, evitando que referências existentes apontem para um ID inexistente.
• Você não tem certeza de que é o endereço certo — primeiro confirme com Consultar endereço ou Listar endereços.

Requisição

Headers

Esta requisição não tem corpo, portanto não precisa de Content-Type. Como toda escrita, você pode enviar X-Idempotency-Key para tornar reenvios seguros — veja Idempotência.

Parâmetros de caminho

Exemplo curl

curl -X DELETE https://api.selectwin.io/v1/addresses/addr_01hqzvabc \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

Status 200 OK. O corpo confirma a exclusão (em vez de um 204 sem conteúdo), o que facilita logging e tratamento por clientes mais antigos.

{
  "id": "addr_01hqzvabc",
  "resource": "address",
  "deleted": true,
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/addresses/addr_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the address."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/addresses",
      "method": "POST",
      "description": "Create a new address."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/addresses",
      "method": "GET",
      "description": "List all addresses."
    }
  }
}

Campos da resposta

Erros

Trate sempre pelo error.code (estável), nunca pela message. Veja Tratamento de Erros para o envelope completo e o Catálogo de Códigos de Erro.

Exemplo de resposta 404:

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

Boas práticas

• Confirme antes de excluir. Faça um Read (ou um List por customerid) para garantir que está removendo o endereço certo, sobretudo em fluxos automatizados.
• Prefira atualizar a recriar. Para corrigir dados, use Atualizar: mantém o mesmo id e não quebra referências existentes.
• Guarde uma cópia se houver chance de recuperação. Como a exclusão é irreversível, persista os dados do endereço no seu sistema antes de excluir caso o cliente possa precisar deles.
• Peça confirmação ao usuário final. Em interfaces, exija uma ação explícita de confirmação antes de disparar a chamada.
• Trate o 404 como idempotente. Em jobs de limpeza, considere addressIdNotFound um resultado já-concluído, não uma falha.
• Atualize caches e telas na hora. Após o 200, remova o endereço de qualquer cache ou lista exibida para não mostrar um registro inexistente.

Veja também

• Visão geral de Endereços — o que é o recurso, modelo do objeto e todas as operações.
• Consultar endereço — confira os detalhes antes de excluir.
• Listar endereços — encontre o endereço certo de um cliente.
• Atualizar endereço — corrija dados sem precisar excluir.
• Criar endereço — cadastre um novo endereço após a remoção.
• Convenções da API · Autenticação · Catálogo de Códigos de Erro