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:
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 para garantir a máxima segurança em produção.
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!
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:
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.
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 itens do carrinho, URLs de callback (success_url, cancel_url) e o campo metadata se houver cupom ou rastreio de checkout.
4. 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.
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/session` contendo o seguinte payload:
{
"line_items": [
{
"variantId": "string",
"quantity": 1
}
],
"success_url": "https://meusite.com/obrigado",
"cancel_url": "https://meusite.com/carrinho"
}
3. Ao receber a resposta da API com a propriedade `checkoutUrl`, redirecione o usuário imediatamente para este link de forma suave.Crie uma interface de carrinho de compras bonita em React + Tailwind CSS e integre o fluxo de finalização com o Plasma Checkout.
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/session` autenticado com os headers customizados `X-PLASMA-Public-Key` e `X-PLASMA-Secret-Key`.
3. Retorne a URL de checkout (`checkoutUrl`) para o frontend.
4. 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).
1) Para autenticar, envie sempre os headers `X-PLASMA-Public-Key` e `X-PLASMA-Secret-Key` com as chaves geradas no painel.
2) O endpoint para criar um checkout é um POST em `/api/sdk/checkout/session`.
3) Envie o JSON com "line_items" (contendo variantId e quantity), "success_url" e "cancel_url".
4) Recupere o link retornado em "checkoutUrl" e faça o redirecionamento.
5) Certifique-se de validar se o retorno foi 200 e tratar falhas de rede.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
try {
const session = await plasma.checkout.createLink({
line_items: [
{
variantId: 'var_premium_01',
quantity: 2,
}
],
success_url: 'https://seuecommerce.com/sucesso',
cancel_url: '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.