Criar um endereço

Visão Geral

Este endpoint permite adicionar um novo endereço a um cliente existente no sistema. Permite o cadastro de endereços com informações completas, incluindo coordenadas geográficas e metadados personalizados, facilitando a gestão de informações de entrega e faturamento em sua plataforma.

Precauções

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

• ID do Cliente: Certifique-se de utilizar um ID de cliente válido e existente no sistema.
• Dados de Localização: latitude e longitude são strings opcionais (máx. 16 caracteres cada).
• Formato do CEP: O postcode é validado no formato brasileiro (CEP: 8 dígitos, com ou sem hífen) e é armazenado apenas com os dígitos.
• Campo primary: Se definido como true, marca este endereço como principal do cliente.

Descrição

O endpoint Criar Endereço permite adicionar um novo endereço a um cliente existente no sistema, com validação de dados e opção de definir metadados personalizados.

Estrutura JSON - Parâmetros Obrigatórios

{
  "customerId": "cus_123456789",
  "street": "Avenida Paulista",
  "country": "BR",
  "postcode": "01310-100"
}

Estrutura JSON - Exemplo Completo

{
  "customerId": "cus_123456789",
  "street": "Avenida Paulista",
  "number": "1000",
  "complement": "Apto 123",
  "district": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "BR",
  "postcode": "01310-100",
  "latitude": "-23.5505",
  "longitude": "-46.6333",
  "primary": true,
  "metadata": {
    "type": "commercial",
    "notes": "Endereço comercial principal"
  }
}

Parâmetros da Requisição

Resposta - 201 Created

Se a requisição for bem-sucedida, o servidor retornará um código de status HTTP 201 Created e um objeto JSON com as informações do endereço criado.

Exemplo de Resposta

Resposta root-level (conforme emitido pelo responser após mount "read" para create).

{
  "id": "addr_01hqzvabc",
  "ownerType": "customer",
  "ownerId": "cus_01hqzvabc",
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Sala 1",
  "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 (padrão para creates/reads).

Nota sobre input vs output: A requisição aceita customerId (vínculo do dono); a resposta deriva ownerType: "customer" e ownerId (o cus_*). Os campos line/line1/line2/line3 são compostos pelo servidor a partir dos componentes do endereço.

Respostas de Erro

400 Bad Request

Esta resposta ocorre quando há erros de validação na requisição, como campos obrigatórios ausentes ou valores inválidos.

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

404 Not Found

Ocorre quando o customerId informado não existe ou não pertence à sua conta (invalidCustomerId).

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "resource",
    "message": "The provided customer id is invalid."
  }
}

Casos de Uso

1. Checkout em E-commerce: Adição de endereços de entrega e faturamento durante o processo de compra
2. Cadastro de Cliente: Captura de endereços durante o registro inicial do cliente
3. Perfil de Usuário: Permitir que usuários adicionem múltiplos endereços em seu perfil
4. Gestão Logística: Cadastro de locais de entrega para planejamento de rotas

Melhores Práticas

1. Validação de Dados: Valide sempre os dados de endereço antes de enviá-los para a API
2. Utilização de Serviço de CEP: Use o endpoint /utils/postcode-validation para preencher automaticamente campos de endereço
3. Metadados Personalizados: Utilize o campo metadata para armazenar informações específicas do seu negócio
4. Tratamento de Erros: Implemente tratamento adequado para todos os códigos de erro possíveis
5. Endereço Principal: Quando apropriado, marque um endereço como principal (primary: true) para facilitar operações futuras