Guías de integración
Usar Organización API Versión 1 desde su servidor
Empiece con dominio aprobado y claves completas, y lea antes de hacer operaciones privadas firmadas.
Antes de empezar
- Cuenta Organización aprobada, dominio HTTPS verificado y claves completas de Creador.
- Node 20+ para el SDK local del espacio de trabajo o HTTPS Python/PHP en su backend.
- Referencia Versión 1 y capacidades; versión API 1 y versión de firma 2 son distintas.
Configurar claves y realizar una lectura
Mantenga SPARKGLIM_APPROVED_DOMAIN y claves keyId:secret solo en servidor. Las lecturas envían x-white-label-domain y la clave pública o de campaña completa; no invente otro identificador configurado aparte.
TypeScript presupone @sparkglim/organization-sdk construido y disponible en su proyecto. Su publicación npm no está verificada. Python y PHP llaman HTTPS directamente, sin afirmar que haya SDKs específicos.
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'];
}Comprender la firma privada
Las operaciones privadas requieren HMAC versión 2, dominio, fecha, nonce nuevo, ámbitos e idempotencia. Forma: v2.domain.idempotencyKey.campaignKey.timestamp.nonce.METHOD.pathname.sortedQuery.sha256(rawBody). Firme bytes transmitidos y consulta ordenada codificada.
El SDK firma sus métodos implementados. No lo incluya en el navegador, reutilice nonce ni copie el firmante antiguo de WordPress.
Preparar un pago de prueba explícito
La función inactiva usa client.checkout.create con campos reales documentados y return_path relativo autorizado. La entrada no es un pedido de precio autorizado por el cliente.
Conserve la clave de idempotencia para la misma operación y devuelva authorization_url al cliente. Server controla pago y entrega, sin verificación ni sondeo del 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();Compruebe su integración
- Comprobar dominio, ámbitos y secretos fuera de bundles y registros.
- Probar firmas inválidas solo con autorización y distinguir código local, publicación y despliegue.