{
  "openapi": "3.1.0",
  "info": {
    "title": "Invoice Software API",
    "version": "v1",
    "description": "Invoice Software APIs help teams create invoices, convert estimates, track payments, calculate tax, and review outstanding receivables.",
    "contact": {
      "name": "Azeosoft Web Technologies",
      "url": "https://azeosoft.com"
    }
  },
  "servers": [
    {
      "url": "https://api-invoice.azeosoft.com/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Authenticate and verify access for Invoice Software integrations."
    },
    {
      "name": "Invoices",
      "description": "Create, read, update, and list invoices in Invoice Software."
    },
    {
      "name": "Payments",
      "description": "Manage payments workflows in Invoice Software."
    },
    {
      "name": "Reports",
      "description": "Export Invoice Software analytics and operational summaries."
    }
  ],
  "paths": {
    "/auth/token": {
      "post": {
        "operationId": "invoice-token",
        "summary": "Create access token",
        "description": "Creates a short-lived access token for Invoice Software API requests.",
        "tags": [
          "Authentication"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Access token returned",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "access_token": "az_live_token",
                    "token_type": "Bearer",
                    "expires_in": 3600
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "description": "Client credentials issued from the product admin panel.",
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "client_id": "invoice_client",
                "client_secret": "********"
              }
            }
          }
        }
      }
    },
    "/auth/profile": {
      "get": {
        "operationId": "invoice-profile",
        "summary": "Get integration profile",
        "description": "Returns organization and permission details for the authenticated Invoice Software integration.",
        "tags": [
          "Authentication"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Integration profile returned",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "organizationId": "org_001",
                    "product": "Invoice Software",
                    "scopes": [
                      "read",
                      "write"
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/invoices": {
      "get": {
        "operationId": "invoice-list-records",
        "summary": "List invoices",
        "description": "Returns a paginated list of invoices for the organization.",
        "tags": [
          "Invoices"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum records to return.",
            "schema": {
              "type": "integer"
            },
            "example": "50"
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Pagination cursor from the previous response.",
            "schema": {
              "type": "string"
            },
            "example": "next_abc123"
          }
        ],
        "responses": {
          "200": {
            "description": "Invoices list returned",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "items": [
                      {
                        "id": "invoice_id_001",
                        "invoice_number": "INV-1001",
                        "customer_name": "Acme Retail",
                        "amount": 25000,
                        "currency": "INR",
                        "status": "unpaid"
                      }
                    ],
                    "nextCursor": null
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "operationId": "invoice-create-record",
        "summary": "Create invoices",
        "description": "Creates a new invoices record.",
        "tags": [
          "Invoices"
        ],
        "parameters": [],
        "responses": {
          "201": {
            "description": "Invoices created",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "invoice_id_001",
                    "invoice_number": "INV-1001",
                    "customer_name": "Acme Retail",
                    "amount": 25000,
                    "currency": "INR",
                    "status": "unpaid",
                    "created_at": "2026-07-26T09:00:00Z"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "description": "Invoices fields.",
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "invoice_number": "INV-1001",
                "customer_name": "Acme Retail",
                "amount": 25000,
                "currency": "INR",
                "status": "unpaid"
              }
            }
          }
        }
      }
    },
    "/invoices/{invoice_id}": {
      "get": {
        "operationId": "invoice-get-record",
        "summary": "Get invoices details",
        "description": "Returns details for a specific invoices record.",
        "tags": [
          "Invoices"
        ],
        "parameters": [
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Invoices ID.",
            "schema": {
              "type": "string"
            },
            "example": "invoice_id_001"
          }
        ],
        "responses": {
          "200": {
            "description": "Invoices details returned",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "invoice_id_001",
                    "invoice_number": "INV-1001",
                    "customer_name": "Acme Retail",
                    "amount": 25000,
                    "currency": "INR",
                    "status": "unpaid"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "patch": {
        "operationId": "invoice-update-record",
        "summary": "Update invoices",
        "description": "Updates selected fields on a invoices record.",
        "tags": [
          "Invoices"
        ],
        "parameters": [
          {
            "name": "invoice_id",
            "in": "path",
            "required": true,
            "description": "Invoices ID.",
            "schema": {
              "type": "string"
            },
            "example": "invoice_id_001"
          }
        ],
        "responses": {
          "200": {
            "description": "Invoices updated",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "invoice_id_001",
                    "status": "active",
                    "updated_at": "2026-07-26T10:00:00Z"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "description": "Partial Invoices fields.",
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "status": "active"
              }
            }
          }
        }
      }
    },
    "/payments": {
      "get": {
        "operationId": "invoice-workflow-list",
        "summary": "List payments",
        "description": "Returns workflow records used by Invoice Software.",
        "tags": [
          "Payments"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Payments returned",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "items": [
                      {
                        "id": "flow_001",
                        "name": "Payments",
                        "status": "active"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/payments/actions": {
      "post": {
        "operationId": "invoice-workflow-action",
        "summary": "Create payments action",
        "description": "Creates an operational action inside the payments workflow.",
        "tags": [
          "Payments"
        ],
        "parameters": [],
        "responses": {
          "201": {
            "description": "Workflow action created",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "actionId": "act_001",
                    "status": "queued"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "description": "Workflow action payload.",
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "target_id": "invoice_id_001",
                "action": "assign",
                "owner_id": "user_001",
                "note": "Assigned from API"
              }
            }
          }
        }
      }
    },
    "/reports/receivables-ageing": {
      "get": {
        "operationId": "invoice-summary-report",
        "summary": "Receivables ageing report",
        "description": "Returns the receivables ageing report for a selected date range.",
        "tags": [
          "Reports"
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "Start date in YYYY-MM-DD format.",
            "schema": {
              "type": "string"
            },
            "example": "2026-07-01"
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "End date in YYYY-MM-DD format.",
            "schema": {
              "type": "string"
            },
            "example": "2026-07-26"
          }
        ],
        "responses": {
          "200": {
            "description": "Report returned",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "from": "2026-07-01",
                    "to": "2026-07-26",
                    "totals": {
                      "records": 128,
                      "open": 18,
                      "closed": 110
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/reports/receivables-ageing/export": {
      "post": {
        "operationId": "invoice-export-report",
        "summary": "Export report",
        "description": "Creates a downloadable Invoice Software report export.",
        "tags": [
          "Reports"
        ],
        "parameters": [],
        "responses": {
          "202": {
            "description": "Export queued",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "exportId": "exp_001",
                    "status": "processing"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "description": "Export options.",
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "format": "csv",
                "from": "2026-07-01",
                "to": "2026-07-26"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    }
  }
}