Guias de integração
Usar Organização API Versão 1 no servidor
Comece com domínio aprovado e chaves completas e leia antes de executar operações privadas assinadas.
Antes de começar
- Conta Organização aprovada, domínio HTTPS verificado e chaves completas do Criador.
- Node 20+ para o SDK local da área de trabalho ou HTTPS Python/PHP no backend.
- Referência Versão 1 e capacidades; versão API 1 e versão de assinatura 2 são diferentes.
Configurar chaves e efetuar uma leitura
Mantenha SPARKGLIM_APPROVED_DOMAIN e chaves keyId:secret apenas no servidor. As leituras enviam x-white-label-domain e a chave pública ou de campanha completa; não invente outro identificador configurado separadamente.
TypeScript pressupõe @sparkglim/organization-sdk construído e disponível no projeto. A publicação npm não foi verificada. Python e PHP usam HTTPS diretamente sem afirmar existirem SDKs próprios.
import { SparkGlimOrganization } from '@sparkglim/organization-sdk';
const client = new SparkGlimOrganization({
baseUrl: 'https://api.sparkglim.net',
domain: process.env.SPARKGLIM_APPROVED_DOMAIN!,
publicKey: process.env.SPARKGLIM_PUBLIC_KEY,
privateKey: process.env.SPARKGLIM_PRIVATE_KEY,
campaignKey: process.env.SPARKGLIM_CAMPAIGN_KEY,
});
export async function readOrganizationCampaigns() {
return client.campaigns.list();
}import json
import os
import urllib.request
def read_organization_campaigns():
key = os.environ["SPARKGLIM_PUBLIC_KEY"]
domain = os.environ["SPARKGLIM_APPROVED_DOMAIN"]
request = urllib.request.Request("https://api.sparkglim.net/api/white-label/v1/campaigns", headers={"Accept":"application/json", "x-white-label-domain":domain, "x-white-label-key":key})
with urllib.request.urlopen(request, timeout=15) as response:
payload = json.load(response)
if payload.get("success") is not True:
raise RuntimeError("Organization read failed")
return payload.get("data")<?php
function read_organization_campaigns(): array {
$handle = curl_init('https://api.sparkglim.net/api/white-label/v1/campaigns');
curl_setopt_array($handle, [CURLOPT_RETURNTRANSFER=>true, CURLOPT_TIMEOUT=>15, CURLOPT_HTTPHEADER=>[
'Accept: application/json', 'x-white-label-domain: '.getenv('SPARKGLIM_APPROVED_DOMAIN'), 'x-white-label-key: '.getenv('SPARKGLIM_PUBLIC_KEY')
]]);
$raw = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
curl_close($handle);
if ($raw === false || $status < 200 || $status >= 300) throw new RuntimeException('Organization read failed');
$payload = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if (($payload['success'] ?? false) !== true) throw new RuntimeException('Organization read failed');
return $payload['data'];
}Compreender a assinatura privada
As ações privadas exigem HMAC versão 2, domínio, data, nonce novo, âmbitos e idempotência. Forma: v2.domain.idempotencyKey.campaignKey.timestamp.nonce.METHOD.pathname.sortedQuery.sha256(rawBody). Assine bytes transmitidos e consulta ordenada codificada.
O SDK assina os métodos implementados. Não o inclua no navegador, reutilize nonce nem copie o assinador antigo do WordPress.
Preparar pagamento de teste explícito
A função inativa usa client.checkout.create com campos reais documentados e return_path relativo autorizado. A entrada não define um preço que o servidor aceite como autoridade.
Preserve a chave de idempotência na mesma ação e devolva authorization_url ao cliente. Server controla pagamento e entrega, sem verificação ou consultas periódicas no navegador.
import { randomUUID } from 'node:crypto';
import { SparkGlimOrganization } from '@sparkglim/organization-sdk';
export async function createApprovedTestCheckout(client: SparkGlimOrganization, input: unknown, stableRequestId: string, approvedTest: boolean) {
if (!approvedTest) throw new Error('Approved test configuration required');
const data = await client.checkout.create(input, stableRequestId);
if (typeof data.authorization_url !== 'string') throw new Error('No paid checkout URL returned');
const target = new URL(data.authorization_url);
if (target.origin !== 'https://checkout.sparkglim.net' || target.username || target.password) throw new Error('Invalid checkout URL');
return { authorization_url: target.href };
}
export const newRequestId = () => randomUUID();Verifique a sua integração
- Verificar domínio, âmbitos e segredos fora de bundles e registos.
- Testar assinaturas inválidas apenas com autorização e distinguir código local, publicação e implementação.