{
  "openapi": "3.1.0",
  "info": {
    "title": "Mobile-ID Sign Reference API",
    "version": "8.0-reference",
    "description": "Offline integration reference, not a production contract. New schema details are proposals for this simulator only. Production servers, authentication, scopes, webhook names, algorithms and retry schedules remain unconfirmed.",
    "contact": {
      "name": "Mobile-ID",
      "email": "info@mobile-id.vn",
      "url": "https://www.mobile-id.vn/"
    }
  },
  "servers": [
    {
      "url": "https://reference.invalid",
      "description": "Non-routable reference only. The explorer uses local simulation and sends no HTTP requests."
    }
  ],
  "x-publication-status": "REFERENCE",
  "x-authentication-status": "UNCONFIRMED",
  "tags": [
    {
      "name": "Signing transactions",
      "description": "Reference asynchronous signing workflow."
    },
    {
      "name": "Verification",
      "description": "Simulation of the verification handoff; no cryptography."
    }
  ],
  "paths": {
    "/v1/signing-transactions": {
      "post": {
        "operationId": "createReferenceSigningTransaction",
        "tags": [
          "Signing transactions"
        ],
        "summary": "Create a signing transaction",
        "description": "Prepare an approved document and signer context in the source system. Store transaction_id on 202; continue following state or agreed events. A lost response is an uncertain outcome, so reconcile before resubmitting. Authentication, authority, idempotency transport and live routing require an approved deployment contract.",
        "x-description-vi": "Chuẩn bị tài liệu đã duyệt và thông tin người ký tại hệ thống nguồn. Khi nhận 202, lưu transaction_id và tiếp tục theo dõi trạng thái. Nếu mất phản hồi, đối soát trước khi gửi lại. Xác thực, quyền ký và cơ chế chống trùng của môi trường thật cần được xác nhận.",
        "requestBody": {
          "required": true,
          "description": "Reference-only JSON input.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReferenceSigningRequest"
              },
              "example": {
                "document_ref": "doc_demo_001",
                "signer_ref": "subject_demo_001",
                "purpose": "contract-approval",
                "route": "AUTO"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted for the reference user-action flow; signing is not complete.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceSigningResponse"
                },
                "example": {
                  "transaction_id": "sig_txn_demo_001",
                  "state": "WAITING_USER_ACTION",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          },
          "400": {
            "description": "REFERENCE ONLY: Malformed request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceError"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "Malformed request.",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          },
          "401": {
            "description": "REFERENCE ONLY: Production authentication requires an approved contract.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceError"
                },
                "example": {
                  "code": "AUTHENTICATION_REQUIRED",
                  "message": "Production authentication requires an approved contract.",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          },
          "409": {
            "description": "REFERENCE ONLY: Conflicting submission; reconcile with the stored transaction.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceError"
                },
                "example": {
                  "code": "IDEMPOTENCY_CONFLICT",
                  "message": "Conflicting submission; reconcile with the stored transaction.",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          },
          "422": {
            "description": "REFERENCE ONLY: Reference input failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceError"
                },
                "example": {
                  "code": "VALIDATION_ERROR",
                  "message": "Reference input failed validation.",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          },
          "503": {
            "description": "REFERENCE ONLY: Provider outcome requires reconciliation before retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceError"
                },
                "example": {
                  "code": "PROVIDER_TEMPORARY_FAILURE",
                  "message": "Provider outcome requires reconciliation before retry.",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          }
        }
      }
    },
    "/v1/signing-transactions/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Reference transaction identifier. Production identifier format is unconfirmed.",
          "schema": {
            "type": "string",
            "minLength": 1
          },
          "example": "sig_txn_demo_001"
        }
      ],
      "get": {
        "operationId": "getReferenceSigningTransaction",
        "tags": [
          "Signing transactions"
        ],
        "summary": "Read transaction state",
        "description": "Correlate the stored reference with the latest authoritative transaction state. COMPLETED is an illustrative simulator state, not a production state guarantee. A missing transaction requires investigation; it is not permission to create a replacement automatically.",
        "x-description-vi": "Dùng mã giao dịch đã lưu để đối chiếu trạng thái. COMPLETED là trạng thái minh họa của trình mô phỏng. Không tự tạo giao dịch thay thế chỉ vì chưa tìm thấy kết quả.",
        "responses": {
          "200": {
            "description": "Illustrative transaction state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceSigningResponse"
                },
                "example": {
                  "transaction_id": "sig_txn_demo_001",
                  "state": "COMPLETED",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          },
          "401": {
            "description": "REFERENCE ONLY: Production authentication requires an approved contract.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceError"
                },
                "example": {
                  "code": "AUTHENTICATION_REQUIRED",
                  "message": "Production authentication requires an approved contract.",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          },
          "404": {
            "description": "REFERENCE ONLY: Reference transaction not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceError"
                },
                "example": {
                  "code": "NOT_FOUND",
                  "message": "Reference transaction not found.",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          },
          "503": {
            "description": "REFERENCE ONLY: Provider outcome requires reconciliation before retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceError"
                },
                "example": {
                  "code": "PROVIDER_TEMPORARY_FAILURE",
                  "message": "Provider outcome requires reconciliation before retry.",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          }
        }
      }
    },
    "/v1/signatures/verify": {
      "post": {
        "operationId": "verifyReferenceSignature",
        "tags": [
          "Verification"
        ],
        "summary": "Demonstrate verification handoff",
        "description": "Proposed reference-only verification model. This offline explorer returns a demonstration result without inspecting signatures, certificates or revocation. Live verification requires an approved document/signature profile and provider contract.",
        "x-description-vi": "Mô hình kiểm chứng tham chiếu. Trình mô phỏng chỉ minh họa kết quả, không kiểm tra chữ ký, chứng thư hoặc thu hồi. Kiểm chứng thật cần hồ sơ định dạng và hợp đồng nhà cung cấp đã xác nhận.",
        "requestBody": {
          "required": true,
          "description": "Proposed simulation-only document reference.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReferenceVerificationRequest"
              },
              "example": {
                "document_ref": "doc_demo_001"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simulated handoff result; not signature-validity evidence.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceVerificationResponse"
                },
                "example": {
                  "model_status": "SIMULATED_ONLY",
                  "verification_result": "SIMULATED_PASS"
                }
              }
            }
          },
          "400": {
            "description": "REFERENCE ONLY: Malformed request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceError"
                },
                "example": {
                  "code": "INVALID_REQUEST",
                  "message": "Malformed request.",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          },
          "401": {
            "description": "REFERENCE ONLY: Production authentication requires an approved contract.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceError"
                },
                "example": {
                  "code": "AUTHENTICATION_REQUIRED",
                  "message": "Production authentication requires an approved contract.",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          },
          "422": {
            "description": "REFERENCE ONLY: Reference input failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceError"
                },
                "example": {
                  "code": "VALIDATION_ERROR",
                  "message": "Reference input failed validation.",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          },
          "503": {
            "description": "REFERENCE ONLY: Provider outcome requires reconciliation before retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReferenceError"
                },
                "example": {
                  "code": "PROVIDER_TEMPORARY_FAILURE",
                  "message": "Provider outcome requires reconciliation before retry.",
                  "model_status": "SIMULATED_ONLY"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ReferenceSigningRequest": {
        "type": "object",
        "description": "Offline reference input. Required fields and constraints apply only to this simulator; production validation requires confirmation.",
        "additionalProperties": false,
        "required": [
          "document_ref",
          "signer_ref",
          "purpose",
          "route"
        ],
        "properties": {
          "document_ref": {
            "type": "string",
            "minLength": 1,
            "description": "Synthetic document reference, not a file upload or document digest.",
            "examples": [
              "doc_demo_001"
            ]
          },
          "signer_ref": {
            "type": "string",
            "minLength": 1,
            "description": "Synthetic signer reference; it does not establish identity or signing authority.",
            "examples": [
              "subject_demo_001"
            ]
          },
          "purpose": {
            "type": "string",
            "minLength": 1,
            "description": "Business intent for the reference transaction.",
            "examples": [
              "contract-approval"
            ]
          },
          "route": {
            "type": "string",
            "minLength": 1,
            "description": "Illustrative route label. AUTO is not a published production enum.",
            "examples": [
              "AUTO"
            ]
          }
        },
        "x-model-status": "REFERENCE_ONLY"
      },
      "ReferenceSigningResponse": {
        "type": "object",
        "description": "Reference transaction outcome. 202 acceptance does not mean signing completion. States shown are illustrative, not an approved production enum.",
        "additionalProperties": false,
        "required": [
          "transaction_id",
          "state",
          "model_status"
        ],
        "properties": {
          "transaction_id": {
            "type": "string",
            "minLength": 1,
            "description": "Reference used to correlate the transaction.",
            "examples": [
              "sig_txn_demo_001"
            ]
          },
          "state": {
            "type": "string",
            "minLength": 1,
            "description": "Illustrative transaction state.",
            "examples": [
              "WAITING_USER_ACTION"
            ]
          },
          "model_status": {
            "type": "string",
            "const": "SIMULATED_ONLY",
            "description": "Every offline response is simulated.",
            "examples": [
              "SIMULATED_ONLY"
            ]
          }
        },
        "x-model-status": "REFERENCE_ONLY"
      },
      "ReferenceVerificationRequest": {
        "type": "object",
        "description": "Proposed reference-only verification input. No real signature bytes or cryptographic validation are processed.",
        "additionalProperties": false,
        "required": [
          "document_ref"
        ],
        "properties": {
          "document_ref": {
            "type": "string",
            "minLength": 1,
            "description": "Synthetic reference to the document used in the demonstration.",
            "examples": [
              "doc_demo_001"
            ]
          }
        },
        "x-model-status": "REFERENCE_ONLY"
      },
      "ReferenceVerificationResponse": {
        "type": "object",
        "description": "Proposed simulation-only verification output. SIMULATED_PASS is not evidence of a valid signature.",
        "additionalProperties": false,
        "required": [
          "model_status",
          "verification_result"
        ],
        "properties": {
          "model_status": {
            "type": "string",
            "const": "SIMULATED_ONLY",
            "description": "Marks the local simulation."
          },
          "verification_result": {
            "type": "string",
            "minLength": 1,
            "description": "Demonstration result; not a production field or cryptographic conclusion.",
            "examples": [
              "SIMULATED_PASS"
            ]
          }
        },
        "x-model-status": "REFERENCE_ONLY"
      },
      "ReferenceError": {
        "type": "object",
        "description": "Proposed error envelope for the offline simulator; production error format is unconfirmed.",
        "additionalProperties": false,
        "required": [
          "code",
          "message",
          "model_status"
        ],
        "properties": {
          "code": {
            "type": "string",
            "minLength": 1,
            "description": "Reference error identifier.",
            "examples": [
              "VALIDATION_ERROR"
            ]
          },
          "message": {
            "type": "string",
            "minLength": 1,
            "description": "Human-readable simulation explanation.",
            "examples": [
              "document_ref is required"
            ]
          },
          "model_status": {
            "type": "string",
            "const": "SIMULATED_ONLY",
            "description": "Marks the local simulation."
          }
        },
        "x-model-status": "REFERENCE_ONLY"
      }
    }
  }
}