Salta al contenuto

API pseudonymize.io

Benvenuti nella documentazione di pseudonymize.io. Inserisci questa API nel percorso dei tuoi dati sensibili prima che raggiungano sistemi esterni (come LLM, warehouse di analisi o strumenti di supporto di terze parti).

Avvio rapido

Invia una richiesta all'API Text per pseudonimizzare la prosa.

curl -X POST https://api.pseudonymize.io/text \
  -H "Authorization: Bearer ps_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Alice Rossi disputed invoice INV-204 from [email protected]",
    "policy": "default"
  }'

Risposta:

{
  "text": "PERSON_01 disputed invoice INV-204 from EMAIL_01",
  "entities": [
    { "type": "PERSON", "original": "Alice Rossi", "pseudonym": "PERSON_01" },
    { "type": "EMAIL", "original": "[email protected]", "pseudonym": "EMAIL_01" }
  ]
}

Autenticazione

Tutte le richieste API devono includere la chiave API nell'intestazione "Autorizzazione".

Authorization: Bearer ps_live_...

Le chiavi API vengono generate nel formato "ps_live_...". Per la tua sicurezza, la chiave segreta completa viene visualizzata solo una volta al momento della creazione. pseudonymize.io non memorizza mai le chiavi API in testo normale: vengono mantenuti solo un hash crittografico non reversibile (SHA-256) e un breve prefisso identificativo (ps_live_XXXX).

Puoi gestire le tue chiavi API nella Dashboard.

API di testo

POST https://api.pseudonymize.io/text (disponibile anche tramite POST https://api.pseudonymize.io/v1/text e /api/v1/text)

Sostituisce gli identificatori all'interno della prosa senza appiattire il testo attorno ad essi.

Richiedi corpo

  • text (stringa, obbligatorio): il testo da elaborare.
  • policy (stringa, opzionale): la policy da utilizzare. Il valore predefinito è "default"`.
  • detect (array, opzionale): tipi di entità specifici da rilevare.
{
  "text": "Call me at +39 333 1234567.",
  "detect": ["PHONE"]
}

API per dati strutturati

POST /api/v1/dati

Pseudonimizza i campi identificatore mantenendo righe e schemi utilizzabili.

Richiedi corpo

  • payload (oggetto | array, obbligatorio): la struttura JSON da elaborare (può anche essere passata come dati).
  • policy (stringa, opzionale): la policy da utilizzare. Il valore predefinito è "default"`.
  • detect (array, opzionale): tipi di entità specifici da rilevare.
{
  "payload": {
    "user": {
      "name": "Mario Rossi",
      "email": "[email protected]"
    }
  },
  "detect": ["PERSON", "EMAIL"]
}

Fatturazione e prenotazione del credito

Pseudonymize.io opera secondo un modello trasparente di pagamento in base al consumo:

  • €1 per milione di token misurati. Ogni richiesta riuscita viene arrotondata per eccesso a blocchi di 1.000 token (1 credito), con un addebito minimo di €0,001.
  • Prenotazione pre-volo: i crediti vengono riservati atomicamente al confine del gateway prima che i payload raggiungano il motore principale. Se un account ha crediti insufficienti, l'API restituisce immediatamente "402 Payment Required" senza inoltrare i dati del cliente.
  • Garanzia di rimborso automatizzato: se una chiamata di elaborazione core upstream fallisce o scade, i crediti riservati vengono immediatamente rimborsati per intero.

Pseudonimi e identità deterministica

Pseudonymize.io utilizza la conservazione deterministica dell'identità all'interno di una singola richiesta. Se "Alice" appare tre volte nello stesso documento, diventa "PERSON_01" tutte e tre le volte. Ciò consente agli LLM di capire che si tratta della stessa persona senza sapere chi sia.

Errori e limiti

Utilizziamo codici di stato HTTP standard.

  • 200 OK: elaborazione riuscita.
  • "400 Bad Request": formato del payload non valido o mancante o profondità dei dati strutturati superiore a 32 livelli.
  • 401 Unauthorized: chiave API mancante, non valida o inattiva.
  • "402 Pagamento richiesto": crediti rimanenti insufficienti. Bloccato al confine del gateway.
  • "413 Payload troppo grande": il corpo della richiesta supera i 10 MB o il conteggio totale degli elementi strutturati supera le 50.000 chiavi.
  • "429 Too Many Requests": limite di velocità superato (60 richieste/min per chiave API, 120 richieste/min per account e IP). L'intestazione "Retry-After" indica quando riprovare.
  • 502 Bad Gateway: motore principale irraggiungibile o errore di elaborazione backend. I crediti vengono rimborsati automaticamente.
  • 504 Gateway Timeout: il motore principale non ha risposto entro 30 secondi. I crediti vengono rimborsati automaticamente.

Entità supportate

  • "PERSONA" (Nomi)
  • "ORGANIZZAZIONE" (Nomi delle aziende)
  • EMAIL (Indirizzi email)
  • "TELEFONO" (numeri di telefono)
  • LOCATION (Città, indirizzi)
  • "IP" (IPv4 e IPv6)
  • "IBAN" (Conti bancari)
  • "CARD" (carte di credito/debito)

Sicurezza

  • Le tabelle di fatturazione del gateway e le metriche delle richieste strutturate escludono i corpi delle richieste e delle risposte API. I metadati di account, autenticazione, utilizzo, prenotazione e pagamento vengono conservati separatamente; l'eliminazione dell'account non elimina ogni record o backup.
  • Le risposte riuscite con un Idempotency-Key vengono conservate nella memoria del processo per una finestra di riproduzione di cinque minuti. I dettagli dell'entità possono contenere identificatori originali. I controlli di motore, proxy, scambio, crash-dump e backup richiedono una verifica separata; la persistenza del disco zero non è garantita lungo la catena di elaborazione.
  • Consulta l'Informativa sulla Privacy e la pagina Sicurezza per i limiti di gestione e cancellazione.