API v3 & Security

The SALESmanago API allows developers to extend the platform's functionality and integrate with virtually any 3rd party software.

Authentication Mechanism

All API v3 requests require a JSON header for authentication.

Required Credentials

1. Client ID: Your unique account identifier.
2. API Secret: A 32-character string used to sign requests.
3. Owner Email: The email address of the account administrator.

Request Format

curl -X POST [https://app.salesmanago.com/api/v3/contact/upsert](https://app.salesmanago.com/api/v3/contact/upsert) \
     -H "Content-Type: application/json" \
     -d '{
           "apiKey": "YOUR_API_KEY",
           "apiSecret": "YOUR_SECRET",
           "owner": "admin@domain.com",
           "contact": { "email": "dev@example.com" }
         }'

Security Best Practices

• Rotate Secrets: We recommend changing your API secret every 90 days.
• Server-to-Server: Never call the API from the frontend (client-side) as it exposes your apiSecret.
• Error Handling: Always implement logic to handle 503 (Service Unavailable) errors by retrying the request after a short delay (Exponential Backoff).

Security Warning

Exposing your apiSecret in client-side JavaScript can lead to unauthorized access to your entire database. Always keep API interactions on the server side.

Rate Limits

Plan	Limit
Professional	1,000 requests / hour
Enterprise	10,000 requests / hour
Custom	Tailored to your needs

API v3: Sending External Events

To track specific user actions—like adding a product to a cart or completing a purchase—you must send an External Event to the SALESmanago API. This data is critical for triggering abandoned cart workflows and calculating ROI.

Example: Purchase Event Request

{
  "apiKey": "550e8400-e29b-41d4-a716-446655440000",
  "apiSecret": "s3cr3t_v4lu3",
  "contact": {
    "email": "customer@example.com"
  },
  "event": {
    "type": "LOCATION_ENTRY", // (1)
    "details": "Downtown Flagship Store",
    "parameters": {
      "lat": 52.2297,
      "lon": 21.0122, // (2)
      "radius": "100m"
    }
  }
}

1. Event Type: This string identifies the action. Common values include PURCHASE, CART, and VISIT.

2. Unique Identifier: The email address is the primary key. If the contact does not exist, the system will create a new profile automatically.

3. Numerical Value: The total order value. Do not include currency symbols here; use the separate currency field.

Requirement

For annotations to render correctly, ensure your mkdocs.yml includes the pymdownx.annotate extension under the markdown_extensions section.

---