Visão geral

Introdução

O recurso de Endereços é um componente fundamental da Selectwin API, permitindo o gerenciamento eficiente das informações de localização física associadas a clientes e transações. Este recurso fornece suporte para armazenar e administrar diversos tipos de endereços, como residenciais, comerciais, de entrega e faturamento.

A API de Endereços foi projetada com foco na flexibilidade, validação precisa e suporte internacional, permitindo que os desenvolvedores implementem soluções robustas para gerenciamento de endereços em diferentes contextos e regiões geográficas.

Conceito e Funcionalidade

Os endereços representam localizações físicas dentro da plataforma, permitindo o registro preciso de informações geográficas e dados de localização. Este recurso é essencial para operações como envio de produtos, faturamento, verificação de cobertura de serviços e análises geográficas.

Cada endereço está associado a um cliente específico e pode ser configurado como endereço principal, facilitando operações que requerem um endereço padrão. O sistema suporta múltiplos formatos de endereço adaptados às convenções locais de diferentes países.

Estrutura do Objeto Endereço

O objeto Endereço contém informações detalhadas sobre uma localização física. A estrutura básica inclui:

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

Nota: Esta é a estrutura do objeto de endereço retornado em operações de leitura/criação/atualização. Respostas completas de sucesso incluem também merchant e _links no nível raiz (ver guias de Create/Read para exemplos completos). Listagens usam projeções mais leves.

Recursos Disponíveis

Validações e Segurança

O recurso de Endereços implementa diversas validações para garantir a integridade e precisão dos dados:

1. Validação de Código Postal - Formatos específicos são validados de acordo com o país informado
2. Códigos de País Padronizados - Utilização de códigos ISO 3166-1 alpha-2 para identificação de países
3. Verificação de Campos Obrigatórios - Garantia de que informações essenciais sejam fornecidas
4. Limitação de Tamanho de Campos - Prevenção contra dados excessivamente longos ou inválidos
5. Validação de Coordenadas Geográficas - Verificação de valores de latitude e longitude dentro de intervalos válidos

Códigos de País Suportados

O sistema utiliza o padrão ISO 3166-1 alpha-2 para identificação de países. Alguns dos códigos mais comuns incluem:

Webhooks Acionados

Casos de Uso Comuns

• Checkout em E-commerce: Gerenciamento de endereços de entrega e faturamento durante o processo de compra
• Perfil de Cliente: Permitir que clientes gerenciem seus endereços cadastrados
• Logística: Utilização de endereços para cálculo de frete e planejamento de entregas
• Faturamento: Utilização de endereços para emissão de notas fiscais e documentos financeiros
• Análise Geográfica: Estudo de distribuição geográfica de clientes e vendas
• Verificação de Cobertura: Determinação de disponibilidade de serviços por região
• Entrega Localizada: Configuração de serviços baseados em proximidade geográfica

Melhores Práticas

1. Sempre valide os dados de endereço antes de enviá-los para a API
2. Utilize o serviço de CEP para preencher automaticamente campos de endereço
3. Implemente tratamento de erros adequado para lidar com falhas nas requisições
4. Defina um endereço principal para cada cliente para facilitar operações futuras
5. Use o campo metadata para armazenar informações adicionais específicas do seu negócio
6. Mantenha os endereços atualizados para garantir entregas bem-sucedidas
7. Armazene coordenadas geográficas para funcionalidades baseadas em localização

Solução de Problemas Comuns

Integração com Outros Recursos

O recurso de Endereços integra-se com:

• Customers: Endereços são associados a clientes específicos através do customerId
• Transactions: Endereços podem ser utilizados em transações para entrega e faturamento
• Utils/Postcode: Serviço de consulta de CEP para preenchimento automático de campos
• Webhooks: Notificações em tempo real sobre operações com endereços
• Finance: Endereços são utilizados para documentos fiscais e financeiros