Stable Pro API · v1

Endpoint e oggetti

Ogni endpoint col suo permesso, i parametri e la risposta, e ogni oggetto coi suoi campi. Generato dal contratto OpenAPI.

I nomi dei campi, i codici e i valori sono il contratto: restano uguali in ogni lingua. Le descrizioni sono tradotte.

Endpoint

GET/api/v1/connection

Il collegamento della chiave che chiama: nome, permessi e la chiave stessa (mai il segreto)

Permesso: qualunque chiave valida
Parametri: lang
Risposta: Connection
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/codes

Il dizionario di ogni codice che l'API restituisce, coi nomi nella lingua richiesta (?lang=, Accept-Language)

Permesso: qualunque chiave valida
Parametri: lang
Risposta: Codes
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/organization

La scuderia della chiave che chiama: nome, paese, valuta, fuso orario, lingua, se Stable Pro calcola le imposte

Permesso: qualunque chiave valida
Parametri: lang
Risposta: Organization
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/customers

Chiunque abbia almeno un addebito, pagato o no, socio o staff; con customers.fiscal:read anche i dati per la fattura

Permesso: customers:read
Parametri: langlimitstarting_after
Risposta: CustomerList
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/customers/{id}

Un cliente; con customers.fiscal:read anche i dati per la fattura. Di un'altra scuderia: 404

Permesso: customers:read
Parametri: id (nel percorso)lang
Risposta: Customer
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/customers/{id}/balance

Cosa deve oggi il cliente, cosa arriva dopo, e il credito che può spendere

Permesso: charges:read
Parametri: id (nel percorso)lang
Risposta: Balance
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/charges

Tutti gli addebiti ai clienti, pagati o no (mai i compensi dello staff)

Permesso

charges:read

Parametri

langlimitstarting_after

Filtri

customer — Solo questo cliente (il suo id)
accounting_month — Solo questo mese contabile (YYYY-MM): il mese in cui il fatto conta, vedi Convenzioni

Risposta

ChargeList

Errori

400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/charges/{id}

Un addebito, com'è adesso: importo e imposte sono la nascita più le correzioni più i cambi d'imposta

Permesso: charges:read
Parametri: id (nel percorso)lang
Risposta: Charge
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/adjustments

Correzioni degli addebiti

Permesso

charges:read

Parametri

langlimitstarting_after

Filtri

charge — Solo le correzioni di questo addebito (il suo id)
accounting_month — Solo questo mese contabile (YYYY-MM): il mese in cui il fatto conta, vedi Convenzioni

Risposta

AdjustmentList

Errori

400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/adjustments/{id}

Una correzione: action, reason, category, importo con segno, consideration_effect, la differenza d'imposta

Permesso: charges:read
Parametri: id (nel percorso)lang
Risposta: Adjustment
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/payments

Movimenti di denaro dei clienti (incassi, rimborsi, storni, credito usato)

Permesso

payments:read

Parametri

langlimitstarting_after

Filtri

customer — Solo questo cliente (il suo id)

Risposta

PaymentList

Errori

400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/payments/{id}

Un movimento di denaro, con le sue assegnazioni; chi ha pagato per conto del cliente

Permesso: payments:read
Parametri: id (nel percorso)lang
Risposta: Payment
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/allocations/{id}

Quanto di un movimento va a un addebito, con segno

Permesso: payments:read
Parametri: id (nel percorso)lang
Risposta: Allocation
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/credit-entries

Movimenti del credito dei clienti (nato, cresciuto, usato, rimborsato)

Permesso

payments:read

Parametri

langlimitstarting_after

Filtri

customer — Solo questo cliente (il suo id)

Risposta

CreditEntryList

Errori

400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/credit-entries/{id}

Un movimento del credito di un cliente

Permesso: payments:read
Parametri: id (nel percorso)lang
Risposta: CreditEntry
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/receipts

Ricevute di Stable Pro (R: ricevute di pagamento, RB: conferme di rimborso), in ordine di emissione; mai documenti fiscali

Permesso

receipts:read

Parametri

langlimitstarting_after

Filtri

customer — Solo questo cliente (il suo id)
payment — Solo le ricevute di questo movimento di denaro (il suo id)

Risposta

ReceiptList

Errori

400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/receipts/{id}

Una ricevuta: tipo, il numero come stampato, stato, il pagamento che conferma, l'importo congelato

Permesso: receipts:read
Parametri: id (nel percorso)lang
Risposta: Receipt
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/receipts/{id}/pdf

Il PDF della ricevuta, lo stesso che ha ricevuto il cliente. Quando porta i dati fiscali di chi ha pagato per conto del cliente, serve anche customers.fiscal:read (altrimenti 403)

Permesso: receipts:read
Parametri: id (nel percorso)lang
Risposta: application/pdf
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/events

Cosa è successo, in ordine: leggi dopo il tuo cursore per restare allineato. Ogni novità chiede il permesso dell'oggetto a cui punta. Mentre si carica la storia della scuderia: 503 events-not-ready

Permesso: qualunque chiave valida
Parametri: langlimitafter
Risposta: EventList
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/events/{id}

Una novità. Di un'altra scuderia, o di un tipo che la tua chiave non legge: 404

Permesso: qualunque chiave valida
Parametri: id (nel percorso)lang
Risposta: Event
Errori: 400 · 401 · 403 · 404 · 429 · 500 · 503

Oggetti

Problem

Campo	Tipo	Descrizione
type	string (uri)	Stabile, in inglese: decidi in base a questo, non al testo
title	string	In inglese
status	integer
detail	string · facoltativo	Una frase per le persone, nella lingua richiesta (?lang=, Accept-Language)
reason	string · facoltativo missing · malformed · wrong_environment · unknown · connection_revoked · revoked · expired · rotated	Solo 401: perché la chiave non è valida
missing_permission	string · facoltativo charges:read · payments:read · receipts:read · customers:read · customers.fiscal:read · external-documents:write	Solo 403 forbidden
invalid_param	string · facoltativo	Solo 400: il parametro che non è valido

Connection

Campo	Tipo	Descrizione
object	"connection"
id	string (uuid)
name	string
permissions	array di string
created_at	string (date-time)	RFC 3339, UTC
key	object
key.id	string (uuid)
key.last_four	string
key.environment	string live · test	live = produzione (sp_live_), test = staging (sp_test_)
key.created_at	string (date-time)	RFC 3339, UTC
key.expires_at	string (date-time) · può essere null	RFC 3339, UTC
key.retires_at	string (date-time) · può essere null	Dopo una rotazione: quando questa chiave smette di funzionare

Organization

Campo	Tipo	Descrizione
object	"organization"
id	string (uuid)
name	string
legal_name	string · può essere null
country	string · può essere null	ISO 3166-1 alpha-2
currency	string	ISO 4217
timezone	string	IANA
language	string	La lingua della scuderia: Stable Pro non conosce quella di ogni cliente
locale	string	BCP 47, per la formattazione
taxes	object
taxes.calculated_by	string stable_pro · external	external = Stable Pro non calcola le imposte questo mese: niente di più
taxes.amount_basis	"gross"	Ogni importo è il totale che paga il cliente
receipts_shown_to_customers	boolean	false: la scuderia ha scelto di non dare le ricevute di Stable Pro ai suoi clienti finché c'è un programma collegato; esistono comunque e sono numerate (GET /receipts)

Customer

Campo	Tipo	Descrizione
object	"customer"
id	string (uuid)	Il codice del cliente: non cambia mai
kind	string member · staff
name	string
given_name	string · può essere null
family_name	string · può essere null
active	boolean	false: ha lasciato la scuderia, o è stato tolto; i suoi addebiti si possono ancora fatturare
created_at	string (date-time)	RFC 3339, UTC
billing_address	object · può essere null · facoltativo	Solo con customers.fiscal:read
billing_address.line1	string · può essere null
billing_address.line2	string · può essere null
billing_address.postal_code	string · può essere null
billing_address.city	string · può essere null
billing_address.subdivision	string · può essere null	ISO 3166-2 (IT-MI, US-OH)
billing_address.country	string · può essere null	ISO 3166-1 alpha-2
billing_address_text	string · può essere null · facoltativo	Solo con customers.fiscal:read: il vecchio indirizzo in testo libero, solo finché billing_address è vuoto
tax_identifiers	array di object · facoltativo	Solo con customers.fiscal:read
tax_identifiers[].scheme	string	VAT, o un ICD ISO 6523 (0210 codice fiscale italiano, 0211 partita IVA italiana)
tax_identifiers[].value	string
tax_code	string · può essere null · facoltativo	Solo con customers.fiscal:read: il vecchio codice fiscale, senza schema

CustomerList

Campo	Tipo	Descrizione
object	"list"
data	array di Customer
has_more	boolean	C'è una pagina successiva: chiedi di nuovo con starting_after = l'id dell'ultimo elemento

Balance

Campo	Tipo	Descrizione
object	"balance"
customer_id	string (uuid)
currency	string
amount_due	integer	Cosa è dovuto oggi: addebiti già visibili
amount_scheduled	integer	Addebiti che diventano visibili più avanti
credit	integer	Credito che si può spendere su un addebito
as_of	string (date)	Oggi, nel fuso orario della scuderia

Charge

Campo	Tipo	Descrizione
object	"charge"
id	string (uuid)
customer_id	string (uuid)
type	string	Elenco aperto: boarding, service_charge, lesson_drop_in, lesson_plan, health_record, …
description	string	Come l'ha scritto la scuderia
period_start	string (date)	YYYY-MM-DD
period_end	string (date)	YYYY-MM-DD
competence_month	string	YYYY-MM
accounting_month	string	Il più recente fra il mese di competenza e quello di registrazione: lo calcola Stable Pro
due_date	string (date)	YYYY-MM-DD
visible_from	string (date)	YYYY-MM-DD
quantity	"1"
unit	string MON · ANN · C62	UNECE Rec. 20
unit_amount	integer	Unità minori della valuta (ISO 4217)
currency	string
original_amount	integer	Alla nascita
amount	integer	Adesso: la nascita più le correzioni
amount_paid	integer	Unità minori della valuta (ISO 4217)
amount_remaining	integer	Unità minori della valuta (ISO 4217)
amount_basis	"gross"
tax_calculated_by	string stable_pro · external
tax_treatment	string standard_rated · zero_rated · not_calculated · undetermined
taxable_amount	integer	Unità minori della valuta (ISO 4217)
taxes	array di object
taxes[].type	"vat"	Elenco aperto: possono arrivare altri tipi
taxes[].jurisdiction	string · può essere null	ISO 3166-1 alpha-2 della scuderia
taxes[].category	string · può essere null	UNCL 5305: S, Z, E, AE, K, G, O; null quando non è dichiarata
taxes[].rate_bp	integer	Punti base: 2200 = 22%
taxes[].amount	integer	Unità minori della valuta
taxes[].exemption_reason	string · può essere null · facoltativo	BT-120, solo con aliquota zero
taxes[].exemption_reason_code	string · può essere null · facoltativo	VATEX (BT-121), solo con aliquota zero
created_at	string (date-time)	RFC 3339, UTC

ChargeList

Campo	Tipo	Descrizione
object	"list"
data	array di Charge
has_more	boolean	C'è una pagina successiva: chiedi di nuovo con starting_after = l'id dell'ultimo elemento

Adjustment

Campo	Tipo	Descrizione
object	"adjustment"
id	string (uuid)
charge_id	string (uuid)
customer_id	string (uuid)
direction	"receivable"
action	string · può essere null	Elenco aperto di codici (vedi /codes)
reason	string · può essere null
category	string · può essere null
origin	string · può essere null	HUMAN, SYSTEM, …
amount	integer	Con segno: negativo abbassa l'addebito
consideration_effect	string changes · none	changes: segue una nota di credito (o di debito); none: una perdita su crediti, senza imposta
taxes	array di object	Con changes: la differenza d'imposta, già calcolata. Con none: vuoto
taxes[].type	"vat"	Elenco aperto: possono arrivare altri tipi
taxes[].jurisdiction	string · può essere null	ISO 3166-1 alpha-2 della scuderia
taxes[].category	string · può essere null	UNCL 5305: S, Z, E, AE, K, G, O; null quando non è dichiarata
taxes[].rate_bp	integer	Punti base: 2200 = 22%
taxes[].amount	integer	Unità minori della valuta
taxes[].exemption_reason	string · può essere null · facoltativo	BT-120, solo con aliquota zero
taxes[].exemption_reason_code	string · può essere null · facoltativo	VATEX (BT-121), solo con aliquota zero
taxable_amount	integer · può essere null	Unità minori della valuta (ISO 4217)
currency	string
competence_month	string	YYYY-MM
accounting_month	string	YYYY-MM
occurred_at	string (date-time)	RFC 3339, UTC
reverses_adjustment_id	string (uuid) · può essere null
taxonomy_version	integer

AdjustmentList

Campo	Tipo	Descrizione
object	"list"
data	array di Adjustment
has_more	boolean	C'è una pagina successiva: chiedi di nuovo con starting_after = l'id dell'ultimo elemento

Allocation

Campo	Tipo	Descrizione
object	"allocation"
id	string (uuid)
payment_id	string (uuid)
charge_id	string (uuid)
amount	integer	Con segno
currency	string · facoltativo
consideration_effect	"none"

Payment

Campo	Tipo	Descrizione
object	"payment"
id	string (uuid)
customer_id	string (uuid) · può essere null
type	string payment · credit_applied · offset · refund · moved_to_credit · reversal	Cosa è successo al denaro (elenco aperto)
amount	integer	Il denaro che si è mosso davvero, con segno: un rimborso o uno storno è negativo, moved_to_credit è zero
currency	string
date	string (date)	YYYY-MM-DD
accounting_month	string	YYYY-MM
method	string	cash, bank_transfer, pos, credit, compensazione, other (elenco aperto)
reference	string · può essere null
paid_by	object · può essere null	Chi ha pagato per conto del cliente (un genitore): non è un cliente a sé
paid_by.kind	string · può essere null
paid_by.name	string · può essere null
paid_by.tax_code	string · può essere null · facoltativo	Solo con customers.fiscal:read
paid_by.address_text	string · può essere null · facoltativo	Solo con customers.fiscal:read
reverses_payment_id	string (uuid) · può essere null
action	string · può essere null	Solo per gli storni
reason	string · può essere null
category	string · può essere null
consideration_effect	"none"
allocations	array di Allocation
taxonomy_version	integer · può essere null
created_at	string (date-time)	RFC 3339, UTC

PaymentList

Campo	Tipo	Descrizione
object	"list"
data	array di Payment
has_more	boolean	C'è una pagina successiva: chiedi di nuovo con starting_after = l'id dell'ultimo elemento

CreditEntry

Campo	Tipo	Descrizione
object	"credit_entry"
id	string (uuid)
customer_id	string (uuid)
direction	string credit · debit	credit: il credito nasce o cresce; debit: viene usato o rimborsato
amount	integer	Sempre positivo: il verso lo dice direction
currency	string
source	string	Elenco aperto di codici
payment_id	string (uuid) · può essere null	Il movimento che l'ha causato
charge_id	string (uuid) · può essere null
action	string · può essere null
reason	string · può essere null
category	string · può essere null
reverses_entry_id	string (uuid) · può essere null
consideration_effect	"none"
created_at	string (date-time)	RFC 3339, UTC

CreditEntryList

Campo	Tipo	Descrizione
object	"list"
data	array di CreditEntry
has_more	boolean	C'è una pagina successiva: chiedi di nuovo con starting_after = l'id dell'ultimo elemento

Receipt

Campo	Tipo	Descrizione
object	"receipt"
id	string (uuid)
kind	string payment_receipt · refund_confirmation	payment_receipt: serie R, denaro ricevuto; refund_confirmation: serie RB, denaro rimborsato (elenco aperto)
series	string	R, RB (elenco aperto): ogni serie ha la sua numerazione
year	integer
sequence	integer	Numero progressivo dentro la serie e l'anno, senza buchi
number	string	Il numero come è stampato sul documento
status	string issued · voided	Una ricevuta annullata resta, col suo numero
issued_at	string (date-time)	RFC 3339, UTC
voided_at	string (date-time) · può essere null	RFC 3339, UTC
operation_type	string · può essere null	Solo per le conferme di rimborso: voluntary_refund, payment_reversal, chargeback (elenco aperto)
payment_id	string (uuid) · può essere null	L'incasso, o il rimborso, che la ricevuta conferma
charge_id	string (uuid) · può essere null	Solo le ricevute del vecchio modello, emesse su un addebito invece che su un incasso
customer_id	string (uuid) · può essere null
amount	integer · può essere null	Come è congelato sul documento, con segno: una conferma di rimborso è negativa
currency	string
pdf_available	boolean	false solo per le ricevute più vecchie, emesse prima dei documenti congelati: nessun foglio da ristampare
fiscal_document	"false"	Una conferma di pagamento: il documento fiscale lo emette il tuo programma

ReceiptList

Campo	Tipo	Descrizione
object	"list"
data	array di Receipt
has_more	boolean	C'è una pagina successiva: chiedi di nuovo con starting_after = l'id dell'ultimo elemento

Event

Campo	Tipo	Descrizione
object	"event"
id	string (uuid)	Stabile, unico fra tutte le scuderie: usalo per riconoscere una novità già elaborata
type	string	Elenco aperto: customer.updated, charge.created, charge.due_date_changed, charge.tax_changed, adjustment.created, payment.created, allocation.created, credit_entry.created, receipt.issued, receipt.voided
data	object
data.object	string	Elenco aperto: customer, charge, adjustment, payment, allocation, credit_entry, receipt
data.id	string (uuid)
data.url	string	Dove leggerlo, a partire dall'host: /api/v1/charges/{id}
occurred_at	string (date-time)	Quando è successo il fatto: l'ora di creazione, di emissione o di annullamento; per un cambio d'imposta, la sua creazione
recorded_at	string (date-time)	Quando la novità è stata scritta: per le novità storiche, il giorno in cui è stata caricata la storia
historical	boolean	true: un fatto di prima che esistessero le novità, caricato una volta, in ordine di data

EventList

Campo	Tipo	Descrizione
object	"list"
data	array di Event
has_more	boolean	Chiedi di nuovo con after = next_cursor. Una pagina può contenere meno novità di limit, anche nessuna, mentre has_more è true
next_cursor	string (uuid) · può essere null	Salvalo dopo aver elaborato la pagina, e ripassalo come after. Può essere l'id di una novità che non ti viene mostrata. null solo quando la scuderia non ha ancora novità per te

Codes

Campo	Tipo	Descrizione
object	"codes"
language	string	La lingua dei nomi: ?lang=, poi Accept-Language, poi en
taxonomy_version	integer	La tassonomia da cui vengono action, reason e category
lists	object
lists.charge_type	object
lists.charge_type.fields	array di string	Dove compaiono questi codici: resource.field
lists.charge_type.codes	array di object
lists.charge_type.codes[].code	string
lists.charge_type.codes[].name	string
lists.action	object
lists.action.fields	array di string	Dove compaiono questi codici: resource.field
lists.action.codes	array di object
lists.action.codes[].code	string
lists.action.codes[].name	string
lists.reason	object
lists.reason.fields	array di string	Dove compaiono questi codici: resource.field
lists.reason.codes	array di object
lists.reason.codes[].code	string
lists.reason.codes[].name	string
lists.reason.codes[].action	string	Il nome di un reason dipende dalla sua action: cercalo con tutti e due
lists.reason.codes[].category	string
lists.category	object
lists.category.fields	array di string	Dove compaiono questi codici: resource.field
lists.category.codes	array di object
lists.category.codes[].code	string
lists.category.codes[].name	string
lists.origin	object
lists.origin.fields	array di string	Dove compaiono questi codici: resource.field
lists.origin.codes	array di object
lists.origin.codes[].code	string
lists.origin.codes[].name	string
lists.payment_type	object
lists.payment_type.fields	array di string	Dove compaiono questi codici: resource.field
lists.payment_type.codes	array di object
lists.payment_type.codes[].code	string
lists.payment_type.codes[].name	string
lists.payment_method	object
lists.payment_method.fields	array di string	Dove compaiono questi codici: resource.field
lists.payment_method.codes	array di object
lists.payment_method.codes[].code	string
lists.payment_method.codes[].name	string
lists.credit_source	object
lists.credit_source.fields	array di string	Dove compaiono questi codici: resource.field
lists.credit_source.codes	array di object
lists.credit_source.codes[].code	string
lists.credit_source.codes[].name	string
lists.receipt_kind	object
lists.receipt_kind.fields	array di string	Dove compaiono questi codici: resource.field
lists.receipt_kind.codes	array di object
lists.receipt_kind.codes[].code	string
lists.receipt_kind.codes[].name	string
lists.refund_operation	object
lists.refund_operation.fields	array di string	Dove compaiono questi codici: resource.field
lists.refund_operation.codes	array di object
lists.refund_operation.codes[].code	string
lists.refund_operation.codes[].name	string
lists.tax_category	object	UNCL 5305
lists.tax_category.fields	array di string	Dove compaiono questi codici: resource.field
lists.tax_category.codes	array di object
lists.tax_category.codes[].code	string
lists.tax_category.codes[].name	string
lists.unit	object	UNECE Rec. 20
lists.unit.fields	array di string	Dove compaiono questi codici: resource.field
lists.unit.codes	array di object
lists.unit.codes[].code	string
lists.unit.codes[].name	string
lists.event_type	object
lists.event_type.fields	array di string	Dove compaiono questi codici: resource.field
lists.event_type.codes	array di object
lists.event_type.codes[].code	string
lists.event_type.codes[].name	string