Stable Pro API · v1

Endpoints et objets

Chaque endpoint avec son autorisation, ses paramètres et sa réponse, et chaque objet avec ses champs. Généré à partir du contrat OpenAPI.

Les noms des champs, les codes et les valeurs sont le contrat : ils sont identiques dans toutes les langues. Les descriptions sont traduites.

Endpoints

GET/api/v1/connection

La connexion de la clé appelante : nom, autorisations et la clé elle-même (jamais le secret)

Autorisation: toute clé valide
Paramètres: lang
Réponse: Connection
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/codes

Le dictionnaire de tous les codes que renvoie l'API, avec les noms dans la langue demandée (?lang=, Accept-Language)

Autorisation: toute clé valide
Paramètres: lang
Réponse: Codes
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/organization

L'écurie de la clé appelante : nom, pays, devise, fuseau horaire, langue, si Stable Pro calcule les taxes

Autorisation: toute clé valide
Paramètres: lang
Réponse: Organization
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/customers

Tous ceux qui ont au moins un débit, payé ou non, membre ou personnel ; avec customers.fiscal:read, aussi les données de facturation

Autorisation: customers:read
Paramètres: langlimitstarting_after
Réponse: CustomerList
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/customers/{id}

Un client ; avec customers.fiscal:read, aussi les données de facturation. D'une autre écurie : 404

Autorisation: customers:read
Paramètres: id (dans le chemin)lang
Réponse: Customer
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

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

Ce que le client doit aujourd'hui, ce qui viendra plus tard, et le crédit qu'il peut utiliser

Autorisation: charges:read
Paramètres: id (dans le chemin)lang
Réponse: Balance
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/charges

Tous les débits aux clients, payés ou non (jamais la rémunération du personnel)

Autorisation

charges:read

Paramètres

langlimitstarting_after

Filtres

customer — Uniquement ce client (son identifiant)
accounting_month — Uniquement ce mois comptable (YYYY-MM) : le mois où le fait compte, voir Conventions

Réponse

ChargeList

Erreurs

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

GET/api/v1/charges/{id}

Un débit, tel qu'il est maintenant : montant et taxes sont la naissance plus les corrections plus les changements de taxe

Autorisation: charges:read
Paramètres: id (dans le chemin)lang
Réponse: Charge
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/adjustments

Corrections des débits

Autorisation

charges:read

Paramètres

langlimitstarting_after

Filtres

charge — Uniquement les corrections de ce débit (son identifiant)
accounting_month — Uniquement ce mois comptable (YYYY-MM) : le mois où le fait compte, voir Conventions

Réponse

AdjustmentList

Erreurs

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

GET/api/v1/adjustments/{id}

Une correction : action, reason, category, montant signé, consideration_effect, la différence de taxe

Autorisation: charges:read
Paramètres: id (dans le chemin)lang
Réponse: Adjustment
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/payments

Mouvements d'argent des clients (encaissements, remboursements, contre-passations, crédit utilisé)

Autorisation

payments:read

Paramètres

langlimitstarting_after

Filtres

customer — Uniquement ce client (son identifiant)

Réponse

PaymentList

Erreurs

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

GET/api/v1/payments/{id}

Un mouvement d'argent, avec ses affectations ; qui a payé pour le compte du client

Autorisation: payments:read
Paramètres: id (dans le chemin)lang
Réponse: Payment
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/allocations/{id}

Quelle part d'un mouvement va à un débit, signée

Autorisation: payments:read
Paramètres: id (dans le chemin)lang
Réponse: Allocation
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/credit-entries

Mouvements du crédit des clients (créé, augmenté, utilisé, remboursé)

Autorisation

payments:read

Paramètres

langlimitstarting_after

Filtres

customer — Uniquement ce client (son identifiant)

Réponse

CreditEntryList

Erreurs

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

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

Un mouvement du crédit d'un client

Autorisation: payments:read
Paramètres: id (dans le chemin)lang
Réponse: CreditEntry
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/receipts

Reçus de Stable Pro (R : reçus de paiement, RB : confirmations de remboursement), dans l'ordre d'émission ; jamais des documents fiscaux

Autorisation

receipts:read

Paramètres

langlimitstarting_after

Filtres

customer — Uniquement ce client (son identifiant)
payment — Uniquement les reçus de ce mouvement d'argent (son identifiant)

Réponse

ReceiptList

Erreurs

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

GET/api/v1/receipts/{id}

Un reçu : type, le numéro tel qu'imprimé, statut, le paiement qu'il confirme, le montant figé

Autorisation: receipts:read
Paramètres: id (dans le chemin)lang
Réponse: Receipt
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

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

Le PDF du reçu, le même que celui qu'a reçu le client. Quand il porte les données fiscales de qui a payé pour le compte du client, il faut aussi customers.fiscal:read (sinon 403)

Autorisation: receipts:read
Paramètres: id (dans le chemin)lang
Réponse: application/pdf
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/events

Ce qui s'est passé, dans l'ordre : lisez après votre curseur pour rester synchronisé. Chaque événement demande l'autorisation de l'objet vers lequel il pointe. Pendant le chargement de l'historique de l'écurie : 503 events-not-ready

Autorisation: toute clé valide
Paramètres: langlimitafter
Réponse: EventList
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/events/{id}

Un événement. D'une autre écurie, ou d'un type que votre clé ne lit pas : 404

Autorisation: toute clé valide
Paramètres: id (dans le chemin)lang
Réponse: Event
Erreurs: 400 · 401 · 403 · 404 · 429 · 500 · 503

Objets

Problem

Champ	Type	Description
type	string (uri)	Stable, en anglais : décidez selon ceci, pas selon le texte
title	string	En anglais
status	integer
detail	string · facultatif	Une phrase destinée aux personnes, dans la langue demandée (?lang=, Accept-Language)
reason	string · facultatif missing · malformed · wrong_environment · unknown · connection_revoked · revoked · expired · rotated	401 uniquement : pourquoi la clé n'est pas valide
missing_permission	string · facultatif charges:read · payments:read · receipts:read · customers:read · customers.fiscal:read · external-documents:write	403 forbidden uniquement
invalid_param	string · facultatif	400 uniquement : le paramètre qui n'est pas valide

Connection

Champ	Type	Description
object	"connection"
id	string (uuid)
name	string
permissions	tableau de 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 = production (sp_live_), test = staging (sp_test_)
key.created_at	string (date-time)	RFC 3339, UTC
key.expires_at	string (date-time) · peut être null	RFC 3339, UTC
key.retires_at	string (date-time) · peut être null	Après une rotation : quand cette clé cesse de fonctionner

Organization

Champ	Type	Description
object	"organization"
id	string (uuid)
name	string
legal_name	string · peut être null
country	string · peut être null	ISO 3166-1 alpha-2
currency	string	ISO 4217
timezone	string	IANA
language	string	La langue de l'écurie : Stable Pro ne connaît pas celle de chaque client
locale	string	BCP 47, pour la mise en forme
taxes	object
taxes.calculated_by	string stable_pro · external	external = Stable Pro ne calcule pas les taxes ce mois-ci : rien de plus
taxes.amount_basis	"gross"	Chaque montant est le total que paie le client
receipts_shown_to_customers	boolean	false : l'écurie a choisi de ne pas donner les reçus de Stable Pro à ses clients tant qu'un logiciel est connecté ; ils existent quand même et sont numérotés (GET /receipts)

Customer

Champ	Type	Description
object	"customer"
id	string (uuid)	Le code du client : il ne change jamais
kind	string member · staff
name	string
given_name	string · peut être null
family_name	string · peut être null
active	boolean	false : a quitté l'écurie, ou a été retiré ; ses débits restent facturables
created_at	string (date-time)	RFC 3339, UTC
billing_address	object · peut être null · facultatif	Uniquement avec customers.fiscal:read
billing_address.line1	string · peut être null
billing_address.line2	string · peut être null
billing_address.postal_code	string · peut être null
billing_address.city	string · peut être null
billing_address.subdivision	string · peut être null	ISO 3166-2 (IT-MI, US-OH)
billing_address.country	string · peut être null	ISO 3166-1 alpha-2
billing_address_text	string · peut être null · facultatif	Uniquement avec customers.fiscal:read : l'ancienne adresse en texte libre, seulement tant que billing_address est vide
tax_identifiers	tableau de object · facultatif	Uniquement avec customers.fiscal:read
tax_identifiers[].scheme	string	VAT, ou un ICD ISO 6523 (0210 code fiscal italien, 0211 numéro de TVA italien)
tax_identifiers[].value	string
tax_code	string · peut être null · facultatif	Uniquement avec customers.fiscal:read : l'ancien code fiscal, sans schéma

CustomerList

Champ	Type	Description
object	"list"
data	tableau de Customer
has_more	boolean	Il y a une page suivante : redemandez avec starting_after = l'identifiant du dernier élément

Balance

Champ	Type	Description
object	"balance"
customer_id	string (uuid)
currency	string
amount_due	integer	Ce qui est dû aujourd'hui : débits déjà visibles
amount_scheduled	integer	Débits qui deviendront visibles plus tard
credit	integer	Crédit utilisable sur un débit
as_of	string (date)	Aujourd'hui, dans le fuseau horaire de l'écurie

Charge

Champ	Type	Description
object	"charge"
id	string (uuid)
customer_id	string (uuid)
type	string	Liste ouverte : boarding, service_charge, lesson_drop_in, lesson_plan, health_record, …
description	string	Tel que l'écurie l'a écrit
period_start	string (date)	YYYY-MM-DD
period_end	string (date)	YYYY-MM-DD
competence_month	string	YYYY-MM
accounting_month	string	Le plus tardif entre le mois de rattachement et celui d'enregistrement : calculé par 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és mineures de la devise (ISO 4217)
currency	string
original_amount	integer	À la naissance
amount	integer	Maintenant : la naissance plus les corrections
amount_paid	integer	Unités mineures de la devise (ISO 4217)
amount_remaining	integer	Unités mineures de la devise (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és mineures de la devise (ISO 4217)
taxes	tableau de object
taxes[].type	"vat"	Liste ouverte : d'autres types peuvent arriver
taxes[].jurisdiction	string · peut être null	ISO 3166-1 alpha-2 de l'écurie
taxes[].category	string · peut être null	UNCL 5305 : S, Z, E, AE, K, G, O ; null si elle n'est pas déclarée
taxes[].rate_bp	integer	Points de base : 2200 = 22 %
taxes[].amount	integer	Unités mineures de la devise
taxes[].exemption_reason	string · peut être null · facultatif	BT-120, uniquement au taux zéro
taxes[].exemption_reason_code	string · peut être null · facultatif	VATEX (BT-121), uniquement au taux zéro
created_at	string (date-time)	RFC 3339, UTC

ChargeList

Champ	Type	Description
object	"list"
data	tableau de Charge
has_more	boolean	Il y a une page suivante : redemandez avec starting_after = l'identifiant du dernier élément

Adjustment

Champ	Type	Description
object	"adjustment"
id	string (uuid)
charge_id	string (uuid)
customer_id	string (uuid)
direction	"receivable"
action	string · peut être null	Liste ouverte de codes (voir /codes)
reason	string · peut être null
category	string · peut être null
origin	string · peut être null	HUMAN, SYSTEM, …
amount	integer	Signé : négatif réduit le débit
consideration_effect	string changes · none	changes : un avoir (ou une note de débit) suit ; none : une perte sur créance, sans taxe
taxes	tableau de object	Avec changes : la différence de taxe, déjà calculée. Avec none : vide
taxes[].type	"vat"	Liste ouverte : d'autres types peuvent arriver
taxes[].jurisdiction	string · peut être null	ISO 3166-1 alpha-2 de l'écurie
taxes[].category	string · peut être null	UNCL 5305 : S, Z, E, AE, K, G, O ; null si elle n'est pas déclarée
taxes[].rate_bp	integer	Points de base : 2200 = 22 %
taxes[].amount	integer	Unités mineures de la devise
taxes[].exemption_reason	string · peut être null · facultatif	BT-120, uniquement au taux zéro
taxes[].exemption_reason_code	string · peut être null · facultatif	VATEX (BT-121), uniquement au taux zéro
taxable_amount	integer · peut être null	Unités mineures de la devise (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) · peut être null
taxonomy_version	integer

AdjustmentList

Champ	Type	Description
object	"list"
data	tableau de Adjustment
has_more	boolean	Il y a une page suivante : redemandez avec starting_after = l'identifiant du dernier élément

Allocation

Champ	Type	Description
object	"allocation"
id	string (uuid)
payment_id	string (uuid)
charge_id	string (uuid)
amount	integer	Signé
currency	string · facultatif
consideration_effect	"none"

Payment

Champ	Type	Description
object	"payment"
id	string (uuid)
customer_id	string (uuid) · peut être null
type	string payment · credit_applied · offset · refund · moved_to_credit · reversal	Ce qui est arrivé à l'argent (liste ouverte)
amount	integer	L'argent qui a réellement bougé, signé : un remboursement ou une contre-passation est négatif, moved_to_credit vaut zéro
currency	string
date	string (date)	YYYY-MM-DD
accounting_month	string	YYYY-MM
method	string	cash, bank_transfer, pos, credit, compensazione, other (liste ouverte)
reference	string · peut être null
paid_by	object · peut être null	Qui a payé pour le compte du client (un parent) : pas un client à part entière
paid_by.kind	string · peut être null
paid_by.name	string · peut être null
paid_by.tax_code	string · peut être null · facultatif	Uniquement avec customers.fiscal:read
paid_by.address_text	string · peut être null · facultatif	Uniquement avec customers.fiscal:read
reverses_payment_id	string (uuid) · peut être null
action	string · peut être null	Uniquement pour les contre-passations
reason	string · peut être null
category	string · peut être null
consideration_effect	"none"
allocations	tableau de Allocation
taxonomy_version	integer · peut être null
created_at	string (date-time)	RFC 3339, UTC

PaymentList

Champ	Type	Description
object	"list"
data	tableau de Payment
has_more	boolean	Il y a une page suivante : redemandez avec starting_after = l'identifiant du dernier élément

CreditEntry

Champ	Type	Description
object	"credit_entry"
id	string (uuid)
customer_id	string (uuid)
direction	string credit · debit	credit : le crédit naît ou augmente ; debit : il est utilisé ou remboursé
amount	integer	Toujours positif : direction indique le sens
currency	string
source	string	Liste ouverte de codes
payment_id	string (uuid) · peut être null	Le mouvement qui l'a causé
charge_id	string (uuid) · peut être null
action	string · peut être null
reason	string · peut être null
category	string · peut être null
reverses_entry_id	string (uuid) · peut être null
consideration_effect	"none"
created_at	string (date-time)	RFC 3339, UTC

CreditEntryList

Champ	Type	Description
object	"list"
data	tableau de CreditEntry
has_more	boolean	Il y a une page suivante : redemandez avec starting_after = l'identifiant du dernier élément

Receipt

Champ	Type	Description
object	"receipt"
id	string (uuid)
kind	string payment_receipt · refund_confirmation	payment_receipt : série R, argent reçu ; refund_confirmation : série RB, argent remboursé (liste ouverte)
series	string	R, RB (liste ouverte) : chaque série a sa propre numérotation
year	integer
sequence	integer	Numéro progressif au sein de la série et de l'année, sans trous
number	string	Le numéro tel qu'imprimé sur le document
status	string issued · voided	Un reçu annulé reste, avec son numéro
issued_at	string (date-time)	RFC 3339, UTC
voided_at	string (date-time) · peut être null	RFC 3339, UTC
operation_type	string · peut être null	Uniquement pour les confirmations de remboursement : voluntary_refund, payment_reversal, chargeback (liste ouverte)
payment_id	string (uuid) · peut être null	L'encaissement, ou le remboursement, que le reçu confirme
charge_id	string (uuid) · peut être null	Uniquement les reçus de l'ancien modèle, émis sur un débit au lieu d'un encaissement
customer_id	string (uuid) · peut être null
amount	integer · peut être null	Tel que figé sur le document, signé : une confirmation de remboursement est négative
currency	string
pdf_available	boolean	false uniquement pour les reçus les plus anciens, émis avant les documents figés : pas de feuille à réimprimer
fiscal_document	"false"	Une confirmation de paiement : le document fiscal est émis par votre logiciel

ReceiptList

Champ	Type	Description
object	"list"
data	tableau de Receipt
has_more	boolean	Il y a une page suivante : redemandez avec starting_after = l'identifiant du dernier élément

Event

Champ	Type	Description
object	"event"
id	string (uuid)	Stable, unique entre toutes les écuries : utilisez-le pour reconnaître un événement déjà traité
type	string	Liste ouverte : 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	Liste ouverte : customer, charge, adjustment, payment, allocation, credit_entry, receipt
data.id	string (uuid)
data.url	string	Où le lire, à partir de l'hôte : /api/v1/charges/{id}
occurred_at	string (date-time)	Quand le fait s'est produit : l'heure de création, d'émission ou d'annulation ; pour un changement de taxe, sa création
recorded_at	string (date-time)	Quand l'événement a été écrit : pour les événements historiques, le jour où l'historique a été chargé
historical	boolean	true : un fait antérieur à l'existence des événements, chargé une fois, classé par sa date

EventList

Champ	Type	Description
object	"list"
data	tableau de Event
has_more	boolean	Redemandez avec after = next_cursor. Une page peut contenir moins d'événements que limit, voire aucun, alors que has_more vaut true
next_cursor	string (uuid) · peut être null	Enregistrez-le après avoir traité la page, et renvoyez-le comme after. Il peut être l'identifiant d'un événement qui ne vous est pas montré. null uniquement quand l'écurie n'a encore aucun événement pour vous

Codes

Champ	Type	Description
object	"codes"
language	string	La langue des noms : ?lang=, puis Accept-Language, puis en
taxonomy_version	integer	La taxonomie dont viennent action, reason et category
lists	object
lists.charge_type	object
lists.charge_type.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.charge_type.codes	tableau de object
lists.charge_type.codes[].code	string
lists.charge_type.codes[].name	string
lists.action	object
lists.action.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.action.codes	tableau de object
lists.action.codes[].code	string
lists.action.codes[].name	string
lists.reason	object
lists.reason.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.reason.codes	tableau de object
lists.reason.codes[].code	string
lists.reason.codes[].name	string
lists.reason.codes[].action	string	Le nom d'un reason dépend de son action : cherchez-le avec les deux
lists.reason.codes[].category	string
lists.category	object
lists.category.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.category.codes	tableau de object
lists.category.codes[].code	string
lists.category.codes[].name	string
lists.origin	object
lists.origin.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.origin.codes	tableau de object
lists.origin.codes[].code	string
lists.origin.codes[].name	string
lists.payment_type	object
lists.payment_type.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.payment_type.codes	tableau de object
lists.payment_type.codes[].code	string
lists.payment_type.codes[].name	string
lists.payment_method	object
lists.payment_method.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.payment_method.codes	tableau de object
lists.payment_method.codes[].code	string
lists.payment_method.codes[].name	string
lists.credit_source	object
lists.credit_source.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.credit_source.codes	tableau de object
lists.credit_source.codes[].code	string
lists.credit_source.codes[].name	string
lists.receipt_kind	object
lists.receipt_kind.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.receipt_kind.codes	tableau de object
lists.receipt_kind.codes[].code	string
lists.receipt_kind.codes[].name	string
lists.refund_operation	object
lists.refund_operation.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.refund_operation.codes	tableau de object
lists.refund_operation.codes[].code	string
lists.refund_operation.codes[].name	string
lists.tax_category	object	UNCL 5305
lists.tax_category.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.tax_category.codes	tableau de object
lists.tax_category.codes[].code	string
lists.tax_category.codes[].name	string
lists.unit	object	UNECE Rec. 20
lists.unit.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.unit.codes	tableau de object
lists.unit.codes[].code	string
lists.unit.codes[].name	string
lists.event_type	object
lists.event_type.fields	tableau de string	Où ces codes apparaissent : resource.field
lists.event_type.codes	tableau de object
lists.event_type.codes[].code	string
lists.event_type.codes[].name	string