{
  "openapi": "3.1.0",
  "info": {
    "title": "contract.mn API",
    "version": "1.0.0",
    "description": "An organisation's systems make and follow e-ID contracts. Every request carries an organisation's API key (Тохиргоо › API ба Webhook) as «Authorization: Bearer cmn_…»; it acts as the administrator who made it, in that organisation. Errors are {\"error\": {\"code\", \"message\"}}. Webhooks tell what happens to its contracts (see x-webhooks)."
  },
  "servers": [{ "url": "https://contract.mn/api/v1/public" }],
  "security": [{ "apiKey": [] }],
  "components": {
    "securitySchemes": {
      "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "cmn_<prefix>_<secret>" }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }
      },
      "Party": {
        "type": "object",
        "properties": {
          "ordinal": { "type": "integer" }, "label": { "type": "string" }, "name": { "type": "string" },
          "reg_number": { "type": "string" }, "org_name": { "type": "string" },
          "signed_at": { "type": "string", "format": "date-time" }, "declined_at": { "type": "string", "format": "date-time" }
        }
      },
      "Contract": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "description": "The verification code (verify_url)." },
          "title": { "type": "string" },
          "status": { "type": "string", "enum": ["draft", "signing", "signed", "declined", "cancelled", "expired"] },
          "template_id": { "type": "string", "format": "uuid" },
          "parties": { "type": "array", "items": { "$ref": "#/components/schemas/Party" } },
          "sign_by": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date" },
          "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" },
          "verify_url": { "type": "string" }, "any_order": { "type": "boolean" }
        }
      },
      "Template": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" },
          "kind": { "type": "string", "enum": ["B2B", "B2C", "C2B", "C2C", "B2G"] },
          "party_labels": { "type": "array", "items": { "type": "string" } },
          "asks": { "type": "array", "items": { "type": "string" }, "description": "The values a contract made from it is given (values)." },
          "sign_days": { "type": "integer" }
        }
      },
      "NewContract": {
        "type": "object",
        "required": ["template_id", "parties"],
        "properties": {
          "template_id": { "type": "string", "format": "uuid" },
          "title": { "type": "string" },
          "parties": {
            "type": "array", "description": "The other parties, in order (the organisation is the first). A person by register and name, an organisation by its register.",
            "items": { "type": "object", "properties": { "reg_number": { "type": "string", "example": "УБ12345678" }, "name": { "type": "string" }, "org_reg": { "type": "string", "example": "6235972" } } }
          },
          "values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The template's asks, by code." },
          "sign_days": { "type": "integer" }, "valid_until": { "type": "string", "format": "date" }, "message": { "type": "string" },
          "any_order": { "type": "boolean", "description": "The parties sign in any order: each is told at once, whoever signs first does. Default: one after another." }
        }
      }
    },
    "responses": {
      "Error": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  },
  "paths": {
    "/templates": {
      "get": { "summary": "The organisation's templates", "operationId": "listTemplates", "x-scope": "templates:read",
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }
    },
    "/templates/{id}": {
      "get": { "summary": "One template", "operationId": "getTemplate", "x-scope": "templates:read",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "default": { "$ref": "#/components/responses/Error" } } }
    },
    "/contracts": {
      "get": { "summary": "The organisation's contracts", "operationId": "listContracts", "x-scope": "contracts:read",
        "parameters": [{ "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 500 } }],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } },
      "post": { "summary": "Make a contract from a template", "operationId": "createContract", "x-scope": "contracts:write",
        "description": "A draft: it goes to the parties' e-ID once the organisation's signer approves it. A retry with the same Idempotency-Key gets the first answer.",
        "parameters": [{ "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "maxLength": 100 } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewContract" } } } },
        "responses": { "201": { "description": "Made", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contract" } } } }, "default": { "$ref": "#/components/responses/Error" } } }
    },
    "/contracts/{id}": {
      "get": { "summary": "One contract", "operationId": "getContract", "x-scope": "contracts:read",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contract" } } } }, "default": { "$ref": "#/components/responses/Error" } } }
    },
    "/contracts/{id}/pdf": {
      "get": { "summary": "Its PDF (signed: PAdES with timestamp and revocation data)", "operationId": "getContractPDF", "x-scope": "contracts:read",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "PDF", "content": { "application/pdf": {} } }, "default": { "$ref": "#/components/responses/Error" } } }
    },
    "/contracts/{id}/evidence": {
      "get": { "summary": "Its evidence package: a ZIP of the PDF, its signatures validated now against the Mongolian national root (validation.json), its parties, every step and each version's SHA-256 (audit-trail.json)", "operationId": "getContractEvidence", "x-scope": "contracts:read",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "ZIP", "content": { "application/zip": {} } }, "default": { "$ref": "#/components/responses/Error" } } }
    },
    "/contracts/{id}/cancel": {
      "post": { "summary": "Cancel a contract not yet signed by all", "operationId": "cancelContract", "x-scope": "contracts:write",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contract" } } } }, "default": { "$ref": "#/components/responses/Error" } } }
    }
  },
  "x-webhooks": {
    "description": "POST, JSON {id, event, created_at, data: {contract_id, code, title, status, actor, detail}}. Headers: X-ContractMN-Event, X-ContractMN-Delivery (the event's id; drop a second one), X-ContractMN-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>. A 2xx is delivered; otherwise tried again after 1 m, 5 m, 30 m, 2 h, 6 h, 24 h. Only https, public addresses.",
    "events": ["contract.created", "signature.requested", "party.signed", "party.sealed", "contract.filled", "contract.approved", "contract.completed", "contract.declined", "contract.cancelled", "contract.expired"]
  }
}
