Configuração

Configure seu ambiente e faça sua primeira requisição à API do Plasma Checkout em 5 minutos.

Início Rápido

Você pode integrar o Plasma de duas formas:

API REST — requisições HTTP diretas de qualquer linguagem (cURL, Python, PHP, Go, etc.)
SDK Node.js/TypeScript — cliente oficial com tipos, retry automático e autocomplete

Escolha a abordagem que melhor se adapta ao seu stack.

Gere suas API Keys

Acesse o Dashboard do Plasma, navegue até Configurações → API Keys e clique em Gerar Nova Chave. Você receberá um par de chaves:

Public Key (pk_live_xxx ou pk_test_xxx)
Secret Key (sk_live_xxx ou sk_test_xxx)

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

Configure variáveis de ambiente

Armazene suas chaves em variáveis de ambiente:

.env

PLASMA_PUBLIC_KEY=pk_test_sua_public_key_aqui
PLASMA_SECRET_KEY=sk_test_sua_secret_key_aqui

Faça sua primeira requisição

Listar Produtos

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

Verifique a resposta

Resposta

{
  "data": [
    {
      "id": "cm1abc2def3ghi",
      "title": "Camiseta Premium",
      "price": 7990,
      "status": "active",
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "cm1abc2def3ghi",
    "count": 50,
    "total": 100
  }
}

Base URL

Todas as requisições devem ser feitas para:

https://api.plasmacheckout.com/api/sdk

Para ambiente de testes:

https://sandbox.plasmacheckout.com/api/sdk

Autenticação

Todas as requisições autenticadas devem incluir duas chaves nos headers:

X-PLASMA-Public-Key: pk_live_sua_public_key_aqui
X-PLASMA-Secret-Key: sk_live_sua_secret_key_aqui

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

Veja os detalhes completos na página de Autenticação.

Pré-requisitos

Requisito	Detalhe
Conta Plasma	Cadastre-se em app.plasmacheckout.com
API Keys	Gere via Dashboard → Configurações → API Keys
Ferramenta HTTP	cURL, Postman, ou qualquer linguagem de programação
HTTPS (webhooks)	Seu endpoint de webhook precisa de HTTPS

Tipos de API Keys

Tipo	Prefixo	Uso
Public Key	`pk_live_` ou `pk_test_`	Obrigatória em todos os requests — identifica a loja
Secret Key	`sk_live_` ou `sk_test_`	Obrigatória em todos os requests — autentica a operação

Ambas as chaves (Public e Secret) devem ser enviadas juntas em todos os requests autenticados. A Public Key identifica sua loja e a Secret Key valida suas permissões.

Ambientes

Ambiente	Prefixo	Descrição
Test	`_test_`	Sandbox para desenvolvimento — sem transações reais
Live	`_live_`	Produção — transações reais

As duas chaves (Public e Secret) devem usar o mesmo ambiente. Misturar pk_test_ com sk_live_ retornará erro 401 Environment Mismatch.

Rate Limiting

A API aplica limites de requisições por API Key. Os seguintes headers são retornados em todas as respostas:

Header	Descrição
`X-RateLimit-Limit`	Máximo de requests por janela de tempo
`X-RateLimit-Remaining`	Requests restantes na janela atual
`X-RateLimit-Reset`	Unix timestamp de quando o limite reseta
`Retry-After`	Segundos até poder tentar novamente (apenas em 429)

Ao receber status 429 Too Many Requests, aguarde o tempo indicado no header Retry-After antes de tentar novamente.

Usando o SDK Node.js/TypeScript

Para projetos Node.js e TypeScript, o SDK oficial oferece tipagem completa, retry automático em erros 429/5xx, e timeout configurável.

Instalação

npm

npm install @plasmacheckout/sdk

pnpm

pnpm add @plasmacheckout/sdk

Inicialização

plasma.ts

import { PlasmaSDK } from '@plasmacheckout/sdk';

const plasma = new PlasmaSDK({
  apiKey: process.env.PLASMA_PUBLIC_KEY!,
  secretKey: process.env.PLASMA_SECRET_KEY!,
});

Exemplos rápidos

Produtos

// Listar produtos
const { data, pagination } = await plasma.products.list({ limit: 10 });

// Criar produto
const { data: product } = await plasma.products.create({
  title: 'Camiseta Premium',
  price: 7990,
  status: 'active',
});

Checkout

// Criar link de checkout
const { data: session } = await plasma.checkout.createLink({
  items: [{ title: 'Camiseta', price: 7990, quantity: 1 }],
  successUrl: 'https://minhaloja.com/sucesso',
});

console.log(session.checkoutUrl); // URL pronta para redirecionar

Pedidos

// Listar pedidos pendentes
const { data: orders } = await plasma.orders.list({ status: 'pending' });

// Atualizar status
await plasma.orders.update('order_id', {
  status: 'completed',
  paymentStatus: 'paid',
});

Clientes

// Buscar cliente por email
const { data: customer } = await plasma.customers.get('cliente@email.com', {
  includeOrders: true,
});

Webhooks

import { verifyWebhookSignature } from '@plasmacheckout/sdk';

// Verificar assinatura de webhook
const isValid = verifyWebhookSignature(
  req.body,
  req.headers['x-plasma-signature'],
  process.env.WEBHOOK_SECRET!,
);

Tratamento de erros

Error Handling

import { PlasmaError } from '@plasmacheckout/sdk';

try {
  await plasma.products.get('id_inexistente');
} catch (error) {
  if (error instanceof PlasmaError) {
    console.log(error.code);       // 'NOT_FOUND'
    console.log(error.statusCode); // 404
    console.log(error.message);    // 'Product not found'
  }
}

Configuração avançada

const plasma = new PlasmaSDK({
  apiKey: 'pk_live_xxx',
  secretKey: 'sk_live_xxx',
  baseUrl: 'https://api.plasmacheckout.com', // opcional
  timeout: 30000,                             // ms, opcional
});

O SDK faz retry automático em erros 429 (rate limit) e 5xx (erros do servidor) com backoff exponencial — até 3 tentativas.

Configuração

Início Rápido

Gere suas API Keys

Configure variáveis de ambiente

Faça sua primeira requisição

Verifique a resposta

Base URL

Autenticação

Pré-requisitos

Tipos de API Keys

Ambientes

Rate Limiting

Usando o SDK Node.js/TypeScript

Instalação

Inicialização

Exemplos rápidos

Tratamento de erros

Configuração avançada

Próximos Passos

Autenticação

Produtos

Checkout

On this page