{ "openapi": "3.1.0", "info": { "title": "TradeVow Connect API", "version": "1.0.0", "description": "TradeVow Connect API for authorised access to transaction, evidence and related trade information. The institutional-review endpoint presents the reviewed transaction context, readiness position, outstanding conditions and review history.", "license": { "name": "Proprietary — controlled TradeVow partner use", "url": "https://connect.tradevow.com/access/terms" } }, "servers": [ { "url": "https://connect.tradevow.com/api", "description": "TradeVow Connect protected API transport" } ], "tags": [ { "name": "C. Transaction APIs", "description": "Transaction context and decision-support records available to an authorised institution." } ], "paths": { "/v1/transactions/{transaction_id}/institutional-review": { "get": { "operationId": "getInstitutionalTransactionReview", "tags": [ "C. Transaction APIs" ], "summary": "Retrieve an authorised institutional transaction review", "description": "Returns the current transaction state, earlier reviews, readiness signals, conditions, source versions and integrity metadata. Evidence files require separate permission. The example response represents the controlled demonstration; access requires an approved API key, transactions:read permission and authorisation for the requested transaction.", "security": [ { "TradeVowApiKey": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^TV-TXN-[A-Z0-9-]{8,64}$" }, "example": "TV-TXN-20260921-8A17367F" }, { "name": "case_snapshot_fingerprint", "in": "query", "required": false, "description": "Optional SHA-256 identifier used to pin or verify the exact reviewed case snapshot. This is not a file hash.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "example": "1ea854f0a2c308b959042f21df537f6e2abaf65b5a5f980dd6ce59458db754f9" } ], "responses": { "200": { "description": "Institutional transaction review response", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current key and operation window." }, "X-RateLimit-Window": { "schema": { "type": "integer" }, "description": "Window length in seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstitutionalReviewResponse" }, "example": { "data": { "type": "institutional_review", "id": "TV-TXN-20260921-8A17367F", "attributes": { "transaction": { "reference": "TV-TXN-20260921-8A17367F", "version": 2, "status": "trade_agreed", "corridor": { "origin_country": "GB", "origin_name": "United Kingdom", "destination_country": "TN", "destination_name": "Tunisia", "route": "Southampton to Tunis" }, "goods_description": "Packaging machine; Spare parts kit", "commercial_value": { "amount": "40000.00", "currency": "GBP" }, "expected_completion_date": "2026-12-01" }, "participants": [ { "role": "applicant", "name": "Factor Inc", "country": "Tunisia", "kyb_status": "phase_1_evidence_review_complete", "classification": "current", "limitation": "External registry, sanctions, PEP, adverse-media and bank checks are outside this synthetic demonstration." }, { "role": "beneficiary", "name": "Seller Inc", "country": "United Kingdom", "kyb_status": "phase_1_evidence_review_complete", "classification": "current", "limitation": "External registry, sanctions, PEP, adverse-media and bank checks are outside this synthetic demonstration." } ], "commercial_source": { "type": "purchase_order", "reference": "TV-PO-YJTTZB6X", "version": 4, "underlying_status": "draft", "transaction_use": "confirmed_for_sourcing", "supplier_acceptance_asserted": false, "classification": "current" }, "evidence": { "accepted_record_count": 9, "status": "reviewed_for_phase_1", "classification": "current", "records": [ { "reference": "EBRD-F-CONTRACT-001", "version": 1, "type": "sales_contract", "status": "reviewed_and_accepted" }, { "reference": "EBRD-F-SPEC-001", "version": 1, "type": "quotation_and_specification", "status": "reviewed_and_accepted" }, { "reference": "EBRD-F-PFI-001-v2", "version": 2, "type": "pro_forma_invoice", "status": "reviewed_and_accepted" }, { "reference": "EBRD-G-LOG-001", "version": 1, "type": "planned_logistics_preparation", "status": "reviewed_and_accepted" }, { "reference": "TV-PO-YJTTZB6X", "version": 4, "type": "purchase_order", "status": "reviewed_and_accepted" }, { "reference": "TV-eBL-DPUCLYD5", "version": 2, "type": "electronic_bill_of_lading", "status": "reviewed_and_accepted" }, { "reference": "TV-CUS-DEC-4GDC2559", "version": 7, "type": "customs_declaration_preparation", "status": "reviewed_and_accepted" }, { "reference": "TV-RULES-20260925-8N0D54", "version": 18, "type": "provisional_rules_assessment", "status": "reviewed_and_accepted" }, { "reference": "TV-COMP-20260925-ETIORI", "version": 10, "type": "provisional_compliance_assessment", "status": "reviewed_and_accepted" } ], "retrieval": { "access": "separate_authorisation_required", "note": "This response exposes metadata and lineage only. Evidence bytes require the existing controlled access and audit decision." } }, "actions_and_conditions": { "open_actions": [ { "reference": "ACT-20260922-DB7D170D", "title": "Retain official customs release after filing", "status": "open", "owner": "Factor Inc", "due_at": "2026-12-15T00:00:00Z", "classification": "open_action", "readiness_effect": "disclosed_future_stage_condition" } ], "completed_remediation": [ { "reference": "ACT-20260921-0F80BD8B", "status": "resolved" }, { "reference": "ACT-20260921-119FC0F0", "status": "resolved" }, { "reference": "ACT-20260923-A197267F", "status": "resolved" }, { "reference": "ACT-20260924-32B367D0", "status": "resolved" }, { "reference": "ACT-20260925-0E4148DB", "status": "resolved" } ], "future_stage_conditions": [ { "code": "bank_terms_confirmation", "description": "All LC terms and presentation requirements await bank confirmation.", "classification": "future_stage_condition" }, { "code": "post_review_execution", "description": "Shipment, customs clearance, formal bank application, credit approval, LC issuance and settlement are future stages.", "classification": "future_stage_condition" } ] }, "event_and_remediation_history": { "classification": "retained_history", "summary": "Earlier evidence gaps and attestation corrections remain retained as resolved actions; one future customs-release action remains open.", "completed_count": 5, "open_count": 1 }, "logistics": { "status": "prepared_for_phase_1", "planned_route": "Southampton to Tunis", "planned_shipment_date": "2026-10-05", "electronic_bill_of_lading": { "reference": "TV-eBL-DPUCLYD5", "version": 2, "status": "reviewed_and_accepted" }, "shipment_execution": "not_started", "classification": "current" }, "customs": { "reference": "TV-CUS-DEC-4GDC2559", "version": 7, "status": "preparation_reviewed_for_phase_1", "filing_or_clearance": "not_asserted", "classification": "current" }, "rules_and_compliance": { "rules": { "reference": "TV-RULES-20260925-8N0D54", "version": 18, "status": "provisional_assessment_reviewed" }, "compliance": { "reference": "TV-COMP-20260925-ETIORI", "version": 10, "status": "provisional_assessment_reviewed" }, "decision_boundary": "Independent institutional and qualified compliance review remains required.", "classification": "current" }, "lc_request": { "reference": "LC-REQ-20260922-0972A23E", "version": 11, "status": "prepared_for_controlled_initial_bank_review", "requested_finance": { "amount": "30000.00", "currency": "GBP" }, "expiry_date": "2026-12-20", "expiry_place": "Tunis Trade Centre", "issued_lc": false, "classification": "current" }, "finance_readiness": { "overall_status": "complete_for_phase_1_initial_review", "complete_signals": 6, "total_signals": 6, "signals": [ { "code": "trust_evidence", "status": "complete_for_phase_1", "classification": "provisional_system_assessment" }, { "code": "rules_evidence", "status": "complete_for_phase_1", "classification": "provisional_system_assessment" }, { "code": "pre_shipment_events", "status": "complete_for_phase_1", "classification": "provisional_system_assessment" }, { "code": "commercial_evidence", "status": "complete_for_phase_1", "classification": "provisional_system_assessment" }, { "code": "risk_and_exceptions", "status": "complete_for_phase_1", "classification": "provisional_system_assessment" }, { "code": "finance_preparation", "status": "complete_for_phase_1_initial_review", "classification": "provisional_system_assessment" } ], "interpretation": "Readiness supports controlled initial review; it is not a credit or underwriting decision." }, "finance_readiness_pack": { "reference": "FRP-20260925-4B6DA6CA", "version": 6, "status": "prepared_for_controlled_initial_bank_review", "classification": "current", "package_url": "https://demo.tradevow.com/ebrd-phase1/" }, "reviews": { "current": { "reference": "REVIEW-20260925-36173CA5", "outcome": "Suitable for controlled Phase 2 discussion", "classification": "current", "decision_type": "human_review_outcome", "pack_reference": "FRP-20260925-4B6DA6CA", "pack_version": 6, "lc_request_reference": "LC-REQ-20260922-0972A23E", "lc_request_version": 11, "purchase_order_reference": "TV-PO-YJTTZB6X", "purchase_order_version": 4 }, "historical": [ { "reference": "REVIEW-20260923-ECE001E1", "outcome_at_review": "Additional information requested", "status_at_review": "Awaiting requested information", "pack_reference": "FRP-20260923-1A0B27D1", "pack_version": 3, "lc_request_version": 6, "classification": "historical" }, { "reference": "REVIEW-20260923-82104941", "outcome_at_review": "Suitable for controlled Phase 2 discussion", "status_at_review": "Completed", "pack_reference": "FRP-20260923-3463E6B4", "pack_version": 4, "lc_request_version": 10, "classification": "historical" } ] }, "source_version_register": [ { "record_type": "transaction", "reference": "TV-TXN-20260921-8A17367F", "version": 2 }, { "record_type": "purchase_order", "reference": "TV-PO-YJTTZB6X", "version": 4 }, { "record_type": "lc_request", "reference": "LC-REQ-20260922-0972A23E", "version": 11 }, { "record_type": "finance_readiness_pack", "reference": "FRP-20260925-4B6DA6CA", "version": 6 }, { "record_type": "customs_preparation", "reference": "TV-CUS-DEC-4GDC2559", "version": 7 }, { "record_type": "rules_assessment", "reference": "TV-RULES-20260925-8N0D54", "version": 18 }, { "record_type": "compliance_assessment", "reference": "TV-COMP-20260925-ETIORI", "version": 10 }, { "record_type": "electronic_bill_of_lading", "reference": "TV-eBL-DPUCLYD5", "version": 2 } ], "execution_boundaries": { "formal_bank_application": "not_submitted", "credit_decision": "not_recorded", "lc_issuance": "not_issued", "customs_filing_or_clearance": "not_asserted", "shipment_delivery_or_title_transfer": "not_asserted", "settlement_execution": "not_started", "institution_decision": "The consuming institution retains all credit, underwriting, approval and execution decisions." } }, "relationships": { "transaction": { "links": { "related": "/v1/transactions/TV-TXN-20260921-8A17367F" } }, "evidence_pack": { "links": { "related": "/v1/transactions/TV-TXN-20260921-8A17367F/evidence-pack" } }, "finance_readiness": { "links": { "related": "/v1/transactions/TV-TXN-20260921-8A17367F/finance-readiness" } } }, "links": { "self": "/v1/transactions/TV-TXN-20260921-8A17367F/institutional-review?case_snapshot_fingerprint=1ea854f0a2c308b959042f21df537f6e2abaf65b5a5f980dd6ce59458db754f9", "demonstration": "https://demo.tradevow.com/ebrd-phase1/" } }, "meta": { "api_version": "v1", "snapshot": { "generated_at": "2026-09-25T16:47:19.416Z", "case_snapshot_fingerprint": "1ea854f0a2c308b959042f21df537f6e2abaf65b5a5f980dd6ce59458db754f9", "algorithm": "SHA-256", "meaning": "Identifies the version-locked transaction state shared by current outputs; it is not a file hash.", "current_at_generation": true }, "integrity": { "package_content_fingerprint": "abea7304213279c8197b677e4df8035ad66ad523b6bf4a43224a5f6431eade17", "package_manifest_sha256": "21c5f2b9bfe9efa80fe4be283ae0574027b42d47d35f3a5574a93521d134030c", "presentation_pdf_sha256": "4ee83f15d66a66beebf788ebfdd0546c0476e018082b7d2fdbcbb23240e19ab3", "downloadable_zip_sha256": "66ba9ac7c5313e1a448eff744eba43d2647f14399d2878408297d441d0198ba6", "note": "File, package-content, manifest, ZIP and case-snapshot fingerprints have distinct scopes." }, "data_classification": "Confidential — controlled synthetic demonstration", "synthetic_demonstration": true, "decision_boundary": "No EBRD endorsement, formal bank application, underwriting decision, credit approval, LC issuance, Customs clearance or settlement is asserted." } } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "securitySchemes": { "TradeVowApiKey": { "type": "apiKey", "in": "header", "name": "X-TradeVow-API-Key", "description": "Existing server-held TradeVow Connect API key. This operation requires transactions:read permission and authorisation for the requested transaction." } }, "schemas": { "InstitutionalReviewResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "type", "id", "attributes", "relationships", "links" ], "properties": { "type": { "const": "institutional_review" }, "id": { "type": "string" }, "attributes": { "type": "object", "description": "Current transaction state, evidence metadata, actions, conditions, readiness, reviews and source versions.", "additionalProperties": true }, "relationships": { "type": "object", "additionalProperties": true }, "links": { "$ref": "#/components/schemas/Links" } } }, "meta": { "type": "object", "required": [ "api_version", "snapshot", "data_classification", "synthetic_demonstration", "decision_boundary" ], "properties": { "api_version": { "type": "string" }, "snapshot": { "type": "object", "required": [ "generated_at", "case_snapshot_fingerprint", "current_at_generation" ], "properties": { "generated_at": { "type": "string", "format": "date-time" }, "case_snapshot_fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "algorithm": { "const": "SHA-256" }, "meaning": { "type": "string" }, "current_at_generation": { "type": "boolean" } } }, "integrity": { "type": "object", "additionalProperties": true }, "data_classification": { "type": "string" }, "synthetic_demonstration": { "type": "boolean" }, "decision_boundary": { "type": "string" } } } } }, "Links": { "type": "object", "properties": { "self": { "type": "string" }, "demonstration": { "type": "string", "format": "uri" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "responses": { "InvalidInput": { "description": "Check the required fields and their formats.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_INPUT", "message": "Check the required fields and their formats." } } } } }, "Unauthorised": { "description": "API key is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_API_KEY", "message": "API key is invalid." } } } } }, "InsufficientScope": { "description": "The key does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SCOPE_DENIED", "message": "The key does not permit this operation." } } } } }, "NotFound": { "description": "The transaction is unavailable or not granted to this organisation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "TRANSACTION_NOT_FOUND", "message": "The transaction is unavailable or not granted to this organisation." } } } } }, "RateLimited": { "description": "API request limit exceeded. Retry after the current window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "API request limit exceeded. Retry after the current window." } } } } }, "Unavailable": { "description": "Connect is temporarily unavailable. Please try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Connect is temporarily unavailable. Please try again." } } } } } } } }