Un’unica API per ordini, portafoglio e il marketplace

Un solo contratto, versionato per data

Ogni endpoint si trova sotto /v1 sul dominio della vetrina con cui integri. Le risposte sono in JSON, gli importi sono stringhe decimali associate a una valuta ISO 4217 e i timestamp seguono il formato ISO 8601. Ogni risposta riporta un’intestazione X-Api-Version con la data del contratto con cui stai comunicando e un X-Request-Id che puoi citare al supporto. Gli errori hanno sempre lo stesso corpo: un oggetto error con un codice stabile, un messaggio leggibile e dettagli facoltativi, insieme al request_id.

Il file OpenAPI 3.1 descrive ogni percorso, schema e codice di errore. Importalo nel tuo client HTTP o nel generatore di codice e otterrai richieste tipizzate per catalogo, ordini, portafoglio, inserzioni, offerte e consegne delle operazioni.

Chiavi, autorizzazioni e l’account per cui agiscono

La chiave è creata dal titolare dell’account nel piano Rivenditore e viene mostrata una sola volta; viene memorizzato solo un hash. Al momento della creazione scegli le sue autorizzazioni, un elenco facoltativo di IP consentiti (fino a 20 indirizzi) e una scadenza facoltativa. La rotazione crea una nuova chiave con le stesse autorizzazioni e revoca la precedente, così puoi sostituire le credenziali senza interruzioni. Gli ordini effettuati con una chiave vengono addebitati sul portafoglio dell’account e compaiono nella stessa dashboard degli ordini manuali, con la fonte indicata come API.

Ogni chiave eredita il limite di richieste al minuto del livello cliente dell’account. Le intestazioni RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset indicano a che punto sei; superato il limite l’API risponde con 429 e un’intestazione Retry-After, e la reazione corretta è attendere esattamente quel tempo.

Scritture idempotenti e lotti

La creazione di un ordine è l’unica chiamata che muove denaro, quindi è protetta due volte. Primo, l’intestazione Idempotency-Key è obbligatoria: ripetere una richiesta con la stessa chiave restituisce l’ordine originale senza un secondo addebito, e riutilizzare la chiave con un corpo diverso viene rifiutato con 409 IDEMPOTENCY_KEY_REUSE. Secondo, una finestra anti-duplicati individua lo stesso servizio, link e quantità inviati di nuovo in un intervallo breve senza corrispondenza della chiave, e restituisce 409 DUPLICATE_ORDER.

I lotti accettano fino a 100 ordini per chiamata. Ogni elemento viene validato e addebitato singolarmente, identificato dalla chiave del lotto più il suo indice, e la risposta riporta un risultato per elemento, così una riga difettosa non blocca mai le altre. Usa prima POST /v1/orders/preview quando vuoi l’addebito esatto e il risultato della validazione senza creare nulla.

• Genera un UUID per ogni ordine logico e salvalo prima dell’invio.
• In caso di timeout, reinvia con la stessa chiave; non generarne mai una nuova per lo stesso ordine.
• Considera i codici 4xx come definitivi e i codici 5xx e 429 come ritentabili con attesa crescente.

Webhook di cui puoi fidarti

Ogni cambio di stato viene scritto in una coda nella stessa transazione di database del cambio stesso, e un distributore lo consegna al tuo endpoint https con tre intestazioni: Webhook-Id, Webhook-Timestamp e Webhook-Signature. La firma è un HMAC-SHA256 del timestamp, di un punto e del corpo grezzo, calcolato con il segreto dell’endpoint mostrato una sola volta alla creazione. Verificala in tempo costante, rifiuta i timestamp più vecchi di cinque minuti e deduplica per Webhook-Id, perché un evento ritentato porta lo stesso id.

Le consegne che non ricevono un 2xx vengono ritentate dopo 1 minuto, 5 minuti, 30 minuti, 2 ore, 6 ore, 12 ore e 24 ore, prima di essere contrassegnate come fallite in modo definitivo. Rispondi rapidamente ed elabora in modo asincrono; un gestore lento è la causa più frequente di elaborazione duplicata.

Pannelli figli tramite l’endpoint SMM v2

Se il tuo pannello parla già il formato diffuso “SMM API v2”, puoi aggiungere questa vetrina come fornitore incollando l’URL /api/v2 e la tua chiave. Sono supportate le azioni services, add, status, balance, refill, refill_status e cancel, i prezzi tornano nella valuta e nel livello del tuo account, e gli errori usano la forma piatta { "error": "messaggio" } che questi pannelli si aspettano. L’idempotenza deriva dal contenuto dell’ordine e dal minuto corrente, quindi gli invii doppi accidentali nello stesso minuto vengono unificati.