Public API: Scanner

The Scanner public API allows querying product information using an access token. It's ideal for mobile applications, barcode scanners, or external systems that need to query products.

Endpoint

GET /api/public/scanner

Authentication

The API uses a Scanner Token unique per company for authentication.

Get Scanner Token

1. Log in to Sarah
2. Go to Settings > Integrations
3. Find your Scanner Token
4. Copy it and save it securely

Important: Don't share your Scanner Token publicly.

Parameters

Request

Basic Example

http
GET /api/public/scanner?token=scanner_token_abc123&query=1234567890123

Example with Company ID

http
GET /api/public/scanner?token=scanner_token_abc123&query=1234567890123&companyId=42

Response

Success (200)

json
{
  "product": {
    "id": 123,
    "name": "Example Product",
    "description": "Product description",
    "BC": "1234567890123",
    "base_price": 1500.00,
    "photo": "https://example.com/photo.jpg",
    "mark": "Example Brand",
    "category_id": 5,
    "enable": true
  },
  "alternatives": [
    {
      "id": 124,
      "name": "Alternative Product",
      "BC": "1234567890124",
      "base_price": 1600.00
    }
  ]
}

Product Not Found (200)

json
{
  "product": null,
  "alternatives": []
}

Errors

Missing token (400):

json
{
  "error": "Missing required parameter: token"
}

Missing query (400):

json
{
  "error": "Missing required parameter: query"
}

Invalid token (401):

json
{
  "error": "Invalid token"
}

Company not found (404):

json
{
  "error": "Company not found"
}

Search Logic

The API searches products in the following order:

1. Exact barcode search: If query exactly matches BC, returns that product
2. Name search: If no exact match, searches products whose name contains query
3. Alternative products: If there's an exact match, also returns similar products (same brand or category)

Search Example

Request:

http
GET /api/public/scanner?token=abc123&query=1234567890123

Processing:

1. Search product with BC = "1234567890123" → Found
2. Returns that product + alternatives

Request:

http
GET /api/public/scanner?token=abc123&query=Product

Processing:

1. Search product with BC = "Product" → Not found
2. Search products with name LIKE "%Product%" → Found several
3. Returns first + alternatives

Product Fields

Use Cases

1. Mobile Scanner Application

javascript
async function scanProduct(barcode) {
  const response = await fetch(
    `https://sarah.ar/api/public/scanner?token=${SCANNER_TOKEN}&query=${barcode}`
  );
  const data = await response.json();
  
  if (data.product) {
    displayProduct(data.product);
    if (data.alternatives.length > 0) {
      showAlternatives(data.alternatives);
    }
  } else {
    showNotFound();
  }
}

2. Query Terminal

javascript
async function searchProduct(query) {
  const response = await fetch(
    `https://sarah.ar/api/public/scanner?token=${SCANNER_TOKEN}&query=${encodeURIComponent(query)}`
  );
  return await response.json();
}

3. External System Integration

python
import requests

def get_product_info(token, barcode):
    url = "https://sarah.ar/api/public/scanner"
    params = {
        "token": token,
        "query": barcode
    }
    response = requests.get(url, params=params)
    return response.json()

Security

Access Token

• Scanner Token is unique per company
• Only allows querying products (read)
• Doesn't allow modifying data
• Can be regenerated from settings

Validation

• Token is validated against database
• Only returns products from associated company
• Only returns enabled products (enable = true)

Rate Limiting

Consider implementing rate limiting in your application to prevent abuse.

Get Company Information

Endpoint

GET /api/public/scanner/company

Parameters

Response

json
{
  "name": "My Company",
  "logo_url": "https://example.com/logo.png"
}

Usage:

javascript
async function getCompanyInfo() {
  const response = await fetch(
    `https://sarah.ar/api/public/scanner/company?token=${SCANNER_TOKEN}`
  );
  const data = await response.json();
  displayCompanyLogo(data.logo_url);
  displayCompanyName(data.name);
}

Best Practices

1. Cache results: Cache frequently queried products
2. Handle errors: Implement error handling for failed requests
3. Validate input: Validate query before sending
4. Use HTTPS: Always use HTTPS in production
5. Protect token: Never expose token in frontend code
6. Implement retry: Retry failed requests with exponential backoff

Troubleshooting

Error: "Invalid token"

1. Verify token: Ensure it's correct
2. Regenerate token: If necessary, regenerate from Settings
3. Verify company: Ensure company exists

Product not found

1. Verify code: Ensure barcode is correct
2. Verify it's enabled: Only products with enable = true are returned
3. Try with name: Try searching by name instead of code

Slow request

1. Verify connection: Ensure you have good connection
2. Implement cache: Cache frequently queried products
3. Optimize searches: Use barcodes when possible (faster)

Additional Resources

• Products API - Internal API for products
• Public Scanner - Scanner web interface

Support

If you need help:

1. Verify token is correct
2. Review API logs
3. Contact Sarah support with error details