Guia · IA e desenvolvimento
Construa com a sua IA favorita.
Dê à sua ferramenta de IA o contrato real da LoopPay. Gere integrações para catálogo, estoque, pagamentos e webhooks com exemplos, permissões e regras claras.
Entregue o contexto certo
/llms.txtMapa da integração ↗
Links e instruções essenciais para começar.
/llms-full.txtReferência em texto ↗
Endpoints, exemplos, pagamentos e protocolo de webhooks.
/openapi.jsonContrato OpenAPI 3.1 ↗
Métodos, campos, respostas e permissões por operação.
O domínio público temporário da plataforma é https://flowpayments.net. Forneça esses endereços públicos para sua IA; localhost funciona somente no computador onde o servidor está rodando. Nenhuma conta de IA é conectada automaticamente.
Do contexto ao primeiro pedido
Crie uma API Key
No painel da aplicação, abra API Keys e conceda somente as permissões necessárias. Para começar a ler catálogo: products:read. Para cobranças: payments:read e payments:write. Webhooks usam webhooks:read e webhooks:write.
Configure as variáveis no seu servidor
Use LOOPPAY_URL com o domínio da plataforma e LOOPPAY_API_KEY com a chave da aplicação. O segredo não deve ir para o frontend, repositório ou conversa com a IA.
Peça que a IA leia a referência
Forneça llms-full.txt e openapi.json antes de solicitar o código. O prompt abaixo pode ser copiado; os exemplos usam flowpayments.net.
Comece por uma consulta
Teste GET /products, confira data.items e percorra as páginas até data.total. As opções de cada produto ficam em /products/id/subproducts.
Teste o fluxo no ambiente adequado
O ambiente é configurado na plataforma. Sandbox não consome estoque e não gera saldo real. Não use saques reais para conferir se o código compila.
# Configure no servidor da sua integração
LOOPPAY_URL=https://flowpayments.net
LOOPPAY_API_KEY=SUA_CHAVE_LOOPPAY
LOOPPAY_WEBHOOK_SECRET=SEGREDO_DO_SEU_WEBHOOK
# No PowerShell, use curl.exe
curl "https://flowpayments.net/api/v1/products?limit=100&page=1" \
-H "Authorization: Bearer SUA_CHAVE_LOOPPAY"Um ponto de partida para a sua IA
Copie o prompt, descreva o seu projeto e acrescente quais recursos deseja integrar. Não inclua credenciais na mensagem.
Integre meu sistema à API LoopPay v1.
Antes de escrever código, leia https://flowpayments.net/llms-full.txt e https://flowpayments.net/openapi.json.
Use https://flowpayments.net/api/v1 como base e LOOPPAY_API_KEY somente no servidor.
Não peça que eu cole a chave no chat e não use credenciais Supabase ou Woovi.
Implemente somente endpoints existentes no contrato. Comece com GET /products?limit=20&page=1 e percorra todas as páginas.
Produtos, subprodutos, fotos, estoque, cobranças e saques devem seguir os nomes, tipos e permissões documentados.
Em escritas, persista um UUID Idempotency-Key por operação e reutilize o mesmo corpo nas novas tentativas. Não crie outro pagamento ou saque após um timeout sem consultar o recurso.
Valide webhooks pelo corpo bruto, timestamp e HMAC SHA-256 antes de fazer JSON.parse. Deduplique event.id em banco com restrição UNIQUE e confirme apenas depois de persistir em uma fila durável.
No sandbox não há saldo real nem consumo de estoque. Não simule aprovação em produção.
Não registre chaves, estoque privado, entrega ou dados pessoais nos logs. Trate erros HTTP, paginação e limites.
Entregue o código, variáveis de ambiente sem segredos, testes automatizados e as instruções para executar.Produtos, estoque e pagamentos
Cada produto e subproduto tem seu próprio ID, preço e estoque. A IA deve consultar o catálogo e enviar o productId selecionado; o servidor calcula o valor. Fotos podem ser vinculadas por URL HTTPS ou pelo endpoint de imagem. O conteúdo privado do estoque exige stock:read/write.
const operationId = crypto.randomUUID(); // persista antes de enviar
const response = await fetch(process.env.LOOPPAY_URL + "/api/v1/payments", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.LOOPPAY_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": operationId,
},
body: JSON.stringify({
productId: "UUID_DO_PRODUTO_OU_SUBPRODUTO",
quantity: 1,
name: "Cliente exemplo",
email: "cliente@exemplo.com",
}),
});
const result = await response.json();
if (!response.ok) {
// Em timeout/503: consulte a reserva antes de criar outra operação.
throw new Error(result.error.message);
}
console.log(result.data.id, result.data.status);Gerar o Pix não confirma uma venda. Espere payment.completed ou valide pela rota /payments/id/refresh. Em produção, a entrega automática fica disponível após a confirmação; entrega manual é registrada em /payments/id/delivery. Não existe endpoint v1 para o cliente forçar uma aprovação.
Receba eventos com assinatura
Cadastre uma URL HTTPS pública no painel, em Integração → Webhooks, ou pela API. Escolha os eventos e o ambiente. Guarde o segredo whsec_ no receptor: ele é diferente da chave usada para chamar a API.
// Verifique antes de fazer JSON.parse(rawBody).
import { createHmac, timingSafeEqual } from "node:crypto";
const timestamp = String(req.headers["x-looppay-timestamp"] || "");
const signature = String(req.headers["x-looppay-signature"] || "");
const expected = "v1=" + createHmac("sha256", process.env.LOOPPAY_WEBHOOK_SECRET)
.update(timestamp + ".").update(rawBody).digest("hex");
const valid = /^\d{10,11}$/.test(timestamp)
&& Math.abs(Math.floor(Date.now()/1000) - Number(timestamp)) <= 300
&& /^v1=[a-f0-9]{64}$/.test(signature)
&& timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!valid) throw new Error("Assinatura inválida");
const event = JSON.parse(rawBody.toString("utf8"));
// Persista event.id UNIQUE + job na mesma transação antes de responder 2xx.Persistência faz parte da integração
A entrega pode se repetir e eventos podem chegar fora de ordem. Peça à IA uma tabela com event.id único e uma fila durável. Confirme com HTTP 2xx depois da gravação; um Set em memória não protege contra reinicializações. Há até 8 tentativas automáticas, com intervalo crescente, e até 3 reprocessamentos manuais.
Baixar receptor Node.jsO exemplo valida a assinatura e retorna 501 até você implementar a persistência. Isso evita reconhecer um evento sem salvá-lo.
O servidor da plataforma precisa manter o worker agendado para enviar os eventos. No painel, Processar pendentes permite um teste manual. Acompanhe HTTP, falhas e tentativas em Fluxos → Logs → Webhooks.
Peça testes que comprovem o comportamento
- Chave inválida ou sem permissão deve retornar 401/403. Uma chave não pode acessar produtos de outra aplicação.
- A paginação deve recuperar todos os itens. Subprodutos devem manter preço e estoque próprios.
- Repetir uma escrita com o mesmo UUID não deve duplicar produto, cobrança ou saque. Em 409/503, consulte o estado antes de criar outra operação.
- Webhooks com assinatura alterada ou timestamp antigo devem ser rejeitados. Duplicar event.id não deve executar o negócio duas vezes.
- O teste deve usar respostas simuladas ou sandbox, sem enviar dinheiro real nem registrar segredos nos logs.