API SnapCost

Un'API REST pulita per ricevute, fatture e report pronti per il fisco. JSON in entrata, JSON in uscita. Auth con token Bearer. Pensata per commercialisti, integrazioni ERP e le tue automazioni.

URL base

https://snapcost.app/api

Formato

Body di richiesta e risposta in JSON, UTF-8.

Autenticazione

HTTP Bearer con una chiave API.

Piano

L'accesso all'API richiede il piano Business.

Autenticazione

Ogni richiesta deve includere un header Authorization con la tua chiave API.

Authorization: Bearer sk_live_••••••••••••••••••••••••••••••••

Le chiavi API sono legate a un singolo account SnapCost e ne ereditano permessi e limiti di piano. Si comportano in modo identico a una sessione utente autenticata — oggi non esiste un sistema di scope separato.

Tratta le chiavi come password. Non committarle mai nel controllo versione e non esporle in codice lato browser. Ruotale subito se una chiave potrebbe essere trapelata.

Gestione chiavi API

Genera, elenca e revoca le chiavi dalla dashboard di SnapCost, oppure usa gli endpoint di gestione qui sotto (richiedono un JWT autenticato, non una chiave API, per impedire escalation di privilegi).

GET/api/keysElenca le tue chiavi

POST/api/keysCrea una nuova chiave

DELETE/api/keys/:idRevoca una chiave

Crea una chiave

POST /api/keys
Content-Type: application/json

{ "name": "Zapier production" }

Risposta

{
  "id":        "9c1f…",
  "name":      "Zapier production",
  "prefix":    "sk_live_AbC",
  "plaintext": "sk_live_AbCDeFGhIJKlMnOPqRsTUVwxYZ0123456789…",
  "createdAt": "2026-04-21T10:42:18.000Z",
  "note":      "Store this key now — the full value will not be shown again."
}

La chiave completa in chiaro viene restituita solo una volta, alla creazione. SnapCost memorizza un hash SHA-256 e non può recuperare il valore originale. Limite: 10 chiavi attive per account.

Avvio rapido

curl https://snapcost.app/api/receipts \
  -H "Authorization: Bearer $SNAPCOST_API_KEY"

const res = await fetch('https://snapcost.app/api/receipts', {
  headers: { Authorization: `Bearer ${process.env.SNAPCOST_API_KEY}` },
});
const { receipts } = await res.json();

import os, requests

r = requests.get(
    "https://snapcost.app/api/receipts",
    headers={"Authorization": f"Bearer {os.environ['SNAPCOST_API_KEY']}"},
)
receipts = r.json()["receipts"]

Ricevute

Le ricevute sono spese scansionate o inserite manualmente.

GET/api/receiptsElenca le ricevute

GET/api/receipts/:idRecupera una ricevuta

POST/api/receiptsCrea una ricevuta

PUT/api/receipts/:idAggiorna una ricevuta

DELETE/api/receipts/:idElimina una ricevuta

Crea una ricevuta

Campo	Tipo		Note
`merchant`	string	obbligatorio	Nome del fornitore
`amount`	number	obbligatorio	Totale in `currency`
`currency`	string	opzionale	ISO 4217, predefinito: valuta del tuo account
`date`	string	obbligatorio	Data ISO (`AAAA-MM-GG`)
`category`	string	opzionale	es. `travel`, `meals`
`notes`	string	opzionale	Memo libero

Fatture

Fatture e preventivi che emetti ai clienti. Gli account Pro+ accedono anche agli endpoint Factur-X / PDP / e-reporting.

GET/api/invoicesElenca fatture & preventivi

POST/api/invoicesCrea una fattura o un preventivo

GET/api/invoices/:idRecupera uno

PUT/api/invoices/:idAggiorna

DELETE/api/invoices/:idElimina

GET/api/invoices/:id/facturx-pdfScarica PDF Factur-X (Pro+)

POST/api/invoices/:id/pdp/sendInvia a PDP (Pro+)

Report

Genera riepiloghi pronti per il fisco per qualsiasi intervallo di date.

GET/api/reportsElenca i report salvati

POST/api/reportsGenera un report

GET/api/reports/:idRecupera un report

Errori

SnapCost usa codici HTTP standard. Gli errori restituiscono sempre JSON con un campo error, talvolta un message, e occasionalmente un upgradeUrl quando è richiesto un piano a pagamento.

Stato	Significato
400	Richiesta malformata — parametri mancanti o non validi
401	Chiave API / token mancante, non valido o revocato
402	Quota del piano gratuito esaurita — upgrade richiesto
403	L'endpoint richiede un piano superiore (es. Pro+)
404	Risorsa non trovata o non posseduta dal tuo account
429	Troppe richieste — vedi i limiti di richiesta sotto
5xx	Errore server transitorio — è sicuro riprovare con backoff

Limiti di richiesta

Limite predefinito: 100 richieste al minuto per IP, applicato a tutti gli endpoint /api/*. Gli endpoint di auth sono più stretti. Per più, contatta il supporto con il tuo caso d'uso.

Versioning

L'API oggi è senza versione e strettamente additiva — aggiungiamo campi ed endpoint senza rompere i client esistenti. Eventuali breaking change usciranno con un nuovo prefisso /api/v2/… e un periodo di deprecazione di almeno 6 mesi.