Stable Pro API · v1

Endpoints y objetos

Cada endpoint con su permiso, sus parámetros y su respuesta, y cada objeto con sus campos. Generado a partir del contrato OpenAPI.

Los nombres de los campos, los códigos y los valores son el contrato: son iguales en todos los idiomas. Las descripciones están traducidas.

Endpoints

GET/api/v1/connection

La conexión de la clave que llama: nombre, permisos y la propia clave (nunca el secreto)

Permiso: cualquier clave válida
Parámetros: lang
Respuesta: Connection
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/codes

El diccionario de todos los códigos que devuelve la API, con los nombres en el idioma solicitado (?lang=, Accept-Language)

Permiso: cualquier clave válida
Parámetros: lang
Respuesta: Codes
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/organization

La cuadra de la clave que llama: nombre, país, moneda, zona horaria, idioma, si Stable Pro calcula los impuestos

Permiso: cualquier clave válida
Parámetros: lang
Respuesta: Organization
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/customers

Todos los que tienen al menos un cargo, pagado o no, socio o personal; con customers.fiscal:read también los datos de facturación

Permiso: customers:read
Parámetros: langlimitstarting_after
Respuesta: CustomerList
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/customers/{id}

Un cliente; con customers.fiscal:read también los datos de facturación. De otra cuadra: 404

Permiso: customers:read
Parámetros: id (en la ruta)lang
Respuesta: Customer
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

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

Lo que el cliente debe hoy, lo que llega después y el crédito que puede usar

Permiso: charges:read
Parámetros: id (en la ruta)lang
Respuesta: Balance
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/charges

Todos los cargos a los clientes, pagados o no (nunca los pagos al personal)

Permiso

charges:read

Parámetros

langlimitstarting_after

Filtros

customer — Solo este cliente (su id)
accounting_month — Solo este mes contable (YYYY-MM): el mes en que cuenta el hecho, consulta Convenciones

Respuesta

ChargeList

Errores

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

GET/api/v1/charges/{id}

Un cargo, tal como es ahora: importe e impuestos son el origen más las correcciones más los cambios de impuesto

Permiso: charges:read
Parámetros: id (en la ruta)lang
Respuesta: Charge
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/adjustments

Correcciones de cargos

Permiso

charges:read

Parámetros

langlimitstarting_after

Filtros

charge — Solo las correcciones de este cargo (su id)
accounting_month — Solo este mes contable (YYYY-MM): el mes en que cuenta el hecho, consulta Convenciones

Respuesta

AdjustmentList

Errores

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

GET/api/v1/adjustments/{id}

Una corrección: action, reason, category, importe con signo, consideration_effect, la diferencia de impuesto

Permiso: charges:read
Parámetros: id (en la ruta)lang
Respuesta: Adjustment
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/payments

Movimientos de dinero de los clientes (cobros, reembolsos, anulaciones, crédito usado)

Permiso

payments:read

Parámetros

langlimitstarting_after

Filtros

customer — Solo este cliente (su id)

Respuesta

PaymentList

Errores

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

GET/api/v1/payments/{id}

Un movimiento de dinero, con sus asignaciones; quién pagó por cuenta del cliente

Permiso: payments:read
Parámetros: id (en la ruta)lang
Respuesta: Payment
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/allocations/{id}

Cuánto de un movimiento va a un cargo, con signo

Permiso: payments:read
Parámetros: id (en la ruta)lang
Respuesta: Allocation
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/credit-entries

Movimientos del crédito de los clientes (creado, aumentado, usado, reembolsado)

Permiso

payments:read

Parámetros

langlimitstarting_after

Filtros

customer — Solo este cliente (su id)

Respuesta

CreditEntryList

Errores

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

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

Un movimiento del crédito de un cliente

Permiso: payments:read
Parámetros: id (en la ruta)lang
Respuesta: CreditEntry
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/receipts

Recibos de Stable Pro (R: recibos de pago, RB: confirmaciones de reembolso), en orden de emisión; nunca documentos fiscales

Permiso

receipts:read

Parámetros

langlimitstarting_after

Filtros

customer — Solo este cliente (su id)
payment — Solo los recibos de este movimiento de dinero (su id)

Respuesta

ReceiptList

Errores

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

GET/api/v1/receipts/{id}

Un recibo: tipo, el número tal como se imprime, estado, el pago que confirma, el importe congelado

Permiso: receipts:read
Parámetros: id (en la ruta)lang
Respuesta: Receipt
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

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

El PDF del recibo, el mismo que recibió el cliente. Cuando lleva los datos fiscales de quien pagó por cuenta del cliente, también necesita customers.fiscal:read (si no, 403)

Permiso: receipts:read
Parámetros: id (en la ruta)lang
Respuesta: application/pdf
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/events

Lo que ha pasado, en orden: lee después de tu cursor para mantenerte sincronizado. Cada evento necesita el permiso del objeto al que apunta. Mientras se carga la historia de la cuadra: 503 events-not-ready

Permiso: cualquier clave válida
Parámetros: langlimitafter
Respuesta: EventList
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

GET/api/v1/events/{id}

Un evento. De otra cuadra, o de un tipo que tu clave no lee: 404

Permiso: cualquier clave válida
Parámetros: id (en la ruta)lang
Respuesta: Event
Errores: 400 · 401 · 403 · 404 · 429 · 500 · 503

Objetos

Problem

Campo	Tipo	Descripción
type	string (uri)	Estable, en inglés: decide según esto, no según el texto
title	string	En inglés
status	integer
detail	string · opcional	Una frase para las personas, en el idioma solicitado (?lang=, Accept-Language)
reason	string · opcional missing · malformed · wrong_environment · unknown · connection_revoked · revoked · expired · rotated	Solo 401: por qué la clave no es válida
missing_permission	string · opcional charges:read · payments:read · receipts:read · customers:read · customers.fiscal:read · external-documents:write	Solo 403 forbidden
invalid_param	string · opcional	Solo 400: el parámetro que no es válido

Connection

Campo	Tipo	Descripción
object	"connection"
id	string (uuid)
name	string
permissions	array 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 = producción (sp_live_), test = staging (sp_test_)
key.created_at	string (date-time)	RFC 3339, UTC
key.expires_at	string (date-time) · puede ser null	RFC 3339, UTC
key.retires_at	string (date-time) · puede ser null	Tras una rotación: cuándo deja de funcionar esta clave

Organization

Campo	Tipo	Descripción
object	"organization"
id	string (uuid)
name	string
legal_name	string · puede ser null
country	string · puede ser null	ISO 3166-1 alpha-2
currency	string	ISO 4217
timezone	string	IANA
language	string	El idioma de la cuadra: Stable Pro no conoce el de cada cliente
locale	string	BCP 47, para el formato
taxes	object
taxes.calculated_by	string stable_pro · external	external = Stable Pro no calcula los impuestos este mes: nada más
taxes.amount_basis	"gross"	Cada importe es el total que paga el cliente
receipts_shown_to_customers	boolean	false: la cuadra ha elegido no dar los recibos de Stable Pro a sus clientes mientras haya un programa conectado; siguen existiendo y están numerados (GET /receipts)

Customer

Campo	Tipo	Descripción
object	"customer"
id	string (uuid)	El código del cliente: nunca cambia
kind	string member · staff
name	string
given_name	string · puede ser null
family_name	string · puede ser null
active	boolean	false: ha dejado la cuadra, o se ha eliminado; sus cargos se pueden seguir facturando
created_at	string (date-time)	RFC 3339, UTC
billing_address	object · puede ser null · opcional	Solo con customers.fiscal:read
billing_address.line1	string · puede ser null
billing_address.line2	string · puede ser null
billing_address.postal_code	string · puede ser null
billing_address.city	string · puede ser null
billing_address.subdivision	string · puede ser null	ISO 3166-2 (IT-MI, US-OH)
billing_address.country	string · puede ser null	ISO 3166-1 alpha-2
billing_address_text	string · puede ser null · opcional	Solo con customers.fiscal:read: la antigua dirección en texto libre, solo mientras billing_address esté vacío
tax_identifiers	array de object · opcional	Solo con customers.fiscal:read
tax_identifiers[].scheme	string	VAT, o un ICD de ISO 6523 (0210 código fiscal italiano, 0211 número de IVA italiano)
tax_identifiers[].value	string
tax_code	string · puede ser null · opcional	Solo con customers.fiscal:read: el antiguo código fiscal, sin esquema

CustomerList

Campo	Tipo	Descripción
object	"list"
data	array de Customer
has_more	boolean	Hay una página siguiente: vuelve a pedir con starting_after = el id del último elemento

Balance

Campo	Tipo	Descripción
object	"balance"
customer_id	string (uuid)
currency	string
amount_due	integer	Lo que se debe hoy: cargos ya visibles
amount_scheduled	integer	Cargos que serán visibles más adelante
credit	integer	Crédito que se puede usar en un cargo
as_of	string (date)	Hoy, en la zona horaria de la cuadra

Charge

Campo	Tipo	Descripción
object	"charge"
id	string (uuid)
customer_id	string (uuid)
type	string	Lista abierta: boarding, service_charge, lesson_drop_in, lesson_plan, health_record, …
description	string	Tal como lo escribió la cuadra
period_start	string (date)	YYYY-MM-DD
period_end	string (date)	YYYY-MM-DD
competence_month	string	YYYY-MM
accounting_month	string	El posterior entre el mes de devengo y el de registro: lo calcula 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	Unidades menores de la moneda (ISO 4217)
currency	string
original_amount	integer	En su origen
amount	integer	Ahora: el origen más las correcciones
amount_paid	integer	Unidades menores de la moneda (ISO 4217)
amount_remaining	integer	Unidades menores de la moneda (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	Unidades menores de la moneda (ISO 4217)
taxes	array de object
taxes[].type	"vat"	Lista abierta: pueden llegar otros tipos
taxes[].jurisdiction	string · puede ser null	ISO 3166-1 alpha-2 de la cuadra
taxes[].category	string · puede ser null	UNCL 5305: S, Z, E, AE, K, G, O; null cuando no se declara
taxes[].rate_bp	integer	Puntos básicos: 2200 = 22 %
taxes[].amount	integer	Unidades menores de la moneda
taxes[].exemption_reason	string · puede ser null · opcional	BT-120, solo con tipo cero
taxes[].exemption_reason_code	string · puede ser null · opcional	VATEX (BT-121), solo con tipo cero
created_at	string (date-time)	RFC 3339, UTC

ChargeList

Campo	Tipo	Descripción
object	"list"
data	array de Charge
has_more	boolean	Hay una página siguiente: vuelve a pedir con starting_after = el id del último elemento

Adjustment

Campo	Tipo	Descripción
object	"adjustment"
id	string (uuid)
charge_id	string (uuid)
customer_id	string (uuid)
direction	"receivable"
action	string · puede ser null	Lista abierta de códigos (consulta /codes)
reason	string · puede ser null
category	string · puede ser null
origin	string · puede ser null	HUMAN, SYSTEM, …
amount	integer	Con signo: negativo reduce el cargo
consideration_effect	string changes · none	changes: sigue una factura rectificativa (o nota de débito); none: un crédito incobrable, sin impuesto
taxes	array de object	Con changes: la diferencia de impuesto, ya calculada. Con none: vacío
taxes[].type	"vat"	Lista abierta: pueden llegar otros tipos
taxes[].jurisdiction	string · puede ser null	ISO 3166-1 alpha-2 de la cuadra
taxes[].category	string · puede ser null	UNCL 5305: S, Z, E, AE, K, G, O; null cuando no se declara
taxes[].rate_bp	integer	Puntos básicos: 2200 = 22 %
taxes[].amount	integer	Unidades menores de la moneda
taxes[].exemption_reason	string · puede ser null · opcional	BT-120, solo con tipo cero
taxes[].exemption_reason_code	string · puede ser null · opcional	VATEX (BT-121), solo con tipo cero
taxable_amount	integer · puede ser null	Unidades menores de la moneda (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) · puede ser null
taxonomy_version	integer

AdjustmentList

Campo	Tipo	Descripción
object	"list"
data	array de Adjustment
has_more	boolean	Hay una página siguiente: vuelve a pedir con starting_after = el id del último elemento

Allocation

Campo	Tipo	Descripción
object	"allocation"
id	string (uuid)
payment_id	string (uuid)
charge_id	string (uuid)
amount	integer	Con signo
currency	string · opcional
consideration_effect	"none"

Payment

Campo	Tipo	Descripción
object	"payment"
id	string (uuid)
customer_id	string (uuid) · puede ser null
type	string payment · credit_applied · offset · refund · moved_to_credit · reversal	Qué ha pasado con el dinero (lista abierta)
amount	integer	El dinero que se movió de verdad, con signo: un reembolso o una anulación es negativo, moved_to_credit es cero
currency	string
date	string (date)	YYYY-MM-DD
accounting_month	string	YYYY-MM
method	string	cash, bank_transfer, pos, credit, compensazione, other (lista abierta)
reference	string · puede ser null
paid_by	object · puede ser null	Quien pagó por cuenta del cliente (un padre o una madre): no es un cliente por sí mismo
paid_by.kind	string · puede ser null
paid_by.name	string · puede ser null
paid_by.tax_code	string · puede ser null · opcional	Solo con customers.fiscal:read
paid_by.address_text	string · puede ser null · opcional	Solo con customers.fiscal:read
reverses_payment_id	string (uuid) · puede ser null
action	string · puede ser null	Solo para anulaciones
reason	string · puede ser null
category	string · puede ser null
consideration_effect	"none"
allocations	array de Allocation
taxonomy_version	integer · puede ser null
created_at	string (date-time)	RFC 3339, UTC

PaymentList

Campo	Tipo	Descripción
object	"list"
data	array de Payment
has_more	boolean	Hay una página siguiente: vuelve a pedir con starting_after = el id del último elemento

CreditEntry

Campo	Tipo	Descripción
object	"credit_entry"
id	string (uuid)
customer_id	string (uuid)
direction	string credit · debit	credit: el crédito nace o crece; debit: se usa o se reembolsa
amount	integer	Siempre positivo: direction indica el sentido
currency	string
source	string	Lista abierta de códigos
payment_id	string (uuid) · puede ser null	El movimiento que lo causó
charge_id	string (uuid) · puede ser null
action	string · puede ser null
reason	string · puede ser null
category	string · puede ser null
reverses_entry_id	string (uuid) · puede ser null
consideration_effect	"none"
created_at	string (date-time)	RFC 3339, UTC

CreditEntryList

Campo	Tipo	Descripción
object	"list"
data	array de CreditEntry
has_more	boolean	Hay una página siguiente: vuelve a pedir con starting_after = el id del último elemento

Receipt

Campo	Tipo	Descripción
object	"receipt"
id	string (uuid)
kind	string payment_receipt · refund_confirmation	payment_receipt: serie R, dinero recibido; refund_confirmation: serie RB, dinero reembolsado (lista abierta)
series	string	R, RB (lista abierta): cada serie tiene su propia numeración
year	integer
sequence	integer	Número correlativo dentro de la serie y el año, sin huecos
number	string	El número tal como aparece impreso en el documento
status	string issued · voided	Un recibo anulado se queda, con su número
issued_at	string (date-time)	RFC 3339, UTC
voided_at	string (date-time) · puede ser null	RFC 3339, UTC
operation_type	string · puede ser null	Solo para las confirmaciones de reembolso: voluntary_refund, payment_reversal, chargeback (lista abierta)
payment_id	string (uuid) · puede ser null	El cobro, o el reembolso, que confirma el recibo
charge_id	string (uuid) · puede ser null	Solo los recibos del modelo antiguo, emitidos sobre un cargo en lugar de un cobro
customer_id	string (uuid) · puede ser null
amount	integer · puede ser null	Tal como quedó congelado en el documento, con signo: una confirmación de reembolso es negativa
currency	string
pdf_available	boolean	false solo para los recibos más antiguos, emitidos antes de los documentos congelados: no hay hoja que reimprimir
fiscal_document	"false"	Una confirmación de pago: el documento fiscal lo emite tu programa

ReceiptList

Campo	Tipo	Descripción
object	"list"
data	array de Receipt
has_more	boolean	Hay una página siguiente: vuelve a pedir con starting_after = el id del último elemento

Event

Campo	Tipo	Descripción
object	"event"
id	string (uuid)	Estable, único entre todas las cuadras: úsalo para reconocer un evento ya procesado
type	string	Lista abierta: 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	Lista abierta: customer, charge, adjustment, payment, allocation, credit_entry, receipt
data.id	string (uuid)
data.url	string	Dónde leerlo, a partir del host: /api/v1/charges/{id}
occurred_at	string (date-time)	Cuándo ocurrió el hecho: la hora de creación, emisión o anulación; para un cambio de impuesto, su creación
recorded_at	string (date-time)	Cuándo se escribió el evento: para los eventos históricos, el día en que se cargó la historia
historical	boolean	true: un hecho de antes de que existieran los eventos, cargado una vez, ordenado por su fecha

EventList

Campo	Tipo	Descripción
object	"list"
data	array de Event
has_more	boolean	Vuelve a pedir con after = next_cursor. Una página puede contener menos eventos que limit, incluso ninguno, mientras has_more es true
next_cursor	string (uuid) · puede ser null	Guárdalo después de procesar la página y devuélvelo como after. Puede ser el id de un evento que no se te muestra. null solo cuando la cuadra aún no tiene eventos para ti

Codes

Campo	Tipo	Descripción
object	"codes"
language	string	El idioma de los nombres: ?lang=, luego Accept-Language y, por último, en (inglés)
taxonomy_version	integer	La taxonomía de la que vienen action, reason y category
lists	object
lists.charge_type	object
lists.charge_type.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.charge_type.codes	array de object
lists.charge_type.codes[].code	string
lists.charge_type.codes[].name	string
lists.action	object
lists.action.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.action.codes	array de object
lists.action.codes[].code	string
lists.action.codes[].name	string
lists.reason	object
lists.reason.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.reason.codes	array de object
lists.reason.codes[].code	string
lists.reason.codes[].name	string
lists.reason.codes[].action	string	El nombre de un reason depende de su action: búscalo con los dos
lists.reason.codes[].category	string
lists.category	object
lists.category.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.category.codes	array de object
lists.category.codes[].code	string
lists.category.codes[].name	string
lists.origin	object
lists.origin.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.origin.codes	array de object
lists.origin.codes[].code	string
lists.origin.codes[].name	string
lists.payment_type	object
lists.payment_type.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.payment_type.codes	array de object
lists.payment_type.codes[].code	string
lists.payment_type.codes[].name	string
lists.payment_method	object
lists.payment_method.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.payment_method.codes	array de object
lists.payment_method.codes[].code	string
lists.payment_method.codes[].name	string
lists.credit_source	object
lists.credit_source.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.credit_source.codes	array de object
lists.credit_source.codes[].code	string
lists.credit_source.codes[].name	string
lists.receipt_kind	object
lists.receipt_kind.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.receipt_kind.codes	array de object
lists.receipt_kind.codes[].code	string
lists.receipt_kind.codes[].name	string
lists.refund_operation	object
lists.refund_operation.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.refund_operation.codes	array de object
lists.refund_operation.codes[].code	string
lists.refund_operation.codes[].name	string
lists.tax_category	object	UNCL 5305
lists.tax_category.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.tax_category.codes	array de object
lists.tax_category.codes[].code	string
lists.tax_category.codes[].name	string
lists.unit	object	UNECE Rec. 20
lists.unit.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.unit.codes	array de object
lists.unit.codes[].code	string
lists.unit.codes[].name	string
lists.event_type	object
lists.event_type.fields	array de string	Dónde aparecen estos códigos: resource.field
lists.event_type.codes	array de object
lists.event_type.codes[].code	string
lists.event_type.codes[].name	string