{
  "openapi": "3.0.3",
  "info": {
    "title": "Payana Travel Agency API",
    "description": "REST API and Webhooks for Payana White-label travel operators to integrate leads, trips, itineraries, and invoicing into external CRM and ERP systems.",
    "version": "1.0.0",
    "contact": {
      "name": "Payana Developer Support",
      "email": "hello@payana.today",
      "url": "https://payana.today/api"
    }
  },
  "servers": [
    {
      "url": "https://api.payana.today/v1",
      "description": "Production API server"
    }
  ],
  "paths": {
    "/trips": {
      "get": {
        "summary": "List trips",
        "description": "Returns active, past, and upcoming agency trips with status and quote-to-balance financial summaries.",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["draft", "quoted", "confirmed", "completed", "cancelled"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": { "description": "List of trips retrieved successfully" }
        }
      },
      "post": {
        "summary": "Create trip draft",
        "description": "Scaffolds a new trip record in the agency workspace.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["destination", "dates", "lead_traveler"],
                "properties": {
                  "destination": { "type": "string" },
                  "dates": { "type": "object", "properties": { "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" } } },
                  "lead_traveler": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" } } }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Trip draft created" }
        }
      }
    },
    "/trips/{id}": {
      "get": {
        "summary": "Get trip details",
        "description": "Retrieves the full trip itinerary, travelers list, payment milestones, and companion app sync status.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Trip details returned" }
        }
      },
      "patch": {
        "summary": "Update trip",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Trip updated" }
        }
      }
    },
    "/leads": {
      "get": {
        "summary": "List leads",
        "description": "Lists pipeline leads across WhatsApp, Instagram, and web form sources.",
        "parameters": [
          { "name": "stage", "in": "query", "schema": { "type": "string", "enum": ["new", "qualifying", "quoted", "won", "lost"] } }
        ],
        "responses": {
          "200": { "description": "Leads returned" }
        }
      },
      "post": {
        "summary": "Ingest lead",
        "description": "Creates an inbound lead in the unified pipeline.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "source"],
                "properties": {
                  "name": { "type": "string" },
                  "phone": { "type": "string" },
                  "source": { "type": "string", "enum": ["whatsapp", "instagram", "web", "referral"] },
                  "destination": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Lead created" }
        }
      }
    },
    "/invoices": {
      "get": {
        "summary": "List invoices",
        "description": "Returns GST-compliant invoices with SAC codes, tax breakdowns, and payment status.",
        "responses": {
          "200": { "description": "Invoices returned" }
        }
      }
    },
    "/invoices/{id}/payment-link": {
      "post": {
        "summary": "Create Razorpay payment link",
        "description": "Generates a merchant-direct Razorpay payment link for advance or balance collection.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Payment link generated" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "pay_live_*"
      }
    }
  },
  "security": [
    { "bearerAuth": [] }
  ]
}