Metadados

#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:

1. Personalização de Dados: Armazenar informações específicas do seu negócio
2. Integração Simplificada: Facilitar o mapeamento entre os sistemas
3. Rastreamento Avançado: Adicionar identificadores para análise e reconciliação
4. Segmentação e Categorização: Organizar recursos com base em critérios personalizados
5. 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"
  }
}

#Limites

O campo metadata é um objeto JSON livre — os valores podem ser texto, número, booleano, null, objeto ou lista. O tamanho tem limite, conferido em toda criação e atualização:

Fora do limite, a requisição é recusada com o erro de validação de contrato — 400 invalidParameters —, e error.params diz o campo e o motivo. O valor nunca é cortado em silêncio:

{
  "error": {
    "statusCode": 400,
    "category": "validation",
    "code": "invalidParameters",
    "params": [{ "metadata[observacao]": "value must have at most 500 characters" }]
  }
}

O limite vale para o metadata de todo recurso (clientes, endereços, transações e seus itens, assinaturas e seus itens, produtos/variantes, links de pagamento, endpoints de webhook, registros de uso). Duas exceções, com números maiores porque o valor é configuração de estrutura conhecida: o metadata de uma template e de um disparo do motor de apps (o vínculo HSM do WhatsApp, a mídia) aceita até 8 KiB por valor e 16 KiB no total.

O metadata de uma sessão de checkout (e o das linhas avulsas dela) é rascunho e aceita mais (até 100 chaves e 16 KiB por objeto), mas desce para a cobrança só dentro do limite acima: na transação (ou na assinatura) que a sessão produz entram, na ordem, as chaves que cabem; a que não cabe fica só na sessão e a cobrança sai sem ela — nada é recusado no pagamento do comprador. As chaves consent, attribution e cookies do metadata da sessão são reservadas à plataforma: não descem para a cobrança e são as únicas que a página do checkout escreve.

#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': 'sk_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

Um valor pode ser um objeto ou uma lista, mas cada valor tem o limite de 500 caracteres (o JSON dele). Para dados maiores, prefira guardar no seu sistema e deixar no metadata só o identificador. Duas abordagens comuns:

1. Achatamento: Use prefixos para representar estrutura

   TextoCopiar

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

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

   TextoCopiar

   "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: O objeto tem limite de 8 KiB (veja Limites)
• 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 (estrutura real do evento)
{
  "id": "wbh_123456789",
  "type": "transaction.approved",
  "source": "automatic",
  "payload": {
    "object": {
      "id": "tra_987654321",
      "amount": 10000,
      "status": "approved",
      "metadata": {
        "order_id": "ORDER-123456",
        "shipping_status": "dispatched",
        "tracking_code": "BR123456789"
      }
    }
  },
  "createdAt": "2026-04-12T17:56:33.000Z"
}

#Perguntas Frequentes

#A metadata é visível para os clientes finais?

Não. A metadata é visível apenas para sua empresa através das APIs e do Dashboard administrativo. Os clientes finais não têm acesso a essas informações.

#Posso atualizar apenas um campo de metadata sem afetar os outros?

Não diretamente. A API substitui todo o objeto de metadata ao invés de mesclar. Para atualizar campos individuais, você deve primeiro obter o objeto atual, modificar o campo específico e enviar o objeto completo atualizado.

#É possível remover um campo específico de metadata?

Sim, basta enviar uma atualização com todo o objeto de metadata, omitindo o campo que deseja remover. Alternativamente, você pode definir o valor do campo específico como uma string vazia.

#A metadata afeta as operações de processamento de pagamento?

Não. A metadata é puramente informativa e não afeta o comportamento funcional do processamento de pagamentos, autorizações, capturas ou outros processos principais.

#Posso usar metadata para identificar transações duplicadas?

Sim, essa é uma prática comum. Ao fornecer identificadores consistentes em seu sistema dentro da metadata (como IDs de pedido), você pode consultar a API para verificar se uma transação já foi processada antes de tentar criá-la novamente.

#A metadata é incluída em relatórios e exportações?

Sim. Todos os relatórios e exportações de dados da plataforma incluem os campos de metadata associados aos recursos, facilitando a análise e reconciliação.