Visão geral

O recurso Endereços (Address) guarda localizações físicas — rua, número, bairro, cidade, estado, país e CEP — vinculadas a um titular (um cliente, por exemplo). Use-o para registrar endereços de entrega, faturamento ou cadastro, consultá-los depois e mantê-los atualizados. Esta página explica o que é o objeto, como ele se comporta e lista todas as operações disponíveis.

Todas as chamadas usam a base https://api.selectwin.io/v1 e autenticam pelo header SelectKey (nunca Authorization: Bearer/Basic). Veja Autenticação e as Convenções gerais (camelCase, datas ISO 8601 UTC, IDs opacos).

O que é um endereço

Um endereço é um registro autônomo, identificado por um ID público no formato addr_... (ex.: addr_01hqzvabc). Trate esse ID como opaco: armazene a string inteira, não faça parsing e não tente construí-lo manualmente (veja Convenções → IDs).

Cada endereço pertence a um titular, exposto na resposta pelos campos ownerType (ex.: "customer") e ownerId (ex.: cus_01hqzvabc). Esse vínculo é determinado pelo contexto da sua chamada — você não envia esses campos no corpo da criação. O servidor também deriva campos de conveniência (line, line1, line2, line3) montados a partir das partes do endereço, úteis para exibição direta.

Modelo do objeto

Abaixo, o objeto retornado em criação, leitura e atualização (respostas individuais). O corpo de sucesso inclui ainda merchant (dados do vendedor) e _links (HATEOAS) no nível raiz — veja Recursos / HATEOAS:

{
  "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,
  "createdAt": "2026-04-12T17:56:33.000Z",
  "updatedAt": "2026-04-12T17:56:33.000Z"
}

Campos do objeto

Projeção em listagens

A operação de listagem (GET /v1/addresses) retorna projeções mais leves por item dentro de data[]. Diferenças relevantes em relação ao objeto individual:

• A linha formatada aparece como lineAddress (em vez de line / line1 / line2 / line3).
• Campos de conveniência por partes (line1–line3) não vêm no item da lista.

Para o objeto completo de um endereço, consulte sempre o recurso individual com Consultar endereço. Veja Paginação para limit, offset, page, hasMore e _links.

Como funciona / ciclo de vida

O ciclo de vida é direto: você cria, lê quantas vezes precisar, substitui por inteiro (PUT) e, se necessário, exclui.

Pontos importantes do comportamento:

• Substituição completa na atualização. PUT substitui o endereço inteiro pelo corpo enviado; reenvie todos os campos que deseja manter. Como na criação, country e postcode são obrigatórios no corpo. Veja Atualizar endereço.
• Endereço principal. O campo primary indica o endereço padrão do titular. Quando um endereço passa a ser principal, o titular tem, na prática, um único principal por vez.
• Exclusão. DELETE remove o registro e retorna uma confirmação ({ "deleted": true, ... }). Veja Excluir endereço para os efeitos.
• Atualizações de estado chegam por webhooks, nunca por polling — veja Proibição de polling e os Webhook Events.

Operações disponíveis

Exemplo rápido — criar um endereço

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

Em sandbox, a chave começa com sl_test_. Use X-Idempotency-Key em escritas para evitar duplicar um endereço em caso de retry — veja Idempotência.

Erros

A API usa o envelope de erro padrão com error.code estável (trate sempre pelo code, nunca pela message). Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Boas práticas

• Valide CEP e país no cliente antes de enviar: postcode segue o formato brasileiro ^\d{5}-?\d{3}$ (com ou sem hífen) e country deve ser um código ISO de 2–3 letras. Isso evita um invalidParameters (400).
• Reenvie o objeto inteiro no PUT. Como é substituição completa, omitir um campo o apaga. Faça um GET antes para partir do estado atual.
• Use X-Idempotency-Key na criação para que um retry de rede não gere endereços duplicados.
• Para o objeto completo, leia o recurso individual. Listagens trazem projeções leves (lineAddress, sem line1–line3); não dependa de campos da projeção para lógica fina.
• Filtre listagens por customerid para recuperar os endereços de um cliente específico, em vez de varrer toda a base; pagine por limit/offset e siga hasMore/_links.
• Trate erros pelo error.code/error.statusCode, com retry com backoff em 429 e 5xx, e tratamento explícito de addressIdNotFound.

Conceitos e relações

• Titular do endereço — Um endereço pertence a um titular identificado por ownerType + ownerId (tipicamente um Customer, cus_...). O vínculo vem do contexto da chamada, não de um campo no corpo.
• Idempotência — X-Idempotency-Key torna seguras as escritas repetidas. Veja Idempotência.
• Paginação e HATEOAS — Listagens retornam page, hasMore e _links; respostas individuais trazem _links com as próximas ações possíveis. Veja Paginação.
• Webhooks — Acompanhe mudanças por eventos de webhook em vez de consultar repetidamente. Veja Webhook Events e Proibição de polling.

Veja também

• Criar endereço
• Consultar endereço
• Atualizar endereço
• Listar endereços
• Excluir endereço
• Convenções · Autenticação · Tratamento de Erros · Catálogo de Códigos de Erro