{
  "openapi": "3.0.3",
  "info": {
    "title": "easy-contract API",
    "description": "API de firma electrónica — easy-contract.co\n\nAutenticación soportada:\n- **Bearer Token**: JWT de Firebase Auth (OAuth2 con Google)\n- **API Key**: Clave generada desde el dashboard (header X-API-Key)",
    "version": "1.0.0",
    "contact": {
      "name": "easy-contract",
      "url": "https://easy-contract.co",
      "email": "api@easy-contract.co"
    }
  },
  "servers": [
    { "url": "https://api.easy-contract.co/v1", "description": "Production" },
    { "url": "http://localhost:8080/v1", "description": "Development" }
  ],
  "security": [
    { "BearerAuth": [] },
    { "ApiKeyAuth": [] }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Firebase Auth JWT token"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API Key (prefijo ec_)"
      }
    },
    "schemas": {
      "Document": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "title": { "type": "string" },
          "status": { "type": "string", "enum": ["draft", "pending", "signing", "completed", "cancelled"] },
          "owner_id": { "type": "string", "format": "uuid" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "SigningField": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "type": { "type": "string", "enum": ["signature", "initials", "date", "text", "checkbox"] },
          "page": { "type": "integer" },
          "x": { "type": "number" },
          "y": { "type": "number" },
          "width": { "type": "number" },
          "height": { "type": "number" },
          "signer_id": { "type": "string", "format": "uuid" },
          "required": { "type": "boolean" }
        }
      },
      "Signer": {
        "type": "object",
        "properties": {
          "email": { "type": "string", "format": "email" },
          "name": { "type": "string" },
          "order": { "type": "integer" }
        },
        "required": ["email"]
      },
      "AuditEvent": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "action": { "type": "string" },
          "actor_email": { "type": "string" },
          "ip_address": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "metadata": { "type": "object" }
        }
      },
      "APIKey": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "key_prefix": { "type": "string" },
          "scopes": { "type": "string" },
          "active": { "type": "boolean" },
          "last_used_at": { "type": "string", "format": "date-time" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Plan": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string", "enum": ["pay_per_use", "starter", "business", "enterprise"] },
          "display_name": { "type": "string" },
          "price_monthly": { "type": "integer", "description": "Price in USD cents" },
          "price_annual": { "type": "integer", "description": "Price in USD cents" },
          "docs_included": { "type": "integer", "description": "0=pay-per-use, -1=unlimited" },
          "price_per_doc": { "type": "integer", "description": "USD cents per document" },
          "price_per_extra_signer": { "type": "integer", "description": "USD cents per extra signer" },
          "max_users": { "type": "integer" },
          "max_templates": { "type": "integer" },
          "has_api": { "type": "boolean" },
          "has_webhooks": { "type": "boolean" },
          "has_mcp": { "type": "boolean" }
        }
      },
      "Subscription": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "plan": { "$ref": "#/components/schemas/Plan" },
          "billing_period": { "type": "string", "enum": ["monthly", "annual", "pay_per_use"] },
          "status": { "type": "string", "enum": ["active", "cancelled", "past_due"] },
          "docs_used_this_period": { "type": "integer" },
          "current_period_start": { "type": "string", "format": "date-time" },
          "current_period_end": { "type": "string", "format": "date-time" }
        }
      },
      "UsageRecord": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "document_id": { "type": "string", "format": "uuid" },
          "type": { "type": "string", "enum": ["document", "extra_signer"] },
          "quantity": { "type": "integer" },
          "unit_price": { "type": "integer", "description": "USD cents" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" }
        }
      }
    }
  },
  "paths": {
    "/documents": {
      "post": {
        "summary": "Upload document",
        "description": "Upload a PDF document to create a new signing request",
        "tags": ["Documents"],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": { "type": "string" },
                  "file": { "type": "string", "format": "binary" }
                },
                "required": ["title", "file"]
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Document created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/documents/{id}": {
      "get": {
        "summary": "Get document",
        "tags": ["Documents"],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "Document details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }
        }
      }
    },
    "/documents/{id}/signing-fields": {
      "post": {
        "summary": "Add signing fields",
        "description": "Define signature field positions on the document",
        "tags": ["Documents"],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fields": { "type": "array", "items": { "$ref": "#/components/schemas/SigningField" } }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Fields added" } }
      }
    },
    "/documents/{id}/send": {
      "post": {
        "summary": "Send for signing",
        "description": "Send document to signers via email",
        "tags": ["Documents"],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "signers": { "type": "array", "items": { "$ref": "#/components/schemas/Signer" } },
                  "message": { "type": "string" }
                },
                "required": ["signers"]
              }
            }
          }
        },
        "responses": { "200": { "description": "Document sent" } }
      }
    },
    "/documents/{id}/sign": {
      "post": {
        "summary": "Sign document",
        "description": "Apply signature to a document field",
        "tags": ["Documents"],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Signature applied" } }
      }
    },
    "/documents/{id}/audit-trail": {
      "get": {
        "summary": "Get audit trail",
        "tags": ["Documents"],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": {
            "description": "Audit trail",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } } } }
          }
        }
      }
    },
    "/documents/{id}/download": {
      "get": {
        "summary": "Download signed PDF",
        "tags": ["Documents"],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "PDF file", "content": { "application/pdf": {} } }
        }
      }
    },
    "/templates": {
      "post": {
        "summary": "Create template",
        "tags": ["Templates"],
        "responses": { "201": { "description": "Template created" } }
      },
      "get": {
        "summary": "List templates",
        "tags": ["Templates"],
        "responses": { "200": { "description": "List of templates" } }
      }
    },
    "/templates/{id}": {
      "get": {
        "summary": "Get template",
        "tags": ["Templates"],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Template details" } }
      }
    },
    "/webhooks": {
      "post": {
        "summary": "Create webhook",
        "tags": ["Webhooks"],
        "responses": { "201": { "description": "Webhook created" } }
      },
      "get": {
        "summary": "List webhooks",
        "tags": ["Webhooks"],
        "responses": { "200": { "description": "List of webhooks" } }
      }
    },
    "/webhooks/{id}": {
      "delete": {
        "summary": "Delete webhook",
        "tags": ["Webhooks"],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "204": { "description": "Webhook deleted" } }
      }
    },
    "/api-keys": {
      "post": {
        "summary": "Create API Key",
        "description": "Generate a new API key. The full key is only shown once in the response.",
        "tags": ["API Keys"],
        "security": [{ "BearerAuth": [] }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "scopes": { "type": "string", "description": "Comma-separated: documents:read,documents:write,templates:read,webhooks:write" }
                },
                "required": ["name"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created (full key shown only once)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string", "format": "uuid" },
                    "name": { "type": "string" },
                    "key": { "type": "string", "description": "Full API key — store securely, not shown again" },
                    "key_prefix": { "type": "string" },
                    "scopes": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List API Keys",
        "tags": ["API Keys"],
        "security": [{ "BearerAuth": [] }],
        "responses": {
          "200": {
            "description": "List of API keys",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/APIKey" } } } }
          }
        }
      }
    },
    "/plans": {
      "get": {
        "summary": "List available plans",
        "description": "Returns all active pricing plans including pay-per-use rates",
        "tags": ["Billing"],
        "security": [],
        "responses": {
          "200": {
            "description": "List of plans",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } } }
          }
        }
      }
    },
    "/subscription": {
      "get": {
        "summary": "Get current subscription",
        "description": "Returns the organization's current subscription and usage",
        "tags": ["Billing"],
        "responses": {
          "200": {
            "description": "Current subscription",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } }
          }
        }
      },
      "put": {
        "summary": "Change plan",
        "description": "Upgrade, downgrade, or switch billing period",
        "tags": ["Billing"],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "plan": { "type": "string", "enum": ["pay_per_use", "starter", "business", "enterprise"] },
                  "billing_period": { "type": "string", "enum": ["monthly", "annual"] }
                },
                "required": ["plan"]
              }
            }
          }
        },
        "responses": { "200": { "description": "Subscription updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } } }
      }
    },
    "/usage": {
      "get": {
        "summary": "Get usage for current period",
        "description": "Returns itemized usage records for the current billing period",
        "tags": ["Billing"],
        "responses": {
          "200": {
            "description": "Usage records",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRecord" } } } }
          }
        }
      }
    },
    "/api-keys/{id}": {
      "delete": {
        "summary": "Revoke API Key",
        "tags": ["API Keys"],
        "security": [{ "BearerAuth": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "204": { "description": "API key revoked" } }
      }
    },
    "/payments/checkout": {
      "post": {
        "summary": "Create payment checkout",
        "description": "Generate a Mercado Pago checkout URL for pay-per-use top-up or plan subscription",
        "tags": ["Payments"],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": { "type": "string", "enum": ["top_up", "subscription"], "description": "top_up for pay-per-use credit, subscription for plan" },
                  "plan": { "type": "string", "enum": ["starter", "business"], "description": "Required for subscription type" },
                  "billing_period": { "type": "string", "enum": ["monthly", "annual"], "description": "Required for subscription type" },
                  "amount": { "type": "number", "description": "USD amount for top_up type" }
                },
                "required": ["type"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout URL generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "checkout_url": { "type": "string", "description": "Mercado Pago checkout URL — redirect user here" },
                    "preference_id": { "type": "string" },
                    "preapproval_plan_id": { "type": "string" },
                    "plan": { "type": "string" },
                    "billing_period": { "type": "string" },
                    "amount": { "type": "number" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/payments": {
      "get": {
        "summary": "Payment history",
        "description": "Returns payment history for the organization",
        "tags": ["Payments"],
        "responses": {
          "200": {
            "description": "List of payments",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string", "format": "uuid" },
                      "mercadopago_id": { "type": "string" },
                      "type": { "type": "string", "enum": ["one_time", "subscription"] },
                      "status": { "type": "string", "enum": ["pending", "approved", "rejected", "refunded", "cancelled"] },
                      "amount": { "type": "number" },
                      "currency": { "type": "string" },
                      "description": { "type": "string" },
                      "paid_at": { "type": "string", "format": "date-time" },
                      "created_at": { "type": "string", "format": "date-time" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/payments/webhook": {
      "post": {
        "summary": "Mercado Pago webhook (IPN)",
        "description": "Receives payment notifications from Mercado Pago. Verified via HMAC signature.",
        "tags": ["Payments"],
        "security": [],
        "responses": {
          "200": { "description": "Notification received" }
        }
      }
    }
  }
}