Autenticação

Visão Geral

O Plasma SDK usa duas API Keys em conjunto para autenticar todas as requisições. Ambas devem ser enviadas como headers HTTP customizados:

Header	Valor	Descrição
`X-PLASMA-Public-Key`	`pk_test_xxx` ou `pk_live_xxx`	Identifica sua loja
`X-PLASMA-Secret-Key`	`sk_test_xxx` ou `sk_live_xxx`	Autentica a operação

Nunca exponha sua Secret Key (sk_) no frontend. Use apenas no backend.

Gerando API Keys

Via Dashboard

Acesse o Dashboard do Plasma
Navegue até Configurações → API Keys
Clique em Gerar Nova Chave
Copie e armazene ambas as chaves em local seguro

A Secret Key é exibida apenas uma vez. Guarde-a em um local seguro!

Usando a Autenticação

Headers Obrigatórios

Inclua ambas as chaves em todas as requisições autenticadas:

X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx
X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx

Ambas as chaves devem usar o mesmo ambiente (ambas _test_ ou ambas _live_). Misturar ambientes retornará erro 401 Environment Mismatch.

Exemplo Completo

curl -X GET "https://api.plasmacheckout.com/api/sdk/products" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

const response = await fetch('https://api.plasmacheckout.com/api/sdk/products', {
  method: 'GET',
  headers: {
    'X-PLASMA-Public-Key': 'pk_live_xxxxxxxxxxxxxxxxxxxx',
    'X-PLASMA-Secret-Key': 'sk_live_xxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

import requests

headers = {
    'X-PLASMA-Public-Key': 'pk_live_xxxxxxxxxxxxxxxxxxxx',
    'X-PLASMA-Secret-Key': 'sk_live_xxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.plasmacheckout.com/api/sdk/products',
    headers=headers
)

print(response.json())

<?php
$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.plasmacheckout.com/api/sdk/products',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx',
        'X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

Permissões

Operação	Public Key (`pk_`)	Secret Key (`sk_`)
Listar produtos	✅	✅
Criar produtos	❌	✅
Listar pedidos	❌	✅
Criar checkout	✅	✅
Gerenciar webhooks	❌	✅

Mesmo endpoints que aceitam Public Key ainda exigem ambas as chaves nos headers. A tabela indica qual tipo de chave concede permissão para cada operação.

Erros de Autenticação

Status HTTP	Código	Descrição
`401`	`UNAUTHORIZED`	API Keys inválidas, ausentes ou desativadas
`401`	`KEY_EXPIRED`	API Key expirada
`401`	`ENVIRONMENT_MISMATCH`	Public Key e Secret Key com ambientes diferentes
`403`	`FORBIDDEN`	Sem permissão para esta operação
`429`	`RATE_LIMITED`	Limite de requisições excedido

Exemplo de erro

{
  "error": "Invalid API key. Key not found or deactivated.",
  "code": "UNAUTHORIZED"
}

Rate Limiting

Todas as requisições são limitadas por API Key. Os headers de rate limit são retornados em cada resposta:

Header	Descrição
`X-RateLimit-Limit`	Máximo de requests por janela
`X-RateLimit-Remaining`	Requests restantes
`X-RateLimit-Reset`	Timestamp Unix do reset
`Retry-After`	Segundos para retry (apenas em `429`)

Resposta 429 Too Many Requests

{
  "error": "Rate limit exceeded. Try again later.",
  "code": "RATE_LIMITED"
}

Boas Práticas

Use variáveis de ambiente

Nunca coloque API Keys diretamente no código:

.env

PLASMA_PUBLIC_KEY=pk_live_xxxxxxxxxxxxxxxxxxxx
PLASMA_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxxxxxx

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}