Obligations

ObligationsClient

High-level synchronous operations for obligations owned by this integration.

All methods use the category and integration associated with the API key. Documented validation responses raise :class:OblidogValidationError; API conflicts raise :class:OblidogConflictError where supported.

list(*, year=None, month=None, lifecycle=None)

List obligations visible to the authenticated integration.

Parameters:

Name	Type	Description	Default
year	int | None	Restrict results to a calendar year.	None
month	int | None	Restrict results to a calendar month (1 through 12).	None
lifecycle	ObligationLifecycle | None	Restrict results to one lifecycle state.	None

Returns:

Type	Description
ObligationsPublic	A page-like collection of matching obligations.

Raises:

Type	Description
OblidogValidationError	If a supplied filter is invalid.
OblidogApiError	If the API returns no parsed response.

get(period)

Return one obligation for period in the key-bound category.

Raises:

Type	Description
TypeError	If period is not an :class:ObligationPeriod.
OblidogApiError	If the API cannot return a parsed obligation.

list_components(period)

List components currently attached to an obligation.

upsert_component(period, *, type, label, external_id, amount=UNSET, metadata=UNSET)

Create or update a component identified by external_id.

amount and metadata distinguish omission from explicit None: omitted values leave those fields out of the request, while None deliberately clears their value. external_id is required so repeated provider imports update the same component.

Returns:

Type	Description
ObligationComponentPublic	The created or updated component.

Raises:

Type	Description
OblidogValidationError	If the request is invalid.

update(period, *, current_amount=UNSET, due_date=UNSET, issue_date=UNSET)

Update integration-controlled values on an obligation.

For every optional value, omission leaves it unchanged; explicit None clears it. This applies to current_amount, due_date, and issue_date.

Returns:

Type	Description
ObligationPublic	The updated obligation.

Raises:

Type	Description
OblidogValidationError	If the update is invalid.

append_note(period, text)

Append text to an obligation's existing notes and return it.

mark_ready(period)

Mark an obligation ready for payment.

mark_paid(period)

Mark an obligation paid.

cancel(period)

Cancel an obligation.

reopen(period)

Reopen a cancelled or completed obligation.

mark_error(period)

Mark an obligation as requiring attention after an integration error.

ObligationPeriod dataclass

Calendar month identifying an obligation within the key-bound category.

Parameters:

Name	Type	Description	Default
year	int	Four-digit calendar year (1 through 9999).	required
month	int	Calendar month (1 through 12).	required

The integration API key supplies the category, so callers do not need to construct or retain an Oblidog obligation key.

ObligationLifecycle

Bases: str, Enum

ObligationPublic

Attributes:

Name	Type	Description
amount_source	CurrentValueSource
amount_state	ValueState
category_code	str
category_id	UUID
counterparty	CounterpartySummaryPublic | None
counterparty_id	None | UUID
created_at	datetime
currency	None | str
current_amount	None | str
due_date	date | None
due_date_source	CurrentValueSource
due_date_state	ValueState
effective_value_source	EffectiveValueSourceMode
id	UUID
issue_date	date | None
issue_date_source	CurrentValueSource
issue_date_state	ValueState
key	str
ledger_id	UUID
lifecycle	ObligationLifecycle
name	str
notes	None | str
paid_at	datetime | None
period	ObligationPeriodPublic
updated_at	datetime

ObligationsPublic

Attributes:

Name	Type	Description
count	int
data	list[ObligationPublic]

ObligationComponentPublic

Attributes:

Name	Type	Description
amount	None | str
created_at	datetime
external_id	None | str
id	UUID
label	str
metadata	None | ObligationComponentPublicMetadataType0
obligation_id	UUID
source	None | str
type_	str
updated_at	datetime

ObligationComponentsPublic

Attributes:

Name	Type	Description
count	int
data	list[ObligationComponentPublic]