Documentazione API

Tutti gli strumenti di questo sito sono disponibili come API JSON gratuita. Nessuna chiave API, nessuna registrazione. CORS è attivo, quindi è possibile chiamarla direttamente dal browser.

URL di base: https://swissinvoice.dev/api/v1
Limite di richieste: Le richieste sono limitate per indirizzo IP: 60 al minuto per la validazione, 120 al minuto per la verifica IBAN e la generazione. Oltre questo limite riceve HTTP 429 con un header Retry-After.
Lingua: Aggiunga ?lang=it per ricevere i messaggi di errore in italiano (oppure ?lang=de o fr per tedesco o francese). La lingua predefinita è l'inglese.
Errori: Gli endpoint di verifica restituiscono sempre HTTP 200 con valid: true/false e gli elenchi di errori (errors) e avvisi (warnings). Ogni problema ha un codice stabile, il campo interessato, la riga nel contenuto (se pertinente) e un messaggio leggibile. Le richieste malformate restituiscono HTTP 4xx con un oggetto error.

Verificare il contenuto di una QR-fattura

POST/api/v1/qr-bill/validate

Invii il testo grezzo del codice QR come text/plain (oppure come JSON {"payload": "…"}).

curl

curl -X POST "https://swissinvoice.dev/api/v1/qr-bill/validate?lang=it" \
  -H "Content-Type: text/plain" \
  --data-binary @payload.txt

Risposta

{
  "valid": false,
  "errors": [
    {
      "code": "iban.checksum",
      "field": "account",
      "line": 4,
      "message": "Le cifre di controllo non corrispondono. Probabilmente c'è un errore di battitura nell'IBAN."
    },
    {
      "code": "address.combined",
      "field": "creditor",
      "line": 5,
      "message": "Dal 21 novembre 2025 gli indirizzi combinati (tipo K) non sono più accettati. Utilizzi un indirizzo strutturato (tipo S)."
    }
  ],
  "warnings": [
    {
      "code": "amount.decimals",
      "field": "amount",
      "line": 19,
      "params": {
        "value": "100.5"
      },
      "message": "L'importo «100.5» dovrebbe avere esattamente due decimali, ad es. 100.00."
    }
  ],
  "data": {
    "version": "0200",
    "account": "CH4431999123000889013",
    "…": "…"
  }
}

Verificare un IBAN

GET/api/v1/iban?iban=…

Passi l'IBAN come parametro di query. Gli spazi sono ammessi.

curl

curl "https://swissinvoice.dev/api/v1/iban?iban=CH0430000001234567890"

Risposta

{
  "valid": true,
  "input": "CH0430000001234567890",
  "iban": "CH0430000001234567890",
  "formatted": "CH04 3000 0001 2345 6789 0",
  "country": "CH",
  "swiss": {
    "iid": "30000",
    "isQrIban": true,
    "referenceTypes": [
      "QRR"
    ],
    "bank": {
      "iid": "30000",
      "name": "PostFinance AG",
      "town": "Bern",
      "bic": "POFICHBEXXX"
    }
  },
  "errors": [],
  "warnings": []
}

Creare una QR-fattura

POST/api/v1/qr-bill

Invii un JSON e riceva un SVG (predefinito) o un PDF. Imposti format su pdf e paperSize su a4 o slip.

curl

curl -X POST https://swissinvoice.dev/api/v1/qr-bill \
  -H "Content-Type: application/json" \
  -d '{
  "creditor": {
    "account": "CH04 3000 0001 2345 6789 0",
    "name": "Robert Schneider AG",
    "street": "Rue du Lac",
    "buildingNumber": "1268",
    "postalCode": "2501",
    "town": "Biel",
    "country": "CH"
  },
  "debtor": {
    "name": "Pia-Maria Rutschmann-Schnyder",
    "street": "Grosse Marktgasse",
    "buildingNumber": "28",
    "postalCode": "9400",
    "town": "Rorschach",
    "country": "CH"
  },
  "amount": 1949.75,
  "currency": "CHF",
  "reference": "210000000003139471430009017",
  "message": "Ordine del 15 giugno 2026",
  "language": "it",
  "format": "pdf",
  "paperSize": "a4"
}' \
  -o qr-bill.pdf

Campi della richiesta

creditor.account	string	IBAN o QR-IBAN (CH/LI). Spazi ammessi.
creditor.name	string ≤70	Obbligatorio.
creditor.street / buildingNumber	string ≤70 / ≤16	Facoltativo.
creditor.postalCode / town	string ≤16 / ≤35	Obbligatorio.
creditor.country	string	ISO 3166-1 alpha-2, ad es. CH.
debtor	object	Facoltativo. Stessi campi di creditor, senza account.
amount	number	Facoltativo. 0.01–999999999.99, al massimo due decimali.
currency	"CHF" \| "EUR"	Predefinito CHF.
reference	string	Riferimento QR (27 cifre) per QR-IBAN, altrimenti riferimento creditore RF o vuoto.
message	string ≤140	Comunicazione non strutturata facoltativa.
billInformation	string ≤140	Informazioni di fatturazione strutturate facoltative, ad es. Swico S1. Insieme a message max. 140.
language	"en" \| "de" \| "fr" \| "it" \| "rm"	Lingua della sezione pagamento. Predefinito en.
format	"svg" \| "pdf"	Predefinito svg.
paperSize	"a4" \| "slip"	Solo PDF. Predefinito a4.

Se dai dati non è possibile creare una QR-fattura valida, l'endpoint risponde con HTTP 422. error.code è invalid_input per campi non validi o invalid_qr_bill per violazioni delle regole della QR-fattura; error.details elenca i problemi con codice, campo e messaggio.