API di integrazione: invia le vendite del tuo programma a TicketBAI e a Vectura
Il tuo software —un POS di un'altra marca, un chiosco, un negozio online, un ERP o il programma di un hotel— invia ogni vendita a Vectura con una chiamata JSON. Vectura emette lo scontrino o la fattura, la firma con TicketBAI o Veri*Factu, la invia al fisco e ti restituisce il QR da stampare. Senza librerie, senza installare nulla e con una chiave per programma.
Account dimostrativo
Dati fittizi, nessun invio al fisco né via e-mail. Ripristinata ogni notte.
{
"seriefactura": "KIOSKO1",
"numfactura": "105",
"fechaexpedicionfactura": "2026-11-06",
"importetotalfactura": "3,50",
"baseimponible": "2,89",
"tipoimpositivo": "21",
"cuotaimpuesto": "0,61"
}
{
"error": "0",
"leyenda": "TicketBAI",
"fiscal_estado": "aceptado",
"qr_url": "https://batuz.eus/QRTBAI/?id=…"
}
Integrare è semplicissimo
Genera una chiave
Nella tua area utente, in Configurazione → API e integrazioni, crei una chiave per ogni programma. Si può eliminare in qualsiasi momento.
Invia la vendita
Il tuo programma fa un POST con il JSON della vendita. Senza codice fiscale esce uno scontrino semplificato; con il codice fiscale, una fattura completa.
Stampa il QR
Vectura firma e invia al fisco, e risponde con il QR e la dicitura da stampare sullo scontrino.
Cosa include
Una chiamata per vendita
Il tuo programma invia un JSON con il codice fiscale (facoltativo), l'importo e l'IVA. Senza codice fiscale si emette uno scontrino semplificato; con il codice fiscale, una fattura completa a quel cliente.
Firma e invio al fisco
Vectura firma con il tuo certificato e invia alla Hacienda Foral (TicketBAI in Biscaglia, Guipúzcoa e Álava) o all'Agenzia tributaria spagnola (Veri*Factu nel resto della Spagna).
Il QR, pronto da stampare
La risposta contiene l'indirizzo del QR e la sua dicitura (TicketBAI o VERI*FACTU), e puoi chiedere a Vectura l'immagine del QR.
Tentativi ripetuti sicuri e la tua numerazione
Rispettiamo la serie e il numero del tuo programma. Se ripeti una vendita con la stessa serie e lo stesso numero, Vectura restituisce l'originale senza crearne un'altra: un calo di rete non duplica mai una fattura.
Annullare, consultare e rettificare
Annulla uno scontrino, consulta lo stato fiscale di una vendita o correggi una fattura con una fattura rettificativa, tutto con la stessa API.
Fatture complete, incassi e preventivi
Con righe, più aliquote IVA, cliente, incasso e invio del PDF via e-mail; fatture da incassare, preventivi e consultazione dei documenti.
Per i programmi che lasciano solo file
Se il tuo software non sa fare chiamate web, uno script PowerShell carica da solo i file JSON di una cartella e scrive la risposta con il QR. Senza programmare.
Manuale e chiavi nella tua area utente
Genera una chiave per programma e consulta il manuale dell'API, con esempi in curl, PHP, C#, JavaScript e Python e l'elenco degli errori.
Domande frequenti
Di cosa ho bisogno per iniziare?
Un account Vectura Suite e i dati fiscali della tua azienda. Per firmare davvero serve il tuo certificato elettronico (e, con TicketBAI, la licenza del software, che configura il nostro supporto). Mentre provi, l'azienda è in modalità di prova.
Funziona con TicketBAI e con Veri*Factu?
Sì. In base al regime della tua azienda, Vectura firma con TicketBAI (Biscaglia, Guipúzcoa e Álava) o genera il registro Veri*Factu; il programma che chiama non deve distinguerli.
Posso provare senza inviare nulla al fisco?
Sì. Finché l'azienda è in modalità di prova, tutto viene firmato e inviato all'ambiente di prova del fisco e i QR non hanno validità legale. Quando tutto funziona, si passa al reale.
Cosa succede se la connessione si interrompe a metà di una vendita?
Riprovi con la stessa serie e lo stesso numero (o lo stesso riferimento): Vectura restituisce la vendita originale senza duplicarla.
C'è un limite di chiamate?
Sì: 120 richieste al minuto, più che sufficienti per un negozio. Se superi il limite, l'API risponde 429 e riprovi dopo un momento.
Dov'è la documentazione?
All'interno di Vectura Suite, nella tua area utente: Aiuto → Manuale dell'API. Include una guida introduttiva, ogni punto dell'API con esempi in curl, PHP, C#, JavaScript e Python, e l'elenco degli errori. Puoi consultarlo con la prova gratuita.
Chi vede la mia chiave?
Nessuno: viene mostrata una sola volta alla creazione e Vectura conserva solo un'impronta. Se la perdi, la elimini e ne crei un'altra; eliminare una chiave non influisce sulle altre.
Posso collegare il programma di un hotel?
Sì: oltre alle vendite, ci sono punti dell'API per le camere occupate e gli addebiti in camera, che il programma dell'hotel consulta e salda.
Lo proviamo con la tua attività?
Crea il tuo account e provalo con i tuoi dati, senza carta e senza impegno.