API in sola lettura

Documentazione per sviluppatori · v1 · 6 novembre 2026

L’API di iSwiss Pay permette a un programma tuo (gestionale, cruscotto, script di riconciliazione) di leggere i tuoi conti, i tuoi movimenti e il tuo wallet crypto. È in sola lettura: con una chiave API non si può muovere, cambiare o ordinare nulla.

1. Ottenere una chiave

Le chiavi API le rilascia il team iSwiss ai clienti con identità verificata. Chiedila dall’Assistenza nell’app o su app.iswisspay.ca: indica il nome che vuoi dare alla chiave (per esempio «gestionale») e, se vuoi, una scadenza.
La chiave ha la forma isk_live_…. Si mostra una volta sola: conservala come una password. Chi la possiede legge i tuoi dati.
Le tue chiavi, con l’ultimo uso, le vedi e le revochi quando vuoi in Profilo → Sicurezza → Chiavi API. Al massimo 5 chiavi attive per cliente.

2. Indirizzo base e autenticazione

https://app.iswisspay.ca/core/api/v1

Manda la chiave nell’intestazione Authorization a ogni richiesta. Si accetta solo GET; ogni altro metodo risponde 405.

curl -H "Authorization: Bearer isk_live_XXXXXXXX" \
     https://app.iswisspay.ca/core/api/v1/accounts

Limiti: 60 richieste al minuto per chiave (oltre, 429). Le risposte sono JSON, UTF-8, mai in cache (Cache-Control: no-store).

3. Chiamate

Metodo e percorso	Cosa rende
`GET /me`	Di chi è la chiave: `clientId`, `name`, `email`, `profile` (`personal` o `company`), e id e nome della chiave stessa.
`GET /accounts`	I tuoi conti con i saldi: id, valuta, IBAN, BIC, sort code e account number britannici dove ci sono, saldo, stato.
`GET /transactions`	I tuoi movimenti, dal più recente. Filtri: `account` (id di un conto), `from` e `to` (date `AAAA-MM-GG`, inclusi), `limit` (1–500, predefinito 100).
`GET /rates?from=EUR&to=GBP`	Il cambio corrente fra due valute (ISO 4217).
`GET /crypto`	Il tuo wallet crypto: saldo per ogni token con il valore in euro, e il totale.
`GET /crypto/transactions`	I movimenti crypto, dal più recente: cambi con l’euro (acquisti, vendite) e movimenti di rete (depositi, prelievi, trasferimenti fra clienti iSwiss). `limit` 1–500.
`GET /crypto/prices`	I prezzi in tempo reale in euro di ogni token (medio, acquisto e vendita, margine incluso).

GET /accounts

{
  "accounts": [
    {
      "id": "cj:5f3a…",
      "provider": "cj",
      "currency": "EUR",
      "iban": "GB12CLJU04130712345678",
      "bic": "CLJUGB21",
      "sortCode": null,
      "accountNumber": null,
      "balance": 1250.40,
      "status": "ACTIVE",
      "opened": "2026-10-01T09:12:00.000Z"
    }
  ]
}

status è ACTIVE, SUSPENDED o CLOSED. I saldi sono numeri nella valuta del conto (due decimali).

GET /transactions

curl -H "Authorization: Bearer isk_live_XXXXXXXX" \
     "https://app.iswisspay.ca/core/api/v1/transactions?from=2026-11-01&to=2026-11-30&limit=200"

{
  "transactions": [
    {
      "id": "cj:9b1c…",
      "accountId": "cj:5f3a…",
      "kind": "CREDIT",
      "status": "DONE",
      "amount": 200.00,
      "fee": 0,
      "currency": "EUR",
      "at": "2026-11-06T19:36:40.000Z",
      "reference": "Fattura 1042",
      "method": "sepa",
      "sender": { "name": "Esempio Srl", "number": "IT60…", "bic": "", "address": "" },
      "recipient": null
    }
  ],
  "count": 1
}

kind è CREDIT (entrata), DEBIT (uscita) o FEE (commissione). status è DONE, PENDING o REJECTED. amount è sempre positivo: la direzione la dice kind. sender c’è nelle entrate, recipient nelle uscite.

GET /crypto

{
  "active": true,
  "verified": true,
  "currency": "EUR",
  "balances": [
    { "asset": "USDT", "amount": 150.0, "valueEur": 134.47 },
    { "asset": "BTC", "amount": 0.0125, "valueEur": 849.18 }
  ],
  "totalEur": 983.65,
  "at": "2026-11-06T22:10:00.000Z"
}

active è falso se il cliente non ha ancora aperto il wallet crypto; verified è falso finché la verifica dell’identità non è completa (in entrambi i casi i saldi sono vuoti).

GET /crypto/transactions

{
  "transactions": [
    { "id": "a1b2…", "kind": "exchange", "status": "done", "from": "EUR", "to": "USDT",
      "amountFrom": 100.00, "amountTo": 111.2, "rate": 0.8993, "eur": 100.00,
      "at": "2026-11-06T18:02:11.000Z", "doneAt": "2026-11-06T18:02:12.000Z" },
    { "id": "e9a5…", "kind": "deposit", "status": "confirmed", "asset": "USDT", "amount": 50.0, "fee": 0,
      "network": "tron", "standard": "TRC-20", "txid": "e9a5534b…", "from": "TEVAe4…", "to": "TXk3…",
      "at": "2026-11-06T11:39:07.000Z" }
  ],
  "count": 2
}

I cambi (kind: "exchange") hanno status done, waiting_stock (ordine in attesa di scorta, nessun addebito), failed o cancelled. I movimenti di rete hanno kind deposit, withdraw o transfer.

GET /rates

{ "from": "EUR", "to": "GBP", "rate": 0.8412, "at": "2026-11-06T21:00:00.000Z" }

4. Errori

Stato	Corpo	Significato
`401`	`{"error":"unauthorized"}`	Chiave mancante, revocata o scaduta.
`403`	`{"error":"account_blocked"}`	Il conto è sospeso: scrivi all’assistenza.
`405`	`{"error":"method_not_allowed"}`	Si accetta solo GET.
`429`	`{"error":"rate_limited"}`	Più di 60 richieste in un minuto: aspetta e riprova.
`404`	`{"error":"not_found"}`	Percorso sconosciuto.

5. Buone pratiche

Tieni la chiave sul tuo server, mai in un browser o in un’app che distribuisci.
Interroga i movimenti al massimo una volta al minuto, con from all’ultimo giorno che hai già; usa l’id del movimento per evitare doppioni.
Revoca una chiave appena smetti di usarla o se pensi sia finita in mani altrui. Poi chiedine una nuova all’assistenza.

Domande: scrivici dall’assistenza nell’app. Il team iSwiss non ti chiederà mai la tua chiave API.

iSwiss Pay Limited
Sede legale: 329 Howe Street #1273, Vancouver, BC V6C 3N2, Canada