A Developer\'s Tutorial for Integrating the CNFans Spreadsheet Product Verification API

Integrate the CNFans Spreadsheet API to automatically verify product links, check seller reputation, and assess risk for items from Taobao, Weidian, and 1688.

A Developer's Tutorial for Integrating the CNFans Spreadsheet Product Verification API

What is the CNFans Product Authenticity Verification API?

The CNFans Product Authenticity Verification API is a powerful programmatic interface designed for developers, spreadsheet curators, and platform managers. Its primary function is to automate the validation of product links from popular Chinese e-commerce platforms like Taobao, Weidian, and 1688. Instead of manually checking each link for validity, stock status, or seller credibility, you can use the API to retrieve structured, real-time data.

This tool is built for anyone who manages large volumes of product links and requires a reliable method for quality control. By integrating this API, you can programmatically fetch crucial information such as product names, prices, seller ratings, and stock availability. A key feature is the proprietary cnfans_risk_assessment, which provides an immediate quality signal for each item, helping you curate more trustworthy and up-to-date product lists for your audience.

The core benefits of using the API include a massive reduction in manual labor, significant improvement in data accuracy, and the ability to enrich your spreadsheets or applications with valuable metadata. This automation ensures your users have a better experience by minimizing their exposure to dead links, out-of-stock items, or untrustworthy sellers.

Getting Started: Prerequisites for API Integration

Before making your first API call, a few preliminary steps are necessary to ensure a smooth integration process. This involves obtaining your unique authentication key and preparing your development environment with the right tools.

Securing Your CNFans API Key

Your API Key is a unique token that authenticates your requests to our servers. It is essential for accessing the API and must be kept confidential. To get your key, you must have an account with cnfan-spreadsheet.com.

Follow these steps to locate your key:

Register or Log In: Visit the official CNFans Spreadsheet website and create an account or log in to your existing one.
Navigate to the Developer Dashboard: Once logged in, find the "Developer" or "API" section in your account dashboard.
Generate Your Key: In the API section, you will find an option to generate or view your unique API key. Copy this key and store it securely. You will need it for every request you make.

Treat your API key like a password. Do not expose it in client-side code or public repositories.

Essential Developer Tools and Environment Setup

The CNFans API is language-agnostic, meaning you can interact with it using any programming language that can make HTTP requests. However, some tools make the process easier.

Programming Language: Python (with the `requests` library) and JavaScript (with `axios` or the native `fetch` API on Node.js) are excellent choices due to their simplicity and strong community support for web requests.
Code Editor: A modern code editor like Visual Studio Code or Sublime Text will help you write and manage your code efficiently.
API Testing Tool (Optional): Tools like Postman or Insomnia are highly recommended for testing API endpoints without writing any code. They allow you to easily construct requests, set headers, and view responses, which is invaluable for debugging. You can also use the command-line tool cURL for quick tests.

How to Implement the CNFans Verification API: A Step-by-Step Tutorial

With your API key and environment ready, you can now start interacting with the API. The process involves sending a product URL to a specific endpoint and parsing the JSON data that is returned.

Understanding the API Endpoints

The API provides two primary endpoints for verifying products. Each is designed for a different use case: one for single, on-demand checks and another for processing multiple items simultaneously.

Endpoint	HTTP Method	Description
`/api/verify/single`	POST	Verifies a single product URL sent in the request body.
`/api/verify/batch`	POST	Verifies a list of up to 50 product URLs in a single request.

Making Your First API Call: Single Product Verification

Let's begin by verifying a single product. This requires a POST request to the /api/verify/single endpoint. You must include your API key in the `Authorization` header and the product URL in the JSON body.

Your request header should look like this:

Authorization: Bearer YOUR_API_KEY

Replace `YOUR_API_KEY` with the key you obtained earlier. The request body should be a JSON object containing the URL:

{
  "product_url": "https://item.taobao.com/item.htm?id=1234567890"
}

Python Example using `requests`

import requests
import json

api_key = 'YOUR_API_KEY'
product_url = 'https://item.taobao.com/item.htm?id=1234567890'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

data = {
    'product_url': product_url
}

response = requests.post(
    'https://cnfan-spreadsheet.com/api/verify/single',
    headers=headers,
    data=json.dumps(data)
)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

JavaScript (Node.js) Example using `axios`

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const productUrl = 'https://item.taobao.com/item.htm?id=1234567890';

const config = {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
};

const data = {
  product_url: productUrl
};

axios.post('https://cnfan-spreadsheet.com/api/verify/single', data, config)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(`Error: ${error.response.status}`);
    console.error(error.response.data);
  });

Interpreting the API Response

A successful request will return a `200 OK` status code and a JSON object containing detailed information about the product. Understanding this data is key to leveraging the API's full potential.

Sample JSON Response:

{
  "status": "success",
  "data": {
    "product_name": "Example T-Shirt",
    "price": "99.00",
    "currency": "CNY",
    "seller_name": "Example Seller Store",
    "seller_rating": "4.9",
    "stock_status": "in_stock",
    "main_image_url": "https://img.taobao.com/...",
    "cnfans_risk_assessment": "low"
  }
}

Here is a breakdown of the key fields in the response:

Field	Type	Description
`product_name`	String	The title or name of the product listing.
`price`	String	The current price of the product in its local currency.
`seller_name`	String	The name of the seller's store.
`seller_rating`	String	The seller's feedback score or rating.
`stock_status`	String	Indicates availability (e.g., 'in_stock', 'out_of_stock', 'unknown').
`cnfans_risk_assessment`	String	CNFans' proprietary risk analysis. Values can be 'low', 'medium', or 'high', based on factors like seller history and product validity.

Advanced Integration: Batch Verification and Error Handling

Once you are comfortable with single verifications, you can move on to more efficient and robust implementations. This involves processing products in bulk and creating logic to handle potential API errors.

How to Efficiently Verify Multiple Products in Bulk

The /api/verify/batch endpoint is designed to maximize efficiency. It allows you to send an array of up to 50 product URLs in a single request, significantly reducing the number of HTTP calls and network latency. The request body should be a JSON object with a `product_urls` key containing an array of strings.

Batch Request Body Format:

{
  "product_urls": [
    "https://item.taobao.com/item.htm?id=123",
    "https://weidian.com/item.html?itemID=456",
    "https://detail.1688.com/offer/789.html"
  ]
}

The API will respond with an array of objects, where each object corresponds to a URL from the request. This allows you to process results for your entire spreadsheet in a few calls rather than one by one.

A Practical Approach to API Error Codes

Building resilient software requires anticipating and handling errors. The CNFans API uses standard HTTP status codes to communicate the outcome of a request. Your application should be designed to interpret these codes and react accordingly.

Status Code	Meaning	Recommended Action
`400 Bad Request`	The request was malformed. This could be due to an invalid URL or incorrect JSON format.	Check the URL format and ensure your JSON is valid before retrying.
`401 Unauthorized`	Your API key is missing, invalid, or expired.	Verify that you are using the correct API key and that it is included in the `Authorization` header.
`429 Too Many Requests`	You have exceeded the API rate limit.	Implement a backoff strategy (e.g., wait a few seconds before retrying) and consider optimizing your calls.
`500 Internal Server Error`	An unexpected error occurred on our servers.	This is a temporary issue. Wait a moment and retry the request.

Leveraging the CNFans API for Superior Spreadsheet Management

Integrating the API transforms a static spreadsheet into a dynamic, intelligent database. By automating data validation and enrichment, you provide immense value to your users. Imagine a system where dead links are automatically flagged for removal, and new, high-quality items from reputable sellers are highlighted. That is the power the CNFans API provides.

You can set up a scheduled script (e.g., a cron job) that runs daily to process all the links in your spreadsheet. Use the stock_status field to hide or remove out-of-stock items, ensuring your list is always fresh. The cnfans_risk_assessment is particularly powerful; you can use it to create a tiered quality system, filtering out high-risk items and promoting low-risk ones. This elevates the quality and trustworthiness of your platform, setting you apart from the competition. By integrating the CNFans API, you can transform your manual spreadsheet into a dynamic, self-updating, and trustworthy resource for your users, powered by CNFans' robust data infrastructure.

Frequently Asked Questions

What are the API rate limits?: Rate limits are specified in the API documentation on the CNFans Spreadsheet developer portal. They are designed to ensure stable performance for all users. If you exceed the limit, you will receive a 429 Too Many Requests error.
Which e-commerce platforms are supported for verification?: The API currently supports product link verification for Taobao, Weidian, and 1688. We are continuously working to expand our platform support.
Is there a cost associated with using the API?: Please refer to the developer section on cnfan-spreadsheet.com for the latest information on API usage tiers and any associated costs.
How is the `cnfans_risk_assessment` calculated?: The risk assessment is a proprietary score generated by our system. It analyzes multiple data points, including seller history, store ratings, product listing quality, and other signals, to provide a simple 'low', 'medium', or 'high' risk rating.