# Supafolio API Complete Documentation

## Overview

Supafolio is a proprietary book metadata management service developed by Supadu specifically for the publishing industry. It specializes in ingesting ONIX (Online Information Exchange) data and transforming it into web-friendly content for publisher websites, stores, and marketing pages.

### Key Features
- **ONIX Integration**: Native support for ONIX 2.1 & 3.0 data formats
- **Publishing Industry Focus**: Specialized features for books, authors, and publishers
- **Managed Service**: No infrastructure maintenance required
- **Real-time Updates**: Automatic daily data refresh by default
- **Metadata Enrichment**: Add supplementary data beyond ONIX standards
- **Dynamic Collections**: Create custom collections on-the-fly
- **SEO Optimization**: Built-in SEO features for book discovery
- **Multi-currency Support**: Price display in multiple currencies

## Authentication

### Method: Header-Based Authentication

```bash
curl -H "x-apikey: {api_key}" \
  "https://api.supafolio.com/v2/{endpoint}"
```

#### Configuration in Supapress Plugin

```php
function supapress_call_supafolio($service, $params, $properties = array(), $cacheCalls = true) {
    // Base URL configuration
    if ((string)get_option('service_url') !== '') {
        $baseUrl = rtrim(get_option('service_url'), '/') . '/';
    } else {
        $baseUrl = SUPAPRESS_DEFAULT_SERVICE_URL;
    }
    
    // API key configuration
    if ((string)get_option('api_key') !== '') {
        $api = trim(get_option('api_key'));
    } else {
        $api = SUPAPRESS_DEFAULT_SERVICE_API;
        $baseUrl .= 'v2/';
    }
    
    // HTTP request via WordPress HTTP API
    $response = wp_remote_post($url, array(
        'method'      => 'GET',
        'timeout'     => 45,
        'redirection' => 5,
        'httpversion' => '1.0',
        'blocking'    => true,
        'headers'     => array('x-apikey' => $api),
        'body'        => array(),
        'cookies'     => array()
    ));
}
```

#### Required Settings
- **`api_key`**: Supafolio API authentication key
- **`service_url`**: Custom API endpoint URL (optional)
- **Default API Key**: `9819864f6ff0e8a5a097c99224cfd18a`
- **Default URL**: `https://api.supafolio.com/v2/`

## Complete API Endpoints Reference

### 1. Search Endpoint

**Endpoint**: `GET /v2/search`

**Purpose**: Primary search operation for finding books based on various criteria.

#### Complete Parameter Reference

| Parameter | Required | Description | Default | Example |
|------------|----------|-------------|---------|
| `keyword` | no | Search term for text matching | `"javascript programming"` |
| `isbns` | no | Comma-separated ISBN list | `"9781234567890,9780987654321"` |
| `collection` | no | Collection name filter | `"fiction"` |
| `amount` | no | Results count (default: 10) | `100` |
| `page` | no | Page number (default: 1) | `2` |
| `order` | no | Sort order (default: relevance) | `publishdate-desc` |
| `format` | no | Format filter | `"hardback"` |
| `publisher` | no | Publisher name filter | `"Penguin Random House"` |
| `imprint` | no | Imprint name filter | `"Penguin Classics"` |
| `series` | no | Series name filter | `"Harry Potter"` |
| `category` | no | Category name filter | `"Science Fiction"` |
| `from_date` | no | Publication date range start | `"2024-01-01"` |
| `to_date` | no | Publication date range end | `"2024-12-31"` |
| `from` | no | Alternative date range start | `"2024-01-01"` |
| `to` | no | Alternative date range end | `"2024-12-31"` |
| `award_winner` | no | Award winner filter | `"true"` |
| `starts_with` | no | Title prefix filter | `"Java"` |
| `exclude_imprint` | no | Exclude specific imprint | `"Classic Books"` |
| `exclude_category` | no | Exclude specific category | `"Academic"` |
| `distinct` | no | Return distinct results | `"true"` |
| `primary_format` | no | Primary format filter | `"paperback"` |
| `guides` | no | Guide filter | `"teacher"` |
| `age` | no | Age range filter | `"adult"` |
| `contributor` | no | Contributor filter | `"John Smith"` |
| `title` | no | Title filter | `"JavaScript"` |
| `type` | no | Product type filter | `"book"` |

#### Advanced Parameters (from shortcode attributes)

| Parameter | Description | Example |
|------------|-------------|---------|
| `include_price` | Include additional format prices | `"true"` |
| `include_promo_price` | Include promotional prices | `"true"` |
| `search_type` | Search type specification | `"author"` |
| `ignore_primary_format` | Return all format rules | `"true"` |
| `series_data` | Include series information | `"true"` |
| `imprint_data` | Include imprint information | `"true"` |
| `publisher_data` | Include publisher information | `"true"` |
| `category_data` | Include category information | `"true"` |
| `locale` | Set locale | `"en_US"` |
| `role` | Filter by author role | `"author"` |
| `get_parent_tree` | Get category parent tree | `"true"` |

#### Sort Order Options

| Option | Description | Example |
|---------|-------------|---------|
| `relevance` | Default relevance ranking | Default |
| `publishdate-desc` | Newest to oldest | `publicationDate:desc` |
| `publishdate-asc` | Oldest to newest | `publicationDate:asc` |
| `title-az` | Title A to Z | `title:asc` |
| `title-za` | Title Z to A | `title:desc` |
| `price-asc` | Price low to high | `price:asc` |
| `price-desc` | Price high to low | `price:desc` |
| `contributor-az` | Contributor A to Z | `contributor:asc` |
| `contributor-za` | Contributor Z to A | `contributor:desc` |

#### Sample Request
```bash
curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/search?keyword=javascript&isbns=9781234567890,9780987654321&amount=20&order=publishdate-desc"
```

#### Sample Response
```json
{
  "status": "success",
  "data": {
    "search": [
      {
        "isbn13": "9781234567890",
        "isbn10": "1234567890",
        "title": "JavaScript: The Good Parts",
        "authors": [
          {
            "name": "Douglas Crockford"
          }
        ],
        "publicationDate": {
          "date": "2014-05-15 00:00:00",
          "timezone": "UTC"
        },
        "saleDate": {
          "date": "2014-06-01 00:00:00", 
          "timezone": "UTC"
        },
        "prices": [
          {
            "locale": "USD",
            "amount": 29.99,
            "discount": 0.00
          },
          {
            "locale": "GBP",
            "amount": 19.99,
            "discount": 10.00
          }
        ],
        "image": "https://example.com/covers/js-good-parts.jpg",
        "formats": [
          {
            "format": {
              "name": "Hardcover",
              "format_id": 1
            },
            "isbn": "9781234567890"
          }
        ],
        "publisher": {
          "name": "O'Reilly Media",
          "id": 123
        },
        "imprint": {
          "name": "O'Reilly Professional",
          "id": 456
        },
        "series": [
          {
            "series": {
              "name": "JavaScript Series",
              "id": 789
            }
          }
        ],
        "categories": [
          {
            "category": {
              "name": "Programming",
              "id": 456,
              "parent_id": 123
            }
          }
        ]
      }
    ],
    "pagination": {
      "results": {
        "amount": 1,
        "total": 1
      },
      "pages": {
        "current": 1,
        "total": 1
      }
    }
  }
}
```

### 2. Predictive Search Endpoint

**Endpoint**: `GET /v2/predictive`

**Purpose**: Autocomplete/search suggestions for user input.

#### Parameters

| Parameter | Required | Description | Default |
|------------|----------|-------------|---------|
| `keyword` | yes | Search term for suggestions | `"javascript"` |
| `amount` | no | Number of suggestions | `10` |
| `type` | no | Product type | `"Products"` |

#### Sample Request
```bash
curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/predictive?keyword=javascript&amount=10&type=Products"
```

#### Sample Response
```json
{
  "status": "success",
  "data": {
    "predictive": [
      {
        "isbn13": "9781234567890",
        "title": "JavaScript: The Definitive Guide",
        "image": "https://example.com/covers/js-definitive-guide.jpg"
      }
    ]
  }
}
```

### 3. Search Filter Endpoint

**Endpoint**: `GET /v2/searchfilter`

**Purpose**: Retrieve available filter values for dynamic navigation.

#### Parameters

| Parameter | Required | Description | Example |
|------------|----------|-------------|---------|
| `filters` | yes | Filter type | `"format"` |

#### Sample Requests

```bash
# Get format filters
curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/searchfilter?filters=format"

# Get collection filters
curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/searchfilter?filters=collection"

# Get multiple filter types
curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/searchfilter?filters=format,collection,publisher"
```

#### Sample Response
```json
{
  "status": "success",
  "data": {
    "filters": {
      "format": {
        "values": [
          {
            "name": "Hardcover",
            "seo_name": "hardcover",
            "count": 1234
          },
          {
            "name": "Paperback", 
            "seo_name": "paperback",
            "count": 987
          },
          {
            "name": "Ebook",
            "seo_name": "ebook",
            "count": 456
          }
        ]
      }
    }
  }
}
```

### 4. Book Details Endpoint

**Endpoint**: `GET /v2/book/{isbn}`

**Purpose**: Retrieve comprehensive information for a specific book.

#### Parameters
All search parameters are supported for book details, including:
- `include_price`, `include_promo_price`
- `series_data`, `imprint_data`, `publisher_data`, `category_data`
- `locale`, `role`, `get_parent_tree`

#### Sample Request
```bash
curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/book/9781234567890?include_price=true&series_data=true"
```

### 5. Bulk Operations

The search endpoint supports bulk operations through:
- Multiple ISBN specification in `isbns` parameter
- High `amount` values (up to several hundred)

#### Bulk ISBN Lookup
```bash
curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/search?isbns=9781234567890,9780987654321,9781111111111,9782222222222&amount=200"
```

## Complete Data Schema

### Book Object Structure

```json
{
  "book": {
    "isbn13": "string (13-digit ISBN)",
    "isbn10": "string (10-digit ISBN)", 
    "title": "string (full title)",
    "subtitle": "string (subtitle/edition)",
    "description": "string (full description)",
    "summary": "string (brief summary)",
    "seo": "string (SEO-optimized title)",
    "date": {
      "date": "YYYY-MM-DD HH:MM:SS",
      "timezone": "string (UTC by default)"
    },
    "saleDate": {
      "date": "YYYY-MM-DD HH:MM:SS", 
      "timezone": "string"
    },
    "prices": [
      {
        "locale": "USD|GBP|CAD|AUD|NZD|EUR|JPY",
        "amount": "number (decimal)",
        "discount": "number (decimal)"
      }
    ],
    "image": "url (cover image URL)",
    "formats": [
      {
        "format": {
          "name": "string",
          "format_id": "number"
        },
        "isbn": {
          "isbn": "string" | "string"
        }
      }
    ],
    "contributors": [
      {
        "contributor": {
          "name": "string",
          "bio": "string (author biography)",
          "seo": "string (SEO-friendly name)"
        }
      }
    ],
    "publisher": {
      "name": "string",
      "id": "number"
    },
    "imprint": {
      "name": "string",
      "id": "number"
    },
    "series": [
      {
        "series": {
          "name": "string",
          "id": "number"
        }
      }
    ],
    "categories": [
      {
        "category": {
          "name": "string",
          "id": "number",
          "parent_id": "number"
        }
      }
    ],
    "collections": [
      {
        "collection": {
          "name": "string", 
          "id": "number"
        }
      }
    ],
    "assets": [
      {
        "asset": {
          "type": "string",
          "sub_type": "string",
          "path": "string", 
          "width": "number",
          "height": "number"
        }
      }
    ],
    "trim": {
      "width": "number",
      "height": "number", 
      "depth": "number",
      "unit": "string"
    },
    "weight": {
      "weight": "number",
      "weight_unit": "string"
    },
    "pages": "number",
    "edition": "string",
    "awards": [
      {
        "award": {
          "name": "string",
          "id": "number"
        }
      }
    ],
    "reviews": [
      {
        "review": {
          "description": "string"
        }
      }
    ],
    "retailers": [
      {
        "label": "string",
        "path": "string", 
        "seo": "string"
      }
    ]
  },
  "pagination": {
    "results": {
      "amount": "number",
      "total": "number"
    },
    "pages": {
      "current": "number", 
      "total": "number"
    }
  },
  "filters": {
    "{filter_name}": {
      "values": [
        {
          "name": "string",
          "seo_name": "string", 
          "count": "number"
        }
      ]
    }
  }
}
```

### Industry-Specific Features

#### ONIX Data Support
- **Format Versions**: ONIX 2.1 & 3.0 support
- **Field Mapping**: Automatic ONIX to web field conversion
- **Code Lists**: Standard publishing industry codes
- **Validation**: ONIX compliance checking

#### Publishing Workflow Integration
- **Title Management**: Automatic title overrides
- **Collection Management**: Dynamic collection creation
- **Business Rules**: Custom pricing and availability rules
- **Territorial Rights**: Region-specific content management
- **Metadata Enrichment**: Add video, audio, supplementary content

#### Multi-Currency Support
```json
"prices": [
  {
    "locale": "USD",
    "amount": 29.99,
    "discount": 5.00
  },
  {
    "locale": "GBP", 
    "amount": 24.99,
    "discount": 10.00
  },
  {
    "locale": "EUR",
    "amount": 27.99,
    "discount": 0.00
  }
]
```

#### Retailer Integration
```json
"retailers": [
  {
    "label": "Amazon",
    "path": "https://amazon.com/dp/{isbn}",
    "seo": "amazon-com"
  },
  {
    "label": "Barnes & Noble",
    "path": "https://bn.com/dp/{isbn}",
    "seo": "barnes-noble-com"
  }
]
```

## Advanced Features

### Caching System

#### WordPress Integration
```php
// Cache key generation
$cacheKey = supapress_get_cache_prefix() . md5($url . $api);

// Object caching
if (supapress_is_object_caching()) {
    return get_site_transient($cacheKey, $data, $lifetime);
}

// File-based caching
if (supapress_is_file_caching()) {
    $path = supapress_cache_get_file_path($cacheKey);
    return file_put_contents($path, gzdeflate(json_encode($data)));
}
```

#### Cache Configuration
| Setting | Description | Default |
|----------|-------------|---------|
| Object Caching | Uses WordPress object cache | Enabled if available |
| File Caching | Compressed JSON files | Fallback if no object cache |
| Default Lifetime | 24 hours (DAY_IN_SECONDS) | Configurable per widget type |
| Cache Prefix | `spcache-` | Rotating for cache invalidation |

### Error Handling

#### Standard Response Format
```json
{
  "status": "error",
  "data": {
    "errors": [
      {
        "message": "Error description"
      }
    ]
  }
}
```

#### Common Error Messages
- `"Product not in database"` - ISBN not found
- `"Something went wrong: {error}"` - Generic error with details
- `"No books found"` - Empty search results

### SEO Integration

#### Yoast SEO Overrides
```php
// Title override
add_filter('wpseo_title', function($title) use ($book) {
    return supapress_translate_template_text($text_template, $book);
});

// Description override  
add_filter('wpseo_metadesc', function($desc) use ($book) {
    return supapress_translate_template_text($desc_template, $book);
});

// Canonical URL override
add_filter('wpseo_canonical', function($url) use ($book) {
    return site_url() . supapress_translate_template_url($url_template, $book);
});
```

#### URL Template Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `%isbn13%` | 13-digit ISBN | `9781234567890` |
| `%isbn10%` | 10-digit ISBN | `1234567890` |
| `%title%` | Book title | `javascript-the-good-parts` |
| `%subtitle%` | Book subtitle | `advanced-concepts` |
| `%author%` | Author name | `douglas-crockford` |
| `%publisher%` | Publisher name | `oreilly-media` |
| `%price_usd%` | USD price | `29.99` |
| `%discount_usd%` | USD discount | `5.00` |
| `%price_gbp%` | GBP price | `24.99` |
| `%discount_gbp%` | GBP discount | `10.00` |

## Performance Characteristics

### Request Limits
- **Timeout**: 45 seconds per request
- **Redirection**: 5 redirects maximum
- **HTTP Version**: 1.0
- **Rate Limiting**: Managed by Supafolio service

### Optimization Strategies
- **Bulk Operations**: Use ISBN lists for efficiency
- **Caching**: Leverage built-in WordPress caching
- **Selective Fields**: Use `include_*` parameters wisely
- **Pagination**: Implement proper page navigation
- **Filter Early**: Apply filters before full-text search

## Security Features

### Authentication Security
- **Header-based**: API key sent in HTTP headers (not URL parameters)
- **HTTPS Required**: All requests use secure protocol
- **Input Validation**: WordPress sanitization functions applied

### Data Privacy
- **Managed Service**: Supafolio handles data privacy and compliance
- **Industry Standards**: ONIX format compliance
- **GDPR Considerations**: Built-in data protection features

## Integration Examples

### WordPress Shortcode

```php
[supapress type="isbn_lookup" 
    isbns="9781234567890,9780987654321"
    amount="50"
    include_price="true"
    series_data="true"]
```

### JavaScript Integration

```javascript
// AJAX search request
fetch('/wp-admin/admin-ajax.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
        action: 'supapress_search',
        keyword: 'javascript',
        amount: 20,
        widget_id: '123'
    })
})
.then(response => response.json())
.then(data => {
    // Process search results
});
```

---

**Generated**: 2026-01-24  
**Supafolio Version**: v2.26.2  
**Supapress Plugin**: v2.26.2