Invoice API reference · mansoq-core

Declared route and availability

This resource is declared in mansoq-core at /api/v1/facility/{facility_external_id}/invoice/. verified core mount in config/urls.py A registered path and an indexed handler do not prove deployment availability, user permission or production readiness.

Operation map

list · GET

GET /api/v1/facility/{facility_external_id}/invoice/ — action list. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

response: InvoiceReadSpec. Declared fields below; inherited fields are retained in the schema inventory.

Observed authorization checks: can_read_invoice_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read invoice; ValidationError: Account is required when payment reconciliation filter is present.

create · POST

POST /api/v1/facility/{facility_external_id}/invoice/ — action create. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

request: InvoiceWriteSpec. Declared fields below; inherited fields are retained in the schema inventory.

response: InvoiceRetrieveSpec. Declared fields below; inherited fields are retained in the schema inventory.

Observed authorization checks: can_read_invoice_in_facility, can_write_invoice_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read invoice; ValidationError: Account is required when payment reconciliation filter is present; ValidationError: Account is not associated with the facility; PermissionDenied: Cannot write invoice; ValidationError: Invoice charge list contains duplicates; ValidationError: Every requested charge must be billable and belong to the invoice account, patient, and facility; ValidationError: Invoice creation failed; ValidationError: Canonical insurance enrollment may cover this invoice; bind the revenue case and commit its financial decision before drafting; ValidationError: One canonical invoice cannot combine multiple cases or commitments; ValidationError: A canonical invoice already exists for this financial commitment; ValidationError: Canonical invoice must contain the exact committed charge set; ValidationError (dynamic detail; inspect source); ValidationError: Canonical invoice charge has no unique insured revenue-cycle case; ValidationError: Canonical invoice requires matching tenant, patient, member binding and unchanged attested charges; ValidationError: Canonical invoice requires exactly one committed financial decision.

retrieve · GET

GET /api/v1/facility/{facility_external_id}/invoice/{external_id}/ — action retrieve. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

response: InvoiceRetrieveSpec. Declared fields below; inherited fields are retained in the schema inventory.

The declared field table is shown at its first occurrence in this reference; this operation links the same schema.

Observed authorization checks: can_read_invoice_in_facility, can_manage_locked_invoice_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read invoice; ValidationError: Account is required when payment reconciliation filter is present; PermissionDenied: Locked invoice permission denied..

update · PUT

PUT /api/v1/facility/{facility_external_id}/invoice/{external_id}/ — action update. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

request: BaseInvoiceSpec. Declared fields below; inherited fields are retained in the schema inventory.

response: InvoiceRetrieveSpec. Declared fields below; inherited fields are retained in the schema inventory.

The declared field table is shown at its first occurrence in this reference; this operation links the same schema.

Observed authorization checks: can_read_invoice_in_facility, can_write_invoice_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read invoice; ValidationError: Account is required when payment reconciliation filter is present; PermissionDenied: Cannot write invoice; ValidationError (dynamic detail; inspect source); ValidationError: Call the cancel invoice API to cancel the invoice; ValidationError: Invoice is already cancelled; ValidationError: Invoice must have at least one charge item; ValidationError: Invoice is already balanced; ValidationError: Invoice is already issued; ValidationError: Invoice needs to be issued before balancing; ValidationError: Invoice changed while this request was being prepared; reload it before changing its financial state; ValidationError: Invoice contains a missing or duplicate charge; ValidationError: Invoice charge does not belong to its account; ValidationError: Invoice charge list is not exclusively reserved to this invoice; attach billable charges through the draft invoice workflow; ValidationError: Canonical insurance enrollment may cover an invoice charge; bind and adjudicate the member coverage before issuance; ValidationError: Insured revenue-cycle case and invoice tenant or patient disagree; ValidationError: Patient has active insurance coverage but this account has no insured revenue-cycle case with attached coverage; resolve coverage before invoice issuance; ValidationError: Insured invoice charge has no unique revenue-cycle case; ValidationError: Insured invoice requires member coverage; ValidationError: Insured invoice requires an attested performed charge that matches its billing quantity and gross price; ValidationError: Insured invoice requires a current presented estimate; ValidationError: Insured invoice charge does not match its resolved estimate; ValidationError: Canonical insured invoice requires an explicit member binding; ValidationError: Canonical insured invoice requires an unchanged attested charge; ValidationError: Canonical insurance invoice finalization requires a committed pricing, benefit, cost-share and accumulator decision; ValidationError: Invoice charge is absent from the committed financial snapshot; ValidationError: Invoice is not bound to its canonical visit commitment; ValidationError: Invoice financial snapshot differs from the committed canonical allowed price; ValidationError: Canonical insurance invoice requires a finalized tax determination before issuance; ValidationError: Canonical insurance invoice requires its applicable ZATCA document lifecycle before issuance.

partial_update · PATCH

PATCH /api/v1/facility/{facility_external_id}/invoice/{external_id}/ — action partial_update. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

request: BaseInvoiceSpec. Declared fields below; inherited fields are retained in the schema inventory.

The declared field table is shown at its first occurrence in this reference; this operation links the same schema.

response: InvoiceRetrieveSpec. Declared fields below; inherited fields are retained in the schema inventory.

The declared field table is shown at its first occurrence in this reference; this operation links the same schema.

Observed authorization checks: can_read_invoice_in_facility, can_write_invoice_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: PermissionDenied: Cannot read invoice; ValidationError: Account is required when payment reconciliation filter is present; PermissionDenied: Cannot write invoice; ValidationError (dynamic detail; inspect source); ValidationError: Call the cancel invoice API to cancel the invoice; ValidationError: Invoice is already cancelled; ValidationError: Invoice must have at least one charge item; ValidationError: Invoice is already balanced; ValidationError: Invoice is already issued; ValidationError: Invoice needs to be issued before balancing.

attach_items_to_invoice · POST

POST /api/v1/facility/{facility_external_id}/invoice/{external_id}/attach_items_to_invoice/ — action attach_items_to_invoice. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

decorator request: AttachChargeItemToInvoiceRequest. Declared fields below; inherited fields are retained in the schema inventory.

Observed authorization checks: can_read_invoice_in_facility, can_write_invoice_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: ValidationError: Invoice charge list contains duplicates; ValidationError: Every requested charge must be billable and belong to the invoice account, patient, and facility; PermissionDenied: Cannot read invoice; ValidationError: Account is required when payment reconciliation filter is present; PermissionDenied: Cannot write invoice; ValidationError: Invoice is not in draft; ValidationError: A canonical invoice's committed charge set is immutable; create an authorized correction instead.

Direct refusal present: the handler/helper contains a top-level raise. Review whether the operation is intentionally disabled or only performs validation before relying on it.

remove_item_from_invoice · POST

POST /api/v1/facility/{facility_external_id}/invoice/{external_id}/remove_item_from_invoice/ — action remove_item_from_invoice. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

decorator request: RemoveChargeItemFromInvoiceRequest. Declared fields below; inherited fields are retained in the schema inventory.

Observed authorization checks: can_read_invoice_in_facility, can_write_invoice_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: ValidationError: Charge item not found in invoice; PermissionDenied: Cannot read invoice; ValidationError: Account is required when payment reconciliation filter is present; PermissionDenied: Cannot write invoice; ValidationError: Invoice is not in draft; ValidationError: A canonical invoice's committed charge set is immutable; create an authorized correction instead.

Direct refusal present: the handler/helper contains a top-level raise. Review whether the operation is intentionally disabled or only performs validation before relying on it.

attach_account_to_invoice · POST

POST /api/v1/facility/{facility_external_id}/invoice/{external_id}/attach_account_to_invoice/ — action attach_account_to_invoice. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_invoice_in_facility, can_write_invoice_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: ValidationError: Account contains a billable charge for another patient or facility; PermissionDenied: Cannot read invoice; ValidationError: Account is required when payment reconciliation filter is present; PermissionDenied: Cannot write invoice; ValidationError: Invoice is not in draft; ValidationError: A canonical invoice's committed charge set is immutable; create an authorized correction instead.

Direct refusal present: the handler/helper contains a top-level raise. Review whether the operation is intentionally disabled or only performs validation before relying on it.

cancel_invoice · POST

POST /api/v1/facility/{facility_external_id}/invoice/{external_id}/cancel_invoice/ — action cancel_invoice. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_write_invoice_in_facility, can_destroy_invoice_in_facility, can_read_invoice_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: ValidationError: Invoice is already cancelled; ValidationError: An issued invoice cannot be cancelled through the draft workflow; use a legally linked correction/credit document; ValidationError: Invalid reason; PermissionDenied: Cannot cancel invoice; PermissionDenied: Cannot read invoice; ValidationError: Account is required when payment reconciliation filter is present.

lock · POST

POST /api/v1/facility/{facility_external_id}/invoice/{external_id}/lock/ — action lock. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_invoice_in_facility, can_manage_locked_invoice_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: ValidationError: Invoice is already locked; PermissionDenied: Cannot read invoice; ValidationError: Account is required when payment reconciliation filter is present; PermissionDenied: Locked invoice permission denied..

unlock · POST

POST /api/v1/facility/{facility_external_id}/invoice/{external_id}/unlock/ — action unlock. static contract extracted; runtime/permission/payload behavior review pending.

Path and deployment-context parameters:

Directly observed request reads (these do not constitute a complete accepted-payload or requiredness guarantee):

Observed authorization checks: can_read_invoice_in_facility, can_manage_locked_invoice_in_facility. Helper/queryset evidence is included; this is not proof of complete security review.

Declared refusal/error evidence: ValidationError: Invoice is not locked; PermissionDenied: Cannot read invoice; ValidationError: Account is required when payment reconciliation filter is present; PermissionDenied: Locked invoice permission denied..

Integration review checklist

Confirm the installed route and full schema; review authentication, organization/facility scoping, all accepted fields, value-state and date/time semantics, idempotency, pagination, response/exception branches and the allowed correction/reversal workflow. Test positive and negative cases with synthetic data. This source reference does not establish external certification or replace an illustrated user procedure.