{ "openapi": "3.1.0", "info": { "title": "AEGVEN Financial Infrastructure API", "version": "0.1.0", "description": "System-neutral financial obligations, hosted interactions, evidence and reconciliation. Invoice is the first source adapter. Issuers integrate server-to-server; recipients use secure links without accounts or SDKs. No money movement." }, "servers": [ { "url": "https://app.aegven.com/api/v1", "description": "AEGVEN API" } ], "security": [ { "apiKey": [] }, { "issuerSession": [] } ], "paths": { "/invoices": { "post": { "operationId": "post_invoices", "summary": "Create an invoice obligation and secure recipient link", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoice" } } } } }, "get": { "operationId": "get_invoices", "summary": "List tenant invoices", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "limit", "offset" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices/{id}": { "get": { "operationId": "get_invoices_id", "summary": "Get invoice details and audit trail", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDetail" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invoices/{id}/actions": { "post": { "operationId": "post_invoices_id_actions", "summary": "Submit an issuer action with optimistic concurrency", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionInput" } } } } } }, "/invoices/{id}/delivery": { "get": { "operationId": "get_invoices_id_delivery", "summary": "Prepare email text; does not send an email or create a sent event", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryDraft" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recipient/session": { "post": { "operationId": "post_recipient_session", "summary": "Exchange a fragment token for an HttpOnly cookie and record link open", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, { "name": "X-Aegven-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_id": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "invoice_id" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ], "additionalProperties": false } } } }, "security": [] } }, "/recipient/invoice": { "get": { "operationId": "get_recipient_invoice", "summary": "Get the single invoice accessible to this link holder", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDetail" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "recipientSession": [] } ] } }, "/recipient/actions": { "post": { "operationId": "post_recipient_actions", "summary": "Acknowledge, share dates, report payment, or post a message", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, { "name": "X-Aegven-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionInput" } } } }, "security": [ { "recipientSession": [] } ] } }, "/invoices/{id}/documents": { "post": { "operationId": "post_invoices_id_documents", "summary": "Upload bounded supporting evidence", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "expected_version": { "type": "integer" }, "kind": { "type": "string", "enum": [ "invoice", "supporting", "payment_evidence", "bank_observation" ] }, "file": { "type": "string", "format": "binary" } }, "required": [ "expected_version", "file" ], "additionalProperties": false } } } } } }, "/invoices/{id}/documents/{document}": { "get": { "operationId": "get_invoices_id_documents_document", "summary": "Download authorized evidence as an attachment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "document", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recipient/documents": { "post": { "operationId": "post_recipient_documents", "summary": "Upload bounded supporting evidence", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, { "name": "X-Aegven-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "expected_version": { "type": "integer" }, "kind": { "type": "string", "enum": [ "invoice", "supporting", "payment_evidence", "bank_observation" ] }, "file": { "type": "string", "format": "binary" } }, "required": [ "expected_version", "file" ], "additionalProperties": false } } } }, "security": [ { "recipientSession": [] } ] } }, "/recipient/documents/{document}": { "get": { "operationId": "get_recipient_documents_document", "summary": "Download authorized evidence as an attachment", "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "recipientSession": [] } ] } }, "/webhook-endpoints": { "post": { "operationId": "post_webhook_endpoints", "summary": "Register a signed webhook destination for future events", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "minLength": 32, "maxLength": 256 } }, "required": [ "url", "secret" ], "additionalProperties": false } } } } }, "get": { "operationId": "get__webhook-endpoints", "summary": "List endpoint configuration and delivery health", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook-deliveries": { "get": { "operationId": "get_webhook_deliveries", "summary": "List up to 100 recent delivery attempts", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook-deliveries/{id}/retry": { "post": { "operationId": "post_webhook_deliveries_id_retry", "summary": "Requeue a failed delivery with a new explicit retry key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "responses": { "204": { "description": "Success" }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Only failed deliveries can be requeued. Unknown or foreign IDs return 404; non-failed deliveries return 409. Replays of an accepted retry key remain no-ops, including after subsequent retry cycles." } }, "/session": { "post": { "operationId": "post__session", "summary": "Sign in as an individual user", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginInput" } } } }, "security": [] }, "delete": { "operationId": "delete_session", "summary": "Clear the issuer session", "parameters": [], "responses": { "204": { "description": "Success" }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "issuerSession": [] } ] }, "get": { "operationId": "get__session", "summary": "Current individual identity and organization", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "issuerSession": [] } ] } }, "/obligations": { "post": { "operationId": "post_obligations", "summary": "Register an obligation and atomically create its secure hosted payment request", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterObligation" } } } } }, "get": { "operationId": "get_obligations", "summary": "List tenant invoices", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FinancialObligation" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "items", "limit", "offset" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/obligations/{id}": { "get": { "operationId": "get_obligations_id", "summary": "Get invoice details and audit trail", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObligationDetail" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/obligations/{id}/actions": { "post": { "operationId": "post_obligations_id_actions", "summary": "Submit an issuer action with optimistic concurrency", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionInput" } } } } } }, "/obligations/{id}/documents": { "post": { "operationId": "post_obligations_id_documents", "summary": "Upload bounded supporting evidence", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "expected_version": { "type": "integer" }, "kind": { "type": "string", "enum": [ "invoice", "supporting", "payment_evidence", "bank_observation" ] }, "file": { "type": "string", "format": "binary" } }, "required": [ "expected_version", "file" ], "additionalProperties": false } } } } } }, "/obligations/{id}/documents/{document}": { "get": { "operationId": "get_obligations_id_documents_document", "summary": "Download authorized evidence as an attachment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "document", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/obligations/{id}/payment-request": { "get": { "operationId": "get_obligations_id_payment_request", "summary": "Retrieve the active hosted request; rejects revoked or expired access", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recipient/contexts/{request}/session": { "post": { "operationId": "post_recipient_request_session", "summary": "Exchange a fragment token for an HttpOnly cookie and record link open", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, { "name": "X-Aegven-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "request", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_id": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "invoice_id" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ], "additionalProperties": false } } } }, "security": [] } }, "/recipient/contexts/{request}/invoice": { "get": { "operationId": "get_recipient_request_invoice", "summary": "Get the single invoice accessible to this link holder", "parameters": [ { "name": "request", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDetail" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "recipientSession": [] } ] } }, "/recipient/contexts/{request}/actions": { "post": { "operationId": "post_recipient_request_actions", "summary": "Acknowledge, share dates, report payment, or post a message", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, { "name": "X-Aegven-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "request", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionInput" } } } }, "security": [ { "recipientSession": [] } ] } }, "/recipient/contexts/{request}/documents": { "post": { "operationId": "post_recipient_request_documents", "summary": "Upload bounded supporting evidence", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, { "name": "X-Aegven-Request", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "request", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "expected_version": { "type": "integer" }, "kind": { "type": "string", "enum": [ "invoice", "supporting", "payment_evidence", "bank_observation" ] }, "file": { "type": "string", "format": "binary" } }, "required": [ "expected_version", "file" ], "additionalProperties": false } } } }, "security": [ { "recipientSession": [] } ] } }, "/recipient/contexts/{request}/documents/{document}": { "get": { "operationId": "get_recipient_request_documents_document", "summary": "Download authorized evidence as an attachment", "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "request", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "recipientSession": [] } ] } }, "/session/password": { "post": { "operationId": "post__session_password", "summary": "Change password and invalidate all user sessions", "responses": { "204": { "description": "Password changed; all sessions revoked" }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current_password": { "type": "string" }, "password": { "type": "string" } }, "required": [ "current_password", "password" ], "additionalProperties": false } } } }, "security": [ { "issuerSession": [] } ] } }, "/invitations/accept": { "post": { "operationId": "post__invitations_accept", "summary": "Accept controlled invitation; existing users must supply their current password", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationAccepted" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" }, "token": { "type": "string" } }, "required": [ "email", "password", "token" ], "additionalProperties": false } } } }, "security": [] } }, "/api-keys": { "get": { "operationId": "get__api-keys", "summary": "List credential metadata; never secrets", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/APIKey" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "issuerSession": [] } ] }, "post": { "operationId": "post__api-keys", "summary": "Create credential; secret appears only in first successful response", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInput" } } } }, "security": [ { "issuerSession": [] } ] } }, "/api-keys/{id}/rotate": { "post": { "operationId": "post__api-keys_id_rotate", "summary": "Credential rotate; rotation preserves old credential until explicitly revoked", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInput" } } } }, "security": [ { "issuerSession": [] } ] } }, "/api-keys/{id}/revoke": { "post": { "operationId": "post__api-keys_id_revoke", "summary": "Credential revoke; rotation preserves old credential until explicitly revoked", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInput" } } } }, "security": [ { "issuerSession": [] } ] } }, "/organization/members": { "get": { "operationId": "get__organization_members", "summary": "List organization members", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "issuerSession": [] } ] } }, "/organization/members/{id}": { "post": { "operationId": "post__organization_members_id", "summary": "Administrator changes role or disables member; invalidates sessions", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInput" } } } }, "security": [ { "issuerSession": [] } ] } }, "/organization/invitations": { "post": { "operationId": "post__organization_invitations", "summary": "Administrator creates a 48-hour invitation; token shown once", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInput" } } } }, "security": [ { "issuerSession": [] } ] }, "get": { "operationId": "get__organization_invitations", "summary": "Administrator inspects the latest 100 Invitation records without credentials", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "issuerSession": [] } ] } }, "/webhook-endpoints/{id}": { "post": { "operationId": "post__webhook-endpoints_id", "summary": "Update endpoint URL and enabled state", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" } } } } } }, "/webhook-endpoints/{id}/rotate": { "post": { "operationId": "post__webhook-endpoints_id_rotate", "summary": "Rotate signing secret", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } } } }, "/webhook-endpoints/{id}/test": { "post": { "operationId": "post__webhook-endpoints_id_test", "summary": "Queue a non-financial test event through transactional outbox", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } } } }, "/organization/readiness": { "get": { "operationId": "get__organization_readiness", "summary": "Manual and API setup readiness", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/overview": { "get": { "operationId": "get__overview", "summary": "Organization operational counts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Overview" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/activity/interactions": { "get": { "operationId": "get__activity_interactions", "summary": "Read accepted interactions facts with exact obligation correlation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityRecord" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer" } } ] } }, "/activity/observations": { "get": { "operationId": "get__activity_observations", "summary": "Read accepted observations facts with exact obligation correlation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityRecord" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer" } } ] } }, "/activity/exceptions": { "get": { "operationId": "get__activity_exceptions", "summary": "Read accepted exceptions facts with exact obligation correlation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityRecord" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer" } } ] } }, "/activity/reconciliation": { "get": { "operationId": "get__activity_reconciliation", "summary": "Read accepted reconciliation facts with exact obligation correlation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityRecord" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer" } } ] } }, "/activity/documents": { "get": { "operationId": "get__activity_documents", "summary": "Read accepted documents facts with exact obligation correlation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityRecord" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer" } } ] } }, "/operations/{id}": { "get": { "operationId": "get__operations_id", "summary": "Lookup accepted issuer operation without secret replay", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/operations": { "get": { "operationId": "get__operations", "summary": "Investigate uncertain result by original idempotency key", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "idempotency_key", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/exports/obligations.csv": { "get": { "operationId": "get__exports_obligations_csv", "summary": "Accepted obligation results v1, up to 10000 rows; spreadsheet formula cells escaped", "responses": { "200": { "description": "CSV v1 accepted results", "content": { "text/csv": { "schema": { "type": "string" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/imports/obligations/preview": { "post": { "operationId": "import_obligations_preview", "summary": "CSV v1 preview through complete canonical decisions; at most 50 rows; atomic acceptance", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "text/csv": { "schema": { "type": "string", "maxLength": 524288 } } } }, "responses": { "200": { "description": "Per-row validation or atomic acceptance result. accepted=false means no rows were committed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/imports/obligations/accept": { "post": { "operationId": "import_obligations_accept", "summary": "CSV v1 accept through complete canonical decisions; at most 50 rows; atomic acceptance", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "text/csv": { "schema": { "type": "string", "maxLength": 524288 } } } }, "responses": { "200": { "description": "Per-row validation or atomic acceptance result. accepted=false means no rows were committed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organization/audit": { "get": { "operationId": "get__organization_audit", "summary": "Administrator inspects the latest 100 AccessAudit records without credentials", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AccessAudit" } } }, "required": [ "items" ], "additionalProperties": false } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "issuerSession": [] } ] } }, "/organization/invitations/{id}/revoke": { "post": { "operationId": "post__organization_invitations_id_revoke", "summary": "Administrator revokes an unaccepted invitation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResult" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessInput" } } } }, "security": [ { "issuerSession": [] } ] } }, "/password-recoveries/accept": { "post": { "operationId": "post__password_recoveries_accept", "summary": "Consume an operator-issued 30-minute recovery link and invalidate all user sessions", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationAccepted" } } } }, "default": { "description": "Stable API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "password": { "type": "string", "minLength": 15, "maxLength": 128 } }, "required": [ "token", "password" ], "additionalProperties": false } } } }, "security": [] } }, "/organization/profile": { "get": { "operationId": "getOrganizationProfile", "summary": "getOrganizationProfile", "description": "", "security": [ { "issuerSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationProfile" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Not authorized or organization access blocked" }, "409": { "description": "Idempotency or version conflict" }, "500": { "description": "Operation unavailable" } } }, "post": { "operationId": "updateOrganizationProfile", "summary": "updateOrganizationProfile", "description": "", "security": [ { "issuerSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResult" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Not authorized or organization access blocked" }, "409": { "description": "Idempotency or version conflict" }, "500": { "description": "Operation unavailable" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationProfileChange" } } } } } }, "/organization/logo": { "delete": { "operationId": "removeOrganizationLogo", "summary": "removeOrganizationLogo", "description": "", "security": [ { "issuerSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResult" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Not authorized or organization access blocked" }, "409": { "description": "Idempotency or version conflict" }, "500": { "description": "Operation unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationLogoRemove" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ] }, "post": { "operationId": "uploadOrganizationLogo", "summary": "uploadOrganizationLogo", "description": "", "security": [ { "issuerSession": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessResult" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Not authorized or organization access blocked" }, "409": { "description": "Idempotency or version conflict" }, "500": { "description": "Operation unavailable" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "expected_version": { "type": "integer" } }, "required": [ "file", "expected_version" ], "additionalProperties": false } } } } } }, "/organization/logo/{id}": { "get": { "operationId": "downloadOrganizationLogo", "summary": "downloadOrganizationLogo", "description": "", "security": [ { "issuerSession": [] } ], "responses": { "200": { "description": "Success", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Not authorized or organization access blocked" }, "409": { "description": "Idempotency or version conflict" }, "500": { "description": "Operation unavailable" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/recipient/contexts/{request}/logo": { "get": { "operationId": "recipientOrganizationLogo", "summary": "recipientOrganizationLogo", "description": "", "security": [ { "recipientSession": [] } ], "responses": { "200": { "description": "Success", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Not authorized or organization access blocked" }, "409": { "description": "Idempotency or version conflict" }, "500": { "description": "Operation unavailable" } }, "parameters": [ { "name": "request", "in": "path", "required": true, "schema": { "type": "string" } } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer" }, "issuerSession": { "type": "apiKey", "in": "cookie", "name": "aegven_session", "description": "Individual user session with active organization membership. API keys cannot create this cookie." }, "recipientSession": { "type": "apiKey", "in": "cookie", "name": "aegven_recipient" } }, "schemas": { "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "issuer_name": { "type": "string" }, "reference": { "type": "string" }, "external_namespace": { "type": "string" }, "external_id": { "type": "string" }, "invoice_number": { "type": "string" }, "recipient_name": { "type": "string" }, "recipient_email": { "type": "string" }, "description": { "type": "string" }, "amount_minor": { "type": "string" }, "allocated_minor": { "type": "string" }, "currency": { "type": "string" }, "due_date": { "type": "string" }, "expected_payment_date": { "type": "string" }, "reported_payment_date": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "link_expires_at": { "type": "string" }, "status": { "type": "string", "enum": [ "OBLIGATION_CAPTURED", "PAYMENT_REQUESTED", "PAYMENT_CLAIMED", "PARTIALLY_RECONCILED", "RECONCILED" ] }, "version": { "type": "integer", "minimum": 1 }, "acknowledged": { "type": "boolean" }, "link_revoked": { "type": "boolean" } }, "required": [ "id", "organization_id", "issuer_name", "reference", "external_namespace", "external_id", "invoice_number", "recipient_name", "recipient_email", "description", "amount_minor", "allocated_minor", "currency", "due_date", "expected_payment_date", "reported_payment_date", "created_at", "updated_at", "link_expires_at", "status", "version", "acknowledged", "link_revoked" ], "additionalProperties": false }, "CreateInvoice": { "type": "object", "properties": { "external_namespace": { "type": "string" }, "external_id": { "type": "string" }, "invoice_number": { "type": "string" }, "recipient_name": { "type": "string" }, "recipient_email": { "type": "string" }, "description": { "type": "string" }, "amount_minor": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Positive integer minor units; never a floating-point number." }, "currency": { "type": "string", "enum": [ "CAD", "USD", "EUR", "GBP", "JPY", "AUD", "CHF" ] }, "due_date": { "type": "string" } }, "required": [ "external_namespace", "external_id", "invoice_number", "recipient_name", "recipient_email", "amount_minor", "currency", "due_date" ], "additionalProperties": false }, "InvoiceEvent": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "type": { "type": "string" }, "actor": { "type": "string", "enum": [ "issuer", "recipient" ] }, "occurred_at": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "id", "version", "type", "actor", "occurred_at", "data" ], "additionalProperties": false }, "Document": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "media_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "sha256": { "type": "string" }, "uploaded_by": { "type": "string", "enum": [ "issuer", "recipient" ] }, "kind": { "type": "string", "enum": [ "invoice", "supporting", "payment_evidence", "bank_observation" ] }, "created_at": { "type": "string" } }, "required": [ "id", "filename", "media_type", "size_bytes", "sha256", "uploaded_by", "kind", "created_at" ], "additionalProperties": false }, "Observation": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "external_id": { "type": "string" }, "reference": { "type": "string" }, "amount_minor": { "type": "string" }, "currency": { "type": "string" }, "date": { "type": "string" }, "evidence_id": { "type": "string" }, "match_status": { "type": "string", "enum": [ "EXACT_REFERENCE", "REVIEW_REQUIRED" ] }, "accepted": { "type": "boolean" } }, "required": [ "id", "source", "external_id", "reference", "amount_minor", "currency", "date", "evidence_id", "match_status", "accepted" ], "additionalProperties": false }, "MutationResult": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" }, "operation_id": { "type": "string" }, "event_type": { "type": "string" }, "tracking_url": { "type": "string" }, "document_id": { "type": "string" }, "observation_id": { "type": "string" }, "obligation": { "$ref": "#/components/schemas/FinancialObligation", "description": "Canonical projection on new operations. Legacy persisted replays may omit it." }, "payment_request": { "$ref": "#/components/schemas/PaymentRequest" } }, "required": [ "invoice", "operation_id", "event_type" ], "additionalProperties": false }, "DeliveryDraft": { "type": "object", "properties": { "to": { "type": "string" }, "subject": { "type": "string" }, "text": { "type": "string" }, "tracking_url": { "type": "string" }, "expires_at": { "type": "string" }, "delivery_status": { "type": "string" } }, "required": [ "to", "subject", "text", "tracking_url", "expires_at", "delivery_status" ], "additionalProperties": false }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "invoice_id": { "type": [ "string", "null" ] }, "event_id": { "type": "string" }, "type": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivering", "delivered", "failed" ] }, "attempts": { "type": "integer" }, "last_status": { "type": [ "integer", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "endpoint_id": { "type": "string" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookAttempt" } } }, "required": [ "id", "invoice_id", "event_id", "type", "url", "status", "attempts", "last_status", "delivered_at", "endpoint_id", "history" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "InvoiceDetail": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "issuer_name": { "type": "string" }, "reference": { "type": "string" }, "external_namespace": { "type": "string" }, "external_id": { "type": "string" }, "invoice_number": { "type": "string" }, "recipient_name": { "type": "string" }, "recipient_email": { "type": "string" }, "description": { "type": "string" }, "amount_minor": { "type": "string" }, "allocated_minor": { "type": "string" }, "currency": { "type": "string" }, "due_date": { "type": "string" }, "expected_payment_date": { "type": "string" }, "reported_payment_date": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "link_expires_at": { "type": "string" }, "status": { "type": "string", "enum": [ "OBLIGATION_CAPTURED", "PAYMENT_REQUESTED", "PAYMENT_CLAIMED", "PARTIALLY_RECONCILED", "RECONCILED" ] }, "version": { "type": "integer", "minimum": 1 }, "acknowledged": { "type": "boolean" }, "link_revoked": { "type": "boolean" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceEvent" } }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "observations": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentClaim" } }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/Allocation" } }, "remaining_minor": { "type": "string", "description": "Exact remaining balance projected by the Rust financial core from this accepted snapshot." } }, "required": [ "id", "organization_id", "issuer_name", "reference", "external_namespace", "external_id", "invoice_number", "recipient_name", "recipient_email", "description", "amount_minor", "allocated_minor", "currency", "due_date", "expected_payment_date", "reported_payment_date", "created_at", "updated_at", "link_expires_at", "status", "version", "acknowledged", "link_revoked", "events", "documents", "observations", "claims", "allocations", "remaining_minor" ], "additionalProperties": false }, "ActionInput": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "sent" ] }, "expected_version": { "type": "integer", "minimum": 1 }, "payload": { "type": "object", "properties": { "delivery_reference": { "type": "string" } }, "required": [], "additionalProperties": false } }, "required": [ "action", "expected_version", "payload" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "acknowledge" ] }, "expected_version": { "type": "integer", "minimum": 1 }, "payload": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } }, "required": [ "action", "expected_version", "payload" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "expected_payment" ] }, "expected_version": { "type": "integer", "minimum": 1 }, "payload": { "type": "object", "properties": { "date": { "type": "string", "format": "date" } }, "required": [ "date" ], "additionalProperties": false } }, "required": [ "action", "expected_version", "payload" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "report_payment" ] }, "expected_version": { "type": "integer", "minimum": 1 }, "payload": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "amount_minor": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Positive integer minor units; never a floating-point number." }, "currency": { "type": "string" }, "note": { "type": "string" } }, "required": [ "date", "amount_minor", "currency" ], "additionalProperties": false } }, "required": [ "action", "expected_version", "payload" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "message" ] }, "expected_version": { "type": "integer", "minimum": 1 }, "payload": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "body" ], "additionalProperties": false } }, "required": [ "action", "expected_version", "payload" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "revoke_link" ] }, "expected_version": { "type": "integer", "minimum": 1 }, "payload": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } }, "required": [ "action", "expected_version", "payload" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "observation" ] }, "expected_version": { "type": "integer", "minimum": 1 }, "payload": { "type": "object", "properties": { "source": { "type": "string" }, "external_id": { "type": "string" }, "reference": { "type": "string" }, "amount_minor": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Positive integer minor units; never a floating-point number." }, "currency": { "type": "string" }, "date": { "type": "string" }, "evidence_id": { "type": "string" } }, "required": [ "source", "external_id", "reference", "amount_minor", "currency", "date", "evidence_id" ], "additionalProperties": false } }, "required": [ "action", "expected_version", "payload" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "accept_observation" ] }, "expected_version": { "type": "integer", "minimum": 1 }, "payload": { "type": "object", "properties": { "observation_id": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "observation_id", "reason" ], "additionalProperties": false } }, "required": [ "action", "expected_version", "payload" ], "additionalProperties": false } ] }, "ExternalReference": { "type": "object", "properties": { "namespace": { "type": "string" }, "id": { "type": "string" } }, "required": [ "namespace", "id" ], "additionalProperties": false }, "Party": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false }, "BusinessContext": { "type": "object", "properties": { "invoice_number": { "type": "string" }, "description": { "type": "string" } }, "required": [ "invoice_number" ], "additionalProperties": false }, "RegisterObligation": { "type": "object", "properties": { "obligation_type": { "type": "string", "enum": [ "invoice" ] }, "external_reference": { "$ref": "#/components/schemas/ExternalReference" }, "debtor": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "name", "email" ], "additionalProperties": false }, "amount_minor": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Positive integer minor units; never a floating-point number." }, "currency": { "type": "string", "enum": [ "CAD", "USD", "EUR", "GBP", "JPY", "AUD", "CHF" ] }, "deadline": { "type": "string", "format": "date" }, "business_context": { "$ref": "#/components/schemas/BusinessContext" } }, "required": [ "obligation_type", "external_reference", "debtor", "amount_minor", "currency", "deadline", "business_context" ], "additionalProperties": false }, "FinancialObligation": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "amount_minor": { "type": "string" }, "allocated_minor": { "type": "string" }, "currency": { "type": "string" }, "expected_payment_date": { "type": "string" }, "reported_payment_date": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "status": { "type": "string", "enum": [ "OBLIGATION_CAPTURED", "PAYMENT_REQUESTED", "PAYMENT_CLAIMED", "PARTIALLY_RECONCILED", "RECONCILED" ] }, "version": { "type": "integer", "minimum": 1 }, "acknowledged": { "type": "boolean" }, "obligation_type": { "type": "string", "enum": [ "invoice" ] }, "external_reference": { "$ref": "#/components/schemas/ExternalReference" }, "debtor": { "$ref": "#/components/schemas/Party" }, "deadline": { "type": "string", "format": "date" }, "business_context": { "$ref": "#/components/schemas/BusinessContext" }, "creditor": { "$ref": "#/components/schemas/Party" }, "reference": { "type": "string", "description": "Unique obligation correlation reference. Optional only for historical idempotent registration responses." } }, "required": [ "id", "organization_id", "amount_minor", "allocated_minor", "currency", "expected_payment_date", "reported_payment_date", "created_at", "updated_at", "status", "version", "acknowledged", "obligation_type", "external_reference", "debtor", "deadline", "business_context", "creditor" ], "additionalProperties": false }, "ObligationDetail": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "amount_minor": { "type": "string" }, "allocated_minor": { "type": "string" }, "currency": { "type": "string" }, "expected_payment_date": { "type": "string" }, "reported_payment_date": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "status": { "type": "string", "enum": [ "OBLIGATION_CAPTURED", "PAYMENT_REQUESTED", "PAYMENT_CLAIMED", "PARTIALLY_RECONCILED", "RECONCILED" ] }, "version": { "type": "integer", "minimum": 1 }, "acknowledged": { "type": "boolean" }, "obligation_type": { "type": "string", "enum": [ "invoice" ] }, "external_reference": { "$ref": "#/components/schemas/ExternalReference" }, "debtor": { "$ref": "#/components/schemas/Party" }, "deadline": { "type": "string", "format": "date" }, "business_context": { "$ref": "#/components/schemas/BusinessContext" }, "creditor": { "$ref": "#/components/schemas/Party" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceEvent" } }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "observations": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentClaim" } }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/Allocation" } }, "remaining_minor": { "type": "string", "description": "Exact remaining balance projected by the Rust financial core from this accepted snapshot." }, "reference": { "type": "string", "description": "Unique obligation correlation reference. Optional only for historical idempotent registration responses." } }, "required": [ "id", "organization_id", "amount_minor", "allocated_minor", "currency", "expected_payment_date", "reported_payment_date", "created_at", "updated_at", "status", "version", "acknowledged", "obligation_type", "external_reference", "debtor", "deadline", "business_context", "creditor", "events", "documents", "observations", "claims", "allocations", "remaining_minor" ], "additionalProperties": false }, "PaymentRequest": { "type": "object", "properties": { "id": { "type": "string" }, "obligation_id": { "type": "string" }, "hosted_url": { "type": "string", "description": "Bearer capability URL for an unregistered recipient; insert into your outgoing message. Do not log." }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "obligation_id", "hosted_url", "expires_at" ], "additionalProperties": false }, "ObligationEvent": { "type": "object", "properties": { "schema_version": { "type": "string" }, "id": { "type": "string" }, "type": { "type": "string", "description": "v1 invoice.* event names retained for compatibility; resource identity is financial_obligation." }, "resource_type": { "type": "string", "enum": [ "financial_obligation" ] }, "resource_id": { "type": "string" }, "obligation": { "$ref": "#/components/schemas/FinancialObligation" }, "invoice": { "$ref": "#/components/schemas/Invoice" }, "occurred_at": { "type": "string" }, "operation_id": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "schema_version", "id", "type", "resource_type", "resource_id", "obligation", "invoice", "occurred_at", "operation_id", "data" ], "additionalProperties": false }, "Session": { "type": "object", "properties": { "organization_id": { "type": "string" }, "organization_name": { "type": "string" }, "user_id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "administrator", "developer", "reviewer" ] } }, "required": [ "organization_id", "organization_name", "user_id", "email", "role" ], "additionalProperties": false }, "LoginInput": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string", "minLength": 15, "maxLength": 128 }, "organization_id": { "type": "string" } }, "required": [ "email", "password" ], "additionalProperties": false }, "AccessInput": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "administrator", "developer", "reviewer" ] }, "disabled": { "type": "boolean" } }, "required": [], "additionalProperties": false }, "AccessResult": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" }, "invitation_token": { "type": "string" }, "email": { "type": "string" }, "replaces_id": { "type": "string" }, "delivery_id": { "type": "string" }, "operation_id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "APIKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "created_at": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "replaces_id": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "description", "created_at", "last_used_at", "revoked_at", "replaces_id" ], "additionalProperties": false }, "Member": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "administrator", "developer", "reviewer" ] }, "disabled_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "name": { "type": "string" }, "last_login_at": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "role", "disabled_at", "created_at" ], "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "enabled": { "type": "boolean" }, "created_at": { "type": "string" }, "test_successful": { "type": "boolean" }, "failed_deliveries": { "type": "integer" } }, "required": [ "id", "url", "enabled", "created_at", "test_successful", "failed_deliveries" ], "additionalProperties": false }, "WebhookConfig": { "type": "object", "properties": { "url": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "url", "enabled" ], "additionalProperties": false }, "WebhookAttempt": { "type": "object", "properties": { "attempt": { "type": "integer" }, "http_status": { "type": "integer" }, "status": { "type": "string" }, "occurred_at": { "type": "string" } }, "required": [ "attempt", "http_status", "status", "occurred_at" ], "additionalProperties": false }, "Readiness": { "type": "object", "properties": { "organization_configured": { "type": "boolean" }, "administrator_configured": { "type": "boolean" }, "hosted_workflow_available": { "type": "boolean" }, "api_credential": { "type": "boolean" }, "webhook_endpoint": { "type": "boolean" }, "webhook_test_successful": { "type": "boolean" }, "documentation_available": { "type": "boolean" } }, "required": [ "organization_configured", "administrator_configured", "hosted_workflow_available", "api_credential", "webhook_endpoint", "webhook_test_successful", "documentation_available" ], "additionalProperties": false }, "Overview": { "type": "object", "properties": { "open_obligations": { "type": "integer" }, "unverified_claims": { "type": "integer" }, "partially_reconciled": { "type": "integer" }, "observations_under_review": { "type": "integer" }, "unmatched_observations": { "type": "integer" }, "webhook_failures": { "type": "integer" } }, "required": [ "open_obligations", "unverified_claims", "partially_reconciled", "observations_under_review", "unmatched_observations", "webhook_failures" ], "additionalProperties": false }, "ActivityRecord": { "type": "object", "properties": { "id": { "type": "string" }, "obligation_id": { "type": "string" }, "reference": { "type": "string" }, "namespace": { "type": "string" }, "external_id": { "type": "string" }, "type": { "type": "string" }, "occurred_at": { "type": "string" }, "actor": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "id", "obligation_id", "reference", "namespace", "external_id", "type", "occurred_at", "data" ], "additionalProperties": false }, "Operation": { "type": "object", "properties": { "id": { "type": "string" }, "obligation_id": { "type": "string" }, "scope": { "type": "string" }, "idempotency_key": { "type": "string" }, "created_at": { "type": "string" }, "status": { "const": "accepted" }, "actor_user_id": { "type": [ "string", "null" ] }, "category": { "type": "string", "enum": [ "financial", "access" ] }, "resource_id": { "type": "string" } }, "required": [ "id", "obligation_id", "scope", "idempotency_key", "created_at", "status", "actor_user_id" ], "additionalProperties": false }, "ImportRow": { "type": "object", "required": [ "row", "status" ], "properties": { "row": { "type": "integer" }, "status": { "type": "string", "enum": [ "valid", "error", "not_accepted", "accepted" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "obligation_id": { "type": "string" } } }, "ImportResult": { "type": "object", "required": [ "profile", "accepted", "rows" ], "properties": { "profile": { "type": "string" }, "accepted": { "type": "boolean" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ImportRow" } } } }, "InvitationAccepted": { "type": "object", "required": [ "organization_id" ], "properties": { "organization_id": { "type": "string" } } }, "IntegrationTestEvent": { "type": "object", "description": "Connectivity test delivered through the signed transactional outbox. It has no financial obligation or settlement meaning.", "properties": { "schema_version": { "type": "string" }, "id": { "type": "string" }, "type": { "type": "string", "const": "integration.test" }, "occurred_at": { "type": "string", "format": "date-time" }, "resource_type": { "type": "string", "const": "webhook_endpoint" }, "resource_id": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "schema_version", "id", "type", "occurred_at", "resource_type", "resource_id", "data" ], "additionalProperties": false }, "PaymentClaim": { "type": "object", "properties": { "id": { "type": "string" }, "payment_date": { "type": "string" }, "amount_minor": { "type": "string" }, "currency": { "type": "string" }, "created_at": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "id", "payment_date", "amount_minor", "currency", "created_at", "details" ], "additionalProperties": false }, "Allocation": { "type": "object", "properties": { "id": { "type": "string" }, "observation_id": { "type": "string" }, "amount_minor": { "type": "string" }, "currency": { "type": "string" }, "reason": { "type": "string" }, "evidence_id": { "type": "string" }, "source": { "type": "string" }, "accepted_at": { "type": "string" } }, "required": [ "id", "observation_id", "amount_minor", "currency", "reason", "evidence_id", "source", "accepted_at" ], "additionalProperties": false }, "Invitation": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "expired", "accepted", "revoked" ] } }, "required": [ "id", "email", "role", "created_at", "expires_at", "status" ], "additionalProperties": false }, "AccessAudit": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string" }, "resource_id": { "type": "string" }, "occurred_at": { "type": "string" }, "user_id": { "type": [ "string", "null" ] } }, "required": [ "id", "action", "resource_id", "occurred_at", "user_id" ], "additionalProperties": false }, "OrganizationProfile": { "type": "object", "properties": { "organization_id": { "type": "string" }, "name": { "type": "string" }, "logo_id": { "type": [ "string", "null" ] }, "version": { "type": "integer" } }, "required": [ "organization_id", "name", "logo_id", "version" ], "additionalProperties": false }, "OrganizationProfileChange": { "type": "object", "properties": { "name": { "type": "string" }, "expected_version": { "type": "integer" } }, "required": [ "name", "expected_version" ], "additionalProperties": false }, "OrganizationLogoRemove": { "type": "object", "properties": { "expected_version": { "type": "integer" } }, "required": [ "expected_version" ], "additionalProperties": false } } } }