API Documentation

# SFTP Upload API Documentation

This document provides instructions on how to use the programmatic API to upload menu data. The API accepts a JSON payload, converts it into a flattened Excel file, and uploads it to the SFTP server configured in the main application UI.

## API Endpoint

- **URL**: The full URL is displayed on the main page of the application (e.g., `https://your-app-url.apphosting.dev/api/upload`).
- **Method**: `POST`
- **Authentication**: `Bearer Token`

You must include an `Authorization` header with your request, containing the secret API key as a bearer token. The API secret can be generated and viewed from the main application interface.

**Header Example:** `Authorization: Bearer <YOUR_API_SECRET>`

## Request Body

The request body must be a JSON object with a specific structure containing `vendor` and `products` information.

### Example Payload

```json
{
  "vendor": {
    "name": "Artcaffe",
    "location_id": "ARTCAFFE_WESTLANDS_001",
    "currency": "KES",
    "updated_at": "2025-10-18T20:27:28Z"
  },
  "products": [
    {
      "external_id": "ART-1001",
      "name": "Chicken Caesar Salad",
      "description": "Romaine lettuce, grilled chicken, parmesan, house Caesar dressing, croutons.",
      "price": {
        "amount": 950,
        "currency": "KES"
      },
      "in_stock": true,
      "sku": "SAL-CAESAR-CHICKEN",
      "category": "Salads",
      "image_url": "https://storage.artcaffe.co.ke/menu/salads/chicken-caesar.jpg",
      "tax_rate": 0.16,
      "options": [
        {
          "name": "Add Avocado",
          "price_delta": 150,
          "default": false
        },
        {
          "name": "No Croutons",
          "price_delta": 0,
          "default": false
        }
      ],
      "tags": [
        "popular",
        "contains-dairy"
      ]
    }
  ]
}
```

### Automatic Excel Generation

The server will automatically perform the following actions:
1.  **Flatten Data**: The `products` array will be flattened into a tabular format. Nested objects (like `price`) and arrays (like `tags` and `options`) will be converted into separate columns.
2.  **Create Excel File**: An Excel `.xlsx` file will be generated from the flattened data.
3.  **Generate Filename**: A unique filename will be created based on the vendor's name and location ID (e.g., `Artcaffe_ARTCAFFE_WESTLANDS_001.xlsx`).
4.  **Upload to SFTP**: The generated file will be uploaded to the `remotePath` configured in the SFTP settings on the main application page.

## Responses

### Success Response (`200 OK`)

If the file is uploaded successfully, the API will return a JSON object with a success message and a list of files in the destination directory.

```json
{
  "success": true,
  "message": "File uploaded to /uploads/Artcaffe_ARTCAFFE_WESTLANDS_001.xlsx",
  "files": [
    ".",
    "..",
    "Artcaffe_ARTCAFFE_WESTLANDS_001.xlsx",
    "anotherfile.txt"
  ]
}
```

### Error Responses

- `400 Bad Request`: The request body is invalid, not valid JSON, or doesn't match the required schema.
- `401 Unauthorized`: The `Authorization` header is missing or the bearer token is invalid.
- `500 Internal Server Error`: An unexpected error occurred on the server. This could be due to incorrect SFTP configuration, connection issues, or other problems. The response body will contain details.

#### Example Error Response (`500`)

```json
{
  "success": false,
  "message": "An internal error occurred during the file upload.",
  "details": "SFTP connection error: All configured authentication methods failed"
}
```