Integração com IA (Cursor / Lovable / v0)
Use inteligência artificial para acelerar e blindar a integração do Plasma Checkout no seu e-commerce em segundos.
Visão Geral
Se você utiliza assistentes de código e geradores de IA, como Cursor, Lovable, v0.dev, Bolt.new, Claude ou ChatGPT, você pode programar toda a sua integração com o Plasma Checkout de forma automática.
Esta documentação foi projetada e estruturada para servir de contexto direto para essas ferramentas, permitindo que a IA gere código livre de bugs, com tratamento de erros avançado e respeitando 100% o nosso SDK e API.
Superpoder para Construtores: Fornecer esta página como referência para o seu assistente de IA garante que ele gere integrações resilientes com retentativa automática, timeouts corretos e tratamento de cupons em poucos segundos.
Como Alimentar a IA
Siga os passos simples abaixo para ensinar qualquer IA a integrar o Plasma Checkout no seu projeto:
Gere um par de chaves de TESTE
No painel, vá em Loja → API Keys e gere um par de ambiente test
(pk_test_... e sk_test_...). São essas que você entrega para a IA.
O prompt manda a IA fazer chamadas reais na API para conferir o que gerou,
antes e depois de escrever o código. Com chaves test, as sessões de
checkout criadas nessa verificação ficam marcadas como teste e não se
misturam às suas vendas.
Copie o Prompt de Integração
Escolha o prompt pré-formatado correspondente à ferramenta que você está usando nas abas abaixo e cole-o no chat da sua ferramenta de IA favorita.
Forneça as API Keys como Variáveis
Informe à IA para ler as credenciais X-PLASMA-Public-Key e X-PLASMA-Secret-Key do arquivo .env, nunca escritas direto no código.
Gere a Integração Completa
A IA irá processar as regras arquiteturais do Plasma e gerar o código completo com listagem de produtos, persistência de carrinho e criação do link de checkout blindado!
Troque para as chaves de produção
Com a verificação passando, gere o par live e substitua as variáveis de
ambiente. Nenhuma linha de código precisa mudar: o par de chaves é o que
define o ambiente.
O catálogo é o mesmo nos dois ambientes. Um produto criado com chave
pk_test_ aparece na sua loja como qualquer outro, porque só a sessão de
checkout distingue teste de produção. Por isso o roteiro de verificação
apaga o produto de sonda ao final. Se a IA interromper no meio, confira em
Produtos se sobrou algum item de teste antes de ir para produção.
Prompts Prontos para Copiar e Colar
Escolha a ferramenta que você está usando e copie o prompt correspondente para obter código perfeito na primeira tentativa:
Os quatro prompts apontam a IA para
llms-api.txt, nossa referência de
integração em texto puro: contrato completo com request e response reais de
autenticação, produtos, checkout, webhooks e tabela de erros, num arquivo só.
Ela traz um roteiro de verificação para a IA executar contra a API, antes e depois de escrever o código. É o que evita entregar integração que só falha em runtime. Se a sua ferramenta não acessa a internet, baixe o arquivo e anexe ao contexto.
Você é um Engenheiro de Software Sênior especialista em integrações de E-commerce.
Integre o Plasma Checkout no meu projeto usando o SDK oficial do Plasma.
ANTES DE ESCREVER CÓDIGO: leia https://plasmacheckout.com/llms-api.txt.
Ele traz o contrato completo com request e response reais, e a seção 0.1
tem um protocolo de verificação com curls para você RODAR, antes e depois
de implementar. Execute-os com as chaves de teste (pk_test_/sk_test_) e só
entregue o código depois que passarem.
Diretrizes de Implementação:
1. Instale o pacote oficial via npm/pnpm: `@plasmacheckout/sdk`.
2. Instancie o cliente `PlasmaSDK` usando as variáveis do arquivo `.env` (`PLASMA_PUBLIC_KEY` e `PLASMA_SECRET_KEY`).
3. Crie um serviço de checkout (`CheckoutService`) contendo:
- Um método para listar produtos (`plasma.products.list`).
- Um método para criar sessões de checkout (`plasma.checkout.createLink`)
enviando `productIds` OU `items`, mais `successUrl`, `cancelUrl` e
`metadata` se houver cupom ou rastreio.
4. REGRA CRÍTICA de dinheiro: a API fala centavos inteiros, em campos com
sufixo `Cents` (`priceCents`, `totalCents`, `shippingCents`). `priceCents:
7990` é R$ 79,90. Nunca envie decimal: o campo é inteiro e recusa 79.90
com 422. Converta na borda com `Math.round(reais * 100)`.
5. Trate erros estritamente usando `PlasmaError` capturando código de erro (code) e status HTTP para logs detalhados.
Crie o código completo, tipado em TypeScript, modular e com comentários detalhados explicativos.Integre o fluxo de checkout do Plasma Checkout na minha aplicação.
Antes de codar, leia https://plasmacheckout.com/llms-api.txt: ele tem o
contrato real da API e, na seção 0.1, curls de verificação para rodar
antes e depois da implementação, com chaves de teste.
Regras da Integração:
1. A autenticação com a API do Plasma é feita através de dois headers obrigatórios em todas as requisições:
- `X-PLASMA-Public-Key`: sua chave pública (pk_test_... ou pk_live_...)
- `X-PLASMA-Secret-Key`: sua chave secreta (sk_test_... ou sk_live_...)
2. Crie uma ação ou função de backend que faça um POST para
`https://api.plasmacheckout.com/api/sdk/checkout/create-link`.
Existem duas formas de montar o corpo, e você deve escolher UMA:
a) Produtos que já existem no catálogo da loja (o preço vem do catálogo,
o cliente não consegue forjar valor):
{
"productIds": ["cm5abc123def456ghi789"],
"successUrl": "https://meusite.com/obrigado",
"cancelUrl": "https://meusite.com/carrinho"
}
b) Itens avulsos, informando o preço:
{
"items": [
{
"title": "Consultoria 1 hora",
"priceCents": 15000,
"quantity": 1
}
],
"successUrl": "https://meusite.com/obrigado",
"cancelUrl": "https://meusite.com/carrinho"
}
3. TODO valor monetário é inteiro em CENTAVOS, em campos terminados em
`Cents`. 15000 significa R$ 150,00. Enviar 150.00 é rejeitado com 422.
4. Ao receber a resposta, o link está em `data.checkoutUrl`. Redirecione o
usuário para lá.Crie uma interface de carrinho de compras bonita em React + Tailwind CSS e integre o fluxo de finalização com o Plasma Checkout.
Antes de codar, leia https://plasmacheckout.com/llms-api.txt e rode os
curls de verificação da seção 0.1, antes e depois de implementar, sempre
com as chaves de teste (pk_test_/sk_test_).
Regras de Backend para o Checkout:
1. Ao clicar em "Finalizar Compra", envie o carrinho de compras para o meu endpoint de backend que realiza a ponte de checkout.
2. O endpoint de backend deve disparar um POST para
`https://api.plasmacheckout.com/api/sdk/checkout/create-link`, autenticado
com os headers `X-PLASMA-Public-Key` e `X-PLASMA-Secret-Key`.
3. O corpo aceita `productIds` (ids do catálogo, preço vem do servidor) OU
`items` com `title`, `priceCents` e `quantity`. Nunca os dois juntos.
4. Preço é sempre inteiro em centavos: `priceCents: 15000` é R$ 150,00.
Nunca envie decimal: a API responde 422.
5. Retorne `data.checkoutUrl` para o frontend.
6. O frontend deve fazer um redirecionamento seguro com um indicador de carregamento (spinner premium) enquanto o link do checkout é processado.Integre o meu sistema com a API de checkout da Plasma (https://api.plasmacheckout.com).
0) Leia antes https://plasmacheckout.com/llms-api.txt, que traz o contrato
com payloads reais e, na seção 0.1, curls para você executar antes e
depois de implementar, usando chaves de teste.
1) Para autenticar, envie sempre os headers `X-PLASMA-Public-Key` e
`X-PLASMA-Secret-Key` com as chaves geradas no painel. As duas precisam ser
do mesmo ambiente: misturar test com live devolve 401.
2) O endpoint para criar um checkout é POST em `/api/sdk/checkout/create-link`.
3) O JSON aceita "productIds" (array de ids do catálogo) OU "items"
(cada um com "title", "priceCents" e "quantity"). Um ou outro, nunca ambos.
As URLs de retorno são "successUrl" e "cancelUrl", em camelCase.
4) Todo dinheiro é inteiro em centavos, em campo terminado em "Cents".
priceCents 7990 é R$ 79,90. Decimal é rejeitado com 422.
5) O link vem em "data.checkoutUrl". Recupere e redirecione.
6) A criação responde 201. Trate 422 (formato do payload), 400 (regra de negócio), 401 (chave) e 429
(rate limit, respeitando o header Retry-After).Regras de Conexão com o SDK (Para Contexto da IA)
Se você estiver indexando arquivos em ferramentas como o Cursor (Ctrl+Enter com referências), garanta que a IA conheça as assinaturas de tipo corretas do nosso SDK:
import { PlasmaSDK, PlasmaError } from '@plasmacheckout/sdk';
// 1. Instanciação Segura (Sempre ler do .env)
const plasma = new PlasmaSDK({
apiKey: process.env.PLASMA_PUBLIC_KEY!,
secretKey: process.env.PLASMA_SECRET_KEY!,
});
// 2. Criação de Checkout com Tratamento de Erros de Elite
//
// `items` leva o preço em centavos inteiros. Para cobrar do catálogo da loja,
// troque `items` por `productIds: ['id_do_produto']`: aí o preço vem do
// servidor e não do cliente.
try {
const session = await plasma.checkout.createLink({
items: [
{
title: 'Camiseta Premium',
priceCents: 7990, // R$ 79,90
quantity: 2,
}
],
successUrl: 'https://seuecommerce.com/sucesso',
cancelUrl: 'https://seuecommerce.com/carrinho',
metadata: {
coupon: 'DESCONTO10',
utm_source: 'instagram',
}
});
console.log('Checkout gerado com sucesso:', session.checkoutUrl);
// Redirecione o usuário para session.checkoutUrl
} catch (error) {
if (error instanceof PlasmaError) {
console.error(`Erro Plasma [${error.code}]: ${error.message} (HTTP ${error.status})`);
} else {
console.error('Erro de conexão ou de rede:', error);
}
}Boas Práticas para Automações de IA
Atenção com chaves de produção (sk_live_...): Certifique-se de que a sua ferramenta de IA não adicione chaves reais de produção em arquivos que são enviados para controle de versão (como GitHub). Utilize sempre variáveis de ambiente (.env.local ou .env.production) para expor chaves confidenciais.
Com essas instruções, qualquer gerador de IA moderno criará sua infraestrutura de pagamentos de forma impecável, alinhada com as melhores práticas de engenharia de software distribuído e performance.