=== Fuuffy Integration for WooCommerce ===
Contributors: davidfuuffy
Tags: woocommerce, api, fuuffy, order-sync, tracking
Requires at least: 5.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Provides REST API endpoints for Fuuffy.com to sync WooCommerce orders and update tracking information.

== External services ==

This plugin connects to Fuuffy-operated external services (`https://api.fuuffy.com`, `https://www.fuuffy.com`, and `https://dev.fuuffy.com`) to provide WooCommerce connection, order sync, and tracking updates.

Service purpose:
- Validate and manage Fuuffy integration credentials for this WooCommerce store.
- Allow merchants to connect their store to Fuuffy from the plugin settings page.
- Exchange order and tracking data between WooCommerce and Fuuffy.

Data sent and when:
- When an admin connects the store from WooCommerce > Fuuffy Integration, the plugin sends store metadata (site URL, site name, admin email), plugin API endpoint URL, and WooCommerce REST API credentials generated for integration.
- When Fuuffy syncs orders through the plugin API, order data is made available to Fuuffy, including customer contact details, billing/shipping addresses, product line items, and tracking records.
- When API key validation runs, the plugin sends the configured Fuuffy API key to Fuuffy's validation endpoint.

These services are provided by Fuuffy:
- Terms of Use: [https://fuuffy.com/terms-of-use](https://fuuffy.com/terms-of-use)
- Privacy Policy: [https://fuuffy.com/privacy-policy](https://fuuffy.com/privacy-policy)

== Description ==

Fuuffy Integration for WooCommerce provides secure REST API endpoints that allow Fuuffy.com to access your WooCommerce order data and update tracking information for shipments.

= Key Features =

* **Order Data API**: Secure endpoint for Fuuffy.com to fetch WooCommerce order data
* **Tracking Updates**: API endpoint for Fuuffy.com to update tracking information
* **Comprehensive Order Data**: Includes shipping addresses, product details, and customer information
* **Custom Fields Support**: Supports HS codes and origin country for customs declarations
* **Comprehensive Logging**: Detailed activity logs for troubleshooting
* **Admin Dashboard**: Easy management interface for API settings and tracking overview

= How It Works =

1. **Install and Configure**: Install the plugin and set an API key in WooCommerce settings
2. **Fuuffy.com Integration**: Users on Fuuffy.com can click "Sync WooCommerce Order" to fetch order data
3. **Order Processing**: Fuuffy.com reads order status and creates shipments for eligible orders
4. **Tracking Updates**: When tracking numbers are generated, they're automatically synced back to WooCommerce

= API Endpoints =

The plugin provides these REST API endpoints for Fuuffy.com (all require `X-API-Key` header):

**Order Management:**
* `GET /wp-json/fuufinfo/v1/orders` - Fetch orders with filters (status, date_from, date_to, page, per_page)
* `GET /wp-json/fuufinfo/v1/orders/{id}` - Get specific order details with all tracking records

**Tracking Management (Multiple tracking numbers per order):**
* `GET /wp-json/fuufinfo/v1/orders/{id}/tracking` - Get all tracking records for an order
* `POST /wp-json/fuufinfo/v1/orders/{id}/tracking` - Add new tracking record
* `PUT /wp-json/fuufinfo/v1/orders/{id}/tracking/{tracking_id}` - Update specific tracking record
* `DELETE /wp-json/fuufinfo/v1/orders/{id}/tracking/{tracking_id}` - Delete specific tracking record

= For Fuuffy.com Users =

After the plugin is installed on a WooCommerce store, Fuuffy.com users can:
* Use the "Sync WooCommerce Order" button to fetch order data
* Access comprehensive order information including shipping addresses and product details
* Automatically generate customs declarations from product data
* Update tracking numbers that sync back to WooCommerce

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/fuuffy-integration-for-woocommerce/` or install through WordPress admin
2. Activate the plugin through the 'Plugins' screen in WordPress
3. Go to WooCommerce > Fuuffy Integration to configure the plugin
4. Set an API key that Fuuffy.com will use to authenticate requests
5. Share the API endpoint URL with Fuuffy.com users

== Configuration ==

= API Setup =

1. **API Key**: Set a secure API key that Fuuffy.com will use to authenticate requests
2. **Endpoint URL**: Share `yoursite.com/wp-json/fuufinfo/v1/` with Fuuffy.com users

= REST API Endpoints =

**Get Orders**: `GET /wp-json/fuufinfo/v1/orders`
Query parameters:
- `status` - Filter by order status
- `date_from` - Filter orders from date (Y-m-d)
- `date_to` - Filter orders to date (Y-m-d)
- `page` - Page number
- `per_page` - Orders per page (max 100)

**Get Single Order**: `GET /wp-json/fuufinfo/v1/orders/{id}`

**Get Order Tracking**: `GET /wp-json/fuufinfo/v1/orders/{id}/tracking`
Returns array of all tracking records for the order.

**Add Tracking**: `POST /wp-json/fuufinfo/v1/orders/{id}/tracking`
Body parameters:
- `tracking_number` (required) - Tracking number
- `tracking_status` - Tracking status (default: "pending")
- `courier_provider` - Courier name (e.g., "ups", "dhl")
- `estimated_delivery` - Estimated delivery date (Y-m-d)

**Update Tracking**: `PUT /wp-json/fuufinfo/v1/orders/{id}/tracking/{tracking_id}`
Body parameters:
- `tracking_number` - Tracking number
- `tracking_status` - Tracking status (e.g., "in_transit", "delivered")
- `courier_provider` - Courier name (e.g., "ups", "dhl")
- `estimated_delivery` - Estimated delivery date (Y-m-d)

**Delete Tracking**: `DELETE /wp-json/fuufinfo/v1/orders/{id}/tracking/{tracking_id}`

= Authentication =

API requests require the `X-API-Key` header with your configured API key.

== Shipping Method ==

The plugin includes a WooCommerce shipping method that provides real-time rates from Fuuffy:

1. Go to WooCommerce > Settings > Shipping
2. Add "Fuuffy Shipping" to your shipping zones
3. Configure rate display options and markup settings
4. Customers will see live shipping rates during checkout

== Order Data Format ==

Orders are provided to Fuuffy.com with comprehensive data including:

```json
{
  "order_id": 123,
  "order_number": "123",
  "order_date": "2024-01-15 10:30:00",
  "order_status": "processing",
  "currency": "USD",
  "total_value": "99.99",
  "customer": {
    "shipping_address": {
      "address_1": "123 Main St",
      "city": "New York",
      "country": "US",
      "postcode": "10001"
    }
  },
  "line_items": [
    {
      "name": "Product Name",
      "quantity": 1,
      "price": "99.99",
      "hs_code": "1234.56.78",
      "origin_country": "US"
    }
  ],
  "fuufinfo_tracking": [
    {
      "id": 1,
      "tracking_number": "1Z999AA1234567890",
      "courier_provider": "ups",
      "tracking_status": "in_transit",
      "estimated_delivery": "2024-01-20",
      "created_at": "2024-01-15 10:30:00",
      "updated_at": "2024-01-16 14:20:00"
    },
    {
      "id": 2,
      "tracking_number": "1Z999BB9876543210",
      "courier_provider": "dhl",
      "tracking_status": "delivered",
      "estimated_delivery": "2024-01-18",
      "created_at": "2024-01-16 09:15:00",
      "updated_at": "2024-01-18 16:45:00"
    }
  ]
}
```

== Frequently Asked Questions ==

= How do I set up the API key? =

Go to WooCommerce > Fuuffy Integration and set a secure API key. Share this key with Fuuffy.com users who need to access your order data.

= What order data is shared with Fuuffy.com? =

The API provides comprehensive order information including customer details, shipping addresses, product information, and any existing tracking data.

= How are tracking numbers updated? =

Fuuffy.com can update tracking numbers via the REST API. These updates are automatically added to WooCommerce order notes and stored in the database.

= Can I customize the order data format? =

Yes, developers can use WordPress filters to modify the order data format. The plugin also supports multiple tracking numbers per order.

= Is the API secure? =

Yes, all API endpoints require authentication via the X-API-Key header. Only users with the correct API key can access your order data.

== Screenshots ==

1. API settings page
2. Tracking overview dashboard
4. Activity logs and monitoring

== Changelog ==

= 1.0.0 =
* Initial release
* Comprehensive REST API for Fuuffy.com integration
* Multiple tracking numbers support per order
* Full CRUD operations for tracking management
* Enhanced order details page with edit/delete tracking
* Comprehensive logging and monitoring
* Admin dashboard for API management
* Support for custom product fields (HS codes, origin country)

== Upgrade Notice ==

= 1.0.0 =
Initial release of Fuuffy Integration for WooCommerce.

== Developer Information ==

= Hooks and Filters =

Developers can use WordPress filters to customize the order data format sent to Fuuffy.com.

= Database Tables =

* `wp_fuufinfo_tracking` - Tracking information storage
* `wp_fuufinfo_api_log` - API activity logging

= REST API Authentication =

Include the `X-API-Key` header with your configured API key for all requests.

== Support ==

For support and documentation, visit our website or contact our support team. We provide integration assistance for connecting with Fuuffy.com.