API / v1 · stabile

Documentazione API

Un endpoint per estrarre numeri casuali da codice: chiave in header, risposte JSON, nessun SDK. Le estrazioni usano il CSPRNG del sistema operativo, non un generatore con seme.

BASE URL https://pseudocodice.it/random/api/v1

Autenticazione

Ogni richiesta a /api/v1 porta la chiave nell'header X-API-Key. Per prove rapide accetta anche il parametro key in query string, sconsigliato in produzione perché finisce nei log. Le chiavi hanno formato rnd_ seguito da 40 caratteri esadecimali e si revocano lato server senza fermare il servizio.

curl -s -H "X-API-Key: rnd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://pseudocodice.it/random/api/v1/random?min=1&max=6&n=2"

Endpoint

GET /random Numeri interi uniformi

Estrae n interi nell'intervallo chiuso [min, max]. Ogni valore è indipendente e uniforme: nessun bias del modulo, perché l'estrazione usa campionamento per rifiuto su random_int() di PHP, che legge dal pool di entropia del sistema.

PARAM	TIPO	DEFAULT	DESCRIZIONE
min	int	1	Estremo inferiore, incluso. Accetta negativi.
max	int	100	Estremo superiore, incluso. Se min > max vengono riordinati.
n	int	1	Quanti valori restituire. Da 1 a 100 per richiesta.
unique	0 \| 1	0	Con 1 estrae senza reimmissione: nessun valore ripetuto nella risposta.
key	string	—	Alternativa all'header, per test rapidi. Non usare in produzione.

RICHIESTA

curl -s -H "X-API-Key: rnd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://pseudocodice.it/random/api/v1/random?min=1&max=90&n=6&unique=1"

200 OK

{
  "ok": true,
  "values": [7, 23, 41, 58, 69, 82],
  "range": [1, 90],
  "bits": 38,
  "quota": { "limit": 10000, "remaining": 9994 },
  "source": "php-random_int (CSPRNG)"
}

values è sempre un array, anche con n=1. bits è l'entropia dell'intera risposta: log2(intervallo) × n. Sui piani forever quota.remaining vale null e quota.unlimited è true.

Errori

STATUS	CODE	SIGNIFICATO
401	invalid_key	Chiave assente, malformata o revocata.
400	bad_range	min e max non definiscono un intervallo valido.
400	range_too_small	Chiesti più valori unici di quanti l'intervallo ne contiene.
429	quota_exceeded	Quota mensile esaurita; il corpo riporta quota.limit.
503	stripe_disabled	Checkout non configurato (solo /api/checkout).
404	not_found	Endpoint inesistente.

Esempi

JavaScript

const res = await fetch(
  "https://pseudocodice.it/random/api/v1/random?min=1&max=100&n=5&unique=1",
  { headers: { "X-API-Key": process.env.RANDOM_KEY } }
);
const data = await res.json();
if (!data.ok) throw new Error(data.error);
console.log(data.values); // [17, 4, 88, 42, 63]

PHP

$ch = curl_init('https://pseudocodice.it/random/api/v1/random?min=1&max=100&n=5');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . getenv('RANDOM_KEY')],
    CURLOPT_TIMEOUT        => 10,
]);
$data = json_decode((string) curl_exec($ch), true);
print_r($data['values'] ?? []);

Python

import os, requests

r = requests.get(
    "https://pseudocodice.it/random/api/v1/random",
    params={"min": 1, "max": 100, "n": 5, "unique": 1},
    headers={"X-API-Key": os.environ["RANDOM_KEY"]},
    timeout=10,
)
print(r.json()["values"])

Quota e limiti

Piani a pagamento: 10.000 estrazioni al mese, contatore azzerato il primo del mese. Piani forever: illimitate, il contatore resta solo per statistica. n è limitato a 100 per richiesta: oltre, suddividi in più chiamate. Non c'è limite di velocità sull'API a chiave; gli endpoint di telemetria hanno un tetto di 120 richieste all'ora per IP.

Come si ottiene una chiave

La chiave arriva con una licenza Pro, emessa dopo il pagamento. Su un altro dispositivo si ripristina incollando la chiave di licenza nella pagina Pro. Non esiste registrazione: la licenza è la credenziale, e si revoca dal server.

Vedi i piani

Endpoint interni

Usati dal sito stesso. Non sono pensati per uso pubblico: possono cambiare senza preavviso e alcuni accettano solo richieste dalla stessa origine.

POST	/api/hit	Telemetria delle estrazioni fatte nel browser: {tool, n, bits}. Rate limit per IP.
GET	/api/stats	Totali aggregati: generations, bits, tools.
POST	/api/checkout	Crea una Checkout Session Stripe: {plan, lang} → {url}.
POST	/api/stripe/webhook	Eventi Stripe con firma HMAC verificata, tolleranza 5 minuti.

L'API non registra i valori restituiti: il server genera la risposta e la dimentica, come per gli strumenti nel browser. Versione v1: nessuna chiave di rottura prevista, i campi si aggiungono, non si rimuovono.