Metadata

A funcionalidade de Metadata da Selectwin API permite anexar informações adicionais personalizadas aos principais recursos da plataforma. Esta característica oferece flexibilidade para armazenar dados

Visão Geral

A funcionalidade de Metadata da Selectwin API permite anexar informações adicionais personalizadas aos principais recursos da plataforma. Esta característica oferece flexibilidade para armazenar dados específicos do seu negócio junto aos objetos do sistema, facilitando integrações, rastreamento e personalização dos processos de pagamento.

O que é Metadata?

Metadata são pares de chave-valor que você pode associar a objetos como transações, clientes, cartões, saques e outros recursos da API. Estas informações adicionais não afetam o comportamento padrão dos objetos, mas permitem:

Personalização de Dados: Armazenar informações específicas do seu negócio
Integração Simplificada: Facilitar o mapeamento entre os sistemas
Rastreamento Avançado: Adicionar identificadores para análise e reconciliação
Segmentação e Categorização: Organizar recursos com base em critérios personalizados
Contexto Adicional: Fornecer dados auxiliares para futuras referências

Estrutura e Limitações

O objeto de metadata é sempre incluído como um atributo chamado metadata nos recursos que o suportam:

{
  // ... outros atributos do objeto ...
  "metadata": {
    "order_id": "PED-12345",
    "customer_reference": "CLI-ABC-789",
    "campaign_source": "email_july",
    "internal_department": "sales_northeast"
  }
}

Limitações:

Aspecto	Limite
Tamanho total	Máximo de 20KB por objeto
Chaves	Até 40 chaves por objeto
Formato de chaves	Apenas alfanuméricos, sublinhados e hífens
Tamanho da chave	Máximo de 40 caracteres
Tamanho do valor	Máximo de 500 caracteres
Tipo de valores	Apenas strings (sem objetos aninhados ou arrays)

Como Utilizar Metadata

Adicionando Metadata na Criação

Você pode incluir metadata ao criar qualquer recurso que o suporte:

// Exemplo: Criando uma transação com metadata
const axios = require('axios');

async function createTransactionWithMetadata() {
  const response = await axios({
    method: 'post',
    url: 'https://api.selectwin.io/v1/transactions',
    headers: {
      'SelectKey': 'sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ',
      'Content-Type': 'application/json'
    },
    data: {
      ...
      metadata: {
        order_id: 'ORDER-123456',
        customer_reference: 'CUST-789',
        product_ids: '10,14,15',
        shipping_address_id: 'ADR-456',
        promo_code: 'SUMMER10'
      }
    }
  });
  
  return response.data;
}

Casos de Uso

1. Integração com E-commerce

Use metadata para rastrear informações do pedido:

metadata: {
  order_number: "PO-28471",
  cart_id: "CART-17283",
  store_id: "STORE-05",
  shipping_method: "express",
  items_count: "3",
  source: "mobile_app"
}

2. Reconciliação Financeira

Facilite a reconciliação adicionando identificadores do seu sistema financeiro:

metadata: {
  invoice_id: "INV-20230915-001",
  cost_center: "CC-MARKETING",
  project_code: "PROJ-2023-Q3",
  department: "sales",
  account_code: "AC-4172"
}

3. Segmentação de Clientes

Adicione informações para segmentação e análise:

metadata: {
  customer_segment: "premium",
  acquisition_channel: "referral",
  lifetime_value: "15240",
  preferred_category: "electronics",
  language_preference: "pt-BR",
  subscription_tier: "pro"
}

4. Campanhas de Marketing

Rastreie a origem e desempenho das campanhas:

metadata: {
  campaign_id: "SUMMER2023",
  utm_source: "facebook",
  utm_medium: "cpc",
  utm_campaign: "back_to_school",
  discount_code: "SUMMER10",
  affiliate_id: "AFF123"
}

5. Logística e Entrega

Acompanhe informações de entrega nos pagamentos:

metadata: {
  tracking_number: "JB437291082",
  carrier: "fedex",
  estimated_delivery: "2023-09-20",
  package_weight: "1.5kg",
  delivery_instructions: "leave_at_door",
  warehouse_id: "WH-SOUTH"
}

Melhores Práticas

1. Nomenclatura Consistente

Estabeleça um padrão de nomenclatura para suas chaves de metadata:

Use snake_case ou camelCase consistentemente
Evite abreviações obscuras
Seja descritivo mas conciso
Agrupe campos relacionados com prefixos comuns (ex: shipping_*, invoice_*)

2. Dados Estruturados vs. Não Estruturados

Como metadata só aceita strings simples (não objetos JSON aninhados), há duas abordagens para dados complexos:

Achatamento: Use prefixos para representar estrutura

"customer_address_street": "Av. Paulista",
"customer_address_number": "1000",
"customer_address_city": "São Paulo"

Serialização: Para estruturas mais complexas, serialize como JSON

"customer_address": "{\"street\":\"Av. Paulista\",\"number\":\"1000\",\"city\":\"São Paulo\"}"

3. Padronização de Valores

Para campos que representam categorias ou estados:

Use enumerações consistentes (ex: status: ["active", "inactive", "pending"])
Defina um conjunto fechado de valores possíveis
Documente internamente o significado de cada valor

4. O que Não Armazenar em Metadata

Evite armazenar:

Dados sensíveis: Informações de cartão de crédito, senhas, tokens
Informações pessoais sensíveis: Evite dados que aumentem exigências de conformidade
Dados muito volumosos: Respeite os limites de tamanho (20KB)
Informações temporárias: A metadata deve ser relevante por toda a vida do objeto
Dados críticos para processamento: Não confie na metadata para lógica principal

5. Backup de Metadata

Não dependa apenas da metadata na Selectwin como fonte primária:

Mantenha uma cópia das informações críticas em seu sistema
Considere implementar recuperação de informações em caso de problemas
Faça download periódico dos dados para análise local

Webhooks e Metadata

Quando recursos são atualizados, incluindo suas informações de metadata, webhooks são disparados. Você pode utilizar estes eventos para manter seus sistemas sincronizados:

// Exemplo de payload de webhook com metadata
{
  "id": "evt_123456789",
  "type": "transaction.updated",
  "created": "2023-09-15T16:43:21Z",
  "data": {
    "object": {
      "id": "txn_987654321", 
      "amount": 10000,
      "status": "paid",
      "metadata": {
        "order_id": "ORDER-123456",
        "shipping_status": "dispatched", 
        "tracking_code": "BR123456789"
      }
    },
    "previous_attributes": {
      "metadata": {
        "order_id": "ORDER-123456",
        "shipping_status": "pending"
      }
    }
  }
}