#GoFile Connetti API

Cos'è l'API Connect

Un gateway di conformità per la dichiarazione dei redditi nel Regno Unito: il tuo software si connette a un endpoint con il cliente e i suoi dati, e # GoFile gestisce tutto ciò che intercorre tra la chiamata e la ricezione da parte HMRC .

Rendere la tassazione digitale non è un'API difficile da chiamare una volta. È un'API difficile da ProprioRiconoscimento, autorizzazioni OAuth che scadono dopo 18 mesi, intestazioni antifrode che devono descrivere il dispositivo di origine reale, corrispondenza degli obblighi, chiavi temporali che non bisogna mai inventare, idempotenza dell'invio e una traccia di controllo che resiste per anni: questo è il lavoro, e non finisce mai.

L'API Connect è quel lavoro, svolto e mantenuto, dietro una piccola superficie REST. La versione 1 copre I.V.A.: verificare che il cliente sia autorizzato, analizzare la sua situazione IVA completa, presentare la dichiarazione e seguirne l'iter fino all'emissione della ricevuta.

A chi è destinato

L'API è progettata per un modello agente: la tua azienda partner collega il suo HMRC conto servizi agente Una sola autorizzazione, valida per tutti i clienti per i quali è autorizzata ad agire.

Come funziona

Ogni richiesta è una chiamata REST firmata. Tutto ciò che legalmente richiede l'intervento umano avviene su una pagina che ospitiamo.

GET /api/v1/vat/193054661/status

{
  "vat_number": "193054661",
  "mode": "live",
  "obligations": {
    "open": [
      { "period": { "start": "2026-04-01",
                    "end":   "2026-06-30" },
        "due": "2026-08-07",
        "overdue": false }
    ],
    "fulfilled": [ /* filed periods + figures */ ]
  }
}

{
  "external_client_id": "CLIENT-91827",
  "client_name": "Acme Trading Ltd",
  "vat_number": "193054661",
  "return": {
    "vat_due_sales": "12500.00",
    "total_vat_due": "12500.00",
    "net_vat_due":   "8300.00"
    /* ...nine boxes in total */
  }
}

{
  "id": "vfs_...",
  "status": "submitted",
  "receipt": {
    "gofile_reference": "GF-VAT-123",
    "form_bundle": "258868935084"
  }
}

L'approvazione ospitata e perché è importante

HMRC non vuole semplicemente una dichiarazione dei redditi; vuole sapere che la dichiarazione proviene da una persona reale su un dispositivo reale e che una persona si è assunta la responsabilità della dichiarazione. A questo servono le intestazioni antifrode, e un loro utilizzo errato rappresenta un problema di conformità, non un bug.

Quindi l'API Connect non chiede mai al tuo software di falsificarli. Quando invii un file, restituiamo un URL a una pagina ospitiamoSu quella pagina, la persona autorizzata effettua l'accesso con l'autenticazione a due fattori, viene acquisito il suo dispositivo reale, la dichiarazione viene visualizzata per intero e la persona conferma la dichiarazione. Solo a quel punto contattiamo HMRC entrate britannica) — con le intestazioni generate da quel dispositivo specifico, di cui viene scattata un'istantanea insieme alla dichiarazione come prova.

La pagina guida il cliente anche attraverso la procedura di connessione una tantum HMRC . Quando un'azienda presenta la dichiarazione per la prima volta, autorizza il proprio account per i servizi di agente in quella pagina e torna direttamente alla presentazione della dichiarazione.

Ciò che non devi costruire

Non ti viene mai chiesto un tasto periodo o un finalised flag — l'API li rifiuta categoricamente, perché spetta a noi determinarli e gli errori in questo ambito sono la causa di pratiche errate.

Sandbox e live

Le modalità vengono selezionate in base alla chiave utilizzata per l'accesso, quindi non è necessario azionare alcun interruttore globale e non c'è nulla da dimenticare durante l'implementazione:

• gfk_sandbox_… File chiave per l'ambiente di test di HMRC . Gratuito, illimitato e sicuro da eseguire in CI.
• gfk_live_… file delle chiavi rendimenti reali.

Entrambi gli ambienti funzionano contemporaneamente. La suite di test può essere eseguita nell'ambiente di test (sandbox) mentre i file di produzione sono attivi, e il passaggio da un ambiente all'altro dipende dalle credenziali utilizzate per l'accesso. L'utilizzo, i registri delle richieste e i limiti giornalieri vengono monitorati separatamente per ciascuna modalità.

Sicurezza e prove

La rotazione non prevede tempi di inattività: diverse chiavi possono essere attive contemporaneamente, quindi si emette la nuova coppia, la si implementa e si revoca la vecchia non appena nessun altro sistema la utilizza.

Webhook, log e portale per sviluppatori

La procedura di invio è per sua natura asincrona: un operatore umano deve approvarla e HMRC deve rispondere. Invece di richiedere continue verifiche, inviamo al tuo endpoint gli eventi firmati man mano che la pratica procede: in attesa di approvazione, inviata, non riuscita e così via. Ogni invio è firmato da HMAC con il tuo segreto webhook, in modo che tu possa verificarne la provenienza.

Il portale dei partner su api.gofile.co.uk offre al tuo team:

• chiavi API — emetti coppie sandbox e live, visualizza l'ultimo utilizzo, ruota e revoca.
• Registri delle richieste — ogni richiesta firmata con il relativo stato, codice di errore, modalità, durata e ID della richiesta. Vengono visualizzati anche gli errori di firma, che è esattamente ciò di cui hai bisogno quando commetti errori con HMAC alle 2 del mattino.
• Consegne tramite webhook — stato, codice di risposta e pianificazione dei tentativi per ogni evento.
• Utilizzo — Richieste e depositi rappresentati graficamente per giorno, suddivisi per modalità.
• Fatturazione — fatture, metodi di pagamento e il tuo piano tariffario.

Prezzi

I prezzi sono IVA esclusa. Le spese di presentazione verranno aggiunte alla fattura mensile successiva. Nessun costo per cliente, nessun volume minimo e nessun costo per la presentazione in ambiente di test: paghi solo quando una dichiarazione dei redditi effettiva viene inviata HMRC .

Cosa succederà dopo?

La versione 1 riguarda l'IVA, perché è lì che MTD è obbligatoria e il volume è più elevato. Lo stesso modello – una chiamata pulita, un'approvazione ospitata, una ricevuta – è progettato per essere esteso al resto degli adempimenti fiscali nel Regno Unito.

MTD per l'imposta sul reddito è la naturale evoluzione successiva, ed è qui che il valore di un'API semplificata è massimo: l'interfaccia ITSA di HMRC si estende su un gran numero di endpoint e forme, e intendiamo semplificarla nella stessa interfaccia razionale che Connect ti offre per l'IVA. Se la tua roadmap dipende da una specifica imposta o tempistica, dicci — La richiesta del partner determina l'ordine.

Inizia