Criar um endereço

Cria um novo endereço e o vincula ao contexto autenticado (o cliente ou a empresa dona da chave de API). Use esta operação para registrar endereços de entrega, cobrança ou cadastro a partir de um checkout, de um formulário de perfil ou de uma importação do seu CRM/ERP.

POST /v1/addresses

Como funciona

Quando você envia um POST /v1/addresses, o servidor:

1. Valida o corpo: confere os campos obrigatórios (country e postcode), o formato do CEP e os limites de tamanho dos demais campos.
2. Normaliza os dados: o CEP é gravado sem máscara (01310-100 vira 01310100) e o endereço é montado em linhas formatadas (line, line1, line2, line3) e em uma line completa para exibição.
3. Vincula o endereço ao dono determinado pelo contexto da sua SelectKey. Na resposta, isso aparece como ownerType (ex.: customer) e ownerId (ex.: cus_01hqzvabc) — você não envia esse vínculo no corpo; ele é resolvido pelo servidor.
4. Persiste e devolve 201 Created com o objeto completo do endereço, incluindo o id recém-gerado (prefixo addr_), o bloco merchant e os links HATEOAS (_links) para as próximas operações.

A criação é síncrona: quando você recebe 201, o endereço já existe e pode ser lido, atualizado ou deletado imediatamente pelo id retornado.

Quando usar

• Checkout / e-commerce: registrar o endereço de entrega ou cobrança no momento da compra.
• Cadastro de cliente: capturar o endereço durante o registro inicial.
• Perfil do usuário: permitir que o usuário adicione um novo endereço à sua conta.
• Importação: sincronizar endereços vindos do seu CRM/ERP.

Quando NÃO usar: se o endereço já existe e você só quer alterá-lo, use Atualizar (PUT) em vez de criar um novo. Para apenas consultar um endereço existente, use Ler ou Listar.

Requisição

Headers

Corpo

Exemplo curl

curl -X POST https://api.selectwin.io/v1/addresses \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 2f1c9a7e-checkout-001" \
  -d '{
    "street": "Av. Paulista",
    "number": "1000",
    "complement": "Apt 42",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR",
    "postcode": "01310-100"
  }'

Corpo mínimo

Apenas os campos obrigatórios:

{
  "country": "BR",
  "postcode": "01310-100"
}

Resposta

201 Created — o corpo é o objeto completo do endereço no nível raiz, acrescido de merchant e _links.

{
  "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": 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-chave da resposta

Entrada vs. saída: você envia o CEP com ou sem hífen (01310-100); a resposta devolve normalizado (01310100). Não compare strings de CEP cruamente entre o que enviou e o que recebeu.

Erros

Em caso de falha, a API devolve o envelope padrão com error.code estável. Trate sempre pelo error.code, nunca pela message.

O recurso Addresses expõe addressIdNotFound (404) nas operações que recebem um addressId (ler, atualizar, deletar). Na criação não há ID na URL, então esse código não se aplica aqui. Veja o Catálogo de Códigos de Erro e o Tratamento de Erros.

Exemplo de erro de validação (400)

{
  "error": {
    "code": "invalidParameters",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      { "country": "This field is required." },
      { "postcode": "Postcode must match the format 00000-000." }
    ]
  }
}

Boas práticas

• Normalize antes de comparar. A API grava o CEP sem máscara. Se você guarda o CEP localmente, padronize o formato para evitar duplicidades aparentes.
• Sempre envie X-Idempotency-Key em criações disparadas por ações do usuário (checkout). Um retry após timeout não deve gerar dois endereços. Veja Idempotência.
• Valide country e postcode no cliente antes do POST. São os únicos campos obrigatórios e a causa mais comum de 400 invalidParameters.
• Guarde o id retornado (string completa, opaca) para ler, atualizar ou deletar o endereço depois. Não tente reconstruir o ID a partir de partes.
• Use _links para as próximas ações em vez de hardcodar URLs — isso deixa sua integração resiliente a mudanças de roteamento.
• Reaproveite os campos line/line1..3 para exibir o endereço já formatado, em vez de concatenar os campos manualmente.
• Trate 429 e 5xx com backoff e o default da sua lógica de erro pelo error.statusCode, não pela message.

Veja também

• Visão geral de Endereços — o modelo do objeto e o ciclo de vida.
• Ler endereço — buscar um endereço pelo id.
• Atualizar endereço — substituir os dados de um endereço (PUT).
• Listar endereços — paginar e filtrar endereços.
• Deletar endereço — remover um endereço.
• Convenções · Autenticação · Idempotência · Catálogo de Códigos de Erro