Vai al contenuto principale

Come configurare e utilizzare i Webhook per le fatture

I webhook per le fatture ti permettono di inviare automaticamente i dati delle fatture da bsport a un altro sistema (come il tuo software di

Cos'è un webhook?

Un webhook è un messaggio automatico inviato dal nostro sistema a un'altra applicazione ogni volta che accade qualcosa di importante, come quando una fattura viene creata o annullata. Ricevi queste notifiche in tempo reale, così puoi reagire immediatamente.

Questo ti permette di:

  • Sincronizzare le fatture con strumenti di contabilità

  • Avviare automazioni

  • Mantenere i sistemi esterni aggiornati in tempo reale

Nota: I webhook richiedono una configurazione tecnica e non sono funzionalità pronte all'uso. Assicurati di avere conoscenze di sviluppo software prima di seguire questa guida fino alla fine.

Prima di iniziare

Per utilizzare i webhook per le fatture, devi disporre di un endpoint HTTPS sicuro (URL) in grado di ricevere richieste POST con dati JSON.

Guida passo dopo passo

  1. Una volta che il tuo endpoint è pronto, visita https://backoffice.bsport.io/settings/webhook.

  2. Clicca sul pulsante "Aggiungi un webhook"

  3. Seleziona l'evento a cui vuoi iscriverti (i tipi di evento sono elencati qui).

  4. Inserisci l'URL a cui vuoi che il webhook invii il messaggio.

  5. Clicca su conferma.

  6. Ora puoi vedere il tuo nuovo webhook creato 🎉.

  7. (Facoltativo) Cliccando sul pulsante "Test", puoi simulare un evento per verificare che il tuo webhook funzioni correttamente.

Tipi di eventi

Puoi iscriverti a diversi eventi relativi al ciclo di vita di una fattura:

  • invoice-finalize – Attivato quando una fattura viene creata e aperta (finalizzata).

  • invoice-revert – Attivato quando una fattura viene annullata (cancellata o rimborsata)

  • invoice-pay – Attivato quando una fattura viene pagata interamente.

  • invoice-dispute – Attivato quando una fattura viene contestata.

I seguenti eventi fattura sono deprecati e non devono quindi essere utilizzati.

  • invoice-create

  • invoice-update

Payload dell'evento

Ognuno di questi eventi invia lo stesso formato di payload, definito come segue.

Puoi trovare qui la descrizione dello schema JSON del payload.

Descrizione dei campi

Campo

Tipo

Descrizione

Esempio

event_type

string

Tipo di evento

"invoice-finalize"

date

number (timestamp)

Timestamp di quando l'evento è stato attivato

1762246989

data

Object

Dettagli sull'evento e sulla fattura (vedi sotto).

-

data.date

"2025-11-04T09:03:11.653072Z"

data.object.id

string (uuid)

Identificatore univoco della fattura

"923e2c97-8228-4d42-8a44-1783c70c50a1"

data.object.object

string

Tipo di oggetto (sempre invoice).

"invoice"

data.object.status

string

Stato della fattura (open, paid, refunded, voided).

"open"

data.object.date_created

string (date-time)

Quando la fattura è stata creata (UTC).

"2025-11-04T09:03:06.515219Z"

data.object.date_created

string (date-time)

Quando la fattura è stata creata (UTC).

"2025-11-04T09:03:06.515219Z"

data.object.date_issued

string (date-time)

Quando la fattura è stata emessa (UTC).

"2025-11-04T09:03:08.225042Z"

data.object.date_due

string (date-time)

Data di scadenza del pagamento (UTC).

"2025-11-04T09:03:07.292000Z"

data.object.date_cancelled

string (date-time) | null

Quando la fattura è stata annullata (se applicabile).

null

data.object.currency

string

Valuta della fattura (codice ISO 4217).

"eur"

data.object.total

number (cents)

Importo totale della fattura nell'unità più piccola (es. centesimi).

36665

data.object.amount_due

number (cents)

Importo dovuto nell'unità più piccola (es. centesimi).

36665

data.object.amount_paid

number (cents)

Importo già pagato nell'unità più piccola (es. centesimi).

0

data.object.company

object

Azienda che emette la fattura.

{ ... }

data.object.company.id

number

ID univoco dell'azienda. Per conoscere l'ID della tua azienda, visita questa pagina del backoffice.

85329

data.object.company.name

string

Nome dell'azienda.

"SaudeViva Portugal"

data.object.company.country

string

Codice paese.

"PT"

data.object.company.city

string

Città.

"Lisbon"

data.object.company.address

string

Indirizzo.

"Rua do Ouro 115"

data.object.company.postal_code

string

Codice postale/CAP.

"1100-062"

data.object.customer

object | null

Cliente a cui viene emessa la fattura (può essere null per le fatture anonime del Point Of Sales).

{ ... }

data.object.customer.id

number

ID univoco del cliente/membro.

7644312

data.object.customer.type

string

Tipo di cliente (sempre individual qui).

"individual"

data.object.customer.name

string

Nome completo.

"Maria Oliveira"

data.object.customer.first_name

string

Nome.

"Maria"

data.object.customer.last_name

string

Cognome.

"Oliveira"

data.object.customer.email

string

Email di contatto.

"maria.oliveira77@example.com"

data.object.customer.phone

string

Numero di telefono.

"+351 912 345 678"

data.object.customer.official_document_id

string

Documento ufficiale/ID nazionale (può essere codice fiscale/NIF).

"PT-19847765"

data.object.customer.address

object

Indirizzo del cliente.

{ ... }

data.object.customer.address.line1

string

Indirizzo stradale.

"Avenida da Liberdade 202"

data.object.customer.address.line2

string (optional)

Informazioni aggiuntive sull'indirizzo.

"4º Esq."

data.object.customer.address.city

string

Città.

"Lisbon"

data.object.customer.address.postal_code

string

Codice postale.

"1250-147"

data.object.customer.address.state

string

Stato/regione.

"Lisboa"

data.object.customer.address.country

string

Codice paese.

"PT"

data.object.line_items

object

Contenitore delle voci di fattura.

{ ... }

data.object.line_items.line_count

number

Numero di voci di fattura.

6

data.object.line_items.data

array<object>

Array delle voci di fattura.

[{ ... }, { ... }]

data.object.line_items.data[].id

number

Identificatore univoco della voce di fattura.

2153

data.object.line_items.data[].description

string

Nome/etichetta del prodotto o servizio.

"£100 General Gift Voucher"

data.object.line_items.data[].quantity

number

Numero di unità acquistate.

1

data.object.line_items.data[].tax_included_unit_amount

number (cents)

Prezzo unitario IVA inclusa, in centesimi.

10000

data.object.line_items.data[].tax_included_amount

number (cents)

Prezzo totale IVA inclusa prima dello sconto (quantity * unit_amount).

10000

data.object.line_items.data[].voucher_applied

number (cents)

Sconto/voucher applicato a questa voce, in centesimi.

0

data.object.line_items.data[].line_total

number (cents)

Importo finale della voce dopo lo sconto, in centesimi.

10000

data.object.line_items.data[].tax_breakdown

object

Dettagli del calcolo fiscale.

{ ... }

data.object.line_items.data[].tax_breakdown.rate

number (%)

Percentuale dell'aliquota fiscale (es. 20 = 20%).

0

data.object.line_items.data[].tax_breakdown.total_tax

number (cents)

Totale imposte incluse in questa voce, in centesimi.

0

data.object.line_items.data[].tax_breakdown.unit_tax

number (cents)

Imposta inclusa per unità, in centesimi.

0

data.object.line_items.data[].item_type

string

Tipo di articolo bsport (shop-product, pass, private_pass, consumer_giftcard, refund).

"consumer_giftcard"

data.object.invoice_pdf

string (url)

Link al PDF della fattura.

"https://assets.staging.bsport.io/.../invoice-24092226.pdf"

data.object.receipt_pdf

string (url) | null

Link al PDF della ricezione del pagamento (se applicabile).

null

data.object.invoice_type

number

Tipo di fattura: 0=normale, 1=storno, 2=nota di credito, 3=migrazione.

0

data.object.source_invoice_id

string (uuid) | null

UUID della fattura originale annullata tramite questa (se applicabile).

null

Esempio

{
  "event_type": "invoice-finalize",
  "date": 1762246989,
  "data": {
    "date": "2025-11-04T09:03:11.653072Z",
    "object": {
      "id": "923e2c97-8228-4d42-8a44-1783c70c50a1",
      "object": "invoice",
      "status": "open",
      "date_created": "2025-11-04T09:03:06.515219Z",
      "date_issued": "2025-11-04T09:03:08.225042Z",
      "date_due": "2025-11-04T09:03:07.292000Z",
      "date_cancelled": null,
      "currency": "eur",
      "total": 36665,
      "amount_due": 36665,
      "amount_paid": 0,
      "company": {
        "id": 85329,
        "name": "SaudeViva Portugal",
        "country": "PT",
        "city": "Lisbon",
        "address": "Rua do Ouro 115",
        "postal_code": "1100-062"
      },
      "customer": {
        "id": 7644312,
        "type": "individual",
        "name": "Maria Oliveira",
        "first_name": "Maria",
        "last_name": "Oliveira",
        "email": "maria.oliveira77@example.com",
        "phone": "+351 912 345 678",
        "official_document_id": "PT-19847765",
        "address": {
          "line1": "Avenida da Liberdade 202",
          "line2": "4º Esq.",
          "city": "Lisbon",
          "postal_code": "1250-147",
          "state": "Lisboa",
          "country": "PT"
        }
      },
      "line_items": {
        "line_count": 6,
        "data": [
          {
            "id": 2153,
            "description": "£100 General Gift Voucher",
            "quantity": 1,
            "tax_included_unit_amount": 10000,
            "tax_included_amount": 10000,
            "voucher_applied": 0,
            "line_total": 10000,
            "tax_breakdown": {
              "rate": 0,
              "total_tax": 0,
              "unit_tax": 0
            },
            "item_type": "consumer_giftcard"
          },
          {
            "id": 249955,
            "description": "Classic Jumper - Peacoat Navy",
            "quantity": 2,
            "tax_included_unit_amount": 4500,
            "tax_included_amount": 9000,
            "voucher_applied": 964,
            "line_total": 8036,
            "tax_breakdown": {
              "rate": 20,
              "total_tax": 1339,
              "unit_tax": 670
            },
            "item_type": "shop-product"
          },
          {
            "id": 15305,
            "description": "Single 60 Minute Reiki Treatment",
            "quantity": 1,
            "tax_included_unit_amount": 7500,
            "tax_included_amount": 7500,
            "voucher_applied": 1384,
            "line_total": 6116,
            "tax_breakdown": {
              "rate": 20,
              "total_tax": 1019,
              "unit_tax": 1019
            },
            "item_type": "private_pass"
          },
          {
            "id": 15301,
            "description": "Single 60 Minute Session",
            "quantity": 1,
            "tax_included_unit_amount": 7500,
            "tax_included_amount": 7500,
            "voucher_applied": 1383,
            "line_total": 6117,
            "tax_breakdown": {
              "rate": 20,
              "total_tax": 1019,
              "unit_tax": 1019
            },
            "item_type": "private_pass"
          },
          {
            "id": 427448,
            "description": "Newbies",
            "quantity": 1,
            "tax_included_unit_amount": 4900,
            "tax_included_amount": 4900,
            "voucher_applied": 904,
            "line_total": 3996,
            "tax_breakdown": {
              "rate": 20,
              "total_tax": 666,
              "unit_tax": 666
            },
            "item_type": "pass"
          },
          {
            "id": 427451,
            "description": "1 Session",
            "quantity": 1,
            "tax_included_unit_amount": 2500,
            "tax_included_amount": 2500,
            "voucher_applied": 100,
            "line_total": 2400,
            "tax_breakdown": {
              "rate": 20,
              "total_tax": 400,
              "unit_tax": 400
            },
            "item_type": "pass"
          }
        ]
      },
      "invoice_pdf": "https://assets.staging.bsport.io/invoices/2025-11-04/5cab7c93-cd01-4d15-9362-46b0a89919b5/invoice-24092226.pdf",
      "receipt_pdf": null,
      "invoice_type": 0,
      "source_invoice_id": null
    }
  }
}
Articoli correlati
Esporta le tue fatture in blocco
Hai ricevuto la risposta alla tua domanda?