Shipping

O objeto Shipping na API Selectwin representa as informações de entrega associadas a uma transação. Esta estrutura permite armazenar e gerenciar todos os detalhes logísticos de uma venda, desde o ende

Visão Geral

O objeto Shipping na API Selectwin representa as informações de entrega associadas a uma transação. Esta estrutura permite armazenar e gerenciar todos os detalhes logísticos de uma venda, desde o endereço de entrega até o status de rastreamento, proporcionando visibilidade completa sobre o processo de envio.

Estrutura do Objeto Shipping

O objeto Shipping está disponível dentro do objeto Transaction e contém os seguintes campos:

{
  "shipping": {
    "customerCost": "R$ 100,00",
    "internalCost": "R$ 50,00",
    "recipientName": "João da Silva",
    "recipientDocument": "12345678900",
    "recipientDocumentType": "cpf",
    "recipientPhone": "5511999999999",
    "trackingSiteUrl": "https://www.correios.com.br/rastreamento",
    "trackingCode": "BR123456789BR",
    "addressIsValid": "true",
    "deliveryStatus": "in_transit",
    "deliveryDate": "2023-11-15",
    "deliveryTimeWindow24h": "10h/12h",
    "packageWeight": "1.5kg",
    "packageDimensions": "30x20x15",
    "instructions": "Deixar com o porteiro",
    "geolocationLatitude": "-23.5505",
    "geolocationLongitude": "-46.636108",
    "insurance": true,
    "method": "SEDEX",
    "address": {
      "id": "addr_1234567890",
      "street": "Avenida Paulista",
      "complement": "Conjunto 1501",
      "district": "Bela Vista",
      "number": "1000",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postcode": "01310-100"
    }
  }
}

Campos do Objeto Shipping

Campo	Tipo	Descrição
`customerCost`	string	Custo de entrega cobrado do cliente (ex: "R$ 100,00")
`internalCost`	string	Custo interno de entrega (valor pago à transportadora) (ex: "R$ 50,00")
`recipientName`	string	Nome completo do destinatário
`recipientDocument`	string	Número do documento do destinatário
`recipientDocumentType`	string	Tipo do documento do destinatário (cpf, cnpj, passport)
`recipientPhone`	string	Telefone do destinatário no formato internacional (55 seguido de 10-11 dígitos)
`trackingSiteUrl`	string	URL do site de rastreamento da transportadora
`trackingCode`	string	Código de rastreamento fornecido pela transportadora
`addressIsValid`	string	Indicador se o endereço foi validado ("true" ou "false")
`deliveryStatus`	string	Status atual da entrega (ex: "pending", "in_transit", "delivered")
`deliveryDate`	string	Data prevista ou efetiva de entrega (formato YYYY-MM-DD)
`deliveryTimeWindow24h`	string	Janela de horário para entrega no formato 24h (ex: "10h/12h")
`packageWeight`	string	Peso do pacote com unidade (ex: "1.5kg")
`packageDimensions`	string	Dimensões do pacote no formato LxAxP (ex: "30x20x15")
`instructions`	string	Instruções especiais para entrega
`geolocationLatitude`	string	Latitude da geolocalização do endereço de entrega
`geolocationLongitude`	string	Longitude da geolocalização do endereço de entrega
`insurance`	boolean	Indica se o envio possui seguro
`method`	string	Método/serviço de entrega utilizado (ex: "SEDEX", "PAC")

Objeto Address dentro de Shipping

Campo	Tipo	Descrição
`id`	string	Identificador único do endereço
`street`	string	Nome da rua/avenida
`complement`	string	Complemento do endereço (apto, sala, etc.)
`district`	string	Bairro
`number`	string	Número do endereço
`city`	string	Cidade
`state`	string	Estado/província (sigla)
`country`	string	País (código ISO 3166-1 de 2 letras)
`postcode`	string	CEP/código postal (formato: 12345-678 ou 12345678)

Status de Entrega

O campo deliveryStatus pode conter os seguintes valores:

Status	Descrição
`pending`	Envio registrado, mas ainda não processado
`shipped`	Encomenda entregue ao destinatário

Como Utilizar o Objeto Shipping

1. Criando uma Transação com Dados de Shipping

// Exemplo: Criando uma transação com informações de entrega
const axios = require('axios');

async function createTransactionWithShipping() {
  const response = await axios({
    method: 'post',
    url: 'https://api.selectwin.io/v1/transactions',
    headers: {
      'SelectKey': 'sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ',
      'Content-Type': 'application/json'
    },
    data: {
      ... Data
      shipping: {
        customerCost: "R$ 15,90",
        method: "SEDEX",
        recipientName: "Maria Silva",
        recipientDocument: "12345678900",
        recipientDocumentType: "cpf",
        recipientPhone: "5511987654321",
        packageWeight: "0.5kg",
        packageDimensions: "20x15x10",
        instructions: "Entregar somente ao destinatário",
        insurance: true,
        address: {
          street: "Rua das Flores",
          number: "123",
          complement: "Apto 45",
          district: "Jardim Primavera",
          city: "São Paulo",
          state: "SP",
          country: "BR",
          postcode: "04567-890"
        }
      }
    }
  });
  
  return response.data;
}

Melhores Práticas

1. Validação de Endereços

Para evitar problemas de entrega:

Sempre valide o CEP/código postal antes de confirmar o endereço
Utilize o campo addressIsValid para indicar se o endereço foi validado
Consulte o endpoint /utils/validate-postcode/:code para validar CEPs

2. Dados do Destinatário

Para garantir entregas bem-sucedidas:

Forneça sempre o nome completo do destinatário
Inclua um documento válido para identificação na entrega
Disponibilize um telefone de contato atualizado

3. Rastreamento

Para melhorar a experiência do cliente:

Forneça a URL correta do site de rastreamento da transportadora
Mantenha o status de entrega atualizado com base nas informações da transportadora

Shipping

On this page