# AI Integration Hub



# Build With Donutwork, Faster

This page is the main entry point for AI-assisted integration on Donutwork.
If your team uses Codex or other AI copilots, start here to reduce implementation time, lower scope mistakes, and ship production-ready integrations faster.

## Why This Matters

* Faster onboarding with a pre-packaged integration skill.
* Clear endpoint-to-scope mapping for least-privilege access.
* Field-level entity models for safer payload implementation.
* Repeatable go-live checklist for reliable releases.

## Official AI Integration Assets

* Donutwork Skill (latest): [`/downloads/donutwork-skill-latest.tar.gz`](/downloads/donutwork-skill-latest.tar.gz)
* Checksum (latest): [`/downloads/donutwork-skill-latest.sha256`](/downloads/donutwork-skill-latest.sha256)
* Donutwork Claude Code skill (latest): [`/downloads/donutwork-claude-code-skill-latest.skill`](/downloads/donutwork-claude-code-skill-latest.skill)
* Claude Code checksum (latest): [`/downloads/donutwork-claude-code-skill-latest.sha256`](/downloads/donutwork-claude-code-skill-latest.sha256)
* OpenAPI snapshot: [`/openapi.json`](/openapi.json)
* AI full context bundle: [`/llms-full.txt`](/llms-full.txt)
* AI quick index: [`/llms.txt`](/llms.txt)

## Install In 60 Seconds

```bash
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
tar -xzf donutwork-skill-latest.tar.gz -C "${CODEX_HOME:-$HOME/.codex}/skills"
```

Then invoke:

```text
Use $donutwork to design my integration plan.
```

## Claude Code Setup

```bash
unzip -o donutwork-claude-code-skill-latest.skill -d "$HOME"
```

Optional integrity check:

```bash
sha256sum -c donutwork-claude-code-skill-latest.sha256
```

## What You Get With `$donutwork`

* Endpoint plan by feature (method, path, purpose).
* Required OAuth/API scopes by endpoint.
* Entity payload model guidance with required fields.
* Ready-to-use request examples.
* Launch checklist for staging and production.

## Recommended First Prompts

1. `Use $donutwork to map scopes for customers, charges, and webhooks.`
2. `Use $donutwork to generate payload models for customer and subscription sync.`
3. `Use $donutwork to produce a production go-live checklist for our integration.`

## Next Step

Go to the full skill documentation:

* [Donutwork Codex Skill](/en/docs/applications/donutwork-skill)
* [Donutwork Claude Code Skill](/en/docs/applications/donutwork-claude-code-skill)


# Introduction



import { Card, Cards } from 'fumadocs-ui/components/card';
import { BarChart3, CreditCard, ShieldCheck, Layout, Users, Workflow } from 'lucide-react';

# Welcome to Donutwork

Donutwork is a comprehensive SaaS platform designed to help you manage your business efficiently. Whether you are managing customers, partners, or recurring payments, Donutwork provides the tools you need to scale.

## What is Donutwork?

Donutwork simplifies the complex operations of running a SaaS by providing a unified interface for:

* **Customer Management**: Track and engage with your user base.
* **Partner Programs**: Manage affiliates and revenue sharing.
* **Subscription Billing**: Automate recurring payments and invoicing.
* **Analytics**: Gain deep insights into your business performance.

## Platform Areas

<Cards>
  <Card icon={<CreditCard className="text-green-500" />} title="Recurring Payments" href="/en/docs/recurring-payments" description="Run subscriptions, seat pricing, lifecycle changes, and renewal calculations with predictable rules." />

  <Card icon={<BarChart3 className="text-blue-500" />} title="BI & Growth" href="/en/docs/bi-growth" description="Track MRR/ARR, revenue mix, and growth dynamics to guide commercial decisions." />

  <Card icon={<ShieldCheck className="text-rose-500" />} title="Sentinel Security" href="/en/docs/sentinel" description="Protect accounts with adaptive MFA, risk scoring, and identity controls." />

  <Card icon={<Layout className="text-amber-500" />} title="Dynamic Content" href="/en/docs/dynamic-content-modeling" description="Model custom schemas and manage content through structured, reusable entries." />

  <Card icon={<Users className="text-indigo-500" />} title="Partner Program" href="/en/docs/partner-program" description="Configure partner groups, commission logic, and payout-ready growth models." />

  <Card icon={<Workflow className="text-cyan-500" />} title="Applications & Workflow" href="/en/docs/applications" description="Integrate third-party applications and automate business logic with workflow orchestration." />
</Cards>

***

## Recommended First Path

1. Start with [Recurring Payments](/en/docs/recurring-payments) to define your monetization baseline.
2. Configure [Customer Management](/en/docs/customer) for profile, billing, and transaction operations.
3. Enable [Sentinel Security](/en/docs/sentinel) to harden authentication and risk controls.
4. Activate [Email Gateway](/en/docs/email-gateway) and [Workflow](/en/docs/workflow) for communication automation.
5. Use [BI & Growth](/en/docs/bi-growth) to validate outcomes and iterate on pricing and retention.

## Target Audience

This documentation is specifically tailored for **Business Users** (Founders, Product Managers, Customer Success, and Sales) to help you get the most out of the platform without needing technical expertise.

## AI Integration Entry Point

If you are integrating Donutwork with AI copilots or autonomous coding agents, start from:

* [AI Integration Hub](/en/docs/ai-integration)


# Authentication



import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';

# Authentication

The Donutwork API uses API Keys to authenticate requests. You can view and manage your API keys in the Donutwork Dashboard.

## Authorization Header

All API requests must include your API Key in the `Authorization` HTTP header as a Bearer token.

```http
Authorization: Bearer <your_api_key>
```

<Callout type="warn">
   Your API keys carry significant privileges. Keep them secure and never expose them in client-side code or public repositories. 
</Callout>

## Obtaining an API Key

Donutwork is currently in a controlled rollout phase. Access is granted to partners and early adopters through the following process:

<Steps>
  <Step>
    ### Request Access

    Submit a request to the Donutwork team outlining your integration use case.
  </Step>

  <Step>
    ### Review & Provisioning

    Our team will review your requirements and provision the necessary environments.
  </Step>

  <Step>
    ### Environment Keys

    Upon approval, you will be provided with distinct keys for:

    * **Staging**: For development, testing, and sandbox experimentation.
    * **Production**: For live, customer-facing traffic.
  </Step>
</Steps>

## Connectivity and Health Checks

Use these endpoints to validate your authentication credentials and monitor API availability.

### System Ping

Verify the operational status of the Donutwork API environment.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/ping.json"
  responses={[ 
  { 
    status: "200 OK", 
    description: "API is operational and responding.", 
    content: { "status": "success", "env": "production", "RRT": "0.08 ms" } 
  }, 
  { 
    status: "401 Unauthorized", 
    description: "Invalid or revoked API key.", 
    content: { "error": "Invalid token" } 
  } 
]}
/>

### Connection Metadata

Retrieve detailed information about your current connection, including client IP and protocol negotiation.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/connection.json"
  responses={[ 
  { 
    status: "200 OK", 
    description: "Connection metadata retrieved successfully.", 
    content: {
      "client": {
        "userAgent": "axios/1.6.0",
        "ips": { "ipv4": "192.168.1.1" }
      },
      "endpoint": {
        "apiVersion": "2026-02-01",
        "env": "production",
        "protocol": "HTTP3"
      }
    } 
  } 
]}
/>


# Company



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Company

The Company API allows you to retrieve metadata about your own organization and lookup public data for third-party companies using VAT identifiers.

***

## Get Company Profile

Retrieve the core configuration and identification attributes for your company profile. This includes your unique internal identifier and official registered name.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/company.json"
  responses={[
  { 
    status: "200 OK", 
    description: "Company profile retrieved successfully.",
    content: {
      "id": "668ea32f5485467fd7149f48",
      "name": "Acme Corp"
    } 
  }
]}
/>

***

## List Active Modules

Discover and monitor the status of functional modules enabled for your organization. Each module represents a specific capability (e.g., Recurring Payments, Email Gateway) along with its configuration and activation state.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/company/modules.json"
  responses={[
  { 
    status: "200 OK", 
    description: "List of organizational modules.",
    content: [
      {
          "id": "recurring-payments",
          "description": "Automated subscription billing and payment orchestration.",
          "price": 0,
          "active": true
      },
      {
          "id": "email-gateway",
          "description": "Transactional email delivery via unified REST interface.",
          "price": 0,
          "active": true
      },
      {
          "id": "geoip",
          "description": "IPv4 geolocation and regional metadata resolution.",
          "price": 0,
          "active": true
      }
    ] 
  }
]}
/>

***

## Company Intelligence Stats

Retrieve the company intelligence snapshot used by operational dashboards. This endpoint returns KPI data, usage widgets, revenue chart aggregates, and metadata for the current company context.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/company/stats/intelligence.json"
  responses={[
  { 
    status: "200 OK", 
    description: "Company intelligence payload retrieved.",
    content: {
      "kpi": {
        "mrr_growth": { "raw_percent": 12.3, "display_label": "12.30%" },
        "total_customers": 120,
        "active_subscriptions": 93
      },
      "usage": {
        "banner": { "show": false, "status": null, "upgrade_url": null },
        "widgets": []
      },
      "recent_activity": [],
      "revenue_chart": {
        "graph": [],
        "stats": { "one_shot": 0, "subscriptions": 0, "total": 0 }
      },
      "revenue_insights": {
        "visible": false,
        "net_revenue": 0,
        "tax_total": 0,
        "discounts_total": 0,
        "services": [],
        "top_services": []
      },
      "meta": {
        "company_id": "668ea32f5485467fd7149f48",
        "year": 2026,
        "month": 4,
        "generated_at": "2026-04-15T10:00:00+00:00"
      }
    } 
  }
]}
/>

***

## Lookup Registered Company (Open Data)

Retrieve public business information for a company using its VAT number. This is particularly useful for automating KYC (Know Your Customer) workflows and ensuring data accuracy during customer onboarding.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/company/{vatNumber}.json"
  params={[
  { name: "vatNumber", type: "string", required: true, description: "The VAT registration number of the target company.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Public company data found.",
    content: {
      "vatNumber": "IT12345678901",
      "name": "Example Solutions S.r.l.",
      "address": "Corso Vittorio Emanuele II, 1, 00186 Roma RM, Italy",
      "vies_interrogation": { "valid": true }
    } 
  },
  { 
    status: "404 Not Found", 
    description: "No data available for the specified VAT number.",
    content: { "error": "Company not found" } 
  }
]}
/>


# Currency



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Currency

The Currency API provides programmatic access to platform-supported monetary denominations and enables precision-grade currency conversion based on Donutwork's centralized exchange data.

***

## List Enabled Currencies

Retrieve the full collection of ISO 4217 currency codes supported by the platform.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/currencies.json"
  responses={[
  { 
    status: "200 OK", 
    description: "List of supported ISO 4217 currency codes (uppercase).",
    content: ["EUR", "USD", "GBP"] 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "NODEJS"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/currencies.json' \
    --header 'Authorization: Bearer YOUR_API_KEY'
    ```
  </Tab>

  <Tab value="NODEJS">
    ```js
    const currencies = await sdk.currency.list();
    console.table(currencies);
    ```
  </Tab>
</Tabs>

***

## Perform Currency Conversion

Execute a real-time conversion between two supported currencies.\
The response field `amount` is the converted value, not the original request amount.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/currencies/{fromCurrency}/{toCurrency}.json"
  params={[
  { name: "fromCurrency", type: "string", required: true, description: "The source ISO currency code (e.g., EUR).", location: "path" },
  { name: "toCurrency", type: "string", required: true, description: "The target ISO currency code (e.g., USD).", location: "path" }
]}
  body={{
  "amount": 100.00
}}
  properties={[
  { name: "amount", type: "number", required: false, description: "The monetary value to be converted. Defaults to `0` when omitted." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Conversion successfully processed.",
    content: {
      "from": "EUR",
      "to": "USD",
      "rate": 1.085,
      "amount": 108.5
    } 
  },
  { 
    status: "400 Bad Request", 
    description: "Unsupported base or destination currency code.",
    content: { "error": "Invalid currency passed" } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "NODEJS"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request POST \
    'https://api.hub.donutwork.com/2026-02-01/currencies/EUR/USD.json' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --data '{"amount": 100}'
    ```
  </Tab>

  <Tab value="NODEJS">
    ```js
    const conversion = await sdk.currency.convert("EUR", "USD", 100);
    console.log(`Converted: ${conversion.amount} ${conversion.to} @ rate ${conversion.rate}`);
    ```
  </Tab>
</Tabs>


# Customers



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Customers

The Customer API is the central hub for managing your client base. It allows you to synchronize your internal CRM data, manage billing profiles, and monitor subscription health across your organization.

***

## List All Customers

Retrieve a paginated collection of customers associated with your organization. This endpoint is ideal for dashboard overviews and batch synchronization processes.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers.json"
  params={[
  { name: "size", type: "integer", required: false, description: "The number of customer records to return per page (maximum 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "The specific results page to retrieve.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "A paginated list of customers.",
    content: {
      "entities": "Customer",
      "count": 150,
      "per_page": 100,
      "pages": { "current": 1, "max": 2 },
      "elements": [
        {
          "id": "67248941cbe2b1ff8b099a6c",
          "external_id": "CRM-UID-9921",
          "company_name": "Global Logistics S.A.",
          "email": "billing@globallogistics.com"
        }
      ]
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "NODEJS"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/customers.json?size=20' \
    --header 'Authorization: Bearer YOUR_API_KEY'
    ```
  </Tab>

  <Tab value="NODEJS">
    ```js
    const customers = await sdk.customers.list({ size: 20 });
    console.table(customers.elements);
    ```
  </Tab>
</Tabs>

***

## Create a New Customer

Initialize a new customer profile. This is the prerequisite step for attaching subscriptions or processing one-time charges. High-quality data at this stage ensures accurate tax calculation and communication delivery.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/customers.json"
  body={{
  "customer": {
      "company_name": "Acme Corporation",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@acme.com",
      "externalId": "CRM-UID-9921",
      "address": {
          "country": "US",
          "city": "San Francisco",
          "address": "123 Market St"
      }
  }
}}
  properties={[
  { name: "customer.company_name", type: "string", required: true, description: "Official legal name of the organization." },
  { name: "customer.email", type: "string", required: true, description: "Primary contact email for billing and notifications." },
  { name: "customer.first_name", type: "string", required: true, description: "Contact person's first name." },
  { name: "customer.last_name", type: "string", required: true, description: "Contact person's last name." },
  { name: "customer.address.country", type: "string", required: true, description: "ISO 3166-1 alpha-2 country code (e.g., US, IT)." },
  { name: "customer.externalId", type: "string", required: false, description: "Your internal system identifier for cross-referencing." },
  { name: "customer.address.city", type: "string", required: false, description: "City of residence or incorporation." },
  { name: "customer.address.address", type: "string", required: false, description: "Street address including number." },
  { name: "customer.address.postal_code", type: "string", required: false, description: "Postal or ZIP code." },
  { name: "customer.address.state", type: "string", required: false, description: "State, province, or region." },
  { name: "customer.address.vat_number", type: "string", required: false, description: "Tax identifier for business entities." },
  { name: "customer.properties", type: "array", required: false, description: "Custom metadata fields for specialized integration logic." },
  { name: "customer.partner.id", type: "string", required: false, description: "Donutwork identifier for a referring partner." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Customer profile successfully created.",
    content: { "customer": { "id": "67c9...", "partner": null } } 
  },
  { 
    status: "409 Conflict", 
    description: "A profile with this email or externalId already exists.",
    content: { "error": "A customer already exists with this email" } 
  }
]}
/>

***

## Retrieve Customer Details

Fetch the complete profile for a specific customer. This includes organizational metadata, contact information, and summarized subscription status.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Complete customer profile retrieved.",
    content: {
      "id": "672489...",
      "email": "jane.doe@acme.com",
      "company_name": "Acme Corporation",
      "externalId": "CRM-UID-9921"
    } 
  }
]}
/>

***

## Search by External Identifier

Locate a customer profile using your internal system's identifier (externalId). This is essential for maintaining synchronization between Donutwork and your primary CRM/ERP.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/customer.json"
  params={[
  { name: "externalId", type: "string", required: true, description: "The unique identifier from your internal system.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Customer profile found.",
    content: {
      "id": "672489...",
      "email": "jane.doe@acme.com",
      "externalId": "CRM-UID-9921"
    } 
  },
  { 
    status: "404 Not Found", 
    description: "No customer matches the provided externalId.",
    content: { "error": "This customer does not exist" } 
  }
]}
/>

***

## Update Customer Profile

Modify an existing customer record. This endpoint supports partial updates (PATCH-style behavior); only the fields included in the request body will be modified. This is useful for updating contact information or adding organizational tags.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  body={{
  "customer": {
      "email": "updated.contact@acme.com",
      "tags": ["enterprise", "priority-support"]
  }
}}
  properties={[
  { name: "customer.email", type: "string", required: false, description: "The updated primary contact email." },
  { name: "customer.first_name", type: "string", required: false, description: "Updated first name." },
  { name: "customer.last_name", type: "string", required: false, description: "Updated last name." },
  { name: "customer.company_name", type: "string", required: false, description: "Updated legal company name." },
  { name: "customer.tags", type: "array", required: false, description: "A collection of labels for internal classification and reporting." },
  { name: "customer.address.country", type: "string", required: false, description: "Updated ISO country code." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Customer profile successfully updated.",
    content: { "customer": { "id": "6724..." } } 
  }
]}
/>

***

## Decommission Customer Profile

Permanently remove a customer profile and all associated metadata. This action is destructive and irreversible. Ensure that all active subscriptions are terminated before choosing to decommission a profile.

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/customers/{customerId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  responses={[
  { 
    status: "202 Accepted", 
    description: "Deletion request accepted and queued for processing.",
    content: { "id": "67c9...", "deleted": true } 
  }
]}
/>

***

## Customer Properties (Metadata)

Extend the customer profile with custom key-value pairs. Properties are ideal for storing domain-specific data, integration identifiers, or specialized configuration flags that are not captured by standard profile fields.

### Retrieve All Properties

Fetch the complete set of custom metadata associated with a customer.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/properties.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Collection of customer-specific properties retrieved.",
    content: {
      "count": 2,
      "type": "CustomerProperties",
      "elements": {
        "crm_segment": "enterprise",
        "onboarding_status": "completed"
      }
    } 
  }
]}
/>

### Atomic Update/Insert (Upsert) Properties

Update existing property values or append new keys to the customer's property collection. This endpoint performs an "upsert" operation; keys that do not exist will be created, and existing keys will have their values overwritten.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/properties.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  body={{
  "CustomerProperties": {
    "support_tier": "platinum",
    "preferred_language": "en"
  }
}}
  properties={[
  { name: "CustomerProperties", type: "object", required: true, description: "An object containing the key-value pairs to persist." }
]}
  responses={[
  { 
    status: "202 Accepted", 
    description: "Properties successfully updated.",
    content: { 
      "customer": { "id": "6724..." },
      "CustomerProperties": {
          "support_tier": "platinum",
          "preferred_language": "en"
      }
    } 
  }
]}
/>

***

## Secure Hosted Payment Link

Generate a unique, short-lived URL for the Donutwork Hosted Payment Page. This secure interface allow customers to update their sensitive payment information (e.g., Credit Card, SEPA Mandate) without sensitive data passing through your servers.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/payment_link.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Secure payment link generated.",
    content: { "url": "https://pay.donutwork.com/l/xxxxxxxxxx" } 
  }
]}
/>

***

## Subscription Management

Manage recurring billing cycles and plan associations for your customers. Subscriptions automate the generation of invoices and payment processing based on predefined logic.

### List Active and Historical Subscriptions

Retrieve a collection of all subscription entities associated with a customer, including active, canceled, and past-due states.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "A list of customer subscriptions.",
    content: {
      "type": "CustomerSubscriptions",
      "elements": [
        {
          "id": "sub_123",
          "name": "Enterprise SaaS Plan",
          "status": "success",
          "next_renew": "2026-04-01",
          "price": { "amount": 499.00, "vat": { "percentage": 22, "name": "IVA" } }
        }
      ]
    } 
  }
]}
/>

### Attach New Subscription

Provision a new subscription for a customer. This endpoint allows for runtime overrides of plan defaults, such as custom discounts and initial addon quantities.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  body={{
  "subscription": {
    "id": "PLAN_PREMIUM_V2",
    "taxes": "TAX_STANDARD_22",
    "global_discount": { "value": 15, "type": "percentage" },
    "addons": [
      { "element": "api_quota", "quantity": 10000 }
    ]
  }
}}
  properties={[
  { name: "subscription.id", type: "string", required: true, description: "The identifier of the target plan." },
  { name: "subscription.taxes", type: "string", required: true, description: "The tax profile ID to apply to this subscription." },
  { name: "subscription.global_discount.value", type: "number", required: false, description: "The absolute or percentage value of the discount." },
  { name: "subscription.global_discount.type", type: "string", required: false, description: "The type of discount: 'percentage' or 'amount'." },
  { name: "subscription.addons", type: "array", required: false, description: "A list of addon overrides with their respective quantities." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Subscription successfully provisioned.",
    content: { "id": "sub_67c9...", "status": "active" } 
  }
]}
/>

### Detach Subscription

Detach a subscription from the customer profile.

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID to remove from the customer.", location: "path" }
]}
  responses={[
  { 
    status: "202 Accepted", 
    description: "Subscription detached from customer profile.",
    content: { "id": "sub_67c9...", "deleted": true } 
  }
]}
/>

### Retrieve Subscription Status

Read the operational status of a specific customer subscription.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/status.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Current status for the selected subscription.",
    content: { "id": "sub_123", "status": "active", "next_renew": "2026-05-01" } 
  },
  {
    status: "404 Not Found",
    description: "Subscription does not exist for the specified customer.",
    content: { "error": "This subscription does not exists for this customer" }
  }
]}
/>

### Modify Subscription Status

Manually transition a subscription between operational states. This is typically used for administrative overrides or manual churn management.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/status.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  body={{ "subscription": { "status": "dismiss" } }}
  properties={[
  { name: "subscription.status", type: "string", required: true, description: "Target status. Supported values: `active`, `dismiss`." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Status successfully updated.",
    content: { "id": "sub_123", "status": "dismiss", "next_renew": null } 
  }
]}
/>

***

### Advanced Subscription Lifecycle (Additive)

These endpoints extend subscription lifecycle management without replacing existing legacy routes.
Use them when you need pause/resume, plan amendments, scheduled changes, and proration-aware updates.

#### Read Extended Lifecycle State

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/lifecycle.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Extended lifecycle metadata for the subscription.",
    content: {
      "id": "sub_123",
      "status": "success",
      "lifecycle_status": "active",
      "cancel_at_period_end": false,
      "scheduled_change": null,
      "carryover_credit": 0
    } 
  }
]}
/>

#### Pause, Resume, Cancel-at-Period-End

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/pause.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  body={{
  "lifecycle": {
    "idempotency_key": "lifecycle-evt-001"
  }
}}
  properties={[
  { name: "lifecycle.idempotency_key", type: "string", required: false, description: "Optional idempotency key for safe retries." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Lifecycle transition applied.",
    content: {
      "id": "sub_123",
      "lifecycle_status": "paused",
      "amendment": { "action": "pause", "status": "applied" }
    } 
  }
]}
/>

Use the same payload model with:

* `.../lifecycle/resume.json`
* `.../lifecycle/cancel-at-period-end.json`
* `.../lifecycle/undo-cancel-at-period-end.json`

Pause/resume billing behavior:

* No retroactive automatic billing is created when resuming after a long pause.
* If resumed two months later (for example pause on **May 1, 2026** and resume on **July 1, 2026**), renewal is re-anchored to the resume date (or future `resume_at` if provided).

Undo-cancel behavior:

* If a subscription is `cancel_pending`, you can revert it to `active` before renewal boundary.
* Plan/addons remain the current ones on the subscription; cancellation flag is removed.

#### Change Plan or Addons with Immediate/Scheduled Application

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-plan.json"
  body={{
  "lifecycle": {
    "plan_id": "PLAN_ENTERPRISE_V3",
    "taxes": "TAX_STANDARD_22",
    "when": "period_end",
    "proration": true
  }
}}
  properties={[
  { name: "lifecycle.plan_id", type: "string", required: true, description: "Target plan identifier." },
  { name: "lifecycle.taxes", type: "string", required: false, description: "Tax profile override." },
  { name: "lifecycle.when", type: "string", required: false, description: "`immediate` (default) or `period_end`." },
  { name: "lifecycle.proration", type: "boolean", required: false, description: "Enable or disable proration logic." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Plan change accepted (immediate or scheduled).",
    content: {
      "id": "sub_123",
      "scheduled_change": { "type": "plan", "apply_on": "2026-06-01" },
      "amendment": { "action": "change_plan", "status": "applied" }
    } 
  }
]}
/>

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-addons.json"
  body={{
  "lifecycle": {
    "addons": [
      { "element": "workspace_seat", "quantity": 25 }
    ],
    "when": "immediate",
    "proration": true
  }
}}
  responses={[
  { 
    status: "200 OK", 
    description: "Addon amendment applied with optional proration.",
    content: {
      "id": "sub_123",
      "carryover_credit": 18.5,
      "amendment": { "action": "change_addons", "status": "applied" }
    } 
  }
]}
/>

#### Proration Preview (No Mutation)

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/preview.json"
  body={{
  "lifecycle": {
    "action": "change_addons",
    "addons": [
      { "element": "workspace_seat", "quantity": 40 }
    ]
  }
}}
  responses={[
  { 
    status: "200 OK", 
    description: "Economic preview of the amendment without persisting changes.",
    content: {
      "action": "change_addons",
      "proration": { "old_due": 499, "new_due": 679, "delta": 180, "direction": "debit" }
    } 
  }
]}
/>

#### Amendment History

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/amendments.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Max entries per page (1-100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Paginated amendment stream for audit and support operations.",
    content: {
      "type": "CustomerSubscriptionAmendments",
      "elements": [
        { "action": "change_addons", "when": "immediate", "status": "applied" }
      ]
    } 
  }
]}
/>

### Backward Compatibility

Lifecycle endpoints are **additive and opt-in**.
Existing integrations can keep using current routes unchanged.

| Area                     | Legacy Contract        | Lifecycle Extension                              |
| :----------------------- | :--------------------- | :----------------------------------------------- |
| Attach/Detach            | Unchanged              | Still valid                                      |
| Status route             | Unchanged payload keys | Additional lifecycle visibility                  |
| Addons route             | Unchanged              | Optional proration-aware lifecycle change-addons |
| Usage/metering           | Unchanged              | Unchanged                                        |
| Existing panel/API flows | Unchanged              | New actions available when explicitly called     |

***

### Subscription Addons

Manage the quantity of modular features (addons) attached to a specific subscription. Addons allow for flexible, feature-based pricing.

#### Audit Addon Quantities

Retrieve a list of all addons currently active on a subscription along with their provisioned quantities.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/addons.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "List of provisioned addons.",
    content: [
      { "element": "compute_units", "quantity": 10 },
      { "element": "secondary_domains", "quantity": 2 }
    ] 
  }
]}
/>

#### Reconcile Addon Quantities

Update the provisioned quantities for one or more addons. This operation is additive or disruptive based on the provided quantity values.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/addons.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  body={{
  "addons": [
    { "element": "compute_units", "quantity": 15 }
  ]
}}
  properties={[
  { name: "addons", type: "array", required: true, description: "Addon collection to upsert." },
  { name: "addons[].element", type: "string", required: true, description: "Addon identifier." },
  { name: "addons[].quantity", type: "integer", required: true, description: "Requested addon quantity." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Addon quantities successfully updated.",
    content: { "status": "updated" } 
  }
]}
/>

***

### Simulation Interface (Sandbox Only)

Accelerate development cycles by simulating subscription lifecycle events in non-production environments.

#### Simulate Success Event

Force a successful renewal or provisioning event for a subscription.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/simulate/{subscriptionId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  responses={[
  { status: "200 OK", content: { "status": "simulated_success" } }
]}
/>

#### Simulate Failure Event

Force a failed renewal or payment rejection event.

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/simulate/{subscriptionId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  responses={[
  { status: "200 OK", content: { "status": "simulated_failure" } }
]}
/>

***

## Metered Usage Tracking

For subscriptions with `metering: true`, consumption must be reported via these endpoints. Usage is aggregated and billed at the end of the current billing cycle.

### Report Usage Event

Record a new consumption event (e.g., API requests, data processed, seats occupied). Each record requires a unique `externalId` to prevent idempotent replay errors.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  body={{
  "usage": {
    "amount": 10.50,
    "value": 100,
    "value_type": "api_requests",
    "externalId": "evt_unique_uuid_123"
  }
}}
  properties={[
  { name: "usage.amount", type: "number", required: true, description: "The monetary value or unit count to bill." },
  { name: "usage.value", type: "number", required: true, description: "The raw consumption value." },
  { name: "usage.value_type", type: "string", required: true, description: "The metric identifier (e.g., 'storage_gb', 'api_calls')." },
  { name: "usage.externalId", type: "string", required: true, description: "A unique identifier for idempotency." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Usage successfully recorded.",
    content: { "id": "usage_67c9...", "amount": 10.50 } 
  }
]}
/>

### Audit Usage History

Retrieve a paginated history of all usage events reported for a specific subscription.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Paginated usage history retrieved.",
    content: { "type": "CustomerSubscriptionUsages", "elements": [] } 
  }
]}
/>

***

## Ad-hoc Charges

Charges represent immediate, non-recurring billable events created independently of a subscription's billing cycle (e.g., setup fees, professional services).

### Create One-Time Charge

Generate an ad-hoc charge. If the `capture` flag is set to `true`, the system will immediately attempt to authorize and capture the funds using the customer's primary payment method.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/customers/{customerId}/charges.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" }
]}
  body={{
  "charge": {
    "capture": true,
    "services": [
      { "name": "Technical Consulting", "amount": 250.00, "taxProfile": "TAX_SERVICES_22" }
    ]
  }
}}
  properties={[
  { name: "charge.capture", type: "boolean", required: false, description: "Whether to attempt immediate payment capture." },
  { name: "charge.services", type: "array", required: true, description: "A list of line items included in the charge." },
  { name: "charge.instruction", type: "string", required: false, description: "Payment instruction (e.g., 'sepa_debit', 'manual')." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Charge created and payment status returned.",
    content: { "status": "success", "id": "ch_777", "captured": true } 
  }
]}
/>

### List Organizational Charges

Retrieve all charges (including pending and failed attempts) associated with a specific customer profile.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/charges.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "List of customer-specific charges.",
    content: { "type": "CustomerCharges", "elements": [] } 
  }
]}
/>

### Charge Details and Reconciliation

Retrieve detailed metadata for a specific charge, including its internal lifecycle state and tax calculations.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/charges/{chargeId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "chargeId", type: "string", required: true, description: "The unique charge identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Full charge metadata.",
    content: {
      "id": "ch_777",
      "customer_id": "cust_123",
      "total": 305.00,
      "type": "one-shot",
      "status": "paid",
      "statuses": { "pending": false, "paid": true, "refunded": false },
      "date": { "date": "2026-03-01 10:00:00.000000", "timezone": "+00:00" }
    } 
  }
]}
/>

### External Invoice Synchronization

Manage links to external accounting systems (e.g., Fatture in Cloud) for each charge.

#### Retrieve Invoice Metadata

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/charges/{chargeId}/invoice.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "chargeId", type: "string", required: true, description: "The unique charge identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Invoice synchronization details.",
    content: { "number": "INV-2026-001", "date": "2026-03-01", "source": "accounting-system", "link": "https://docs.acme.com/inv/123.pdf" } 
  }
]}
/>

#### Persist Invoice Metadata

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/charges/{chargeId}/invoice.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "chargeId", type: "string", required: true, description: "The unique charge identifier.", location: "path" }
]}
  body={{
  "invoice": {
    "number": "INV-2026-001",
    "date": "2026-03-01",
    "source": "erp-system",
    "link": "https://erp.example.com/invoices/991.pdf"
  }
}}
  properties={[
  { name: "invoice.number", type: "string", required: true, description: "Invoice number." },
  { name: "invoice.date", type: "string", required: true, description: "Invoice issue date." },
  { name: "invoice.source", type: "string", required: false, description: "Originating source system identifier." },
  { name: "invoice.link", type: "string", required: false, description: "Public or internal URL to invoice document." }
]}
  responses={[
  { status: "200 OK", content: { "status": "success" } }
]}
/>

***

### Global Charge Resolution

Resolve charge details using only the global unique identifier. This is optimized for callback handlers and webhook reconciliation modules.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/charges/{chargeId}.json"
  params={[
  { name: "chargeId", type: "string", required: true, description: "The global unique identifier for the charge.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Charge metadata resolved globally.",
    content: { "id": "ch_777", "customer_id": "cust_123" } 
  }
]}
/>


# Directory Monitor



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Directory Monitor

The Directory Monitor API enables real-time synchronization and event orchestration for local filesystem changes. It is designed for deep integration with local agents to monitor project directories, capture file events, and trigger remote workflows.

***

## Initialize Monitor (Startup)

Signal the start of a monitoring session for a specific project. This initialization step validates the project configuration and prepares the environment for ingress events.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/directory-monitor/{projectId}.json"
  params={[
  { name: "projectId", type: "string", required: true, description: "The unique identifier for the monitored project.", location: "path" }
]}
  body={{
  "ingressToken": "DM_SECURE_TOKEN_XYZ"
}}
  properties={[
  { name: "ingressToken", type: "string", required: false, description: "Security token for ingress authentication (can also be sent via X-Directory-Monitor-Token header)." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Monitor successfully initialized.",
    content: { "status": "success", "projectId": "proj_123" } 
  }
]}
/>

***

## Synchronize Event (Ingress)

Report a filesystem event (creation, modification, deletion) to the centralized monitor. This endpoint processes file metadata and executes any associated workflow triggers.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/directory-monitor/{projectId}.json"
  params={[
  { name: "projectId", type: "string", required: true, description: "The project identifier.", location: "path" }
]}
  body={{
  "projectId": "proj_123",
  "filename": "src/controllers/UserController.php",
  "event": "modified",
  "filesize": 4096,
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "uid": 1000,
  "pid": 4512
}}
  properties={[
  { name: "projectId", type: "string", required: true, description: "Must match the projectId in the path." },
  { name: "filename", type: "string", required: true, description: "Relative path of the affected file." },
  { name: "event", type: "string", required: true, description: "Type of event (e.g., created, modified, deleted, renamed)." },
  { name: "filesize", type: "integer", required: true, description: "Size of the file in bytes." },
  { name: "filetype", type: "string", required: false, description: "MIME type or file classification." },
  { name: "sha256", type: "string", required: false, description: "SHA-256 hash of the file content for integrity verification." },
  { name: "uid", type: "integer", required: false, description: "User ID of the process owner." },
  { name: "pid", type: "integer", required: false, description: "Process ID that triggered the event." },
  { name: "timestampUtc", type: "string", required: false, description: "ISO 8601 timestamp of the local event." },
  { name: "ingressToken", type: "string", required: false, description: "Authentication token." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Event successfully ingested and indexed.",
    content: { 
      "status": "success", 
      "eventId": "evt_7721...", 
      "projectId": "proj_123", 
      "inserted": true,
      "workflowTriggered": true
    } 
  }
]}
/>

***

## Audit Monitor Events

Retrieve a paginated history of synchronized filesystem events for a specific project. This is used for auditing changes and verifying synchronization state.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/systems/directory-monitor/{projectId}/events.json"
  params={[
  { name: "projectId", type: "string", required: true, description: "The project identifier.", location: "path" },
  { name: "size", type: "integer", required: false, description: "Number of events to return (max 200).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Pagination page number.", location: "query" },
  { name: "event", type: "string", required: false, description: "Filter by event type (e.g., modified).", location: "query" },
  { name: "pathLike", type: "string", required: false, description: "Filter by partial file path.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Collection of project events retrieved.",
    content: {
      "status": "fetch",
      "projectId": "proj_123",
      "page": 1,
      "size": 50,
      "count": 120,
      "items": []
    } 
  }
]}
/>


# DNS



# DNS API

Use DNS endpoints for diagnostic and propagation checks across public resolvers.

## DNS Capabilities

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/dns/capabilities.json"
  responses={[
  {
    status: "200 OK",
    description: "Supported record types, default record types, and resolver catalog.",
    content: {
      "recordTypes": ["A", "AAAA", "CNAME", "TXT", "MX", "NS", "SOA", "CAA", "SRV"],
      "defaultRecordTypes": ["A", "AAAA", "CNAME", "TXT"],
      "resolvers": [
        { "id": "cloudflare_primary", "label": "Cloudflare (1.1.1.1)", "server": "1.1.1.1" },
        { "id": "google_primary", "label": "Google (8.8.8.8)", "server": "8.8.8.8" }
      ]
    }
  }
]}
/>

## DNS Lookup (GET)

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/dns/lookup.json"
  params={[
  { name: "target", type: "string", required: true, description: "Hostname or IP to resolve.", location: "query" },
  { name: "recordTypes", type: "array|string", required: false, description: "Record types list (for example A, MX, TXT).", location: "query" },
  { name: "resolverPreset", type: "array|string", required: false, description: "Resolver preset filter.", location: "query" },
  { name: "customResolvers", type: "string", required: false, description: "Space/comma separated custom resolvers.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "DNS lookup completed.",
    content: {
      "target": "example.com",
      "generated_at": "2026-04-15T10:00:00+00:00",
      "recordTypes": ["A", "AAAA"],
      "resolver_count": 2,
      "resolvers": [
        { "id": "cloudflare_primary", "label": "Cloudflare (1.1.1.1)", "server": "1.1.1.1" },
        { "id": "google_primary", "label": "Google (8.8.8.8)", "server": "8.8.8.8" }
      ],
      "propagation": {
        "A": { "is_consistent": true, "distinct_statuses": 1, "distinct_answers": 1 }
      },
      "queries": {
        "A": [
          {
            "resolver_label": "Cloudflare (1.1.1.1)",
            "resolver": "1.1.1.1",
            "record_type": "A",
            "status": "NOERROR",
            "server": "1.1.1.1#53",
            "query_time_ms": 12,
            "answers": [{ "name": "example.com.", "ttl": 300, "class": "IN", "type": "A", "value": "93.184.216.34" }],
            "answer_signature": "A|93.184.216.34",
            "error": null
          }
        ]
      }
    }
  },
  {
    status: "400 Bad Request",
    description: "Invalid or missing target.",
    content: { "error": "target is required" }
  }
]}
/>

## DNS Lookup (POST)

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/dns/lookup.json"
  body={{
  "target": "example.com",
  "recordTypes": ["A", "AAAA"],
  "resolverPreset": ["public"],
  "customResolvers": "1.1.1.1 8.8.8.8",
  "resolvers": ["9.9.9.9"]
}}
  properties={[
  { name: "target", type: "string", required: true, description: "Hostname or IP to resolve." },
  { name: "recordTypes", type: "array|string", required: false, description: "Record types list (for example A, MX, TXT)." },
  { name: "resolverPreset", type: "array|string", required: false, description: "Resolver preset filter." },
  { name: "customResolvers", type: "string", required: false, description: "Space/comma separated custom resolvers." },
  { name: "resolvers", type: "array", required: false, description: "Additional custom resolver list." }
]}
  responses={[
  {
    status: "200 OK",
    description: "DNS lookup completed.",
    content: {
      "target": "example.com",
      "generated_at": "2026-04-15T10:00:00+00:00",
      "recordTypes": ["A", "AAAA"],
      "resolver_count": 2,
      "resolvers": [
        { "id": "cloudflare_primary", "label": "Cloudflare (1.1.1.1)", "server": "1.1.1.1" },
        { "id": "google_primary", "label": "Google (8.8.8.8)", "server": "8.8.8.8" }
      ],
      "propagation": {
        "A": { "is_consistent": true, "distinct_statuses": 1, "distinct_answers": 1 }
      },
      "queries": {
        "A": [
          {
            "resolver_label": "Cloudflare (1.1.1.1)",
            "resolver": "1.1.1.1",
            "record_type": "A",
            "status": "NOERROR",
            "server": "1.1.1.1#53",
            "query_time_ms": 12,
            "answers": [{ "name": "example.com.", "ttl": 300, "class": "IN", "type": "A", "value": "93.184.216.34" }],
            "answer_signature": "A|93.184.216.34",
            "error": null
          }
        ]
      }
    }
  }
]}
/>


# Content Box



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Content Box API

The Content Box system provides a schematized storage layer for unstructured or custom-structured data. It allows organizations to define complex data models (Types) and instantiate them as managed content entities (Contents), suitable for blogs, product catalogs, and internal metadata repositories.

***

## Content Entity Management

Manage the lifecycle of data entries within your defined content structures.

### List Content Entities

Retrieve a paginated collection of content entities. Results can be filtered by state, content type, or via a full-text search query.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/contentbox/contents.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records to return (up to 100). Default is 50.", location: "query" },
  { name: "page", type: "integer", required: false, description: "The page index for pagination.", location: "query" },
  { name: "type_id", type: "string", required: false, description: "Filter by a specific Content Type ID.", location: "query" },
  { name: "state", type: "string", required: false, description: "Filter by lifecycle state (e.g., 'public', 'draft', 'archived').", location: "query" },
  { name: "search", type: "string", required: false, description: "Perform a text search across content titles and data fields.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Collection of content entities retrieved.",
    content: {
      "entities": "Contents",
      "count": 12,
      "per_page": 50,
      "elements": [
          {
              "id": "6768...",
              "type_id": "6751...",
              "title": "Q1 Product Launch",
              "state": "public",
              "data": {
                  "headline": "Introducing the 2026 Fleet",
                  "hero_image": "https://cdn.acme.com/img/l1.jpg",
                  "featured": true
              }
          }
      ]
    } 
  }
]}
/>

### Create Content Entity

Provision a new content entry. The `data` payload must adhere to the requirements of the associated `type_id`.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/contentbox/contents.json"
  body={{
  "content": {
      "title": "Annual Sustainability Report",
      "type_id": "675112233b498f30",
      "state": "draft",
      "data": {
          "period": "2025",
          "impact_score": 92
      }
  }
}}
  properties={[
  { name: "content.title", type: "string", required: true, description: "Internal-facing title for the content entry." },
  { name: "content.type_id", type: "string", required: true, description: "The unique identifier of the target Content Type schema." },
  { name: "content.state", type: "string", required: false, description: "Operational state (default: 'draft')." },
  { name: "content.data", type: "object", required: false, description: "Dictionary of custom fields defined in the type schema." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Content entity successfully provisioned.",
    content: { "id": "6768..." } 
  }
]}
/>

### Update Content Entity

Modify an existing content entry. This endpoint supports partial updates; only the fields provided in the `content` object will be modified.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/contentbox/contents/{contentId}.json"
  params={[
  { name: "contentId", type: "string", required: true, description: "The unique identifier of the content entry.", location: "path" }
]}
  body={{
  "content": {
      "state": "public",
      "data": {
          "revised_at": "2026-03-01T10:00:00Z"
      }
  }
}}
  properties={[
  { name: "content.title", type: "string", required: false, description: "Update the internal title." },
  { name: "content.state", type: "string", required: false, description: "Transition the lifecycle state." },
  { name: "content.data", type: "object", required: false, description: "Update specific keys within the data object." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Content entity successfully updated.",
    content: { "id": "6768...", "updated": true } 
  }
]}
/>

### Retrieve Content Entity

Fetch the full payload for a single content entry.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/contentbox/contents/{contentId}.json"
  params={[
  { name: "contentId", type: "string", required: true, description: "The unique identifier of the content entry.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Content entity retrieved.",
    content: { "id": "6768...", "title": "Q1 Product Launch", "state": "public", "data": {} } 
  },
  {
    status: "404 Not Found",
    description: "Content entry does not exist.",
    content: { "error": "Content Box not found" }
  }
]}
/>

### Decommission Content Entity

Permanently delete a content entry. This action is irreversible.

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/contentbox/contents/{contentId}.json"
  params={[
  { name: "contentId", type: "string", required: true, description: "The content identifier.", location: "path" }
]}
  responses={[
  { 
    status: "202 Accepted", 
    description: "Deletion request processed.",
    content: { "id": "6768...", "deleted": true } 
  }
]}
/>

***

## Content Type Modeling (Schema Definition)

Define and manage the structural blueprints that govern how content is stored and validated.

### List Content Types

Retrieve the catalog of all defined content schemas for your organization.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/contentbox/types.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Results per page.", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Collection of content type definitions.",
    content: { 
      "entities": "Types", 
      "count": 1, 
      "elements": [
        { "id": "6751...", "title": "Corporate Blog", "description": "Schema for official news", "fields": { "author": { "label": "Author", "type": "string" } } }
      ] 
    } 
  }
]}
/>

### Create Content Type

Define a new organizational schema. Specify the attributes and UI input types for each field in the model.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/contentbox/types.json"
  body={{ 
  "type": { 
    "title": "E-Commerce Product", 
    "description": "Standardized schema for catalog items.",
    "fields": {
      "sku": { "label": "SKU", "type": "string" },
      "price": { "label": "Unit Price", "type": "string" },
      "in_stock": { "label": "Inventory Status", "type": "checkbox" }
    }
  } 
}}
  properties={[
  { name: "type.title", type: "string", required: true, description: "Human-readable name for the schema." },
  { name: "type.description", type: "string", required: false, description: "Internal description of the schema's purpose." },
  { name: "type.fields", type: "object", required: true, description: "A map of field definitions (key -> {label, type})." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Content type definition created.",
    content: { "id": "6751...", "title": "E-Commerce Product" } 
  }
]}
/>

### Retrieve Type Definition

Fetch the precise structural definition for a specific content type.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/contentbox/types/{typeId}.json"
  params={[
  { name: "typeId", type: "string", required: true, description: "The unique identifier for the content type.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Full schema definition retrieved.",
    content: { "id": "6751...", "title": "Corporate Blog", "fields": {  } } 
  }
]}
/>

### Update Type Definition

Update metadata or fields for a specific content schema. When `fields` is provided, each field must include both `label` and `type` and use allowed input types.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/contentbox/types/{typeId}.json"
  params={[
  { name: "typeId", type: "string", required: true, description: "The unique identifier for the content type.", location: "path" }
]}
  body={{
  "type": {
    "title": "Corporate Blog",
    "description": "Schema for official company news",
    "fields": {
      "author": { "label": "Author", "type": "string" },
      "hero_image": { "label": "Hero Image", "type": "url" }
    }
  }
}}
  properties={[
  { name: "type.title", type: "string", required: false, description: "Updated schema title." },
  { name: "type.description", type: "string", required: false, description: "Updated schema description." },
  { name: "type.fields", type: "object", required: false, description: "Updated field map. Each field requires `label` and `type`." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Content type updated.",
    content: { "id": "6751...", "title": "Corporate Blog", "description": "Schema for official company news", "fields": {} } 
  },
  {
    status: "400 Bad Request",
    description: "Invalid fields payload or field type.",
    content: { "error": "Fields must be an associative array" }
  }
]}
/>


# Email Gateway



# Email Gateway API

The Email Gateway API manages template files and transactional sends.

***

## List Templates

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/email-gateway/templates.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index (starting from 1).", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Template list returned.",
    content: {
      "entities": "Email Templates",
      "count": 2,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "welcome.html",
          "endpoint": [
            {
              "type": "POST",
              "action": "Send email using this template",
              "url": "https://api.hub.donutwork.com/2026-02-01/email-gateway/welcome.html/send.json"
            }
          ]
        }
      ]
    }
  }
]}
/>

## Create Template

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/email-gateway/templates.json"
  body={{
  "template": {
    "id": "welcome.html",
    "content": "<h1>Hello FIRST_NAME</h1>"
  }
}}
  properties={[
  { name: "template.id", type: "string", required: true, description: "Template filename identifier." },
  { name: "template.content", type: "string", required: false, description: "Optional initial template content." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Template created.",
    content: { "id": "welcome.html" }
  },
  {
    status: "409 Conflict",
    description: "Template already exists.",
    content: { "error": "Template already exists" }
  }
]}
/>

## Get Template

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/email-gateway/templates/{templateId}.json"
  params={[
  { name: "templateId", type: "string", required: true, description: "Template identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Template returned.",
    content: {
      "id": "welcome.html",
      "content": "<h1>Hello FIRST_NAME</h1>"
    }
  },
  {
    status: "404 Not Found",
    description: "Template not found.",
    content: { "error": "Template not found" }
  }
]}
/>

## Update Template

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/email-gateway/templates/{templateId}.json"
  params={[
  { name: "templateId", type: "string", required: true, description: "Template identifier.", location: "path" }
]}
  body={{
  "template": {
    "content": "<h1>Hello FIRST_NAME</h1><p>Updated</p>"
  }
}}
  properties={[
  { name: "template.content", type: "string", required: true, description: "Template content to persist." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Template updated.",
    content: { "id": "welcome.html", "updated": true }
  }
]}
/>

## Delete Template

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/email-gateway/templates/{templateId}.json"
  params={[
  { name: "templateId", type: "string", required: true, description: "Template identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Template deleted.",
    content: { "id": "welcome.html", "deleted": true }
  }
]}
/>

## Preview Template

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/email-gateway/templates/{templateId}/preview.json"
  params={[
  { name: "templateId", type: "string", required: true, description: "Template identifier.", location: "path" }
]}
  body={{
  "preview": {
    "vars": {
      "first_name": "Alex"
    }
  }
}}
  properties={[
  { name: "preview.vars", type: "object", required: false, description: "Variables used for server-side placeholder rendering." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Rendered HTML preview returned.",
    content: {
      "template_id": "welcome.html",
      "html": "<h1>Hello Alex</h1>"
    }
  }
]}
/>

## Dispatch Transactional Email

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/email-gateway/{templateId}/send.json"
  params={[
  { name: "templateId", type: "string", required: true, description: "Template identifier.", location: "path" }
]}
  body={{
  "email": {
    "to": "recipient@example.com",
    "subject": "Operational Update",
    "from": "notifications@example.com",
    "cc": ["ops@example.com"],
    "vars": {
      "first_name": "Alex"
    },
    "attachments": [
      {
        "content": "SGVsbG8gd29ybGQ=",
        "filename": "summary.txt",
        "type": "text/plain"
      }
    ]
  }
}}
  properties={[
  { name: "email.to", type: "string", required: true, description: "Primary recipient email." },
  { name: "email.subject", type: "string", required: true, description: "Message subject." },
  { name: "email.from", type: "string", required: false, description: "Optional sender email from configured alternative senders." },
  { name: "email.cc", type: "array", required: false, description: "CC recipients." },
  { name: "email.bcc", type: "array", required: false, description: "BCC recipients." },
  { name: "email.vars", type: "object", required: false, description: "Template variables." },
  { name: "email.attachments", type: "array", required: false, description: "Attachments in base64 format." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Email accepted for delivery.",
    content: { "email": { "id": "msg_123" } }
  },
  {
    status: "404 Not Found",
    description: "Template not found.",
    content: { "error": "Template not found or empty" }
  }
]}
/>


# General



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# General API

The General API provides a set of infrastructure-level endpoints designed for environmental diagnostics and the retrieval of global static datasets. These tools are essential for verifying network reachability, inspecting client-server connection properties, and populating standardized geographic data across your application.

***

## Infrastructure Health (Ping)

A high-performance heartbeat endpoint used to verify that the DonutWork API gateway is operational and to measure basic network round-trip time (RTT).

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/ping.json"
  responses={[
  { 
    status: "200 OK", 
    description: "Gateway is responsive.",
    content: { 
      "status": "success", 
      "env": "production", 
      "RRT": "1.42 ms" 
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/ping.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    const heartbeat = await sdk.utils.ping();
    console.log(`System Status: ${heartbeat.status} (${heartbeat.RRT})`);
    ```
  </Tab>
</Tabs>

***

## Connection Diagnostics

Retrieve a detailed diagnostic profile of your current API session. This endpoint is instrumental for debugging network protocols, verifying IP whitelisting, and ensuring the correct API version is being targeted.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/connection.json"
  responses={[
  { 
    status: "200 OK", 
    description: "Diagnostics profile retrieved.",
    content: {
      "client": {
        "userAgent": "PostmanRuntime/7.43.0",
        "ips": { "ipv4": "192.168.1.1" }
      },
      "endpoint": {
        "apiVersion": "2026-02-01",
        "env": "production",
        "protocol": "HTTP2"
      }
    } 
  }
]}
/>

***

## Global Metadata (Countries)

Retrieve a comprehensive, standardized list of countries and their associated ISO 3166-1 alpha-2 codes. This dataset ensures data integrity when capturing geographic information in user profiles or billing addresses.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/countries/countries.json"
  responses={[
  { 
    status: "200 OK", 
    description: "Global country directory retrieved.",
    content: [
      { "code": "US", "name": "United States" },
      { "code": "GB", "name": "United Kingdom" },
      { "code": "IT", "name": "Italy" },
      { "code": "DE", "name": "Germany" },
      { "code": "FR", "name": "France" }
    ] 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/countries/countries.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    const countryList = await sdk.utils.listCountries();
    const italy = countryList.find(c => c.code === 'IT');
    console.log(`Country Name: ${italy.name}`);
    ```
  </Tab>
</Tabs>


# GeoIP (Location Services)



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# GeoIP API

The GeoIP API enables the resolution of IPv4 addresses into rich geographical and jurisdictional datasets. Beyond simple location coordinates, this service provides essential metadata—including currency systems, telecommunication prefixes, and linguistic profiles—enabling automated tax compliance (VAT/GST), regional content personalization, and fraud detection through threat-level auditing.

***

## Intelligence Resolution (Geo-Location)

Retrieve the full intelligence profile for a specific IPv4 address. This includes Autonomous System (AS) data, high-level geolocation, and localized jurisdictional metadata.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/geoip/ip.json"
  params={[
  { 
    name: "ip", 
    type: "string", 
    required: true, 
    description: "The targeted IPv4 address for resolution (e.g., 8.8.8.8).",
    location: "query"
  }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "IP intelligence profile successfully resolved.",
    content: {
      "requested_ip": "8.8.8.8",
      "geolocation": {
          "as_domain": "google.com",
          "as_name": "Google LLC",
          "asn": "AS15169",
          "continent": "NA",
          "country": "US",
          "country_name": "United States"
      },
      "country_metadata": {
          "name": "United States",
          "phone": [1],
          "capital": "Washington D.C.",
          "currency": ["USD", "USN", "USS"],
          "languages": ["en"]
      },
      "threats": ["proxy", "vpn"],
      "_credits": "IP address data powered by https://ipinfo.io"
    } 
  },
  { 
    status: "400 Bad Request", 
    description: "The provided IP address is malformed or resolution failed.",
    content: { "error": "Unable to get info for this IP Address" } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/geoip/ip.json?ip=8.8.8.8' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    const ipAddress = "8.8.8.8";
    try {
      const data = await sdk.geolocation.resolve(ipAddress);
      console.dir(data, { depth: null });
    } catch (error) {
      console.error(`Resolution Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **Business Context:** Use this data to automate tax profile selection for checkout flows or to enforce regional compliance for regulated digital services.
</Callout>


# Identity Provider (IDP) & MFA



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Identity Provider (IDP) API

The Identity Provider (IDP) service centralizes user identity management and provides robust secondary authentication layers. It allows organizations to link external user identifiers to a secure, managed identity capable of Multi-Factor Authentication (MFA) via Time-based One-Time Passwords (TOTP) and advanced risk assessment (Sentinel).

***

## Identity Management

### Provision External User

Provision a new managed identity within the IDP ecosystem. This creates a security context linked to your platform's internal `external_id`.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/idp/user.json"
  body={{
  "user": {
    "external_id": "ORG_USR_9921_AFG"
  }
}}
  properties={[
  { name: "user.external_id", type: "string", required: true, description: "Your system's unique identifier for the user (e.g., UUID or DB ID)." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "User identity successfully provisioned.",
    content: {
      "user": {
          "id": "6908bffd...",
          "external_id": "ORG_USR_9921_AFG",
          "status": "active"
      }
    } 
  },
  { 
    status: "409 Conflict", 
    description: "Identity already exists for the specified external_id.",
    content: { "error": "User with this external_id already exists for this company" } 
  }
]}
/>

### Retrieve Identity Profile

Fetch the security profile for a specific user. This includes authentication capabilities (MFA status), operational status (locked/active), and audit metadata.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/idp/{externalUserId}.json"
  params={[
  { name: "externalUserId", type: "string", required: true, description: "The identifier provided during provisioning.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Identity profile retrieved.",
    content: {
      "id": "6908...",
      "external_id": "ORG_USR_9921_AFG",
      "status": "active",
      "has_otp": true,
      "has_passkeys": false,
      "is_locked": false,
      "failed_attempts": 0,
      "saas_client_id": "67c9..."
    } 
  }
]}
/>

***

## Multi-Factor Authentication (MFA)

### Configuration of TOTP Secret

Generate a new TOTP secret and QR code payload to enable secondary authentication. Scanning this payload into an authenticator application (e.g., Microsoft/Google Authenticator) completes the setup.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/idp/{externalUserId}/otp.json"
  params={[
  { name: "externalUserId", type: "string", required: true, description: "The user identifier.", location: "path" }
]}
  body={{
  "otp": {
    "issuer_name": "Acme Enterprise",
    "account_name": "alexander@enterprise.com"
  }
}}
  properties={[
  { name: "otp.issuer_name", type: "string", required: true, description: "The organization name displayed in the authenticator app." },
  { name: "otp.account_name", type: "string", required: true, description: "The specific account identifier displayed in the app." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "New MFA secret successfully generated.",
    content: {
      "user": {
          "external_id": "ORG_USR_9921_AFG",
          "new_otp_secret": "REDACTED_OTP_SECRET",
          "qrcode_payload": "otpauth://totp/Acme+Enterprise:alexander%40enterprise.com?secret=REDACTED_OTP_SECRET&issuer=Acme+Enterprise",
          "is_setup_complete": true
      }
    } 
  }
]}
/>

### Verify Authentication Code

Validate a 6-digit TOTP code (or a one-time backup code) to finalize the authentication process.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/idp/otp/verify.json"
  body={{
  "otp": {
    "id": "ORG_USR_9921_AFG",
    "code": "552192"
  }
}}
  properties={[
  { name: "otp.id", type: "string", required: true, description: "The unique external user identifier." },
  { name: "otp.code", type: "string", required: true, description: "The 6-digit code or numeric backup code." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Authentication successful.",
    content: { "status": "success", "id": "ORG_USR_9921_AFG", "message": "OTP verified successfully." } 
  },
  { 
    status: "401 Unauthorized", 
    description: "Invalid credentials or code expired.",
    content: { "error": "Invalid credentials or access denied" } 
  }
]}
/>

### Provision Backup Codes

Generate a collection of single-use backup codes. These allow users to regain access if the primary MFA device is unavailable.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/idp/{externalUserId}/backupcodes.json"
  params={[
  { name: "externalUserId", type: "string", required: true, description: "The user identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Set of 10 backup codes generated.",
    content: {
      "user": {
          "id": "ORG_USR_9921_AFG",
          "backupCodes": ["ABCD-1234", "EFGH-5678", "..."]
      }
    } 
  }
]}
/>

***

## Sentinel Risk Assessment

Sentinel provides a sophisticated analytical layer for evaluating authentication risk in real-time.

### Analyze Session Integrity (Discover)

Submit session metadata to Sentinel to perform a risk assessment based on behavioral patterns, network reputation, and environmental context.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/sentinel/verify.json"
  body={{
  "sentinel": {
    "id": "6908bffd...",
    "context": { "ip": "1.1.1.1", "ua": "EnterpriseAgent/1.0" }
  }
}}
  properties={[
  { name: "sentinel.id", type: "string", required: true, description: "External user identifier for the risk evaluation." },
  { name: "sentinel.context.ip", type: "string", required: true, description: "Source IP address of the session." },
  { name: "sentinel.context.ua", type: "string", required: true, description: "User-Agent value for the session." },
  { name: "sentinel.context.user_id", type: "string", required: false, description: "Optional explicit user identifier override." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Risk assessment completed.",
    content: { "status": "authorized", "risk_score": 0.05, "recommendation": "allow" } 
  },
  { 
    status: "403 Forbidden", 
    description: "High-risk indicators detected.",
    content: { "error": "High risk detection", "risk_score": 0.95 } 
  }
]}
/>


# API Reference



import { 
  ShieldCheck, 
  Key, 
  Mail, 
  MapPin, 
  Link, 
  Percent, 
  Share2, 
  Box,
  Layers,
  Zap
} from 'lucide-react';

Initialize your integration with our unified headless architecture. Designed to handle millions of requests with enterprise-grade latency and deterministic execution.

***

## Core Infrastructure

<div className="grid grid-cols-1 md:grid-cols-2 gap-6 mt-10">
  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#7ABA23]/50 transition-all group">
    <ShieldCheck size={40} className="text-[#7ABA23] mb-4" />

    ### Identity Provider (IDP)

    Manage user identities with native MFA and TOTP support.
    [Explore IDP →](/en/docs/api/idp)
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#FECC55]/50 transition-all group">
    <Key size={40} className="text-[#FECC55] mb-4" />

    ### Key Management Service (KMS)

    Store and reveal sensitive credentials with strict IP whitelisting.
    [Explore KMS →](/en/docs/api/kms)
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#7ABA23]/50 transition-all group">
    <Mail size={40} className="text-[#7ABA23] mb-4" />

    ### Email Gateway

    **Transactional Intelligence.** Trigger localized templates with dynamic variable injection. Scale communications via high-deliverability routes.
    [Explore Email →](/en/docs/api/email-gateway)
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#FECC55]/50 transition-all group">
    <MapPin size={40} className="text-[#FECC55] mb-4" />

    ### GeoIP & Metadata

    **Localized Intelligence.** Resolve IPv4 to precise geographic data and rich country metadata for automated compliance and tax logic.
    [Explore GeoIP →](/en/docs/api/geo-ip)
  </div>
</div>

***

## Growth & Operations

<div className="grid grid-cols-1 md:grid-cols-5 gap-4">
  <div className="p-6 rounded-2xl border border-white/5 bg-[#0D0D0D] hover:bg-white/5 transition-all">
    <Share2 size={24} className="text-[#7ABA23] mb-3" />

    #### Share Secrets

    One-time encrypted payload sharing with automatic purge.
  </div>

  <div className="p-6 rounded-2xl border border-white/5 bg-[#0D0D0D] hover:bg-white/5 transition-all">
    <Link size={24} className="text-[#7ABA23] mb-3" />

    #### Shortlinks

    URL redirection with traffic attribution.
  </div>

  <div className="p-6 rounded-2xl border border-white/5 bg-[#0D0D0D] hover:bg-white/5 transition-all">
    <Percent size={24} className="text-[#FECC55] mb-3" />

    #### Taxes

    VAT and sales tax logic for billing compliance.
  </div>

  <div className="p-6 rounded-2xl border border-white/5 bg-[#0D0D0D] hover:bg-white/5 transition-all">
    <Zap size={24} className="text-[#FECC55] mb-3" />

    #### DNS

    Multi-resolver DNS diagnostics and propagation checks.
  </div>

  <div className="p-6 rounded-2xl border border-white/5 bg-[#0D0D0D] hover:bg-white/5 transition-all">
    <Key size={24} className="text-[#7ABA23] mb-3" />

    #### Mobile Push

    Register and revoke iOS push tokens for mobile clients.
  </div>
</div>

***

## Enterprise Orchestration

<div className="grid grid-cols-1 md:grid-cols-2 gap-6">
  <div className="group relative p-8 rounded-[2.5rem] border border-[#7ABA23]/20 bg-gradient-to-br from-[#7ABA23]/5 to-transparent flex flex-col items-start gap-4">
    <Box size={40} className="text-[#7ABA23]" />

    ### Content Box

    Model custom data structures and serve them via a unified JSON API.
    [Explore Content Box →](/en/docs/api/dynamic-content)
  </div>

  <div className="group relative p-8 rounded-[2.5rem] border border-[#FECC55]/20 bg-gradient-to-br from-[#FECC55]/5 to-transparent flex flex-col items-start gap-4">
    <Layers size={40} className="text-[#FECC55]" />

    ### Workflow

    Automate business logic with stage-based auditing and dynamic payload injection.
    [Explore Workflow →](/en/docs/api/workflow)
  </div>
</div>

***

### Integration Architecture

| Metric              | Specification               |
| :------------------ | :-------------------------- |
| **Uptime SLA**      | 99.99% Enterprise Tier      |
| **Auth Protocol**   | Bearer Token (Stateless)    |
| **Default Version** | `2026-02-01`                |
| **Execution**       | Deterministic / Low Latency |


# Integrations & Capabilities



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Integrations & Capabilities API

The Integrations API provides a unified abstraction layer for extending the DonutWork core platform with third-party application functionalites. By declaring "capabilities," applications can expose their own endpoints as managed actions within the DonutWork ecosystem, allowing for seamless cross-platform orchestration, automated authorization handling (app-to-app), and centralized audit logging.

***

## Lifecycle Management

### Audit Active Integrations

Retrieve a paginated directory of all integrations currently authorized for your organization. This includes high-level connectivity status and identification handlers for each service.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/integrations.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Integration directory successfully retrieved.",
    content: {
      "entities": "Integration",
      "count": 1,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "6908bffd...",
          "handler": "STRIPE_CONNECT",
          "name": "Stripe Global Payments",
          "status": "connected"
        }
      ]
    } 
  }
]}
/>

### Declare Functional Capabilities

Register or update the specific actions (capabilities) that your application exposes. This declaration defines the input requirements and contract for each action, enabling DonutWork to proxy requests to your service securely.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/integrations.json"
  body={{
  "app_token": "ext_auth_token_9921",
  "capabilities": [
    { 
      "action": "SYNC_INVENTORY", 
      "method": "POST", 
      "endpoint": "https://api.myapp.com/v1/sync",
      "inputs": [
        { "name": "sku", "type": "string", "required": true },
        { "name": "quantity", "type": "number", "required": true }
      ]
    }
  ]
}}
  properties={[
  { name: "capabilities", type: "array", required: true, description: "Definition list of actions and their schema." },
  { name: "app_token", type: "string", required: false, description: "Authorization token to be used when DonutWork calls your service." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Capabilities successfully registered.",
    content: { 
      "success": true, 
      "message": "Capabilities declared successfully for MY_CUSTOM_APP",
      "app_handler": "MY_CUSTOM_APP",
      "actions_count": 1
    } 
  }
]}
/>

***

## Resource Discovery

### Retrieve Specific Integration

Fetch the full configuration, permission sets, and connectivity health for a specific integration.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/integrations/{appHandler}.json"
  params={[
  { name: "appHandler", type: "string", required: true, description: "The unique string identifier for the integration.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Detailed integration profile retrieved.",
    content: { 
      "id": "6908...",
      "handler": "SLACK_ENT", 
      "status": "connected", 
      "actions": [
        { "name": "SEND_MESSAGE", "method": "POST" }
      ],
      "metadata": { "workspace": "AcmeHQ" }
    } 
  }
]}
/>

***

## Execution (Capability Proxy)

### Dispatch Delegated Action

Execute a capability on a remote integration. DonutWork acts as a secure proxy, handling authorization headers and validating input schemas before relaying the request to the target service.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/integrations/{appHandler}/{appAction}.json"
  params={[
  { name: "appHandler", type: "string", required: true, description: "The integration identifier.", location: "path" },
  { name: "appAction", type: "string", required: true, description: "The capability to execute.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Action executed and external response relayed.",
    content: { 
      "success": true, 
      "integration": "SLACK_ENT", 
      "action": "SEND_MESSAGE",
      "external_status": 200,
      "response": { "ok": true, "ts": "123456789.0001" }
    } 
  }
]}
/>

The request payload for action dispatch is dynamic. Required body fields are validated at runtime using the integration capability declaration (`capabilities[].inputs[]` with `required: true`).

### Read Delegated Action

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/integrations/{appHandler}/{appAction}.json"
  params={[
  { name: "appHandler", type: "string", required: true, description: "The integration identifier.", location: "path" },
  { name: "appAction", type: "string", required: true, description: "The capability to execute.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Action executed using GET forwarding.",
    content: { "success": true, "integration": "SLACK_ENT", "action": "GET_CHANNEL_INFO", "external_status": 200, "response": {} } 
  }
]}
/>

### Update Delegated Action

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/integrations/{appHandler}/{appAction}.json"
  params={[
  { name: "appHandler", type: "string", required: true, description: "The integration identifier.", location: "path" },
  { name: "appAction", type: "string", required: true, description: "The capability to execute.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Action executed using PUT forwarding.",
    content: { "success": true, "integration": "SLACK_ENT", "action": "UPSERT_TEMPLATE", "external_status": 200, "response": {} } 
  }
]}
/>

### Delete Delegated Action

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/integrations/{appHandler}/{appAction}.json"
  params={[
  { name: "appHandler", type: "string", required: true, description: "The integration identifier.", location: "path" },
  { name: "appAction", type: "string", required: true, description: "The capability to execute.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Action executed using DELETE forwarding.",
    content: { "success": true, "integration": "SLACK_ENT", "action": "DELETE_MESSAGE", "external_status": 200, "response": {} } 
  }
]}
/>

### Emit Integration Event

Emit an application-scoped event so workflows and event listeners can react to integration activity.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/integrations/{appHandler}/events/{eventName}/emit.json"
  params={[
  { name: "appHandler", type: "string", required: true, description: "Application handler associated with the integration.", location: "path" },
  { name: "eventName", type: "string", required: true, description: "Declared event name in `<AppHandler>.<EventName>` format.", location: "path" }
]}
  body={{
  "metadata": {
    "message_id": "msg_001",
    "status": "sent"
  },
  "entity_id": "SLACK_ENT"
}}
  properties={[
  { name: "metadata", type: "object", required: false, description: "Event payload metadata object." },
  { name: "entity_id", type: "string", required: false, description: "Entity identifier. If omitted, the app handler is used." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Event accepted and dispatched.",
    content: { "success": true, "app_handler": "SLACK", "event": "Slack.MESSAGE_SENT", "queued_workflows": 1 } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request POST \
    'https://api.hub.donutwork.com/2026-02-01/integrations/SLACK/SEND_MSG.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN' \
    --header 'Content-Type: application/json' \
    --data-raw '{"message": "Automated Deployment Completed"}'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    const payload = { message: "System Alert: Resource threshold reached." };
    try {
      const result = await sdk.integrations.dispatch("SLACK", "SEND_MSG", payload);
      console.log(`Action Result: ${result.success} (Status: ${result.external_status})`);
    } catch (error) {
      console.error(`Dispatch Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>


# Job Runner



# Job Runner API

## List Jobs

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/job-runner.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Records per page (default 50, max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page number starting from 1.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Job runner list returned.",
    content: {
      "entities": "JobRunner",
      "count": 1,
      "per_page": 50,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "681f10...",
          "title": "Sync CRM Contacts",
          "method": "POST",
          "url": "https://api.partner.com/sync",
          "content_type": "application/json",
          "has_body": true,
          "schedulation": ["08:00", "14:30"]
        }
      ]
    }
  }
]}
/>

## Create Job

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/job-runner.json"
  body={{
  "jobrunner": {
    "title": "Sync CRM Contacts",
    "method": "POST",
    "url": "https://api.partner.com/sync",
    "content_type": "application/json",
    "body": "{\"scope\":\"daily\"}",
    "schedulation": ["08:00", "14:30"]
  }
}}
  properties={[
  { name: "jobrunner", type: "object", required: true, description: "Job runner configuration payload." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Job runner created.",
    content: {
      "id": "681f10...",
      "created": true
    }
  },
  {
    status: "422 Unprocessable Entity",
    description: "Validation error on payload.",
    content: { "error": "Invalid schedulation time \"24:30\". Use HH:mm format" }
  }
]}
/>

## Run Job

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/job-runner/{jobRunnerId}/run.json"
  params={[
  { name: "jobRunnerId", type: "string", required: true, description: "Job runner identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Job execution completed.",
    content: {
      "job_runner_id": "681f10...",
      "status": "success",
      "headers": ["HTTP/1.1 200 OK"],
      "response": "{\"ok\":true}",
      "ms": 122.45
    }
  }
]}
/>

## Delete Job

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/job-runner/{jobRunnerId}.json"
  params={[
  { name: "jobRunnerId", type: "string", required: true, description: "Job runner identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Job runner deleted.",
    content: {
      "id": "681f10...",
      "deleted": true
    }
  }
]}
/>


# Key Management Service (KMS)



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Key Management Service (KMS) API

The Key Management Service (KMS) provides a hardened environment for the storage and lifecycle management of sensitive credentials, such as third-party API keys, service accounts, and cryptographic tokens. By using KMS, organizations can eliminate the risk of hardcoded secrets within source code, instead retrieving them dynamically via secure, audited endpoints protected by strict IP-based whitelisting.

***

## Secret Management

### Audit KMS Inventory

Retrieve a paginated directory of all KMS secret handlers associated with your organization. This endpoint provides administrative metadata and is used for secret discovery; it does **not** expose the underlying secret values.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/kms.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index for pagination.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Secret inventory successfully retrieved.",
    content: {
      "entities": "KMSEntry",
      "count": 12,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "6835c2cd...",
          "name": "Production AWS S3 Access",
          "handler": "aws-s3-prod-credentials"
        }
      ]
    } 
  }
]}
/>

### Retrieve Secret Configuration

Fetch the detailed metadata and operational configuration for a unique KMS handler. This includes the registered IP whitelist and custom properties defined for the secret.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/kms/{handler}.json"
  params={[
  { name: "handler", type: "string", required: true, description: "The unique slug/identifier of the KMS entry.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Secret configuration retrieved.",
    content: {
      "id": "6835c2cd...",
      "name": "Production AWS S3 Access",
      "handler": "aws-s3-prod-credentials",
      "whitelist": ["52.1.2.3", "54.0.0.1"],
      "properties": { "region": "us-east-1" }
    } 
  },
  { 
    status: "404 Not Found", 
    description: "The specified handler does not exist in the vault.",
    content: { "error": "This KMSEntry does not exist" } 
  }
]}
/>

***

## Secret Consumption

### Decrypt & Reveal Secret

Securely decrypt and reveal the underlying secret content. Access to this endpoint is strictly enforced via IP-based whitelisting and results in an immediate audit entry. Use this endpoint only within backend environments to dynamically inject credentials.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/kms/reveal/{handler}.json"
  params={[
  { name: "handler", type: "string", required: true, description: "The KMS handler identifying the secret to reveal.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Secret successfully decrypted and returned.",
    content: { "content": "EXAMPLE_ACCESS_KEY_REDACTED" } 
  },
  { 
    status: "403 Forbidden", 
    description: "Requesting IP is not in the authorized whitelist or permissions are insufficient.",
    content: { "error": "Unauthorized to reveal this KMS Entry" } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/kms/reveal/aws-s3-prod-credentials.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    const handler = "aws-s3-prod-credentials";
    try {
      const secret = await sdk.kms.reveal(handler);
      console.log(`Resource Access Granted. Payload: ${secret.content}`);
    } catch (error) {
      console.error(`Vault Access Denied: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

<Callout type="warning">
  **Security Audit:** Every call to the `reveal` endpoint is logged with the requesting IP, User-Agent, and timestamp. Ensure your infrastructure IPs are properly whitelisted in the KMS configuration to avoid 403 authorization failures.
</Callout>


# Media Library



# Media Library API

## Strategy

For large files, use presigned direct upload:

1. Request upload link from API.
2. Upload file directly to storage with `PUT`.
3. Use media list or download-link APIs for retrieval flow.

## List Files

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/media-library/files.json"
  params={[
  { name: "page", type: "integer", required: false, description: "Page number starting from 1.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Media file list returned.",
    content: {
      "entities": "MediaLibraryFile",
      "count": 1,
      "per_page": 60,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "filename": "invoice-apr-2026.pdf",
          "size": 58211,
          "etag": "15d6a30e7a6f0d...",
          "last_modified": "2026-04-20T08:55:10+00:00"
        }
      ]
    }
  }
]}
/>

## Create Upload Link

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/media-library/files/upload-link.json"
  body={{
  "file": {
    "filename": "invoice-apr-2026.pdf",
    "content_type": "application/pdf",
    "size_bytes": 58211
  }
}}
  properties={[
  { name: "file", type: "object", required: true, description: "Upload target metadata (filename/content type/optional size)." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Presigned direct upload link generated.",
    content: {
      "strategy": "direct_presigned_put",
      "file": {
        "filename": "invoice-apr-2026.pdf",
        "content_type": "application/pdf",
        "max_size_bytes": 524288000
      },
      "upload": {
        "method": "PUT",
        "url": "https://storage.example.com/prod-.../invoice-apr-2026.pdf?...",
        "expires_in": 1200,
        "headers": {
          "Content-Type": "application/pdf"
        }
      }
    }
  }
]}
/>

## Upload File (Fallback)

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/media-library/files.json"
  body={{
  "file": {
    "filename": "small-note.txt",
    "content_type": "text/plain",
    "content_base64": "U2NoZWR1bGVkIG5vdGUgZnJvbSBBUEk="
  }
}}
  properties={[
  { name: "file", type: "object", required: true, description: "Fallback upload payload using base64 content." }
]}
  responses={[
  {
    status: "201 Created",
    description: "File uploaded.",
    content: {
      "filename": "small-note.txt",
      "size": 24,
      "uploaded": true
    }
  }
]}
/>

## Create Download Link

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/media-library/files/download-link.json"
  body={{
  "file": {
    "filename": "invoice-apr-2026.pdf"
  }
}}
  properties={[
  { name: "file", type: "object", required: true, description: "Target file descriptor for secure download URL generation." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Download link generated.",
    content: {
      "filename": "invoice-apr-2026.pdf",
      "url": "https://app.example.com/file-download/download?file=..."
    }
  }
]}
/>


# Mobile Push Tokens



# Mobile Push Tokens API

These endpoints are available only when using a mobile-scoped API key.

## Save Device Push Token

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/mobile/push-token.json"
  body={{
  "device": {
    "device_id": "ios_device_001",
    "push_token": "f6ad7d6f0a3b82d91fd89e88d4d4c6f3e0f9a7f6",
    "platform": "ios",
    "app_version": "1.2.3",
    "environment": "production"
  }
}}
  properties={[
  { name: "device.device_id", type: "string", required: true, description: "Device identifier (8-128 chars, allowed: letters, numbers, . _ : -)." },
  { name: "device.push_token", type: "string", required: true, description: "APNs push token (20-1024 chars)." },
  { name: "device.platform", type: "string", required: false, description: "Platform value. Only `ios` is accepted." },
  { name: "device.app_version", type: "string", required: false, description: "Client application version." },
  { name: "device.environment", type: "string", required: false, description: "Push environment (`sandbox` or `production`)." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Push token saved or updated.",
    content: {
      "status": "success",
      "message": "Push token saved",
      "device": {
        "device_id": "ios_device_001",
        "platform": "ios",
        "environment": "production"
      }
    }
  },
  {
    status: "403 Forbidden",
    description: "API key is not mobile-scoped.",
    content: { "error": "Mobile API key required for this endpoint" }
  }
]}
/>

## Delete Device Push Token

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/mobile/push-token.json"
  params={[
  { name: "device_id", type: "string", required: false, description: "Device identifier when passed via query string. Required if not present in `device.device_id` body.", location: "query" }
]}
  body={{
  "device": {
    "device_id": "ios_device_001"
  }
}}
  properties={[
  { name: "device.device_id", type: "string", required: false, description: "Device identifier when passed via JSON body. Required if not present in `device_id` query param." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Push token deleted or already absent.",
    content: {
      "status": "success",
      "message": "Push token removed",
      "deleted": true,
      "device_id": "ios_device_001"
    }
  },
  {
    status: "400 Bad Request",
    description: "Device identifier missing or invalid.",
    content: { "error": "Missing required field: device_id" }
  }
]}
/>


# Newsletter Campaigns



# Newsletter API

The Newsletter API exposes campaign lifecycle, recipient synchronization, dispatch queue controls, analytics, and suppression list management.

***

## List Newsletter Campaigns

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/newsletters.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index (starting from 1).", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Newsletter list returned.",
    content: {
      "entities": "Newsletter",
      "count": 1,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "672489...",
          "title": "Launch Campaign",
          "subject": "New release",
          "template_id": "welcome.html",
          "total_recipients": 210,
          "status": "draft",
          "created_at": 1704067200
        }
      ]
    }
  }
]}
/>

## Create Newsletter Campaign

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/newsletters.json"
  body={{
  "newsletter": {
    "title": "Launch Campaign",
    "subject": "New release",
    "template_id": "welcome.html",
    "contact_ids": ["cust_1", "cust_2"]
  }
}}
  properties={[
  { name: "newsletter.title", type: "string", required: true, description: "Internal campaign name." },
  { name: "newsletter.subject", type: "string", required: true, description: "Subject line used during sending." },
  { name: "newsletter.template_id", type: "string", required: true, description: "Template filename to use for this campaign." },
  { name: "newsletter.contact_ids", type: "array", required: false, description: "Optional initial recipients list." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Newsletter draft created.",
    content: {
      "id": "672489...",
      "status": "draft",
      "skipped_suppressed": 0,
      "skipped_not_found": 1
    }
  }
]}
/>

## Retrieve Campaign Details

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Campaign details returned.",
    content: {
      "id": "672489...",
      "title": "Launch Campaign",
      "subject": "New release",
      "template_id": "welcome.html",
      "total_recipients": 210,
      "status": "queued",
      "scheduled_at": null,
      "created_at": 1704067200
    }
  }
]}
/>

## Update Campaign Metadata

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" }
]}
  body={{
  "newsletter": {
    "title": "Launch Campaign v2",
    "subject": "Release update",
    "template_id": "welcome-v2.html"
  }
}}
  properties={[
  { name: "newsletter.title", type: "string", required: false, description: "Updated title. Allowed only in draft status." },
  { name: "newsletter.subject", type: "string", required: false, description: "Updated subject. Allowed only in draft status." },
  { name: "newsletter.template_id", type: "string", required: false, description: "Updated template id. Allowed only in draft status." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Campaign metadata updated.",
    content: {
      "id": "672489...",
      "title": "Launch Campaign v2",
      "subject": "Release update",
      "template_id": "welcome-v2.html",
      "total_recipients": 210,
      "status": "draft",
      "scheduled_at": null,
      "created_at": 1704067200
    }
  },
  {
    status: "409 Conflict",
    description: "Campaign is not in draft status.",
    content: { "error": "Only newsletters in draft status can be updated" }
  }
]}
/>

## Delete Campaign

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Campaign and related queue entries deleted.",
    content: { "id": "672489...", "deleted": true }
  }
]}
/>

## Get Campaign Recipients Snapshot

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}/recipients.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" },
  { name: "search", type: "string", required: false, description: "Optional search filter by customer name or email.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Recipients snapshot returned.",
    content: {
      "newsletter_status": "draft",
      "selected_ids": ["cust_1", "cust_2"],
      "all_customers": [
        {
          "id": "cust_1",
          "name": "Alex Doe",
          "email": "alex@example.com",
          "tags": ["beta"],
          "subscription_count": 1,
          "has_consent": true,
          "is_suppressed": false
        }
      ]
    }
  }
]}
/>

## Set Campaign Recipients

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}/recipients.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" }
]}
  body={{
  "newsletter": {
    "contact_ids": ["cust_1", "cust_2", "cust_3"]
  }
}}
  properties={[
  { name: "newsletter.contact_ids", type: "array", required: true, description: "Recipient customer IDs to store on the campaign." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Recipients synchronized.",
    content: {
      "newsletter_id": "672489...",
      "saved_recipients": 2,
      "skipped_suppressed": 1,
      "skipped_not_found": 0
    }
  }
]}
/>

## Queue Campaign Dispatch

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}/queue.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Campaign queued for sending.",
    content: {
      "newsletter_id": "672489...",
      "status": "queued",
      "queued_recipients": 150,
      "skipped_suppressed": 0,
      "skipped_not_found": 0
    }
  },
  {
    status: "409 Conflict",
    description: "Invalid state or usage limit reached.",
    content: { "error": "This newsletter is already queued and cannot be queued again" }
  }
]}
/>

## Send Test Email

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}/test.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" }
]}
  body={{
  "newsletter": {
    "test_email": "qa@example.com"
  }
}}
  properties={[
  { name: "newsletter.test_email", type: "string", required: true, description: "Target email for test send." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Test email sent.",
    content: {
      "newsletter_id": "672489...",
      "test_email": "qa@example.com",
      "sent": true
    }
  }
]}
/>

## Get Campaign Stats

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}/stats.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" },
  { name: "failure_limit", type: "integer", required: false, description: "Maximum failed/skipped items to include.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Campaign stats returned.",
    content: {
      "newsletter": {
        "id": "672489...",
        "title": "Launch Campaign",
        "subject": "New release",
        "template_id": "welcome.html",
        "total_recipients": 150,
        "status": "queued",
        "scheduled_at": null,
        "created_at": 1704067200
      },
      "stats": {
        "pending": 12,
        "processing": 3,
        "sent": 120,
        "failed": 10,
        "skipped": 5,
        "total": 150
      },
      "progress": {
        "processed": 135,
        "total": 150,
        "overall_progress": 90,
        "delivery_rate": 80
      },
      "failures": []
    }
  }
]}
/>

***

## Suppression List

### List Unsubscribes

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/newsletters/unsubscribes.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Suppression list returned.",
    content: {
      "entities": "Unsubscribes",
      "count": 1,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "email": "user@example.com",
          "reason": "Manual unsubscribe via API",
          "unsubscribed_at": 1704067200
        }
      ]
    }
  }
]}
/>

### Add Unsubscribe

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/newsletters/unsubscribes.json"
  body={{
  "unsubscribe": {
    "email": "user@example.com",
    "reason": "Support request"
  }
}}
  properties={[
  { name: "unsubscribe.email", type: "string", required: true, description: "Email to suppress." },
  { name: "unsubscribe.reason", type: "string", required: false, description: "Optional reason for audit trail." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Email added to suppression list.",
    content: {
      "email": "user@example.com",
      "unsubscribed": true
    }
  }
]}
/>

### Resubscribe Email

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/newsletters/unsubscribes/resubscribe.json"
  body={{
  "unsubscribe": {
    "email": "user@example.com"
  }
}}
  properties={[
  { name: "unsubscribe.email", type: "string", required: true, description: "Email to remove from suppression list." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Email removed from suppression list.",
    content: {
      "email": "user@example.com",
      "resubscribed": true
    }
  },
  {
    status: "404 Not Found",
    description: "Email not found in suppression list.",
    content: { "error": "Email not found in suppression list" }
  }
]}
/>


# Partner Groups



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Partner Groups API

Partner Groups provide an automated logic layer for categorizing partners and enforcing organization-wide distribution policies. These groups define rules that govern revenue sharing percentages, time-based commission tiers, and performance-driven upgrades based on total Lifetime Value (LTV) or charge volume.

***

## Group Inventory

### List Partner Groups

Retrieve a paginated directory of all defined Partner Groups. This directory contains the high-level metadata and administrative identifiers for each group.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/groups.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Partner group directory successfully retrieved.",
    content: {
      "entities": "PartnerGroup",
      "count": 4,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
          {
            "id": "68f76721...",
            "name": "Standard Managed Agency",
            "external_id": "P-GROUP-ADVANCED",
            "default": true
          }
      ]
    } 
  }
]}
/>

### Retrieve Group Configuration & Rules

Fetch the comprehensive configuration for a specific governance group, including the active rules engine parameters that define commission logic.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/groups/{groupId}.json"
  params={[
  { name: "groupId", type: "string", required: true, description: "The unique identifier of the partner group.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Group configuration and rules engine definition retrieved.",
    content: {
      "id": "68f76721...",
      "name": "Standard Managed Agency",
      "external_id": "P-GROUP-ADVANCED",
      "rules": [
          {
              "type": "new_customer_time_tier",
              "max_months": 12,
              "percentage": 50,
              "description": "Introductory 12-month high-incentive tier."
          },
          {
              "type": "recurring",
              "percentage": 15,
              "description": "Standard recurring commission (post-time-tier)."
          },
          {
              "type": "partner_ltv_upgrade",
              "min_ltv_total": 10000,
              "upgrade_percentage": 5,
              "description": "LTV Performance Bonus (Threshold: 10,000€)."
          }
      ],
      "tags": "managed,high-volume",
      "description": "Default group for high-performance managed agencies."
    } 
  }
]}
/>

***

## Group Lifecycle Management

### Create Partner Group

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/partners/groups.json"
  body={{
  "partnerGroup": {
    "name": "Performance Agencies",
    "description": "Tier for high-volume agencies",
    "external_id": "P-GROUP-PERF",
    "tags": "managed,performance",
    "default": false,
    "rules": [
      {
        "type": "new_customer_time_tier",
        "max_months": 6,
        "percentage": 30
      },
      {
        "type": "recurring",
        "percentage": 12
      }
    ]
  }
}}
  properties={[
  { name: "partnerGroup.name", type: "string", required: true, description: "Partner group display name." },
  { name: "partnerGroup.rules", type: "array", required: true, description: "Rules array. Must include one recurring fallback rule." },
  { name: "partnerGroup.description", type: "string", required: false, description: "Optional group description." },
  { name: "partnerGroup.external_id", type: "string", required: false, description: "Optional external identifier." },
  { name: "partnerGroup.tags", type: "string", required: false, description: "Comma-separated tags." },
  { name: "partnerGroup.default", type: "boolean", required: false, description: "Mark this group as default for new partners." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Partner group created.",
    content: { "group": { "id": "68f76721..." } }
  }
]}
/>

### Update Partner Group

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/partners/groups/{partnerGroupId}.json"
  params={[
  { name: "partnerGroupId", type: "string", required: true, description: "Partner group identifier.", location: "path" }
]}
  body={{
  "partnerGroup": {
    "name": "Performance Agencies v2",
    "default": true,
    "rules": [
      {
        "type": "recurring",
        "percentage": 14
      }
    ]
  }
}}
  properties={[
  { name: "partnerGroup.name", type: "string", required: false, description: "Updated group name." },
  { name: "partnerGroup.description", type: "string", required: false, description: "Updated description." },
  { name: "partnerGroup.external_id", type: "string", required: false, description: "Updated external identifier." },
  { name: "partnerGroup.tags", type: "string", required: false, description: "Updated comma-separated tags." },
  { name: "partnerGroup.default", type: "boolean", required: false, description: "Update default flag." },
  { name: "partnerGroup.rules", type: "array", required: false, description: "Updated rules array; if provided, must include recurring fallback." }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Partner group updated.",
    content: { "group": { "id": "68f76721..." } }
  }
]}
/>

### Delete Partner Group

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/partners/groups/{partnerGroupId}.json"
  params={[
  { name: "partnerGroupId", type: "string", required: true, description: "Partner group identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Partner group deleted.",
    content: { "group": { "id": "68f76721...", "deleted": true } }
  }
]}
/>

### Simulate Rules

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/partners/groups/simulate-rules.json"
  body={{
  "partnerGroupSimulation": {
    "rules": [
      { "type": "new_customer_time_tier", "max_months": 3, "percentage": 25 },
      { "type": "recurring", "percentage": 10 }
    ],
    "simulation": {
      "charge_amount": 299.90,
      "customer_months": 2,
      "partner_ltv": 4500,
      "qualified_customers": 12,
      "first_paid_customer_bootstrap": false
    }
  }
}}
  properties={[
  { name: "partnerGroupSimulation.rules", type: "array", required: true, description: "Rules set to simulate. Must include recurring fallback." },
  { name: "partnerGroupSimulation.simulation", type: "object", required: true, description: "Simulation context (charge amount, lifecycle and partner KPIs)." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Rules simulation completed.",
    content: {
      "status": "success",
      "result": {
        "final_fee": 74.98
      }
    }
  }
]}
/>

***

## The Rules Engine

Partner groups are powered by a deterministic rules engine that evaluates transactions in real-time. The following rule types are supported:

### Rule Type Definitions

| Rule Type                | Description                                                                                       | Key Parameters                        |
| :----------------------- | :------------------------------------------------------------------------------------------------ | :------------------------------------ |
| `new_customer_time_tier` | Applies a specific commission for the initial months of a customer's lifecycle.                   | `max_months`, `percentage`            |
| `recurring`              | The baseline commission applied to all transactions when no other specific rule applies.          | `percentage`                          |
| `partner_ltv_upgrade`    | Triggers a commission percentage increase once a partner's total managed LTV exceeds a threshold. | `min_ltv_total`, `upgrade_percentage` |
| `charge_threshold_bonus` | Provides a one-time bonus for transactions exceeding a specific amount.                           | `min_charge_total`, `bonus`           |

<Callout type="info">
  **Evaluation Hierarchy:** Rules are evaluated based on the customer's acquisition date and the partner's historical performance. A `recurring` rule is required for all groups as a fallback mechanism.
</Callout>


# Partners



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Partners API

The Partners API enables organizations to build and scale distribution networks through agencies, resellers, and affiliates. It provides a framework for managing partner identities, commission calculations (fees), and financial settlements (payouts), while maintaining clear attribution for every customer acquired through the channel.

***

## Channel Management

### List Partners

Retrieve a paginated directory of all registered partners. This list includes high-level identification data and current status for each collaborative entity.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Partner directory successfully retrieved.",
    content: {
      "entities": "Partner",
      "count": 24,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        { 
          "id": "675d...", 
          "name": "Global Solutions Agency", 
          "external_id": "GSA-9921",
          "partner_code": "GOLD-PARTNER-X"
        }
      ]
    } 
  }
]}
/>

### Provision New Partner

Onboard a new partner into the ecosystem. This initializes their profile and associates them with a governance group (Partner Group) to define their commission rules.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/partners.json"
  body={{
  "partner": {
      "name": "Apex Marketing Group",
      "email": "channel@apex-marketing.com",
      "external_id": "APEX_001",
      "code": "APEXPROMO",
      "partner_group_id": "66bf22b0...",
      "address": {
          "vat_number": "IT09876543210",
          "country": "IT",
          "city": "Milan"
      }
  }
}}
  properties={[
  { name: "partner.name", type: "string", required: true, description: "Legal entity name of the partner." },
  { name: "partner.email", type: "string", required: true, description: "Primary contact for financial and operational notifications." },
  { name: "partner.partner_group_id", type: "string", required: false, description: "The ID of the Partner Group define rules. If empty, the default group is used." },
  { name: "partner.address.country", type: "string", required: true, description: "ISO 3166-1 alpha-2 country code." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Partner successfully provisioned.",
    content: { "partner": { "id": "6768..." } } 
  }
]}
/>

### Retrieve Partner Profile

Fetch the comprehensive profile of a specific partner, including their fee structure, whitelist configuration, and association metadata.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "The unique identifier of the partner.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Partner profile retrieved.",
    content: {
      "id": "66b136b9...",
      "name": "Apex Marketing Group",
      "status": "active",
      "tags": ["tier-1", "mfa-enabled"],
      "email": "channel@apex-marketing.com",
      "address": { "city": "Milan", "country": "IT", "vat_number": "IT098..." }
    } 
  }
]}
/>

***

## Attribution & Performance

### Audit Attributed Customers

Retrieve a paginated list of all customers currently attributed to a specific partner. This is used to verify channel performance and revenue attribution.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/customers.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "The partner identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Attributed customer list retrieved.",
    content: {
      "entities": "PartnerCustomers",
      "count": 142,
      "elements": [
          { "id": "68d2...", "company_name": "Acme Corp", "email": "procurement@acme.com", "status": "active" }
      ]
    } 
  }
]}
/>

### Performance Analytics

Retrieve high-level performance metrics for a partner, including total attributed revenue and cumulative commissions earned.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/stats.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "The partner identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Aggregated performance statistics retrieved.",
    content: { 
      "total_revenue": "45200.00", 
      "commission_earned": "4520.00",
      "currency": "EUR"
    } 
  }
]}
/>

***

## Financial Settlement (Payouts)

### Audit Commission Ledger (Fees)

Retrieve individual commission entries (fees) generated by attributed customer transactions. These entries serve as the basis for payout generation.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/fees.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "The partner identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Commission ledger retrieved.",
    content: {
      "entities": "PartnerFees",
      "elements": [
        { "id": "fee_991", "source_charge": "ch_123", "fee_value": 15.50, "status": "pending" }
      ]
    } 
  }
]}
/>

### Generate Payout Request

Consolidate multiple 'pending' commission fees into a single Payout request. This initiates the financial settlement cycle and generates a draft settlement record.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/partners/payouts.json"
  body={{
  "payout": {
      "partner_id": "675d...",
      "transactions": ["fee_991", "fee_992"],
      "invoice": {
          "number": "INV-2026-001",
          "date": "2026-03-01"
      },
      "vat_settings": {
          "tax_id": "tax_vat_22"
      }
  }
}}
  properties={[
  { name: "payout.partner_id", type: "string", required: true, description: "The partner identifier." },
  { name: "payout.transactions", type: "array", required: true, description: "Collection of fee entry IDs." },
  { name: "payout.invoice.number", type: "string", required: true, description: "Reference number for the partner settlement invoice." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Payout request successfully generated.",
    content: { "id": "pay_5521", "total": "1250.00" } 
  }
]}
/>

### Retrieve Payout Documentation (PDF)

Retrieve a base64-encoded PDF report (Account Statement) for a specific payout. This document serves as the official settlement record for the partner.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/payouts/{payoutId}/report.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "The partner identifier.", location: "path" },
  { name: "payoutId", type: "string", required: true, description: "The payout identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "PDF documentation retrieved.",
    content: { 
      "stream": {
        "type": "application/pdf",
        "base64_content": "JVBER..."
      }
    } 
  }
]}
/>

### Technical Implementation (Payout Flow)

<Tabs items={["Javascript"]}>
  <Tab value="Javascript">
    ```js
    const payoutData = {
      payout: {
        partner_id: "PARTNER_6621",
        transactions: ["FEE_001", "FEE_002"],
        invoice: { number: "REF-9921", date: "2026-03-03" },
        vat_settings: { tax_id: "VAT_22_IT" }
      }
    };

    try {
      const settlement = await sdk.partners.createPayout(payoutData);
      console.log(`Settlement Processed. ID: ${settlement.id}, Total: ${settlement.total}`);
    } catch (error) {
      console.error(`Settlement Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

***

## Additional Partner Operations

### Search Partner by External ID or Email

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/partner.json"
  params={[
  { name: "externalId", type: "string", required: false, description: "Partner external identifier.", location: "query" },
  { name: "email", type: "string", required: false, description: "Partner email address.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Partner record retrieved.",
    content: { "id": "675d...", "name": "Apex Marketing Group", "email": "channel@apex-marketing.com" }
  },
  {
    status: "422 Unprocessable Entity",
    description: "Neither `externalId` nor `email` was provided.",
    content: { "error": "A valid \"externalId\" or \"email\" must be specified in the request" }
  }
]}
/>

### Update Partner Profile

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/partners/{partnerId}.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "Partner identifier.", location: "path" }
]}
  body={{
  "partner": {
    "name": "Apex Marketing Group - Enterprise",
    "email": "enterprise@apex-marketing.com",
    "description": "Updated profile",
    "external_id": "APEX_001",
    "code": "APEXPROMO",
    "partner_group_id": "66bf22b0...",
    "tags": ["tier-1", "priority"],
    "address": {
      "country": "IT",
      "city": "Milan"
    }
  }
}}
  properties={[
  { name: "partner.name", type: "string", required: false, description: "Updated partner legal name." },
  { name: "partner.email", type: "string", required: false, description: "Updated partner contact email." },
  { name: "partner.description", type: "string", required: false, description: "Updated profile description." },
  { name: "partner.external_id", type: "string", required: false, description: "Updated external identifier." },
  { name: "partner.code", type: "string", required: false, description: "Updated partner code." },
  { name: "partner.partner_group_id", type: "string", required: false, description: "Partner group assignment (empty string removes current group)." },
  { name: "partner.tags", type: "array|string", required: false, description: "Updated tags list." },
  { name: "partner.address", type: "object", required: false, description: "Partial address update object." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Partner updated.",
    content: { "id": "675d...", "name": "Apex Marketing Group - Enterprise" }
  }
]}
/>

### Delete Partner

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/partners/{partnerId}.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "Partner identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Partner deleted.",
    content: { "id": "675d...", "deleted": true }
  },
  {
    status: "406 Not Acceptable",
    description: "Partner has still attached customers.",
    content: { "error": "Unable to remove this partner. Customer attached to partner: ..." }
  }
]}
/>

### Get Partner Fee by ID

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/fees/{feeId}.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "Partner identifier.", location: "path" },
  { name: "feeId", type: "string", required: true, description: "Fee entry identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Partner fee entry retrieved.",
    content: { "id": "fee_991", "partner_id": "675d...", "fee_value": 15.5, "status": "pending" }
  }
]}
/>

### List Global Payouts

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/payouts.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (1-100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index (1-based).", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Paginated payout list across all partners.",
    content: { "entities": "PartnerPayout", "count": 3, "elements": [] }
  }
]}
/>

### List Payouts for One Partner

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/payouts.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "Partner identifier.", location: "path" },
  { name: "size", type: "integer", required: false, description: "Maximum records per page (1-100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index (1-based).", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Paginated payout list for the specified partner.",
    content: { "entities": "PartnerPayout", "count": 2, "elements": [] }
  }
]}
/>

### Get Payout by Partner and ID

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/payouts/{payoutId}.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "Partner identifier.", location: "path" },
  { name: "payoutId", type: "string", required: true, description: "Payout identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Payout details retrieved.",
    content: { "id": "pay_5521", "partner_id": "675d...", "status": "pending", "total": 1250.0 }
  }
]}
/>

### Get Payout by ID

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/payouts/{payoutId}.json"
  params={[
  { name: "payoutId", type: "string", required: true, description: "Payout identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Payout details retrieved.",
    content: { "id": "pay_5521", "partner_id": "675d...", "status": "pending", "total": 1250.0 }
  }
]}
/>

### Update Payout Status

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/partners/payouts/{payoutId}/status.json"
  params={[
  { name: "payoutId", type: "string", required: true, description: "Payout identifier.", location: "path" }
]}
  body={{
  "payout": {
    "status": "paid",
    "metadata": {
      "reference": "BANK-TRX-2026-8891"
    }
  }
}}
  properties={[
  { name: "payout.status", type: "string", required: true, description: "Next payout status. Allowed values: pending, paid, refused." },
  { name: "payout.metadata", type: "object", required: false, description: "Optional metadata merged into payout metadata." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Payout status updated and related fee entries synchronized.",
    content: { "payout": { "id": "pay_5521", "status": "paid" } }
  },
  {
    status: "409 Conflict",
    description: "Invalid status transition.",
    content: { "error": "Paid payouts cannot be updated" }
  }
]}
/>

### Stream Payout PDF

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/payouts/{payoutId}/report.pdf"
  params={[
  { name: "partnerId", type: "string", required: true, description: "Partner identifier.", location: "path" },
  { name: "payoutId", type: "string", required: true, description: "Payout identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Inline PDF stream response.",
    content: {
      "note": "Response is streamed as application/pdf."
    }
  }
]}
/>


# Recurring Payments



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Recurring Payments API

The Recurring Payments API provides the operational infrastructure for managing subscription-based revenue models. It allows organizations to define sophisticated billing cycle parameters, configure automated dunning (retry) policies for failed transactions, and monitor the real-time status of all active subscriptions across the platform.

***

## Operational Configuration

### Audit Recurring Settings

Retrieve the global operational parameters governing recurring billing. This includes the current retry logic for failed payments and the timing offsets for subsequent billing cycles.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/recurring-payments/settings.json"
  responses={[
  { 
    status: "200 OK", 
    description: "Operational settings successfully retrieved.",
    content: {
      "status": "success",
      "settings": {
          "retry_policy": "exponential_backoff",
          "max_retries": 5,
          "next_cycle_offset": "24 hours",
          "dunning_notifications": true
      }
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/recurring-payments/settings.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    try {
      const config = await sdk.recurringPayments.getSettings();
      console.log(`Billing Policy: ${config.settings.retry_policy} (Max Retries: ${config.settings.max_retries})`);
    } catch (error) {
      console.error(`Fetch Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

***

## Subscription Lifecycle Monitoring

### Audit Active Subscriptions

Retrieve a comprehensive inventory of all subscriptions currently managed by the recurring payment engine. This endpoint provides crucial visibility into renewal dates, customer associations, and current billing health.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/recurring-payments/subscriptions.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page.", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Subscription inventory retrieved.",
    content: {
      "type": "RecurringSubscriptions",
      "count": 1250,
      "per_page": 100,
      "elements": [
        {
          "id": "67bdf...",
          "customerId": "66a15...",
          "subscription_reference": "sub_premium_9921",
          "status": "active",
          "next_renewal_date": "2026-04-01T00:00:00Z",
          "last_payment_status": "success"
        }
      ]
    } 
  }
]}
/>

### Implementation

<Tabs items={["Javascript"]}>
  <Tab value="Javascript">
    ```js
    const filters = { page: 1, size: 50 };
    try {
      const activeSubs = await sdk.recurringPayments.listSubscriptions(filters);
      activeSubs.elements.forEach(sub => {
        console.log(`Subscription ${sub.id}: Renewal due on ${sub.next_renewal_date}`);
      });
    } catch (error) {
      console.error(`Telemetry Error: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>


# Scheduler



# Scheduler API

## List Events

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/scheduler/events.json"
  params={[
  { name: "start", type: "string", required: true, description: "Start date or datetime (recommended YYYY-MM-DD).", location: "query" },
  { name: "end", type: "string", required: true, description: "End date or datetime (recommended YYYY-MM-DD).", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Events fetched in the requested range.",
    content: {
      "status": "fetch",
      "count": 2,
      "range": {
        "start": "2026-04-01T00:00:00+02:00",
        "end": "2026-04-30T23:59:59+02:00"
      },
      "events": [
        {
          "id": "681f0f...",
          "event_type": "appointment",
          "title": "Quarterly Review",
          "schedule_date": "2026-04-12T09:00:00+02:00",
          "end_date": "2026-04-12T10:00:00+02:00"
        }
      ]
    }
  }
]}
/>

## Create Event

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/scheduler/events.json"
  body={{
  "event": {
    "event_type": "action",
    "title": "Run Workflow Daily",
    "schedule_date": "2026-04-20T07:30:00+02:00",
    "end_date": "2026-04-20T07:30:00+02:00",
    "is_all_day": false,
    "color": "primary",
    "action_type": "workflow",
    "action_details": {
      "workflow_id": "67ffac1f8a3f0f2f88f9dd10",
      "payload": { "source": "api" }
    },
    "recurrence": {
      "type": "week",
      "interval": 1,
      "endDate": "2026-12-31"
    }
  }
}}
  properties={[
  { name: "event", type: "object", required: true, description: "Scheduler event payload." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Event created.",
    content: {
      "id": "681f0f...",
      "event": {
        "id": "681f0f...",
        "event_type": "action",
        "action_type": "workflow"
      }
    }
  },
  {
    status: "422 Unprocessable Entity",
    description: "Validation error on event payload.",
    content: { "error": "Invalid \"action_type\". Allowed values: charge, job_runner, workflow" }
  }
]}
/>

## Update Event

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/scheduler/events/{eventId}.json"
  params={[
  { name: "eventId", type: "string", required: true, description: "Scheduler event identifier.", location: "path" }
]}
  body={{
  "event": {
    "title": "Run Workflow - Updated",
    "recurrence": {
      "type": "month",
      "interval": 1,
      "endDate": "2027-04-30"
    }
  }
}}
  properties={[
  { name: "event", type: "object", required: true, description: "Partial event payload to update." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Event updated.",
    content: {
      "id": "681f0f...",
      "event": {
        "id": "681f0f...",
        "title": "Run Workflow - Updated"
      }
    }
  }
]}
/>

## Delete Event

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/scheduler/events/{eventId}.json"
  params={[
  { name: "eventId", type: "string", required: true, description: "Scheduler event identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Event deleted.",
    content: {
      "id": "681f0f...",
      "deleted": true
    }
  }
]}
/>


# Share Secrets



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Share Secrets API

The Share Secrets API provides a secure mechanism for transmitting sensitive information (such as passwords, private keys, or PII) without leaving a persistent digital footprint. Secrets are encrypted and associated with a unique, short-lived URL. To ensure maximum security, content is **purged immediately after the first successful access**, rendering the link permanently invalid.

***

## Secret Management

### Audit Secret Inventory

Retrieve a paginated directory of all active (unread) or recently expired share secret entries. This allows for administrative tracking of shared links and their current consumption status.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/share-secrets.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Secret directory successfully retrieved.",
    content: {
      "entities": "ShareSecret",
      "count": 5,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
          {
              "id": "6739782b...",
              "name": "Database Migration Credentials",
              "url": "https://hub.donutwork.com/ss/b6a9532aa4a06...",
              "readed": false
          }
      ]
    } 
  }
]}
/>

### Provision Secure Secret Link

Generate a new ephemeral secret link. The `content` provided is encrypted at rest and will be revealed only once. You can optionally trigger an automated email notification to the recipient.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/share-secrets.json"
  body={{
  "shareSecret": {
      "name": "Deployment API Token",
      "content": "secret_value_redacted",
      "sendTo": {
          "email": "engineer@partner-company.com",
          "message": "The requested production API token is now available for one-time retrieval."
      }
  }
}}
  properties={[
  { name: "shareSecret.name", type: "string", required: true, description: "Descriptive label for internal tracking." },
  { name: "shareSecret.content", type: "string", required: true, description: "The sensitive payload to be shared (OTV)." },
  { name: "shareSecret.sendTo.email", type: "string", required: false, description: "Recipient email for automated notification." },
  { name: "shareSecret.sendTo.message", type: "string", required: false, description: "Optional custom message included in notification email." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Secret link successfully provisioned.",
    content: {
      "id": "67397a4c...",
      "name": "Deployment API Token",
      "url": "https://hub.donutwork.com/ss/fb89f610...",
      "readed": false,
      "readerInfo": {
        "ip": null,
        "ua": null,
        "isoDate": null,
        "ts": null
      },
      "sendTo": { "status": true, "messageId": "msg_9921" }
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["Javascript"]}>
  <Tab value="Javascript">
    ```js
    const secretPayload = {
      shareSecret: {
        name: "Inter-Service Auth Key",
        content: "PRIVATE_KEY_CONTENT_HERE",
        sendTo: { email: "security-ops@acme.com", message: "Key Rotation: 2026-Q1" }
      }
    };

    try {
      const response = await sdk.tools.createShareSecret(secretPayload);
      console.log(`Secret Link Generated: ${response.url}`);
    } catch (error) {
      console.error(`Provisioning Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

***

## Access & Revocation

### Audit Access Metadata

Retrieve the access status and reader telemetry for a specific secret link. This endpoint provides audit trails (IP, User-Agent, Timestamp) once the secret has been consumed.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/share-secrets/{secretId}.json"
  params={[
  { name: "secretId", type: "string", required: true, description: "The unique identifier of the secret entry.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Access metadata successfully retrieved.",
    content: {
      "id": "6739782b...",
      "name": "Database Migration Credentials",
      "readed": true,
      "readerInfo": { 
        "ip": "82.1.4.22", 
        "ua": "Mozilla/5.0...", 
        "isoDate": "03/03/2026 11:20:00",
        "ts": 1772536800
      }
    } 
  }
]}
/>

### Revoke Secret Link

Manually revoke a secret link before it is consumed, or purge the audit record of an already read secret.

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/share-secrets/{secretId}.json"
  params={[
  { name: "secretId", type: "string", required: true, description: "The unique identifier to revoke.", location: "path" }
]}
  responses={[
  { 
    status: "202 Accepted", 
    description: "Secret link successfully revoked and record purged.",
    content: { "id": "67397a4c...", "deleted": true } 
  }
]}
/>

<Callout type="warning">
  **Security Policy:** Content retrieval is handled via the specific `url` field returned during provisioning. Once the `readed` flag is set to `true`, the content is physically deleted from the database and cannot be recovered.
</Callout>


# Shortlinks



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Shortlinks API

The Shortlinks API enables organizations to transform complex destination URLs into concise links. Beyond simple redirection, the system provides integrated telemetry for traffic attribution, enabling teams to monitor engagement performance in real time across distribution channels.

***

## Link Lifecycle Management

### Audit Shortlink Directory

Retrieve a paginated directory of all shortlinks associated with your organization. This inventory includes current operational status and destination metadata.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/shortlinks.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Shortlink inventory successfully retrieved.",
    content: {
      "entities": "Shortlink",
      "count": 42,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
          {
              "id": "675d9fea...",
              "title": "Spring 2026 Campaign",
              "original_url": "https://marketing.acme.com/promo/spring",
              "short_code": "k9x2m-spr26",
              "url": "https://d.dw2.it/r/k9x2m-spr26",
              "is_active": true
          }
      ]
    } 
  }
]}
/>

### Provision New Shortlink

Generate a new shortlink for a target destination.\
You can optionally provide a custom `fragment` (bitly-style suffix). The platform always prepends an auto-generated prefix to reduce collision risk.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/shortlinks.json"
  body={{
  "shortlink": {
      "title": "Product Launch Announcement",
      "original_url": "https://acme.com/products/new-gen-ai",
      "fragment": "launch-2026",
      "is_active": true
  }
}}
  properties={[
  { name: "shortlink.title", type: "string", required: true, description: "Administrative label for the link." },
  { name: "shortlink.original_url", type: "string", required: true, description: "The full destination URL (must include protocol)." },
  { name: "shortlink.fragment", type: "string", required: false, description: "Custom shortlink suffix (3-48 chars, letters/numbers/hyphens). Alias: `shortlink.short_code`." },
  { name: "shortlink.is_active", type: "boolean", required: false, description: "Operational status of the link. Defaults to true." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Shortlink successfully provisioned.",
    content: {
      "shortlink": { "id": "6768440..." },
      "short_code": "k9x2m-launch-2026",
      "url": "https://d.dw2.it/r/k9x2m-launch-2026"
    } 
  },
  {
    status: "409 Conflict",
    description: "Requested custom fragment is already in use.",
    content: { "error": "This shortlink fragment is already in use" }
  }
]}
/>

### Retrieve Link Configuration

Fetch the detailed configuration and operational status for a specific shortlink.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/shortlinks/{shortlinkId}.json"
  params={[
  { name: "shortlinkId", type: "string", required: true, description: "The unique identifier of the shortlink.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Shortlink configuration retrieved.",
    content: {
      "id": "675d9fea...",
      "title": "Spring 2026 Campaign",
      "original_url": "https://marketing.acme.com/promo/spring",
      "short_code": "k9x2m-spr26",
      "url": "https://d.dw2.it/r/k9x2m-spr26",
      "is_active": true
    } 
  }
]}
/>

***

## Operational Controls

### Update Link Parameters

Modify the destination URL, custom fragment, or operational status of an existing shortlink. Link updates are propagated across the redirection edge in near real-time.\
When updating `fragment`, the existing auto-generated prefix is preserved.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/shortlinks/{shortlinkId}.json"
  params={[
  { name: "shortlinkId", type: "string", required: true, description: "The unique identifier to update.", location: "path" }
]}
  body={{
  "shortlink": {
      "title": "Revised Spring Campaign",
      "original_url": "https://marketing.acme.com/promo/spring-final",
      "fragment": "spring-final",
      "is_active": true
  }
}}
  properties={[
  { name: "shortlink.title", type: "string", required: true, description: "Updated shortlink title." },
  { name: "shortlink.original_url", type: "string", required: true, description: "Updated destination URL." },
  { name: "shortlink.fragment", type: "string", required: false, description: "Updated custom suffix (3-48 chars, letters/numbers/hyphens). Alias: `shortlink.short_code`." },
  { name: "shortlink.is_active", type: "boolean", required: false, description: "Enable or disable link redirection." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Configuration updated successfully.",
    content: {
      "shortlink": { "id": "675d9fea..." },
      "short_code": "k9x2m-spring-final",
      "url": "https://d.dw2.it/r/k9x2m-spring-final"
    } 
  },
  {
    status: "409 Conflict",
    description: "Requested custom fragment is already in use.",
    content: { "error": "This shortlink fragment is already in use" }
  }
]}
/>

### Revoke Shortlink

Permanently revoke a shortlink and decommission its redirection service.

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/shortlinks/{shortlinkId}.json"
  params={[
  { name: "shortlinkId", type: "string", required: true, description: "The identifier to decompose.", location: "path" }
]}
  responses={[
  { 
    status: "202 Accepted", 
    description: "Shortlink successfully revoked.",
    content: { "id": "675d9fea...", "deleted": true } 
  }
]}
/>

***

## Analytics & Telemetry

### Retrieve Interaction Metrics

Access real-time engagement telemetry for a specific shortlink. This include visit counts, unique interactions, and longitudinal performance data.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/shortlinks/{shortlinkId}/stats.json"
  params={[
  { name: "shortlinkId", type: "string", required: true, description: "The shortlink identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Engagement metrics successfully aggregated.",
    content: {
      "shortlink": {
          "id": "675d9fea...",
          "title": "Spring 2026 Campaign",
          "original_url": "https://marketing.acme.com/promo/spring",
          "short_code": "k9x2m-spr26",
          "is_active": true,
          "url": "https://d.dw2.it/r/k9x2m-spr26",
          "created_at": 1772536800
      },
      "metrics": {
          "summary": { "human": 1530, "bot": 12, "total": 1542 },
          "view_density": [{ "country": "IT", "count": 600 }, { "country": "US", "count": 420 }],
          "referrers": { "Direct": 900, "linkedin.com": 350, "newsletter.acme.com": 292 },
          "bots": { "Google": 7, "Facebook": 5 },
          "browsers": { "Chrome": 1100, "Safari": 320, "Firefox": 110 },
          "os": { "Windows": 620, "macOS": 410, "iOS": 320, "Android": 180 }
      }
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["Javascript"]}>
  <Tab value="Javascript">
    ```js
    const shortlinkId = "675d9fea...";
    try {
      const stats = await sdk.dw2.getStats(shortlinkId);
      console.log(`Campaign Performance: ${stats.metrics.summary.total} total interactions.`);
    } catch (error) {
      console.error(`Telemetry Error: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>


# Taxes



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Taxes API

The Taxes API provides a centralized layer for managing tax profiles and regional tax logic. By defining tax profiles (such as VAT, GST, or Sales Tax), organizations can automate tax calculation during invoicing and subscription renewals, ensuring consistent compliance with local regulations.

***

## Tax Profiles

### List Tax Profiles

Retrieve a comprehensive directory of all tax profiles configured for your organization. These profiles act as the authoritative source for tax percentage calculations and must be referenced when provisiong new customers or products.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/taxes.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index for results.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Tax profile directory successfully retrieved.",
    content: {
      "entities": "Taxes",
      "count": 5,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
          {
              "id": "66a151b7...",
              "name": "Standard EU VAT (22%)",
              "percentage": 22.0,
              "description": "Standard Value Added Tax for European Union member states."
          }
      ]
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/taxes.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    try {
      const taxProfiles = await sdk.taxes.list();
      console.log(`Active Tax Profiles: ${taxProfiles.count}`);
    } catch (error) {
      console.error(`Compliance Check Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **Integration Note:** When orchestrating customer provisioning (via the CRM/Customer API), ensure the `tax_id` from these profiles is correctly mapped. This association is critical for accurate automated invoicing and financial reporting.
</Callout>

***

## Tax Profile Lifecycle

### Create Tax Profile

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/taxes.json"
  body={{
  "tax": {
    "name": "Standard EU VAT (22%)",
    "description": "EU default VAT profile",
    "percentage": 22.0,
    "default": false
  }
}}
  properties={[
  { name: "tax.name", type: "string", required: true, description: "Unique tax profile label." },
  { name: "tax.percentage", type: "number", required: true, description: "Tax percentage value. Must be >= 0." },
  { name: "tax.description", type: "string", required: false, description: "Optional internal description." },
  { name: "tax.default", type: "boolean", required: false, description: "Marks the profile as default when true." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Tax profile created.",
    content: {
      "status": "success",
      "tax": {
        "id": "tax_001",
        "name": "Standard EU VAT (22%)",
        "percentage": 22.0
      }
    }
  }
]}
/>

### Update Tax Profile

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/taxes/{taxId}.json"
  params={[
  { name: "taxId", type: "string", required: true, description: "Tax profile ID.", location: "path" }
]}
  body={{
  "tax": {
    "name": "EU VAT 2026",
    "description": "Updated profile metadata",
    "percentage": 23.0,
    "default": true
  }
}}
  properties={[
  { name: "tax.name", type: "string", required: false, description: "Updated tax profile label." },
  { name: "tax.description", type: "string", required: false, description: "Updated profile description." },
  { name: "tax.percentage", type: "number", required: false, description: "Updated percentage value. Must be >= 0." },
  { name: "tax.default", type: "boolean", required: false, description: "Update default profile flag." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Tax profile updated.",
    content: {
      "status": "success",
      "tax": {
        "id": "tax_001",
        "name": "EU VAT 2026",
        "percentage": 23.0
      }
    }
  }
]}
/>

### Delete Tax Profile

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/taxes/{taxId}.json"
  params={[
  { name: "taxId", type: "string", required: true, description: "Tax profile ID.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Tax profile deleted.",
    content: {
      "status": "success",
      "tax": {
        "id": "tax_001",
        "deleted": true
      }
    }
  },
  {
    status: "404 Not Found",
    description: "Tax profile not found.",
    content: { "error": "This tax profile does not exists" }
  }
]}
/>


# Webhook API



# Webhook API

Use webhooks to receive asynchronous notifications for supported platform events.

***

## List Webhooks

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/webhooks.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (1-100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index (1-based).", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Paginated list of webhook subscriptions.",
    content: {
      "entities": "Webhook",
      "count": 2,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "wh_001",
          "name": "Billing Events",
          "description": "Receive invoice and payment updates",
          "url": "https://example.com/webhooks/billing",
          "events": ["RecurringPayments.charge.paid"],
          "token": "redacted"
        }
      ]
    }
  }
]}
/>

## Create Webhook

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/webhooks.json"
  body={{
  "webhook": {
    "name": "Billing Events",
    "description": "Receive invoice and payment updates",
    "url": "https://example.com/webhooks/billing",
    "events": ["RecurringPayments.charge.paid"]
  }
}}
  properties={[
  { name: "webhook.name", type: "string", required: true, description: "Display name of the webhook subscription." },
  { name: "webhook.url", type: "string", required: true, description: "HTTPS endpoint that receives webhook payloads." },
  { name: "webhook.events", type: "array|string", required: true, description: "Subscribed event names. A single event string is also accepted." },
  { name: "webhook.description", type: "string", required: false, description: "Optional free-text description for internal use." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Webhook created successfully.",
    content: {
      "id": "wh_001",
      "name": "Billing Events",
      "description": "Receive invoice and payment updates",
      "url": "https://example.com/webhooks/billing",
      "events": ["RecurringPayments.charge.paid"],
      "token": "generated_webhook_token"
    }
  },
  {
    status: "412 Precondition Failed",
    description: "Name, url, or events missing; or TLS certificate validation failed.",
    content: { "error": "A valid \"url\" must be specified." }
  },
  {
    status: "422 Unprocessable Entity",
    description: "URL format invalid or unsupported event specified.",
    content: { "error": "Some events are not available" }
  }
]}
/>

## List Supported Webhook Types

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/webhooks/types.json"
  responses={[
  {
    status: "200 OK",
    description: "List of available webhook event names for the company context.",
    content: [
      "RecurringPayments.charge.paid",
      "RecurringPayments.charge.failed"
    ]
  }
]}
/>

## Get Webhook

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/webhooks/{webhookId}.json"
  params={[
  { name: "webhookId", type: "string", required: true, description: "Webhook unique identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Webhook details.",
    content: {
      "id": "wh_001",
      "name": "Billing Events",
      "description": "Receive invoice and payment updates",
      "url": "https://example.com/webhooks/billing",
      "events": ["RecurringPayments.charge.paid"],
      "token": "redacted"
    }
  },
  {
    status: "404 Not Found",
    description: "Webhook resource not found.",
    content: { "error": "Webhook not found." }
  }
]}
/>

## Delete Webhook

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/webhooks/{webhookId}.json"
  params={[
  { name: "webhookId", type: "string", required: true, description: "Webhook unique identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Webhook deletion accepted.",
    content: {
      "id": "wh_001",
      "deleted": true
    }
  },
  {
    status: "404 Not Found",
    description: "Webhook resource not found.",
    content: { "error": "Webhook not found. Unable to delete unknown resource" }
  }
]}
/>


# Workflow



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Workflow API

The Workflow API provides an engine for orchestrating complex, multi-stage business processes. By defining structured workflows, organizations can automate repetitive operational tasks, ensuring deterministic execution and full auditability. The engine supports dynamic payload injection for contextualized automation across the platform.

***

## Workflow Management

### List Workflows

Retrieve a comprehensive directory of all registered business workflows for your organization. This inventory includes the operational status, task count, and administrative metadata for each automation.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/workflow.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Workflow inventory successfully retrieved.",
    content: {
      "entities": "Workflow",
      "count": 12,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "6724bffd...",
          "name": "Enterprise Onboarding Logic",
          "active": true,
          "tasks_count": 8,
          "description": "Orchestrates account provisioning and initial compliance checks."
        }
      ]
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/workflow.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    try {
      const inventory = await sdk.workflow.list();
      console.log(`Active Automations: ${inventory.count}`);
    } catch (error) {
      console.error(`Workflow Audit Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

***

## Workflow Execution

### Dispatch Workflow Execution

Trigger the execution of a specific business workflow. This endpoint accepts a dynamic `data` payload that is injected into the execution context, allowing tasks to operate on real-time request data.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/workflow/{workflowId}.json"
  params={[
  { name: "workflowId", type: "string", required: true, description: "The unique identifier of the workflow to execute.", location: "path" }
]}
  body={{
  "data": {
    "customer_id": "cust_9921",
    "priority": "high",
    "metadata": { "source": "api_v2" }
  }
}}
  properties={[
  { name: "data", type: "object", required: true, description: "Dynamic context data injected into the workflow execution." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Workflow execution completed. Detailed stage results returned.",
    content: { 
      "success": true, 
      "execution_id": "exe_8821abd033",
      "stages": [
        { "node": "validate_identity", "status": "completed", "output": { "valid": true } }
      ]
    } 
  },
  { 
    status: "404 Not Found", 
    description: "The specified workflow identifier does not exist.",
    content: { "error": "This workflow does not exists" } 
  }
]}
/>

### Technical Implementation (Execution Flow)

<Tabs items={["Javascript"]}>
  <Tab value="Javascript">
    ```js
    const context = {
      data: {
        userId: "USR-001",
        action: "PROVISION_RESOURCE",
        quota: 100
      }
    };

    try {
      const result = await sdk.workflow.execute("ONBOARD_WF_01", context);
      if (result.success) {
        console.log(`Automation Finished: ${result.execution_id}`);
      }
    } catch (error) {
      console.error(`Execution Halted: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **Auditability:** Every workflow execution generates a unique `execution_id` and provides detailed telemetry for each stage (node) within the sequence, including input/output data and operational latency.
</Callout>

***

## Workflow Tracing

### List Workflow Traces

Retrieve paginated execution traces for a workflow.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/workflow/{workflowId}/traces.json"
  params={[
  { name: "workflowId", type: "string", required: true, description: "Workflow identifier.", location: "path" },
  { name: "size", type: "integer", required: false, description: "Records per page (default 50, max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page number starting from 1.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Trace list retrieved.",
    content: {
      "entities": "WorkflowTrace",
      "count": 2,
      "per_page": 50,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "6803f0f1...",
          "workflow_id": "67ffac1f...",
          "uuid": "d76d716e-0f91-4f7f-b37f-4475e573f807",
          "run_date": "2026-04-20T08:41:12+00:00",
          "status": "executed"
        }
      ]
    }
  },
  {
    status: "404 Not Found",
    description: "Workflow not found.",
    content: { "error": "This workflow does not exists" }
  }
]}
/>

### Get Workflow Trace

Load full trace payload for one workflow run.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/workflow/{workflowId}/traces/{traceId}.json"
  params={[
  { name: "workflowId", type: "string", required: true, description: "Workflow identifier.", location: "path" },
  { name: "traceId", type: "string", required: true, description: "Trace identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Trace retrieved.",
    content: {
      "id": "6803f0f1...",
      "workflow_id": "67ffac1f...",
      "uuid": "d76d716e-0f91-4f7f-b37f-4475e573f807",
      "run_date": "2026-04-20T08:41:12+00:00",
      "status": "executed",
      "response": {
        "input": { "customer_id": "cust_9921" },
        "result": { "workflow_status": "executed" },
        "stages": [
          { "node_name": "validate_identity", "status": "SUCCESS", "duration": 0.1281 }
        ]
      }
    }
  },
  {
    status: "404 Not Found",
    description: "Trace not found for workflow.",
    content: { "error": "Trace not found for this workflow." }
  }
]}
/>


# Authentication & Iframe Governance



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';

# Authentication & Embedding

DonutWork uses a robust security model to ensure that third-party applications can securely access data while providing a unified user experience. This guide covers the Dual-Auth workflow and the requirements for enterprise-grade Iframe embedding.

***

## 1. The OAuth 2.0 Workflow

Applications use a standard OAuth 2.0 Authorization Code flow to obtain scoped access to a company's data.

<Steps>
  ### Step 1: Authorization Request

  Redirect the user to the DonutWork authorization server. This occurs when a user first installs or accesses your app.

  **Endpoint**: `GET /i3/oauth/authorize`

  **Parameters**:

  * `client_id`: Your unique application identifier.
  * `redirect_uri`: The endpoint where the code will be sent.
  * `response_type`: Always `code`.
  * `scope`: Space- or comma-separated list of permissions in canonical format `resource:action` (e.g., `customers:read charges:write`).
  * `scope` minimum requirement: include at least `company:read` to complete a valid OAuth connection flow for app integrations.
  * `state`: A unique string to prevent CSRF attacks.

  ### Step 2: Token Exchange

  Once the user approves the request, DonutWork redirects them to your `redirect_uri` with a `code`. Exchange this code for an access token immediately.

  **Endpoint**: `POST /i3/oauth/token` (Form-Encoded)

  **Body**:

  * `client_id`: Your application identifier.
  * `client_secret`: Your secure application secret.
  * `code`: The authorization code received in the redirect.
  * `redirect_uri`: Must match the URI used in Step 1.

  ### Step 3: Persistence

  Store the returned `access_token` and `refresh_token` securely. These tokens allow your app to make direct API calls to DonutWork (e.g., to `/2026-02-01/customers.json`).
</Steps>

***

## 2. Iframe Context & Security

When an application is rendered inside the DonutWork dashboard, it is embedded via an Iframe. Every request to your application's entry point includes a security signature.

### Request Parameters

DonutWork appends the following query parameters to your application URL:

* `company`: The unique identifier of the active company.
* `hmac`: A cryptographic signature of the request.
* `timestamp`: The Unix timestamp of the request.

### Signature Verification (HMAC-SHA256)

To verify that the request is authentic and originated from DonutWork, you must validate the `hmac` parameter using your `client_secret`.

**Verification Procedure**:

1. Remove the `hmac` parameter from the key-value pairs.
2. Sort the remaining parameters alphabetically by key.
3. Concatenate the sorted keys and values into a query string (e.g., `company=C123&timestamp=1740000000`).
4. Calculate the HMAC-SHA256 of this string using your `client_secret` as the key.
5. Compare the result with the provided `hmac`.

<Tabs items={["Javascript", "Pseudo-Code"]}>
  <Tab value="Javascript">
    ```js
    const crypto = require('crypto');

    function verifyHmac(queryParams, clientSecret) {
      const { hmac, ...params } = queryParams;
      const message = Object.keys(params)
        .sort()
        .map(key => `${key}=${params[key]}`)
        .join('&');

      const expectedHmac = crypto
        .createHmac('sha256', clientSecret)
        .update(message)
        .digest('hex');

      return hmac === expectedHmac;
    }
    ```
  </Tab>

  <Tab value="Pseudo-Code">
    ```text
    1. ARGS = QueryString.Remove("hmac")
    2. SORTED_MSG = ARGS.SortByKey().Join("&")
    3. SIGNATURE = HMAC_SHA256(SORTED_MSG, APP_CLIENT_SECRET)
    4. VALIDATE(SIGNATURE == QueryString["hmac"])
    ```
  </Tab>
</Tabs>

***

## 3. UI Integration Requirements

Because the application runs in a cross-site Iframe, standard browser security policies apply.

### Session Management

Modern browsers block third-party cookies by default. To maintain a session within the Iframe, your session cookies **must** use the following attributes:

* `SameSite=None`: Allows the cookie to be sent in a cross-site context.
* `Secure=true`: Required when `SameSite=None` is used.

<Callout type="warning">
  If your cookies do not have `SameSite=None; Secure`, users will be logged out immediately after redirection or when navigating within the app.
</Callout>

### Content Security Policy (CSP)

Ensure your server headers allow DonutWork to embed your application:

```http
Content-Security-Policy: frame-ancestors 'self' https://hub.donutwork.com;
X-Frame-Options: ALLOW-FROM https://hub.donutwork.com
```

***

## 4. Capability Discovery

As the final step of the authentication flow, your application should declare its "capabilities" to the platform. This allows DonutWork to proxy requests to your app (Actions).

**Action**: `PUT /2026-02-01/integrations.json`

This declaration should include your `app_token` (used by DonutWork to call you) and a manifest of supported endpoints. Refer to the [Application Discovery Guide](/en/docs/applications/how-to-build#2-capability-discovery-the-manifest) for details.

For uninstall flow details (`DELETE uninstall_url` with `company_id` + HMAC `verify`), refer to [How to Build](/en/docs/applications/how-to-build).


# Donutwork Claude Code Skill



import { Callout } from 'fumadocs-ui/components/callout';

# Donutwork Claude Code Skill

The official Claude Code bundle is designed for teams that use Claude Code as their implementation copilot for Donutwork integrations.
It provides ready-to-use context so your team can move from API discovery to production launch with less rework.

***

## Why Teams Adopt It

* Speed up integration delivery with a structured `SKILL.md`.
* Reduce scope mistakes with endpoint and ACL references.
* Build payloads with higher confidence using field-level entity models.
* Standardize AI-assisted implementation across teams.

***

## What Is Included

* `.claude/skills/donutwork/SKILL.md`: Claude Code skill instructions and operating workflow.
* `references/api-endpoint-map.json`: method/path/scope inventory.
* `references/entity-models.json`: field-level entity model catalog.
* `references/openapi.public.json`: OpenAPI snapshot for tooling.
* `references/integration-playbook.md`: implementation and launch blueprint.

***

## Download

* Latest package (`.skill`): [`/downloads/donutwork-claude-code-skill-latest.skill`](/downloads/donutwork-claude-code-skill-latest.skill)
* Latest checksum: [`/downloads/donutwork-claude-code-skill-latest.sha256`](/downloads/donutwork-claude-code-skill-latest.sha256)
* Versioned package (`v1.1.0`): [`/downloads/donutwork-claude-code-skill-v1.1.0.skill`](/downloads/donutwork-claude-code-skill-v1.1.0.skill)
* Versioned checksum (`v1.1.0`): [`/downloads/donutwork-claude-code-skill-v1.1.0.sha256`](/downloads/donutwork-claude-code-skill-v1.1.0.sha256)

***

## Install In 60 Seconds

```bash
unzip -o donutwork-claude-code-skill-latest.skill -d "$HOME"
```

Optional integrity check:

```bash
sha256sum -c donutwork-claude-code-skill-latest.sha256
```

<Callout type="info">
  This package installs `.claude/skills/donutwork/SKILL.md` and references under your home directory, so Claude Code can auto-discover the skill.
</Callout>

***

## Quickstart Prompts

1. `Map required scopes for customers, charges, and webhooks in our Donutwork integration.`
2. `Generate payload contracts for customer and subscription synchronization.`
3. `Prepare a production readiness checklist for our Donutwork API launch.`

***

## Next Steps

* Start from the [AI Integration Hub](/en/docs/ai-integration) for the full AI-first path.
* If your team uses Codex, see [Donutwork Codex Skill](/en/docs/applications/donutwork-skill).
* Use [API Authentication](/en/docs/api/authentication) to validate key and OAuth setup.


# Donutwork Codex Skill



import { Callout } from 'fumadocs-ui/components/callout';

# Donutwork Codex Skill

The official `donutwork` Codex skill is a ready-to-use integration accelerator for partner and product teams.
It turns API docs into implementation-ready guidance with scope mapping, entity payload models, and go-live checklists.

***

## Why Teams Adopt It

* Reduce API onboarding time from days to hours.
* Build safer integrations with least-privilege scope guidance.
* Standardize payload contracts across engineering teams.
* Improve go-live confidence with repeatable validation checklists.

***

## What Is Included

* `SKILL.md`: operating workflow and response contract.
* `references/api-endpoint-map.json`: method/path/scope inventory.
* `references/entity-models.json`: field-level entity model catalog.
* `references/openapi.public.json`: OpenAPI snapshot for tooling.
* `references/integration-playbook.md`: implementation and launch blueprint.

***

## Download

* Latest package: [`/downloads/donutwork-skill-latest.tar.gz`](/downloads/donutwork-skill-latest.tar.gz)
* Latest checksum: [`/downloads/donutwork-skill-latest.sha256`](/downloads/donutwork-skill-latest.sha256)
* Versioned package (`v1.0.0`): [`/downloads/donutwork-skill-v1.0.0.tar.gz`](/downloads/donutwork-skill-v1.0.0.tar.gz)
* Versioned checksum (`v1.0.0`): [`/downloads/donutwork-skill-v1.0.0.sha256`](/downloads/donutwork-skill-v1.0.0.sha256)

***

## Install In 60 Seconds

```bash
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
tar -xzf donutwork-skill-latest.tar.gz -C "${CODEX_HOME:-$HOME/.codex}/skills"
```

Optional integrity check:

```bash
sha256sum -c donutwork-skill-latest.sha256
```

<Callout type="info">
  The extracted folder name is `donutwork`, so you can invoke it directly with `$donutwork`.
</Callout>

***

## Quickstart Prompts

1. `Use $donutwork to design an integration plan for syncing customers and subscriptions.`
2. `Use $donutwork to map required scopes for customer, charge, and webhook endpoints.`
3. `Use $donutwork to generate request payload models and a production go-live checklist.`

***

## Next Steps

* Start from the [AI Integration Hub](/en/docs/ai-integration) for a complete AI-first integration path.
* If your team uses Claude Code, see [Donutwork Claude Code Skill](/en/docs/applications/donutwork-claude-code-skill).
* Use [API Authentication](/en/docs/api/authentication) to validate API key and OAuth setup.
* Use [API Reference](/en/docs/api) to expand your endpoint coverage after the first release.


# How to Build a DonutWork App



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Building for DonutWork

This guide provides a conceptual and technical blueprint for developing third-party applications. The DonutWork framework is explicitly **programming language agnostic**, relying on standard HTTP/REST protocols and secure UI embedding to facilitate cross-system orchestration.

***

## 1. Application Registration

Before you begin development, you must register your application to obtain the necessary credentials for identity and platform access.

* **Client ID**: Your application's public identifier.
* **Client Secret**: A secure credential used to authorize your app to act on behalf of a company.
* **Redirect URI**: The URL where DonutWork will send authorization codes.

Refer to the [Detailed OAuth Guide](/en/docs/applications/auth-and-embedding) for the technical authentication handshake.

***

## 2. Capability Discovery (The Manifest)

DonutWork uses a **Discovery Pattern** to understand what your application is capable of. Instead of DonutWork calling your app blindly, your app must "declare" its capabilities (Actions).

### Declaring Capabilities

Your application should send a `PUT` request to the `/integrations.json` endpoint. This manifest tells DonutWork which endpoints to call when a specific action is triggered (e.g., via a Workflow or the UI).

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/integrations.json"
  body={{
  "app_token": "YOUR_APP_SHARED_TOKEN",
  "capabilities": [
      {
          "name": "ping",
          "description": "Test connection health",
          "endpoint": "https://your-app.com/api/ping.json",
          "method": "GET",
          "inputs": []
      },
      {
          "name": "provision_resource",
          "description": "Create a new resource",
          "endpoint": "https://your-app.com/api/provision.json",
          "method": "POST",
          "inputs": [
              { "name": "resource_name", "type": "string", "required": true }
          ]
      }
  ]
}}
/>

* **app\_token**: DonutWork will include this Bearer token in every `Authorization` header when it calls your application. This allows your app to verify that the request is coming from DonutWork.
* **capabilities**: An array of allowed actions, each with a defined `endpoint`, `method`, and expected `inputs`.

***

## 3. Communication Pattern (The Action Logic)

When a user or a generic workflow triggers an action, DonutWork acts as a **Secure Proxy**.

1. **Trigger**: DonutWork identifies the target `Action` (e.g., `provision_resource`).
2. **Identification**: DonutWork retrieves the `endpoint` and `app_token` from your saved manifest.
3. **Execution**: DonutWork sends an HTTP request to your endpoint, including the `app_token` in the header and the required data in the body.
4. **Response**: Your application processes the request and returns a standard JSON response.

***

## 4. UI Framework (The Iframe)

DonutWork embeds your application's frontend inside its own dashboard via an **Iframe**. To ensure a smooth user experience and maintain security, you must adhere to the following policies:

### Cookie Security (`SameSite=None`)

Because your application is running in an Iframe context (cross-site), traditional session cookies may be blocked by modern browsers. You must configure your session cookies with:

* `SameSite=None`
* `Secure=true`

### Security Headers

DonutWork allows Iframe embedding from registered applications. On your end, you should ensure your headers allow the platform to display your content. For a deep dive into signature verification, see [Iframe Context & Security](/en/docs/applications/auth-and-embedding#2-iframe-context--security).

```http
Content-Security-Policy: frame-ancestors 'self' https://hub.donutwork.com;
X-Frame-Options: ALLOW-FROM https://hub.donutwork.com
```

***

## 5. Event Synchronization (Webhooks)

To react to platform events in real-time (e.g., when a user pays a bill), you should register a Webhook.

1. **Endpoint**: Your application should provide a dedicated HTTPS URL to receive POST payloads.
2. **Key Rotation**: During registration, you will receive a `token`. Use this key to verify the `X-SIGNATURE` header on every incoming request.

***

## 6. Uninstall Callback (Company Data Cleanup)

When a company uninstalls your app from DonutWork, the platform sends a server-to-server callback to your configured `uninstall_url`.

* **Method**: `DELETE`
* **Content-Type**: `application/x-www-form-urlencoded`
* **Body**:
  * `company_id`: Company identifier to delete.
  * `verify`: HMAC signature computed as `HMAC_SHA256(company_id, client_secret)`.

Example payload:

```http
DELETE /uninstall HTTP/1.1
Content-Type: application/x-www-form-urlencoded

company_id=699ecb44790ac4eea20e9cd3&verify=7c72b2...
```

Verification rule on your side:

```php
$expected = hash_hmac('sha256', $companyId, $clientSecret);
$isValid = hash_equals($expected, $verify);
```

Implementation requirements:

* Validate `company_id` and `verify` before deleting anything.
* Delete only tenant-scoped data for that `company_id`.
* Make the endpoint idempotent (repeated calls must not fail).
* Return a `2xx` response only when cleanup is completed (or already completed).

If your endpoint returns non-2xx, DonutWork will treat the uninstall callback as failed and local uninstall will be blocked.

***

## Summary Checklist

* [ ] Register App and obtain Client ID/Secret.
* [ ] Implement OAuth 2.0 to obtain Platform Access Tokens.
* [ ] Use `PUT /integrations.json` to declare your app's endpoints.
* [ ] Implement your API endpoints to handle requests from the DonutWork proxy.
* [ ] Configure `SameSite=None` and `Secure` cookies for your Iframe UI.
* [ ] Register Webhooks for real-time event processing.
* [ ] Implement `DELETE uninstall_url` with `company_id` + HMAC `verify` and tenant-safe cleanup.


# Application Framework



import { 
  Puzzle, 
  Settings, 
  Zap, 
  Shield,
  Package
} from 'lucide-react';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';

The DonutWork Application Framework allows developers to extend the platform's core capabilities with specialized third-party services. Whether you are building a financial connector, a marketing automation tool, or a custom CRM integration, our framework provides the necessary hooks for seamless orchestration.

***

## Integration Architecture

DonutWork applications operate on a hybrid model that combines secure UI embedding with robust API-driven capability discovery.

<div className="grid grid-cols-1 md:grid-cols-2 gap-6 mt-10">
  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#7ABA23]/50 transition-all group">
    <Puzzle size={40} className="text-[#7ABA23] mb-4" />

    ### Capability Discovery

    **Autonomous Registration.** Applications declare their available "Actions" via a standard JSON manifest. DonutWork then makes these actions available to the core engine and workflows.
    [How to build →](/en/docs/applications/how-to-build)
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#FECC55]/50 transition-all group">
    <Settings size={40} className="text-[#FECC55] mb-4" />

    ### Iframe Embedding

    **Unified UI Experience.** Apps are embedded directly into the DonutWork dashboard. This ensures a consistent user experience while maintaining the app's independent execution context.
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#7ABA23]/50 transition-all group">
    <Zap size={40} className="text-[#7ABA23] mb-4" />

    ### Event-Driven Hooks

    **Real-Time Synchronization.** Use Webhooks to react to platform lifecycle events (charges, renewals, identity changes) and maintain data integrity across systems.
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#FECC55]/50 transition-all group">
    <Shield size={40} className="text-[#FECC55] mb-4" />

    ### Zero-Trust Security

    **Managed Authorization.** DonutWork acts as a secure proxy, handling authorization between the platform and your application with signed requests and scoped tokens.
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#7ABA23]/50 transition-all group">
    <Package size={40} className="text-[#7ABA23] mb-4" />

    ### Codex Integration Skill

    **Faster Implementation.** Download the official `donutwork` skill package to get endpoint maps, entity models, and launch checklists for your integration team.
    [Get the skill →](/en/docs/applications/donutwork-skill)
  </div>
</div>

***

## Developer Roadmap

Building an application for DonutWork involves the following key phases:

<Steps>
  ### Registration & Authentication

  Provision your application in the Developer Portal to obtain a unique `Client ID` and `Client Secret`. Use these to implement the standard [OAuth 2.0 flow](/en/docs/applications/auth-and-embedding).

  ### Capability Declaration

  Call the `/integrations.json` endpoint to tell DonutWork what your app can do. This manifest defines your endpoints, the methods they support, and the required input data.

  ### Lifecycle & UI Implementation

  Build your application frontend, ensuring compatibility with our [Iframe-based embedding system](/en/docs/applications/auth-and-embedding#2-iframe-context--security) and security policies (such as `SameSite` cookie requirements).

  ### Production Readiness

  Configure your webhook security tokens and deploy your service to a production environment.
</Steps>


# Business Intelligence & Growth



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { TrendingUp, PieChart, Activity, Zap } from 'lucide-react';

# Business Intelligence & Growth

The Donutwork BI & Growth section is designed to give you a crystal-clear view of your project's financial health. No more cross-referencing spreadsheets: everything is calculated automatically in real time.

## Key Metrics Tracked

Donutwork aggregates data from the billing engine and user interactions to provide you with precise KPIs:

<Cards>
  <Card icon={<TrendingUp className="text-blue-500" />} title="MRR & ARR" description="View monthly and annual recurring revenue with historical growth projections." />

  <Card icon={<PieChart className="text-purple-500" />} title="Revenue Mix" description="Detailed analysis of recurring revenue (subscriptions) and one-time revenue (add-ons, setup fees)." />

  <Card icon={<Activity className="text-green-500" />} title="Growth Rate" description="Month-over-Month (MoM) growth tracking to validate your marketing strategy." />
</Cards>

***

## Revenue Analysis

Donutwork intelligently separates the different revenue sources to allow you to understand what's truly driving your growth.

### Real-time Analytics

As soon as you access the dashboard, you'll have a quick overview of:

* **Recent Transactions:** Real-time history of every purchase or renewal.
* **Customer Lifetime Value (LTV):** Automatic calculation of the average value of a customer over time.

***

## Growth Strategies

Use the data collected to fuel your growth processes:

* **Identify Power Users:** Discover which customers are most consistent and/or growing and propose upgrades to higher plans.
* **Churn Prevention:** Monitor sudden drops in subscription activity to intervene before the user cancels their subscription.
* **Partner Performance:** Cross-reference BI data with the [Partner Program](/en/docs/partner-program) to see which affiliates bring in the highest LTV customers.

***

## Operating Rhythm

Turn BI into action with a recurring cadence:

1. Weekly: review failed renewals and churn signals.
2. Bi-weekly: compare cohort retention by acquisition source.
3. Monthly: adjust pricing, partner incentives, or plan packaging based on margin and LTV.

<Callout type="info" title="Cross-functional playbook">
  For best results, review BI dashboards together with Customer, Recurring Payments, and Partner Program owners before shipping pricing or lifecycle changes.
</Callout>

## Related Areas

* [Recurring Payments](/en/docs/recurring-payments)
* [Customer Management](/en/docs/customer)
* [Partner Program](/en/docs/partner-program)


# Customer Management & Financial Hub



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { 
  Users, 
  Fingerprint, 
  CreditCard, 
  Tags, 
  TrendingUp, 
  ShieldAlert, 
  Receipt,
  Layers
} from 'lucide-react';

# Customer Management & Financial Hub

The **Customer** module in Donutwork is more than just a contact database; it is a financial control center for every individual client. It allows you to monitor business health through predictive metrics and manage the entire payment lifecycle.

## Customer Financial Scorecard (Beta)

For every customer with at least one transaction, Donutwork automatically generates a **financial scorecard** to help evaluate stability and growth:

<Cards>
  <Card icon={<TrendingUp className="text-green-500" />} title="MRR & YRR" description="Instant calculation of Monthly Recurring Revenue and annual projections based on active subscriptions." />

  <Card icon={<ShieldAlert className="text-red-500" />} title="Risk Assessment" description="Analysis of volatility and history duration to assign a specific risk class to the customer." />
</Cards>

***

## Subscription & Add-ons Management

Donutwork allows for granular management of recurring revenue directly from the customer profile:

* **Plan Association:** Quickly link existing subscription plans to the profile.
* **Add-on Modification:** Dynamic management of quantities and pricing for additional subscription components.
* **Tax & Discounts:** Apply global discounts (percentage or fixed) and manage multiple VAT rates per service line.
* **Metering:** Monitor usage for consumption-based plans (Metered Billing).

***

## Payments & Transactions

The interface organizes financial activities into three main sections using a persistent tab system:

### 1. Payment Methods

Manage associated credit cards (via Stripe). The system supports:

* **Secure Payment Links:** Generate protected links to allow customers to enter their payment details autonomously.
* **CVC/3DS Validation:** Real-time security status checks for payment methods.

### 2. Transactions (Charges)

A complete history of every charge attempt or successful payment:

* **Manual Creation:** Create "One-time charges" (e.g., setup fees or consulting) directly from the panel.
* **Receipts & Logs:** Immediate access to PDF receipts and status monitoring (Pending, Succeeded, Failed).

### 3. Subscriptions

A dedicated tab to control active plans, renewal dates, and provisioning status.

***

## Dynamic Properties (Custom Fields)

Beyond financial data, you can extend the customer profile using **Customer Properties**. These metadata fields are essential for:

* Configuring custom API limits per customer.
* Saving specific workflow preferences.
* Mapping External IDs for third-party system integrations.


# Directory Monitor & Event Automation



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import {
  FolderSearch,
  ShieldCheck,
  Activity,
  Workflow,
  FileSearch,
  Timer,
  Fingerprint,
  Zap
} from 'lucide-react';

# Directory Monitor

The Donutwork Directory Monitor is a native **security + automation module** that tracks file activity in watched paths and converts those events into actionable automations.

It is designed for teams that need:

1. Reliable filesystem event capture
2. Centralized event visibility
3. Deterministic workflow triggering

***

## System Architecture

The module is built on four connected layers:

1. **Local Agent (Rust):** Watches directories and emits normalized events (`Create`, `Delete`, `WriteFinished`).
2. **Secure Ingress API:** Accepts monitor payloads, validates auth, and deduplicates by `eventId`.
3. **Event Store:** Persists monitor events with indexed search for operational and forensic review.
4. **Workflow Dispatcher:** Publishes both generic and typed triggers to run matching workflows.

<Callout type="info" title="Backward Compatibility">
  Existing generic triggers remain supported: <code>DirectoryMonitor.\{projectId}.notify</code>.
  You can progressively adopt typed triggers such as <code>DirectoryMonitor.\{projectId}.WriteFinished.notify</code>.
</Callout>

***

## Event Pipeline

When a file changes, the following happens:

1. The monitor emits a payload with event metadata (`filename`, `event`, `filesize`, optional `sha256`, `uid`, `pid`, `timestampUtc`, `eventId`).
2. Ingress validates:
   * API key (`Authorization: Bearer ...`)
   * Project token (`X-Directory-Monitor-Token`)
3. Event is saved in the monitor event collection.
4. Two notifications are dispatched:
   * Generic: `DirectoryMonitor.{projectId}.notify`
   * Typed: `DirectoryMonitor.{projectId}.{event}.notify`
5. Matching workflows are queued and executed through the existing workflow async pipeline.

***

## Logs & Observability

Directory Monitor includes a dedicated **Logs View** per project with:

1. Event filtering by:
   * Event type
   * Path contains
   * Status
   * Date range
2. Paginated event list with:
   * Timestamp
   * Event type
   * File path
   * File size
   * Workflow status badges (`queued`, `workflow_triggered`, `workflow_failed`)
3. Direct links to related workflow traces.

<Callout type="info" title="Retention">
  Events are stored with TTL indexing (default 90 days).
</Callout>

***

## Workflow Triggering Model

For high-precision automation, prefer typed triggers:

| Trigger                                             | Purpose                                 | Example                                     |
| :-------------------------------------------------- | :-------------------------------------- | :------------------------------------------ |
| `DirectoryMonitor.{projectId}.WriteFinished.notify` | Run only after file write stabilization | Launch malware scan after upload completion |
| `DirectoryMonitor.{projectId}.Create.notify`        | React on object creation                | Tag and classify newly dropped files        |
| `DirectoryMonitor.{projectId}.Delete.notify`        | Detect deletions                        | Alert on unexpected file removal            |
| `DirectoryMonitor.{projectId}.notify`               | Legacy generic trigger                  | Backward compatible workflows               |

***

## Security Controls

The monitor ingress path is protected with layered controls:

1. **Company API key authentication**
2. **Project-level secret token validation**
3. **Payload validation for required fields**
4. **Idempotent dedupe through unique `eventId`**

This model allows multi-project isolation while preserving your current API gateway behavior.

***

## Real World Automation Patterns

<Cards>
  <Card icon={<FileSearch className="text-blue-500" />} title="File Compliance Checks" description="On WriteFinished, run validation workflows (hash policy, naming convention, extension checks)." />

  <Card icon={<ShieldCheck className="text-green-500" />} title="Security Response" description="Trigger scan, quarantine, and alert actions when suspicious files appear in watched paths." />

  <Card icon={<Workflow className="text-yellow-500" />} title="Business Automation" description="Automatically launch ingestion pipelines, enrichment jobs, and webhook notifications from file events." />
</Cards>

***

## Feature Snapshot

<Cards>
  <Card icon={<FolderSearch className="text-indigo-500" />} title="Recursive Monitoring" description="Observe complete directory trees and capture create, modify, and delete behavior." />

  <Card icon={<Timer className="text-cyan-500" />} title="Write Stability Handling" description="`WriteFinished` is emitted after stabilization windows to avoid partial-file processing." />

  <Card icon={<Activity className="text-emerald-500" />} title="Heartbeat & Startup Signals" description="Monitors report startup and active status, enabling operational visibility per project." />

  <Card icon={<Fingerprint className="text-purple-500" />} title="Rich Event Metadata" description="Attach `sha256`, `uid`, and `pid` (when available) for stronger audit and investigation context." />

  <Card icon={<Zap className="text-amber-500" />} title="Event-Driven Workflows" description="Bridge file system events directly into the existing Donutwork workflow engine." />
</Cards>


# Dynamic Content Modeling



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { 
  Layout, 
  Database, 
  FileJson, 
  Eye, 
  Settings, 
  FormInput 
} from 'lucide-react';

# Dynamic Content Modeling (Content Box)

The **Content Box** system is designed to eliminate the rigidity of traditional databases. It allows you to create "Models" (Types) that define the schema of your data, and then manage that content through automatically generated, user-friendly interfaces.

## The Core Concept: Types vs. Contents

To master content modeling in Donutwork, it is important to distinguish between these two levels:

1. **Types (The Schema):** You define the structure. Example: "A *Team Member* type has a name, a photo, a bio, and a role."
2. **Contents (The Data):** You create the actual entries based on that schema. Example: "John Doe, CEO, photo.jpg..."

***

## Supported Field Types

The **Fields Manager** offers a wide variety of inputs to cover any data-entry requirement, from simple strings to complex logic:

| Category          | Input Type           | Typical Use Case                                       |
| :---------------- | :------------------- | :----------------------------------------------------- |
| **Textual**       | Standard Text        | Titles, short names, labels.                           |
|                   | Long Text (Textarea) | Descriptions, bios, rich content.                      |
|                   | Password / Secure    | API Keys, secrets, or sensitive data (masked).         |
|                   | URL Address          | External links, social media profiles.                 |
| **Logic & Lists** | Dropdown Select      | Single choice from a predefined list (e.g., Category). |
|                   | Multiple Selection   | Tags, skills, or multi-category assignments.           |
|                   | Toggle / Checkbox    | Boolean states (Yes/No, Active/Inactive).              |

***

## Structure Examples (Use Cases)

Here are common ways to configure your **Types** for different business scenarios:

### 1. FAQ Section

* **Question:** Standard Text (Required)
* **Answer:** Long Text
* **Category:** Dropdown Select (Options: *Billing, Technical, Account*)
* **Featured:** Toggle

### 2. Product Datasheet (SaaS)

* **Product Name:** Standard Text
* **Stripe Price ID:** Masked Input (to protect sensitive billing IDs)
* **Feature List:** Multiple Selection
* **Documentation:** URL Address
* **Maturity:** Dropdown Select (*Beta, Stable, Deprecated*)

### 3. Customer Testimonials

* **Client Name:** Standard Text
* **Company:** Standard Text
* **Quote:** Long Text
* **Rating:** Dropdown Select (*1, 2, 3, 4, 5 stars*)

***

## Visibility States

Every **Content Box** entry can be set to one of the following states:

* 🟡 **Draft:** The content is saved but not accessible via public APIs or the frontend.
* 🟢 **Public:** The content is live and ready to be displayed.
* 🔴 **Private:** Only visible within the Donutwork Admin area—perfect for internal configuration data.

***

## Advanced Features

<Cards>
  <Card icon={<Settings className="text-blue-500" />} title="Auto-Generated UI" description="No need to build forms manually. As soon as you update a Type's schema, the entry form updates instantly." />

  <Card icon={<Layout className="text-green-500" />} title="Drag & Drop Ordering" description="Reorder fields within your schema to prioritize the most important information for your team." />

  <Card icon={<FileJson className="text-purple-500" />} title="Headless-Ready" description="All saved data is delivered as clean JSON via REST API, perfect for React, Vue, or Mobile Apps." />
</Cards>

<Callout type="info" title="Developer Tip">
  Every field has an **Internal Key (DB)**. Use clear, `snake_case` names (e.g., `hero_image_url`) because this key will be used as the property name in the JSON returned by the Donutwork API.
</Callout>


# Email Gateway



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Palette, Settings, ShieldCheck } from 'lucide-react';

# Email Gateway

The Donutwork **Email Gateway** is the complete infrastructure for managing your SaaS communications. It handles the entire lifecycle of an email: from DNS record configuration to visual template design.

<Cards>
  <Card icon={<Palette className="text-blue-500" />} title="Template Design" href="/en/docs/email-gateway/template" description="Create professional emails using the Drag & Drop editor or write your own custom HTML code." />

  <Card icon={<Settings className="text-green-500" />} title="SMTP Configuration" href="/en/docs/email-gateway/settings" description="Set up your own sending servers (Custom SMTP) or use Donutwork's shared infrastructure." />

  <Card icon={<ShieldCheck className="text-purple-500" />} title="Deliverability" href="/en/docs/email-gateway/settings" description="Protect your sender reputation by correctly configuring SPF and DKIM records." />
</Cards>

***

## Key Features

### 1. Visual & Code Editor

Choose how you work. The visual **Mail Designer** (powered by GrapesJS) allows anyone to create responsive layouts. For developers, the integrated **Ace Editor** provides total control over the source code with real-time previews.

### 2. Multi-Sender Management

Define **Alternative Senders** to send communications from different departments (e.g., `support@`, `billing@`, `info@`) without needing to configure multiple SMTP servers.

### 3. Native Integration

Templates saved in the Gateway are instantly available across the platform:

* **Workflows:** Send automated emails by dragging a simple node.
* **API:** Call templates via REST endpoints while passing dynamic variables.

***

## Quick Navigation

The Email Gateway is divided into two main areas:

### [Template Management & Design](/en/docs/email-gateway/template)

Learn how to create new files, organize your template library, and use the designer to make your emails look perfect on any device.

### [Settings & Deliverability](/en/docs/email-gateway/settings)

Learn how to configure your custom SMTP server, validate connections with the test tool, and set up the DNS records required to stay out of the SPAM folder.

## Suggested Go-Live Sequence

1. Configure SMTP and DNS authentication first.
2. Create one transactional template and one operational alert template.
3. Run delivery tests from staging addresses.
4. Connect template sends to [Workflow](/en/docs/workflow) and API flows.


# Settings & Deliverability



import { Callout } from 'fumadocs-ui/components/callout';

# Email Settings & Deliverability

To ensure your emails reach the inbox and not the spam folder, Donutwork provides advanced tools for mail server configuration and domain authentication.

## SMTP Configuration

Donutwork allows you to choose between two sending modes:

1. **System SMTP:** Use Donutwork’s default infrastructure for immediate setup.
2. **Custom SMTP:** Configure your own providers (e.g., SendGrid, Mailgun, Amazon SES) by entering Host, Port, Username, and Password.

***

## Domain Authentication (SPF & DKIM)

Security is key to email delivery. Use the following settings to authorize Donutwork to send mail on your behalf.

### SPF Record

Add this value to your domain's SPF record in your DNS settings:
`include:_spf_hosted.donutwork.com`

### Enforce DKIM

DKIM adds a digital signature to your emails. To enable it:

1. Toggle the **Enforce DKIM** option in settings.
2. Add a **CNAME** record to your DNS:
   * **Host:** `donutwork._domainkey.YOUR_DOMAIN`
   * **Target:** `smtp._domainkey.donutwork.com`

***

## Alternative Senders

You are not limited to a single "From" address. You can define multiple senders for different purposes:

* `support@yourbrand.com` for help desk replies.
* `billing@yourbrand.com` for automated invoices.
* `news@yourbrand.com` for marketing updates.

Each sender can have a unique **Display Name** to increase user trust.

***

## Email Tester

Before going live, use the integrated **Email Tester**.

1. Enter your personal email address.
2. Click **Send Test Email**.
3. Instantly verify if your SMTP settings are correct and if the email arrives with the correct formatting.

<Callout type="info" title="Connection Test">
  Use the **Test Connection** button after entering your SMTP credentials for immediate feedback on server reachability before saving.
</Callout>


# Templates



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Palette, Code, Eye } from 'lucide-react';

# Managing Email Templates

Donutwork decouples email design from your application logic. By using templates, your marketing team can update content and layouts without touching a single line of backend code.

## Two Editing Modes

Donutwork offers total flexibility in template creation by supporting two distinct approaches:

<Cards>
  <Card icon={<Palette className="text-blue-500" />} title="Visual Mail Designer" description="A drag-and-drop editor based on GrapesJS for creating responsive layouts without coding." />

  <Card icon={<Code className="text-purple-500" />} title="Advanced Code Editor" description="A professional environment (Ace Editor) with syntax highlighting for developers needing custom HTML/CSS." />
</Cards>

***

## Working with Templates

From the main dashboard, you can:

* **Create New Templates:** Define clear filenames (e.g., `welcome-kit` or `payment-failed`). Naming follows the `[a-z0-9-]` pattern.
* **Visual Designer:** Click the **Palette** icon to enter the visual editor. It includes pre-built blocks like buttons, images, and columns.
* **Code Editor:** Click the **Pencil** icon to edit raw HTML.
* **Live Preview:** Use the **Eye** icon within the editor to see how your email renders on mobile and desktop devices.

***

## Workflow Integration

Once a template is saved, it is immediately available in the **Workflow** module. Simply drag a **Send Email** node into your flow and select the desired template from the dropdown menu.

***

## Next Steps

<Cards>
  <Card title="SMTP & Deliverability" href="/en/docs/email-gateway/settings" description="Configure sending servers and authentication records before scaling volume." />

  <Card title="Workflow Automation" href="/en/docs/workflow" description="Attach your templates to customer, billing, and lifecycle automation flows." />
</Cards>


# Charge Entity



import { Steps, Step } from 'fumadocs-ui/components/steps';

# Charge Entity

A **Charge** (also referred to as a Transaction) represents a specific financial balance associated with a **Customer**. It can be generated automatically by a subscription renewal or created manually for one-off services.

## Usage

The Charge entity is used to:

* Process ad-hoc payments for setup fees, consulting, or hardware.
* Store the history of recurring billing events.
* Manage association with legal documents (invoices and receipts).
* Track the real-time payment status (Pending, Paid, Refunded).

## Expected Operational Flow

Lifecycle of a financial transaction:

<Steps>
  <Step>
    ### Charge Generation

    Create a charge object via `POST /customers/{id}/charges.json`. You can define multiple service lines, each with its own specific tax profile for granular accounting.
  </Step>

  <Step>
    ### Execution & Capture

    If `capture: true` is set, DonutWork immediately attempts to process the transaction using the customer's primary payment method. Otherwise, the charge remains `awaiting_response`.
  </Step>

  <Step>
    ### Status Synchronization

    Monitor the real-time status of the charge. Upon successful payment, the system triggers a `Charge.Paid` webhook to your application.
  </Step>

  <Step>
    ### Invoicing & Compliance

    Once paid, synchronize the transaction with your accounting software and use the `PUT /.../invoice.json` endpoint to attach the legal document details to the record.
  </Step>
</Steps>

***

## Data Schema

The fields defining a Charge object:

| Field         | Type     | Description                                             |
| :------------ | :------- | :------------------------------------------------------ |
| `id`          | `eid`    | Unique extended identifier.                             |
| `customer_id` | `string` | The owner of the transaction.                           |
| `total`       | `number` | Net total of the transaction (including tax lines).     |
| `status`      | `string` | Current state: `pending`, `paid`, `refunded`, `failed`. |
| `services`    | `array`  | List of items being billed with their tax profiles.     |
| `invoice`     | `object` | Metadata for accounting (number, date, external link).  |
| `date`        | `object` | Precise timestamp of the creation event.                |

***

## Relationship Call Graph

How Charges interact with external payment gateways:

<Mermaid
  chart="sequenceDiagram
    participant App as Your Application
    participant DW as DonutWork API
    participant Provider as Payment Provider
    
    App->>DW: POST /charges (with capture: true)
    DW->>Provider: Auth & Capture (using default CC)
    Provider-->>DW: Status: Successful
    DW->>DW: Update Charge Status to 'paid'
    DW->>App: Webhook: Charge.Paid
    App->>DW: PUT /charges/{id}/invoice (Sync Invoice Data)
    DW-->>App: Acknowledged"
/>


# Customer Entity



import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { User, Key, CreditCard, Play } from 'lucide-react';

# Customer Entity

The **Customer** is the central node of the DonutWork ecosystem. It represents the legal entity or individual that consumes your services and generates revenue.

## Usage

The Customer entity is used to:

* Track contact and billing information.
* Associate recurring subscriptions and one-time charges.
* Store custom metadata via dynamic properties for deep integration with your own platform.
* Monitor financial risk and health (MRR/YRR).

## Expected Implementation Flow

To successfully onboard and bill a customer, follow this standard logical flow:

<Steps>
  <Step>
    ### Customer Lifecycle Initialization

    Create the identity using the `POST /customers.json` endpoint. Assign a unique `externalId` from your internal database to maintain perfect synchronization.
  </Step>

  <Step>
    ### Context & Property Enrichment

    (Optional) Use `PUT /customers/{id}/properties.json` to store platform-specific data like billing tiers, preferred language, or API quotas.
  </Step>

  <Step>
    ### Secure Payment Onboarding

    Call `GET /customers/{id}/payment_link.json`. This generates a one-time use URL. Redirect your user to this page—DonutWork handles the PCI-compliant credit card entry via Stripe.
  </Step>

  <Step>
    ### Activation & Billing

    Once the payment method is attached (confirmed via Webhook), trigger a billing event. You can either attach a `Subscription` for recurring revenue or create a `Charge` for one-time fees.
  </Step>
</Steps>

***

## Data Schema

The following table defines the core structure of a Customer object:

| Field          | Type     | Description                                          |
| :------------- | :------- | :--------------------------------------------------- |
| `id`           | `eid`    | Unique extended identifier generated by DonutWork.   |
| `external_id`  | `string` | Your internal system identifier.                     |
| `email`        | `string` | Primary contact and billing email.                   |
| `company_name` | `string` | Legal name used for invoicing.                       |
| `address`      | `object` | Geographic data (country is required for tax logic). |
| `properties`   | `array`  | Key-value pairs for custom integration data.         |
| `status`       | `string` | `active`, `suspended`, or `deleted`.                 |

***

## Relationship Call Graph

This graph illustrates how the Customer entity interacts with other core system components during its lifecycle.

<Mermaid
  chart="sequenceDiagram
    participant App as Your Application
    participant DW as DonutWork API
    participant Provider as Payment Provider
    
    rect rgb(30, 30, 35)
    Note over App, Provider: Phase 1: Identity & Setup
    App->>DW: POST /customers (Create)
    DW-->>App: Return Customer ID
    App->>DW: GET /customers/{id}/payment_link
    DW-->>App: Return Hosted URL
    end

    rect rgb(20, 40, 20)
    Note over App, Provider: Phase 2: Funding & Activation
    App->>Provider: User Enters CC Info (Secure)
    Provider-->>DW: Webhook: Method Attached
    DW->>App: Webhook: Payment.Updated
    App->>DW: POST /customers/{id}/subscriptions
    DW-->>App: Subscription Activated
    end"
/>


# Email Delivery Entity



import { Steps, Step } from 'fumadocs-ui/components/steps';

# Email Delivery Entity

The **Email Delivery** (or Email Job) represents a single transactional communication event. It bridges your application logic with the professional SMTP infrastructure of DonutWork.

## Usage

The Email Delivery entity is used to:

* Send transactional emails (receipts, password resets) using pre-defined templates.
* Inject dynamic data into responsive layouts via variables.
* Distribute legal or technical documents as secure attachments.
* Orchestrate multi-sender communication (Support, Billing, Sales).

## Expected Delivery Flow

Sending a secure email with attachments follows this operational path:

<Steps>
  <Step>
    ### Template Selection

    Identify the logical `templateId` in your Email Gateway. This defines the visual layout and the placeholders available for injection.
  </Step>

  <Step>
    ### Variable Mapping & Context

    Prepare the `vars` object containing the dynamic data (e.g., customer name, order number) that will replace the placeholders in the designer.
  </Step>

  <Step>
    ### Attachment Encoding

    Convert your files (PDF, CSV, Images) into **Base64** strings. DonutWork processes these strings to recreate valid SMTP attachments safely.
  </Step>

  <Step>
    ### Dispatch & Transmission

    Submit a `POST` request to the delivery endpoint. DonutWork validates the sender identity, resolves the variables, attaches the files, and transmits via the configured SMTP.
  </Step>
</Steps>

***

## Data Schema (JSON Body)

The payload for an email delivery job:

| Field         | Type     | Description                                             |
| :------------ | :------- | :------------------------------------------------------ |
| `to`          | `string` | **Required**. Primary recipient email address.          |
| `subject`     | `string` | **Required**. The title of the email.                   |
| `from`        | `string` | Optional. Must match one of your "Alternative Senders". |
| `vars`        | `object` | Key-value pairs matching placeholders in the template.  |
| `attachments` | `array`  | List of attachment objects (see below).                 |
| `cc` / `bcc`  | `mixed`  | String or array of additional recipients.               |

### Attachment Object

| Field         | Type     | Description                                         |
| :------------ | :------- | :-------------------------------------------------- |
| `filename`    | `string` | The display name of the file (e.g., `invoice.pdf`). |
| `type`        | `string` | MIME type (e.g., `application/pdf`).                |
| `content`     | `string` | The file content encoded in **Base64**.             |
| `disposition` | `string` | `attachment` (default) or `inline`.                 |

***

## Relationship Call Graph

How your app interacts with the Gateway to send a document:

<Mermaid
  chart="sequenceDiagram
    participant App as Your Application
    participant DW as DonutWork API
    participant SMTP as SMTP Server
    
    rect rgb(30, 30, 35)
    Note over App, DW: Phase 1: Payload Preparation
    App->>App: Encode PDF to Base64
    App->>DW: POST /email-gateway/{templateId}/send.json
    end

    rect rgb(20, 40, 20)
    Note over DW, SMTP: Phase 2: Processing & Delivery
    DW->>DW: Load HTML Template
    DW->>DW: Resolve {{vars}} with context
    DW->>DW: Attach Base64 files
    DW->>SMTP: SMTP Transmission
    SMTP-->>DW: Success / MessageID
    DW-->>App: Return success + MessageID
    end"
/>


# Partner Entity



import { Steps, Step } from 'fumadocs-ui/components/steps';

# Partner Entity

A **Partner** represents an external agency, reseller, or affiliate that manages its own pool of customers. Partners are categorized into **Groups** for tiered commission management and service segmentation.

## Usage

The Partner entity is used to:

* Segment your customer base by agency or reseller.
* Manage commission structures and payout history.
* Distribute reporting and management capabilities to third parties.

## Expected Lifecycle Flow

Follow this logical flow to establish a partner-based reseller model:

<Steps>
  <Step>
    ### Define Tiers & Groups

    Use `POST /partners/groups.json` to categorize partners. This allows you to apply different commission rules or API access levels to different types of resellers.
  </Step>

  <Step>
    ### Partner Onboarding

    Initialize the partner identity via `POST /partners.json`. Associate them with a `group_id` and provide their legal and tax information.
  </Step>

  <Step>
    ### Customer Attribution

    When onboarding a new customer through your platform, include the `partner.id` in the creation payload. DonutWork will automatically attribute future revenue to this partner.
  </Step>

  <Step>
    ### Performance & Payouts

    Monitor real-time performance via `GET /partners/{id}/stats.json` and manage revenue sharing through the `payouts.json` endpoints.
  </Step>
</Steps>

***

## Data Schema

The core fields defining a Partner object:

| Field         | Type     | Description                                                       |
| :------------ | :------- | :---------------------------------------------------------------- |
| `id`          | `eid`    | Unique extended identifier.                                       |
| `name`        | `string` | Legal company name of the partner.                                |
| `email`       | `string` | Main contact and billing address.                                 |
| `group_id`    | `string` | The ID of the assigned classification group.                      |
| `external_id` | `string` | Your internal system reference.                                   |
| `tags`        | `array`  | Arbitrary labels for custom filtering (e.g., 'gold', 'reseller'). |

***

## Relationship Call Graph

How Partners interact with the customer onboarding flow:

<Mermaid
  chart="sequenceDiagram
    participant App as Your Application
    participant DW as DonutWork API
    participant Partner as Partner Portal
    
    App->>DW: POST /partners (Create Partner)
    Partner->>App: Submits New Customer Data
    App->>DW: POST /customers (with partner.id)
    DW-->>DW: Link Customer to Partner
    DW->>DW: Trigger Commission Logic
    App->>DW: GET /partners/{id}/stats
    DW-->>App: Return Cumulative Revenue Data"
/>


# Subscription Entity



import { Steps, Step } from 'fumadocs-ui/components/steps';

# Subscription Entity

The **Subscription** object represents a recurring commercial agreement attached to a **Customer**.
It combines plan pricing, addon quantities, billing cadence, and lifecycle state.

## Usage

Use the Subscription entity to:

* Attach a pricing plan to a customer.
* Manage seat-based pricing through addon quantity.
* Apply global and addon-level discounts.
* Track metered usage when enabled.
* Execute lifecycle transitions (pause, resume, change, cancel-at-period-end).
* Keep amendment history for audits.

## Seat-Based Pricing Model

In Donutwork, seat-based pricing is handled through **addons**.

* Configure the per-seat value in the addon price.
* Set the number of seats in `addons[].quantity`.
* Renewal totals automatically include seat addons.

Example:

* Addon `workspace_seat` price: `12.00`
* Quantity: `25`
* Seat subtotal contribution: `300.00` (before taxes/discounts)

## Expected Subscription Flow

<Steps>
  <Step>
    ### Plan Association

    Attach a plan with `POST /customers/{id}/subscriptions.json`.
  </Step>

  <Step>
    ### Runtime Configuration

    Adjust addon quantities (including seats), discounts, and usage inputs as needed.
  </Step>

  <Step>
    ### Lifecycle Transitions

    Optionally apply lifecycle operations (`pause`, `resume`, `change-plan`, `change-addons`, `cancel-at-period-end`).
  </Step>

  <Step>
    ### Renewal Boundary Processing

    At `next_renew`, scheduled changes are applied and recurring billing is executed.
  </Step>
</Steps>

***

## Lifecycle States and Transitions

| Lifecycle State         | Meaning                                   | Typical Entry                          |
| :---------------------- | :---------------------------------------- | :------------------------------------- |
| `active`                | Subscription is billable and renewable    | Attach, resume, successful change      |
| `paused`                | Billing is temporarily suspended          | Pause action                           |
| `cancel_pending`        | Marked to stop at period boundary         | Cancel-at-period-end                   |
| `cancelled`             | No longer active                          | Post-boundary stop/legacy cancellation |
| `trialing` / `past_due` | Optional advanced states for integrations | External lifecycle orchestration       |

### State Definitions with Practical Examples

* `active`: customer is billed normally at each renewal date.
  Example: a monthly plan renews on May 1, 2026 and remains active.
* `paused`: billing is temporarily halted.
  Example: customer asks to freeze service for 30 days; no renewal charge is attempted while paused.
* `cancel_pending`: subscription will stop at period boundary.
  Example: customer cancels on April 15, 2026; access remains until the next renewal boundary.
* `cancel_pending` can be reversed before boundary.
  Example: customer cancels, then changes mind after 3 days; use undo-cancel-at-period-end to return to `active`.
* `cancelled`: subscription is fully closed.
  Example: boundary reached and cancellation finalized.
* `trialing`: customer is in free trial before first paid cycle.
  Example: plan includes 14-day trial after initial attach.
* `past_due`: payment issue detected and recovery flow is required.
  Example: renewal attempt failed and account is awaiting payment method update.

### Pause and Resume Billing Semantics

When a subscription is paused, Donutwork stops renewal execution and clears `next_renew` while storing the previous renewal date in `pause_state.previous_next_renew`.

When resumed:

* If `resume_at` is provided and is in the future, that date becomes the new `next_renew`.
* If `resume_at` is missing, Donutwork uses the stored `previous_next_renew`.
* If the stored date is already in the past, Donutwork sets `next_renew` to the resume day (today), not retroactively.

Practical timeline example:

* Subscription paused on **May 1, 2026**.
* Resumed on **July 1, 2026** (after 2 months).
* Result: no automatic back-billing for May/June; `next_renew` is re-anchored to July 1, 2026 (or a future `resume_at` if provided).

### Lifecycle Graph

<Mermaid
  chart="stateDiagram-v2
    [*] --> trialing
    [*] --> active
    trialing --> active: trial ends
    active --> paused: pause
    paused --> active: resume
    active --> cancel_pending: cancel at period end
    cancel_pending --> active: undo cancel
    cancel_pending --> cancelled: boundary reached
    active --> past_due: renewal failure
    past_due --> active: payment recovered"
/>

## Proration Rules

* **Positive delta** (upgrade): immediate debit charge.
* **Negative delta** (downgrade): credit stored in `carryover_credit`.
* Carryover credit is consumed in future renewals before charging new amount.

## Scheduled Changes

For `change-plan` and `change-addons`, you can set `when: period_end`.
The request is stored in `scheduled_change` and applied automatically at renewal boundary.

## Amendment History

Every lifecycle change is written to an immutable amendment stream.
This supports support/debug/audit use cases with before/after snapshots and proration metadata.

***

## Data Schema

| Field                  | Type             | Description                                                    |
| :--------------------- | :--------------- | :------------------------------------------------------------- |
| `id`                   | `eid`            | Unique customer-subscription identifier.                       |
| `subscription_id`      | `string`         | Plan identifier currently applied.                             |
| `status`               | `string`         | Legacy status (`active`, `dismiss`, `dismissed`, ...).         |
| `next_renew`           | `date \| null`   | Next billing boundary.                                         |
| `addons`               | `array`          | Addon entries with price and `quantity` (seat count included). |
| `global_discount`      | `object`         | Plan-level discount descriptor.                                |
| `lifecycle`            | `object`         | Advanced lifecycle state metadata.                             |
| `pricing_snapshot`     | `object`         | Captured pricing context for lifecycle operations.             |
| `scheduled_change`     | `object \| null` | Deferred mutation to apply at renewal.                         |
| `pause_state`          | `object \| null` | Pause/resume metadata.                                         |
| `carryover_credit`     | `number`         | Credit wallet generated by negative prorations.                |
| `cancel_at_period_end` | `boolean`        | Explicit cancellation intent at renewal boundary.              |

***

## Backward Compatibility

No legacy route or payload shape is removed.

### Legacy vs New lifecycle behavior

| Area            | Legacy Behavior               | New Lifecycle Behavior                                       |
| :-------------- | :---------------------------- | :----------------------------------------------------------- |
| Attach/Detach   | Existing routes remain valid  | Unchanged, plus additive lifecycle metadata                  |
| Addons update   | Existing addon mutation works | Optional lifecycle change-addons with proration/scheduling   |
| Status endpoint | Legacy `status` continues     | Adds lifecycle visibility without removing legacy keys       |
| Seat pricing    | Addons with quantity          | Same model, now explicitly documented as official seat model |
| Cancellation    | `dismiss` based flow          | `cancel_at_period_end` maps to compatible legacy status      |

***

## Relationship Call Graph

<Mermaid
  chart="sequenceDiagram
    participant App as Your Application
    participant DW as Donutwork API
    participant Rec as Renewal Processor

    App->>DW: POST /customers/{id}/subscriptions.json
    DW-->>App: Subscription attached (legacy + lifecycle metadata)
    App->>DW: PUT /lifecycle/change-addons (optional)
    DW-->>App: Amendment + proration details
    Rec->>Rec: Apply scheduled change at boundary (if present)
    Rec->>DW: Generate and capture renewal charge
    DW-->>App: Webhook: Customer.subscriptionRenewal.success"
/>


# Media Library



import { Card, Cards } from 'fumadocs-ui/components/card';
import { UploadCloud, HardDrive, FileSearch, Download } from 'lucide-react';

# Media Library

The **Media Library** serves as a centralized repository for all files within your workspace. It leverages a scalable remote storage infrastructure to ensure your assets are always available, secure, and ready to be served via CDN.

## Core Features

<Cards>
  <Card icon={<UploadCloud className="text-blue-500" />} title="Fast Upload" description="Multi-file upload system with Drag & Drop support." />

  <Card icon={<HardDrive className="text-purple-500" />} title="Remote Storage" description="Native integration with isolated company buckets, ensuring maximum data security." />

  <Card icon={<FileSearch className="text-green-500" />} title="Format Recognition" description="Automatic identification of file types (Images, PDFs, Documents) with dedicated iconography." />
</Cards>

***

## File Management

The gallery interface provides immediate control over your uploaded assets:

### 1. Upload & Ingestion

Drag multiple files simultaneously into the upload area. The system automatically manages the queue and notifies you when the process is complete.

### 2. Gallery & Navigation

Files are displayed in a responsive grid showing:

* **Filename:** The original asset name (Key).
* **Size:** Automatic calculation of file weight (KB, MB, GB).
* **Identifier (ETag):** The unique file hash for cache and versioning management.

### 3. Intelligent Pagination

For workspaces with thousands of files, the Media Library uses **Continuation Token-based pagination**, optimizing load times and reducing bandwidth consumption.

***

## Common Use Cases

* **Dynamic Content:** Upload product images or partner logos to be referenced in your [Dynamic Content](/en/docs/dynamic-content-modeling).
* **Email Gateway:** Host graphical assets for your transactional email templates.
* **User Documents:** Store PDFs or guides for your customers in a secure environment.


# Partner Program & Revenue Sharing



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { Calculator, Fingerprint, TrendingUp, Zap } from 'lucide-react';

# Partner Program

Donutwork helps you run a partner channel like a product, not a spreadsheet.
Create structured partner groups, define powerful commission rules, and validate outcomes before you publish.

## What You Can Do

1. Group partners by commercial model (agencies, resellers, strategic channels).
2. Apply layered commission logic to each group.
3. Enforce quality gates (X paying customers in N months).
4. Simulate outcomes instantly and avoid guesswork.
5. Keep payouts transparent and explainable.

***

## Configure In 7 Steps

1. Open a partner group.
2. Set your base logic with `Time-Based Tier` or `Recurring (Fallback)`.
3. Add optional growth levers:

* `Charge Amount`
* `LTV Bonus`

4. Add a `Customer Volume Gate` if you want minimum performance requirements.
5. Test realistic scenarios in `Commission Simulator`.
6. Review the breakdown and confirm expected behavior.
7. Save and apply to the group.

<Callout type="info" title="Best-practice setup order">
  Start with base commission, then add upgrades/adjustments, and only then add eligibility gates. This gives the clearest and most controllable result.
</Callout>

***

## Rule Catalog (How Each Rule Behaves)

### Time-Based Tier

Use it for onboarding acceleration.

* Goal: reward early lifecycle months more aggressively.
* Key fields:
* `Max Months (e.g., 12)`
* `Percentage (%)`
* `Bonus (€ - Optional)`
* Behavior: applies when customer age is within the configured month limit.
* Typical use: “12% for first 12 months + optional one-time bonus.”

### Recurring (Fallback)

Use it as your long-term baseline.

* Goal: define steady commission after no time tier matches.
* Key field:
* `Recurring Percentage (%)`
* Behavior: used as default base commission.
* Typical use: “6% lifetime after introductory tiers.”

### Charge Amount

Use it to adapt margins by transaction size.

* Goal: adjust commission when charge value crosses a threshold.
* Key fields:
* `Min Charge Total (€)`
* `Deduction % (e.g., 1.0)`
* Behavior: when threshold is met, adjustment is applied to the fee at that point.
* Typical use: “Apply a deduction on high-ticket deals to preserve margin.”

### LTV Bonus

Use it to reward long-term partner contribution.

* Goal: unlock extra commission when cumulative partner revenue reaches milestones.
* Key fields:
* `Min LTV Total (€)`
* `Upgrade Bonus %`
* Behavior: highest qualified LTV bonus is applied.
* Typical use: “+3% after €20k generated.”

### Customer Volume Gate

Use it to protect quality and consistency.

* Goal: require minimum paying-customer volume.
* Key fields:
* `Required Customers (X)`
* `Lookback Months (N)`
* `Window Mode`
* `Anchor Source`
* `Below-threshold Action`
* `Reduction Mode`
* Behavior:
* checks whether partner reaches X paying customers in the selected window.
* if below threshold, applies your configured policy (reduce, defer, forfeit).

***

## Calculation Logic You Can Trust

### Monetary base

Commission percentages and thresholds are evaluated on the charge net taxable amount (before taxes), for consistent financial behavior.

### Deterministic order

Rules are applied in this order:

1. Base: `Time-Based Tier` or `Recurring (Fallback)`
2. `Charge Amount`
3. `LTV Bonus`
4. `Customer Volume Gate`

### No retroactive surprises

When rules change, historical approved calculations stay untouched.

***

## Customer Volume Gate: Rolling vs Anchored

### Rolling window

Best for continuous performance monitoring.

* evaluates the last N months from each charge date.

### Anchored window

Best for lifecycle-based partner programs.

* evaluates N months from a chosen anchor point.

### First paid customer bootstrap

If anchored mode uses first paid customer and there is no historical paid event yet, the first paid transaction starts the window automatically. The rule is still evaluated normally.

***

## Commission Simulator

Use the simulator before publishing any rule update.

* Input realistic values in:
* `Simulated Charge Amount (€)`
* `Months Since Customer Creation`
* `Simulated Partner LTV (€)`
* `Qualified Customers (X window)`
* `First Paid Customer (bootstrap)`
* Run `Simulate Commission` and review `Commission Simulation Breakdown`.

This is the fastest way to align finance, sales, and operations before go-live.

***

## Ready-to-Use Playbooks

1. Startup acquisition push:

* strong first-year tier
* lower recurring fallback
* moderate volume gate

2. Agency channel:

* stable recurring
* LTV milestones for upsell behavior
* rolling gate to maintain consistency

3. Enterprise referrals:

* high-ticket charge adjustment
* selective LTV upgrades
* anchored gate for program-cycle governance

***

## Why Donutwork Stands Out

<Cards>
  <Card icon={<Fingerprint className="text-blue-500" />} title="Explainable" description="Every payout can be justified with a clear rule sequence and simulation breakdown." />

  <Card icon={<Calculator className="text-green-500" />} title="Configurable" description="Mix lifecycle, value, LTV, and performance gates without custom development." />

  <Card icon={<TrendingUp className="text-indigo-500" />} title="Scalable" description="Move from simple affiliate payouts to sophisticated partner economics as you grow." />

  <Card icon={<Zap className="text-yellow-500" />} title="Fast to Operate" description="Design, test, and publish changes quickly with confidence." />
</Cards>


# Recurring Payments



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { Repeat, Zap, Gift, Settings2, Calculator, GitBranchPlus, ShieldCheck } from 'lucide-react';

# Recurring Payments & Subscriptions

Donutwork lets you run subscription billing with a predictable model:

* create plan catalog rules,
* attach subscriptions to customers,
* scale seat-based pricing through addons,
* change contracts over time with lifecycle controls,
* keep compatibility with existing legacy integrations.

This page explains how the system behaves in production, with practical examples.

## What A Subscription Includes

<Cards>
  <Card icon={<Repeat className="text-blue-500" />} title="Renewal Cadence" description="Day-based or month-based cycles (`renewal_days` / `renewal_months`) with a next renewal date (`next_renew`)." />

  <Card icon={<Gift className="text-emerald-500" />} title="Trial Handling" description="Optional trial before first paid cycle." />

  <Card icon={<Zap className="text-amber-500" />} title="Seat + Addon Pricing" description="Seat-based pricing uses addon quantity (`addons[].quantity`) and unit price (`addons[].price`)." />

  <Card icon={<Settings2 className="text-cyan-500" />} title="Discounts & Taxes" description="Addon discounts, global discount, carryover credit, and tax profile are applied in deterministic order." />
</Cards>

***

## Renewal Amount Calculation (Order Matters)

At each renewal boundary, Donutwork computes the due amount in this order:

1. Base plan amount.
2. Addon charges (`price * quantity`) for active addon quantities.
3. Addon-level discount if configured and still active (`discount_until`).
4. Global discount (`fixed` or `percentage`, if still active).
5. Carryover credit (`carryover_credit`) from previous downgrade/proration.
6. Taxes from subscription tax profile.

### Formula (simplified)

```text
net_subtotal = base + addons_after_addon_discounts
net_after_global_discount = net_subtotal - global_discount
net_due = max(0, net_after_global_discount - carryover_credit_applied)
vat_due = net_due * tax_rate
gross_due = net_due + vat_due
```

### Example

* Base plan: `99.00`
* Seat addon: `12.00` x `8` seats = `96.00`
* Addon discount 10% active => addon effective `86.40`
* Net subtotal = `185.40`
* Global discount 15% => `-27.81`
* Carryover credit used: `20.00`
* Net due = `137.59`
* VAT 22% = `30.27`
* Gross due = `167.86`

***

## Seat-Based Pricing Model

Seat pricing does **not** use a separate seat schema.
It is intentionally modeled through addons:

* per-seat value: `addons[].price`
* seats count: `addons[].quantity`
* final seat amount: included automatically in subscription renewal

This model is stable and backward compatible with existing panel/API flows.

***

## Lifecycle States (Billing Meaning)

| State            | Billable     | Meaning                                                          |
| :--------------- | :----------- | :--------------------------------------------------------------- |
| `active`         | Yes          | Normal recurring billing.                                        |
| `trialing`       | Usually no   | Trial phase before first paid renewal.                           |
| `past_due`       | Conditional  | Payment recovery state after failed attempt.                     |
| `paused`         | No           | Billing paused. Renewals are not charged while paused.           |
| `cancel_pending` | No new cycle | Scheduled to stop at period end (can be undone before boundary). |
| `cancelled`      | No           | Closed subscription.                                             |

<Callout type="info" title="Pause Semantics">
  Pausing does not create retroactive debt. If a subscription is resumed after 2 months, the system does not auto-charge the paused months. The next renewal is re-anchored to resume date logic.
</Callout>

### Lifecycle Graph

<Mermaid
  chart="stateDiagram-v2
    [*] --> trialing
    [*] --> active
    trialing --> active: trial ends
    active --> paused: pause
    paused --> active: resume
    active --> cancel_pending: cancel at period end
    cancel_pending --> active: undo cancel
    cancel_pending --> cancelled: period boundary
    active --> past_due: renewal failed
    past_due --> active: payment recovered"
/>

***

## Supported Lifecycle Operations

All lifecycle features are additive (no legacy route removal):

| Operation                 | Immediate  | Period End            | Proration | Notes                                    |
| :------------------------ | :--------- | :-------------------- | :-------- | :--------------------------------------- |
| Pause                     | Yes        | No                    | No        | Stops renewal attempts while paused.     |
| Resume                    | Yes        | No                    | No        | `resume_at` can define next boundary.    |
| Change Plan               | Yes        | Yes                   | Optional  | Upgrade/downgrade supported.             |
| Change Addons             | Yes        | Yes                   | Optional  | Seat quantity updates included.          |
| Cancel At Period End      | Yes (flag) | Effective at boundary | No        | Legacy-compatible cancellation behavior. |
| Undo Cancel At Period End | Yes        | No                    | No        | Restores active plan before boundary.    |
| Next Renewal Preview      | Read-only  | N/A                   | N/A       | Shows expected next charge breakdown.    |
| Amendment History         | N/A        | N/A                   | N/A       | Full audit trail for lifecycle changes.  |

***

## API Examples

### Schedule Seat Change At Period End

```json
{
  "subscription": {
    "action": "change_addons",
    "when": "period_end",
    "proration": false,
    "addons": [
      {
        "name": "workspace_seat",
        "quantity": 25,
        "price": 12
      }
    ]
  }
}
```

### Preview Next Renewal (response excerpt)

```json
{
  "status": "success",
  "data": {
    "subscription_id": "sub_abc123",
    "next_renewal": "2026-07-01",
    "billable": true,
    "pricing": {
      "items": [
        { "service": "Subscription Base: Pro", "net": 99, "tax_rate": 22, "tax": 21.78, "total": 120.78 },
        { "service": "Addon: workspace_seat (Qty: 25)", "net": 300, "tax_rate": 22, "tax": 66, "total": 366 }
      ],
      "net_due": 399,
      "vat_due": 87.78,
      "gross_due": 486.78
    }
  }
}
```

***

## API FAQ (Common Combinations)

The combinations below refer to Customer API routes documented in `/en/docs/api/customer#subscription-management`.

### How can I upgrade a plan?

Use `change-plan` with immediate application.

```json
{
  "lifecycle": {
    "plan_id": "PLAN_ENTERPRISE_V3",
    "when": "immediate",
    "proration": true
  }
}
```

* Endpoint: `PUT /customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-plan.json`
* If proration delta is positive, an immediate adjustment charge is attempted.
* If that immediate charge fails, the lifecycle change is not applied.

### How can I downgrade a plan?

Use `change-plan` and target a lower-priced plan.

```json
{
  "lifecycle": {
    "plan_id": "PLAN_STARTER_V1",
    "when": "immediate",
    "proration": true
  }
}
```

* Endpoint: `PUT /customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-plan.json`
* With a negative delta, the platform stores credit in `carryover_credit`.
* That credit is consumed on future renewals before new debit.

### How can I schedule plan changes for next renewal?

```json
{
  "lifecycle": {
    "plan_id": "PLAN_PRO_V2",
    "when": "period_end",
    "proration": false
  }
}
```

* Endpoint: `PUT /customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-plan.json`
* No immediate charge is attempted; change is applied at renewal boundary.

### How can I change addon quantities (including seats)?

```json
{
  "lifecycle": {
    "addons": [
      { "element": "workspace_seat", "quantity": 25 }
    ],
    "when": "immediate",
    "proration": true
  }
}
```

* Endpoint: `PUT /customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-addons.json`
* In seat-based setups, seat count is `addons[].quantity`.

### How can I schedule addon quantity changes at period end?

```json
{
  "lifecycle": {
    "addons": [
      { "element": "workspace_seat", "quantity": 40 }
    ],
    "when": "period_end",
    "proration": false
  }
}
```

* Endpoint: `PUT /customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-addons.json`
* Useful for commercial changes that should start next cycle.

### What happens if I pause and resume after two months?

* Pause: `PUT .../lifecycle/pause.json`
* Resume: `PUT .../lifecycle/resume.json` (optional `resume_at`)

Concrete timeline:

* pause on **May 1, 2026**
* resume on **July 1, 2026**
* no retroactive billing for May/June; renewal restarts from resume logic.

### Can I undo a cancellation already set for period end?

Yes:

* set cancellation: `PUT .../lifecycle/cancel-at-period-end.json`
* undo cancellation: `PUT .../lifecycle/undo-cancel-at-period-end.json`

If undone before renewal boundary, subscription returns to `active`.

### How can I preview financial impact before applying changes?

Use lifecycle preview (no mutation):

```json
{
  "lifecycle": {
    "action": "change_addons",
    "addons": [
      { "element": "workspace_seat", "quantity": 30 }
    ]
  }
}
```

* Endpoint: `POST /customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/preview.json`
* Response includes `old_due`, `new_due`, `delta`, `direction`.

### How should I handle safe retries in integrations?

Use `lifecycle.idempotency_key` on mutating operations.
On retries, this prevents duplicate application of the same change.

### Where can I fetch full lifecycle change history?

Use amendment history:

* Endpoint: `GET /customers/{customerId}/subscriptions/{subscriptionId}/amendments.json`
* Includes action, timing (`immediate`/`period_end`), before/after, and proration metadata.

### Quick combination matrix

| Goal                        | Endpoint                             | `when`       | `proration` |
| :-------------------------- | :----------------------------------- | :----------- | :---------- |
| Upgrade plan now            | `.../change-plan.json`               | `immediate`  | `true`      |
| Downgrade plan now          | `.../change-plan.json`               | `immediate`  | `true`      |
| Change plan next cycle      | `.../change-plan.json`               | `period_end` | `false`     |
| Increase/decrease seats now | `.../change-addons.json`             | `immediate`  | `true`      |
| Change seats next cycle     | `.../change-addons.json`             | `period_end` | `false`     |
| Pause service               | `.../pause.json`                     | N/A          | N/A         |
| Resume service              | `.../resume.json`                    | N/A          | N/A         |
| Cancel at period end        | `.../cancel-at-period-end.json`      | boundary     | N/A         |
| Undo cancellation           | `.../undo-cancel-at-period-end.json` | immediate    | N/A         |
| Simulate impact             | `.../preview.json`                   | N/A          | N/A         |
| Audit changes               | `.../amendments.json`                | N/A          | N/A         |

***

## Practical Scenarios

### 1) Pause For 2 Months, Then Resume

* Pause on **May 1, 2026**
* Resume on **July 1, 2026**
* Result: no back-charge for May/June, renewal continues from resumed schedule.

### 2) Mid-Cycle Upgrade

* Customer increases seats from 10 to 20 with immediate change.
* Positive proration delta => immediate debit adjustment.

### 3) Mid-Cycle Downgrade

* Customer reduces seats mid-cycle.
* Negative delta => credit is stored in `carryover_credit`.
* Next renewal consumes this credit before any new debit.

### 4) Cancel Pending Then Undo

* Customer requests cancellation at period end.
* State moves to `cancel_pending`.
* If customer changes mind before boundary, undo operation restores normal lifecycle.

***

## Backward Compatibility (No Break Changes)

Legacy panel and API flows stay valid.
New lifecycle capabilities are opt-in.

| Area                       | Legacy Behavior | Current Behavior                  |
| :------------------------- | :-------------- | :-------------------------------- |
| Attach/detach subscription | Supported       | Still supported                   |
| Legacy addon update route  | Supported       | Still supported                   |
| Legacy status field        | Supported       | Still present                     |
| Seat modeling              | Addon quantity  | Same official model               |
| Existing integrations      | Stable          | Can adopt lifecycle incrementally |

<Callout type="info" title="Adoption Strategy">
  If you already use legacy routes, you can keep them unchanged and adopt lifecycle endpoints gradually for pause/resume, proration, and amendment tracking.
</Callout>

***

## Recommended Setup Checklist

<Cards>
  <Card icon={<Calculator className="text-indigo-500" />} title="Model Seats Via Addons" description="Set per-seat price on addon and update quantity for seat count." />

  <Card icon={<GitBranchPlus className="text-sky-500" />} title="Use Scheduled Changes" description="Prefer `period_end` for commercial changes that should start from next cycle." />

  <Card icon={<ShieldCheck className="text-emerald-500" />} title="Enable Audit Visibility" description="Use amendment history and renewal preview to improve support and billing transparency." />
</Cards>

***

## Related Docs

<Cards>
  <Card title="Customer API" href="/en/docs/api/customer#subscription-management" description="Full customer-subscription routes, including lifecycle operations." />

  <Card title="Subscription Entity" href="/en/docs/entities/subscription" description="Detailed schema, state transitions, and compatibility mapping." />
</Cards>


# Sentinel Dashboard



import { Callout } from 'fumadocs-ui/components/callout';

# Security Command Center

The Sentinel Dashboard is the operational heart of your security infrastructure. It provides an immediate, high-impact visual overview of your authentication ecosystem's health.

## Real-Time Metrics

The dashboard monitors four critical KPIs:

* **Threats Detected:** Number of threats actively blocked by the system.
* **Failed Logins:** Unsuccessful access attempts (potential brute-force or credential stuffing).
* **Active Sessions:** Number of users currently authenticated globally.
* **Avg Response:** Average response time of the security engine (in milliseconds).

## Global Login Activity

Powered by **MapLibre GL**, Sentinel visualizes login density on a global map.

* **Blue points** indicate regular activity.
* **Red points** signal high-density attempts, helping you quickly identify geographically targeted attacks.

## Security Alerts & Decisions

This section lists recent anomalies. For every alert, Sentinel displays:

1. **Severity:** From *Low* to *Critical*.
2. **Decision Taken:** - `Allow`: Access granted.
   * `Challenge MFA`: Two-factor authentication required.
   * `Deny`: Access blocked immediately.
   * `Monitor`: Suspicious activity recorded but below the intervention threshold.
3. **Triggers:** Specific reasons that raised the risk (e.g., *New User Agent*, *TOR/VPN Flag*).

<Callout type="info">
  You can click on any IP or User ID within the alerts to view the full activity history for that specific profile.
</Callout>


# Sentinel Security Platform



import { Card, Cards } from 'fumadocs-ui/components/card';
import { ShieldCheck, Lock, Eye, Zap } from 'lucide-react';

# Sentinel Security Platform

**Sentinel** is Donutwork's intelligent security module designed to protect your business and users from modern threats. Unlike static security systems, Sentinel analyzes every login attempt in real-time, assigning a dynamic **Risk Score** based on dozens of behavioral and environmental signals.

## Core Pillars of Sentinel

<Cards>
  <Card icon={<Zap className="text-yellow-500" />} title="Adaptive MFA" description="Requires two-factor authentication only when the detected risk exceeds a predefined threshold." />

  <Card icon={<Eye className="text-blue-500" />} title="IP Intelligence" description="Automatic analysis of malicious IPs, TOR nodes, VPNs, and suspicious geographic locations." />

  <Card icon={<ShieldCheck className="text-green-500" />} title="Identity Provider (IDP)" description="Centralized management of external users with support for T-OTP and backup recovery codes." />

  <Card icon={<Lock className="text-red-500" />} title="Risk-Based Decisions" description="Automates security decisions (Allow, Challenge MFA, Deny) in milliseconds." />
</Cards>

***

## How the Risk Engine Works

Every time a user interacts with the authentication system, Sentinel evaluates the following factors:

1. **IP Reputation:** Does the address come from a network known for botnets or attacks?
2. **Device Novelty:** Is the user using a browser or OS never seen before for this account?
3. **Geolocation:** Is the access attempt coming from an unusual country for this user?
4. **Session Continuity:** If the user is already logged in and the session is stable, the risk score is reduced.

The result is a score from **0.00** to **1.00**. Based on this value and your configurations, Sentinel decides the next step.

***

## Sentinel Sections

* **[Dashboard](/en/docs/sentinel/dashboard):** Real-time monitoring of global threats.
* **[User Management](/en/docs/sentinel/users):** Granular control over user access and security status.
* **[Risk Settings](/en/docs/sentinel/settings):** Fine-tuning of risk weights and decision thresholds.

## Recommended Setup Order

1. Define your baseline thresholds in [Risk Settings](/en/docs/sentinel/settings).
2. Validate high-risk scenarios from the [Dashboard](/en/docs/sentinel/dashboard).
3. Operationalize controls in [User Management](/en/docs/sentinel/users) for exceptions and manual overrides.


# Sentinel Risk Configuration



import { Callout } from 'fumadocs-ui/components/callout';

# Sentinel Configuration

Sentinel allows you to "train" the risk engine based on your specific security needs. You can decide how much weight to assign to various security events.

## Score Adjustments (Weights)

Every suspicious event adds a value to the total **Risk Score** (from 0.0 to 1.0). You can adjust the following parameters:

* **Malware/Threat IP Flag:** High risk score for IPs found in global blacklists.
* **TOR/VPN Flag:** Risk associated with anonymizing networks.
* **Unknown IP / Country:** Extra risk added when a user logs in from a location or IP never seen before.
* **New User Agent:** Risk for using a new browser or hardware.

### Risk Reduction

* **Session Continuity Reduction:** This negative value reduces the risk score if the user maintains a stable, known session. This is vital for avoiding "false positives" during normal app usage.

***

## Decision Thresholds

Define the limits at which Sentinel must intervene:

| Threshold                   | Description                                                                                                           |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| **Challenge MFA Threshold** | If the score is `>=` this value, the user will be prompted for T-OTP, even if not strictly required by their profile. |
| **Deny Threshold**          | If the score is `>=` this value, access is denied immediately, regardless of correct credentials.                     |

<Callout type="warn" title="Calibration Warning">
  Setting a *Deny* threshold too low (e.g., 0.40) might block legitimate users who are traveling or using new devices. It is recommended to start with conservative thresholds (MFA at 0.50 and Deny at 0.85).
</Callout>

***

## T-OTP Integration

Sentinel allows you to globally enable or disable the **Time-Based One-Time Password** service. When enabled, you can offer 2FA via apps like Google Authenticator or Authy using Donutwork's native APIs.


# User Management (IDP)



# Sentinel User Management

Sentinel acts as a native **Identity Provider (IDP)** for your SaaS applications. In this section, you can monitor and manage the security profile of every registered user.

## User Security Status

For every user, the table provides:

* **CustomerID:** The external identifier linked to your user.
* **Status:** Account state (Active or Suspended).
* **OTP (One-Time Password):** Indicates if the user has correctly configured 2FA (T-OTP).
* **Backup Codes:** Shows whether emergency recovery codes have been generated.

## Administrative Actions

As an administrator, you have total control over user sessions:

1. **Suspend Access:** If you detect compromised activity, you can instantly suspend the user. This invalidates all active sessions.
2. **Restore Access:** Allows you to reactivate a previously suspended user once the threat is resolved.
3. **Delete:** Permanently removes the user from the Sentinel system.

> **Note:** Suspending a user in Sentinel blocks authentication at the IDP level, preventing access to all services connected to the platform.


# Directory Monitor



import { Card, Cards } from 'fumadocs-ui/components/card';
import { FolderOpen, Terminal, Bell, Cpu } from 'lucide-react';

# Directory Monitor

The **Directory Monitor** is a file system surveillance engine designed for automation. It allows you to monitor specific folders—locally or on remote servers—and trigger notifications or workflows whenever a file is created, modified, or deleted.

## The Monitoring Agent

To enable monitoring on your own infrastructure, Donutwork provides a **Linux Binary** agent. This lightweight agent runs on your server and communicates securely with the platform, providing low-latency event tracking without exposing your file system to the public internet.

<Cards>
  <Card icon={<Terminal className="text-blue-500" />} title="Linux Binary" description="Download the pre-compiled .tar package and run it as a service on your server." />

  <Card icon={<Bell className="text-orange-500" />} title="Real-time Alerts" description="Receive instant notifications via Webhook or Email when critical files are accessed or changed." />
</Cards>

## Common Use Cases

1. **Automated Data Ingestion:** Drop a CSV into a monitored folder to automatically trigger a Donutwork [Workflow](/en/docs/workflow) for data processing.
2. **Security Auditing:** Monitor sensitive directories (like `/etc/` or `/bin/`) and get alerted if unauthorized changes occur.
3. **Backup Verification:** Trigger post-processing tasks as soon as a database dump file is completed in a specific directory.

## Project Structure

* **Project ID:** A unique identifier used by the monitoring agent to sync with the Donutwork dashboard.
* **Startup Status:** Indicates if the monitoring process has successfully initialized and is actively listening for events.


# Systems & Monitoring



import { Card, Cards } from 'fumadocs-ui/components/card';
import { ShieldCheck, FolderTree, Code2, Key } from 'lucide-react';

# Systems & Monitoring

The **Systems & Monitoring** section is the operational command center of Donutwork. It provides the essential tools to ensure your SaaS infrastructure remains secure, high-performing, and constantly monitored. From SSL certificate validation to secret management via KMS, Donutwork offers total visibility into your system's operational health.

## Monitoring & Infrastructure Modules

Explore the dedicated sections to configure and manage the different layers of your infrastructure:

<Cards>
  <Card icon={<ShieldCheck className="text-blue-500" />} title="TLS Monitor" href="/en/docs/system-and-monitoring/tls-monitor" description="Monitor SSL/TLS certificate validity and expiration to prevent service downtime." />

  <Card icon={<FolderTree className="text-yellow-500" />} title="Directory Monitor" href="/en/docs/system-and-monitoring/directory-monitor" description="Automate processes and notifications by monitoring changes in critical directories." />

  <Card icon={<Code2 className="text-purple-500" />} title="Sources" href="/en/docs/system-and-monitoring/sources" description="Manage SFTP/FTP remote connections for automated file exchanges." />

  <Card icon={<Key className="text-red-500" />} title="KMS Keys" href="/en/docs/system-and-monitoring/kms" description="Key Management Service (KMS) for encrypting sensitive data and managing master keys." />
</Cards>

***

## Why Monitoring is Crucial?

In a modern SaaS environment, stability and data flow integrity are non-negotiable. Donutwork automates routine checks to prevent issues before they impact the end user:

1. **Proactive Security:** Detect expiring TLS certificates or unauthorized system file modifications before they cause an outage.
2. **Data Governance:** Centrally manage cryptographic keys via the **KMS** module, ensuring compliance with global security standards.
3. **Automation & Traceability:** Streamline operations by triggering notifications and workflows as soon as changes are detected in remote or local directories.

## First 15 Minutes Setup

1. Start with [TLS Monitor](/en/docs/system-and-monitoring/tls-monitor) for certificate visibility.
2. Configure [KMS](/en/docs/system-and-monitoring/kms) before onboarding secrets into automations.
3. Connect [Sources](/en/docs/system-and-monitoring/sources) if your flows pull files from SFTP/FTP endpoints.
4. Use [Directory Monitor](/en/docs/system-and-monitoring/directory-monitor) to convert filesystem events into workflow triggers.


# Key Management System (KMS)



import { Callout } from 'fumadocs-ui/components/callout';

# Key Management System (KMS)

The Donutwork **KMS** is your SaaS's cryptographic vault. It provides a centralized system for storing sensitive credentials, application secrets, and master keys that should never be hard-coded or stored in plain text.

## Key Structure

Each KMS entry is designed for programmatic access and high security:

* **Handler:** A unique alias used by your APIs or scripts to retrieve the key without exposing its actual content.
* **Content:** The secret value (e.g., Stripe Secret Key, AWS Access Key, or a private certificate).
* **Whitelist (Network Isolation):** Restrict key usage to specific IP addresses or CIDR ranges. If a request comes from an unauthorized IP, the KMS will block access even with valid credentials.

## Security Auditing

Traceability is built into the core of the KMS. Every time a key is read or modified, an **Audit Log** is generated.

### Audit Log Details:

* **Requester Identity:** Who accessed the key.
* **Timestamp:** Exactly when the access occurred.
* **Source IP:** The network origin of the request.
* **Outcome:** Whether the request was successful or blocked by the whitelist policy.

<Callout type="info">
  Use the **Handler** in your application code to keep your repositories clean of secrets. This allows you to rotate keys in the Donutwork dashboard without re-deploying your application.
</Callout>


# External Connections (Sources)



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Link, Shield, Server, FileCode } from 'lucide-react';

# Sources & External Connections

The **Sources** module manages the secure communication gateways between Donutwork and your external infrastructure. It allows you to configure and store credentials for remote servers, enabling automated file transfers and data synchronization.

## Supported Protocols

Donutwork supports the most common industry-standard protocols for secure file exchange:

* **SFTP (SSH File Transfer Protocol):** The most secure method, utilizing SSH for data transit.
* **FTPS (FTP over SSL/TLS):** A secure version of FTP that encrypts both commands and payload.
* **FTP:** Supported for legacy system compatibility (not recommended for sensitive data).

## Security & Advanced Settings

* **SSL/TLS Encryption:** Force encrypted connections to ensure credentials and files are never transmitted in plain text.
* **Passive Mode:** Essential for FTP/S connections to bypass firewall or NAT restrictions on the server side.
* **Credential Masking:** For security compliance, passwords are never displayed in the UI after the initial setup.

## Technical Configuration

When creating a connection, you will need:

* **Hostname & Port:** The address of the remote server (e.g., `sftp.partner.com`).
* **Authentication:** Username and Password (securely stored and encrypted).
* **Security Toggles:** Enable SSL/TLS and Passive Mode depending on your server's requirements.


# TLS Monitor



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { ShieldCheck, Clock, Globe, Lock } from 'lucide-react';

# TLS Monitor

The **TLS Monitor** is a dedicated security tool designed to track the health of your HTTPS endpoints. Unlike basic uptime monitors, it performs deep cryptographic scans to ensure your SSL/TLS certificates are valid, up-to-date, and compliant with modern security standards.

## Key Features

* **Expiration Tracking:** Get real-time visibility into certificate expiry dates to prevent service downtime.
* **Protocol Version Verification:** Ensures your servers are using secure versions (TLS 1.2, 1.3) and flags deprecated protocols (SSLv3, TLS 1.0/1.1).
* **Compliance Warnings:** Automatically identifies non-compliant configurations based on GDPR and industry best practices.
* **Multi-Host Management:** Centralized dashboard to manage and monitor dozens of domains simultaneously.

## Dashboard Overview

The TLS Monitor table provides a comprehensive snapshot of your monitored hosts:

| Field           | Description                                                        |
| :-------------- | :----------------------------------------------------------------- |
| **Hostname**    | The full URL being monitored (e.g., `https://api.yourdomain.com`). |
| **Status**      | The result of the last automated check (Success/Failed).           |
| **TLS Version** | The specific protocol version currently served by the host.        |
| **Expire Date** | The exact date when the current certificate will stop being valid. |

<Callout type="warn" title="Automated Alerts">
  The system will generate a "Warning" badge if the scan detects insecure cipher suites or upcoming expirations, allowing your team to rotate certificates before users are affected.
</Callout>

## Configuration

To add a new monitor, simply provide a descriptive name and the full hostname. You can also assign **Tags** to organize monitors by environment (e.g., `Production`, `Staging`) or project.


# Automation & Workflows



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { 
  Zap, 
  Code2, 
  Cpu, 
  Workflow, 
  MessageSquare, 
  Bot 
} from 'lucide-react';

# Workflow Automation

The Donutwork **Workflow** module is the operational "brain" of the platform. It is a **No-Code/Low-Code** visual automation engine that allows you to connect events (triggers), decision logic, and external actions via an intuitive node-based interface.

Built on an **event-driven** architecture, you can trigger sequences of actions whenever a specific event occurs in your SaaS (e.g., customer creation, payment updates, or partner onboarding).

## How It Works

Every Workflow consists of three fundamental building blocks:

1. **Trigger (The Start):** The event that initiates the flow (e.g., `Customer.create`).
2. **Logic Nodes:** Blocks that process data, apply filters, or make decisions (IF/Else, Switch).
3. **Actions (The Output):** Concrete operations such as sending emails, triggering Webhooks, or updating database records.

***

## Node Catalog

The editor provides an extensive library of ready-to-use blocks categorized by function:

| Category    | Key Nodes             | Function                                                                |
| :---------- | :-------------------- | :---------------------------------------------------------------------- |
| **Control** | Trigger, End          | Handle the entry and exit points of the flow.                           |
| **Logic**   | IF, Switch, Filter    | Create conditional paths and route data based on specific criteria.     |
| **Data**    | Math, Merge, Text     | Perform calculations, merge JSON objects, or format dynamic strings.    |
| **CRM**     | Get Customer, Partner | Retrieve real-time entity data directly from your database.             |
| **Actions** | Webhook, Email        | Communicate with external tools (e.g., Slack, Zapier, or your own API). |

***

## AI-Powered Automation

Donutwork takes automation to the next level by integrating AI tools directly into the workflow canvas:

<Cards>
  <Card icon={<Bot className="text-purple-500" />} title="AI Build (Copilot)" description="Describe your logic in plain English (e.g., 'If a new customer is created, send a webhook') and the AI will architect the flow for you." />

  <Card icon={<MessageSquare className="text-blue-500" />} title="AI Explain" description="Analyze any existing workflow to get a clear, step-by-step textual explanation of the implemented logic." />
</Cards>

***

## Advanced Capabilities

### Loops and Variables

Use the **Set Variable** node to store temporary data during execution or the **For Each** node to iterate over arrays (e.g., processing all pending payouts for a partner).

### Error Prevention & Safety

The editor includes a built-in **Cycle Detection** system that prevents infinite loops, ensuring the stability of your system and protecting your external API rate limits.

### Custom Blocks

Developers can register **Custom Blocks** to extend the platform. These nodes appear in the sidebar with specific icons and badges, allowing non-technical team members to use proprietary business functions (e.g., `CRM Notifier`) safely.

<Callout type="warn" title="Validation Requirements">
  Before saving, the system ensures that the workflow contains at least one **Initial Trigger**, one **End** node, and that all placed nodes are properly connected.
</Callout>

***

## Use Case Example: Onboarding Flow

1. **Trigger:** `Customer.create`
2. **Logic:** `IF` node to check if the customer provided a VAT number.
3. **Action (True):** Send a "Business Welcome Kit" email.
4. **Action (False):** Send a "Prosumer Welcome Kit" email.
5. **End:** Close the execution.


# AI Integration Hub



# Integra Donutwork Più Velocemente

Questa e' la pagina principale per l'integrazione AI-assisted su Donutwork.
Se il tuo team usa Codex o altri copiloti AI, parti da qui per ridurre i tempi di implementazione, limitare errori sugli scope e pubblicare integrazioni piu' solide.

## Perche' E' Importante

* Onboarding rapido con skill di integrazione pronta all'uso.
* Mappa endpoint-to-scope chiara per privilegio minimo.
* Modelli entita' a livello campo per payload piu' sicuri.
* Checklist go-live ripetibile per rilasci affidabili.

## Asset Ufficiali Per Integrazione AI

* Skill Donutwork (latest): [`/downloads/donutwork-skill-latest.tar.gz`](/downloads/donutwork-skill-latest.tar.gz)
* Checksum (latest): [`/downloads/donutwork-skill-latest.sha256`](/downloads/donutwork-skill-latest.sha256)
* Skill Donutwork per Claude Code (latest): [`/downloads/donutwork-claude-code-skill-latest.skill`](/downloads/donutwork-claude-code-skill-latest.skill)
* Checksum Claude Code (latest): [`/downloads/donutwork-claude-code-skill-latest.sha256`](/downloads/donutwork-claude-code-skill-latest.sha256)
* Snapshot OpenAPI: [`/openapi.json`](/openapi.json)
* Bundle AI completo: [`/llms-full.txt`](/llms-full.txt)
* Indice AI rapido: [`/llms.txt`](/llms.txt)

## Installazione In 60 Secondi

```bash
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
tar -xzf donutwork-skill-latest.tar.gz -C "${CODEX_HOME:-$HOME/.codex}/skills"
```

Poi invoca:

```text
Use $donutwork to design my integration plan.
```

## Setup Claude Code

```bash
unzip -o donutwork-claude-code-skill-latest.skill -d "$HOME"
```

Verifica integrita' (opzionale):

```bash
sha256sum -c donutwork-claude-code-skill-latest.sha256
```

## Cosa Ottieni Con `$donutwork`

* Piano endpoint per feature (metodo, path, scopo).
* Scope OAuth/API richiesti per endpoint.
* Guida modelli payload con campi richiesti.
* Esempi request pronti da usare.
* Checklist di rilascio per staging e produzione.

## Prompt Consigliati

1. `Use $donutwork to map scopes for customers, charges, and webhooks.`
2. `Use $donutwork to generate payload models for customer and subscription sync.`
3. `Use $donutwork to produce a production go-live checklist for our integration.`

## Prossimo Step

Apri la documentazione completa della skill:

* [Skill Codex Donutwork](/it/docs/applications/donutwork-skill)
* [Donutwork Claude Code Skill](/it/docs/applications/donutwork-claude-code-skill)


# Benvenuto in Donutwork



import { Card, Cards } from 'fumadocs-ui/components/card';

import {
BarChart3,
CreditCard,
ShieldCheck,
Cpu,
Layout,
Users
} from 'lucide-react';

# Accelerare il tuo Business con Donutwork

Donutwork è il cuore pulsante del tuo SaaS. Abbiamo creato un ecosistema di strumenti pronti all’uso che eliminano la necessità di reinventare la ruota ogni volta che lanci un nuovo progetto. Dalla gestione dei pagamenti al monitoraggio dell’infrastruttura, Donutwork gestisce la complessità, così puoi concentrarti sul tuo core business.

## Esplora i Pilastri della Piattaforma

Scegli l’area che desideri esplorare per configurare i tuoi sistemi.

<Cards>
  <Card icon={<BarChart3 className="text-blue-500" />} title="Business Intelligence" href="/it/docs/bi-growth" description="Monitora MRR, KPI e crescita dei ricavi in tempo reale con dashboard avanzate." />

  <Card icon={<CreditCard className="text-green-500" />} title="Fatturazione & Monetizzazione" href="/it/docs/recurring-payments" description="Gestisci abbonamenti, componenti aggiuntivi dinamici e regole di reward." />

  <Card icon={<ShieldCheck className="text-red-500" />} title="Sicurezza Sentinel" href="/it/docs/sentinel" description="Proteggi i tuoi utenti con MFA adattivo, analisi comportamentale e policy di sicurezza enterprise." />

  <Card icon={<Cpu className="text-purple-500" />} title="Piattaforma per Sviluppatori" href="/it/docs/applications" description="Webhook, gestione chiavi API, Job Runner e Scheduler per il controllo totale." />

  <Card icon={<Layout className="text-orange-500" />} title="Contenuti Dinamici" href="/it/docs/dynamic-content-modeling" description="Sistema headless-ready e Media Library per contenuti dinamici." />

  <Card icon={<Users className="text-indigo-500" />} title="Partner & Revenue" href="/it/docs/partner-program" description="Crea programmi partner, gestisci commissioni e calcola automaticamente i pagamenti." />
</Cards>

***

## Strumenti Utility Integrati

Donutwork include una suite di microservizi pronti per le tue API, risparmiando ore di sviluppo personalizzato:

* **Utility Finanziarie:** validazione Partita IVA, conversione valuta.
* **Networking:** IP Intelligence, geolocalizzazione e monitoraggio certificati TLS.
* **Produttività per Sviluppatori:** generatore di short link, strumenti di screenshot e bot Telegram integrato.
* **Comunicazione:** gateway email integrato con template transazionali.

***

## Approccio Enterprise-Ready

Ogni componente di Donutwork è progettato per scalare. Gestisci **Multi-company**, ambienti separati **Staging** e **Production**, e mantieni il controllo completo tramite il **Key Management Service (KMS)**.

> **Hai bisogno di supporto tecnico?**
> Se stai integrando Donutwork nel tuo stack tecnologico, consulta la nostra Documentazione API ([https://api.hub.donutwork.com/docs](https://api.hub.donutwork.com/docs)) o contatta il nostro team di supporto dedicato all’architettura dei sistemi.

## Percorso Consigliato Per Partire

1. Definisci il modello commerciale da [Pagamenti Ricorrenti](/it/docs/recurring-payments).
2. Configura i flussi operativi nel modulo [Customer](/it/docs/customer).
3. Attiva [Sentinel](/it/docs/sentinel) per controlli rischio e autenticazione adattiva.
4. Imposta [Email Gateway](/it/docs/email-gateway) e [Workflow](/it/docs/workflow) per automazioni end-to-end.
5. Misura impatto e trend in [Business Intelligence & Growth](/it/docs/bi-growth).

## Punto di Accesso AI

Se stai integrando Donutwork con copiloti AI o agent coding autonomi, parti da:

* [AI Integration Hub](/it/docs/ai-integration)


# Authentication



import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';

# Authentication

The Donutwork API uses API Keys to authenticate requests. You can view and manage your API keys in the Donutwork Dashboard.

## Authorization Header

All API requests must include your API Key in the `Authorization` HTTP header as a Bearer token.

```http
Authorization: Bearer <your_api_key>
```

<Callout type="warn">
   Your API keys carry significant privileges. Keep them secure and never expose them in client-side code or public repositories. 
</Callout>

## Obtaining an API Key

Donutwork is currently in a controlled rollout phase. Access is granted to partners and early adopters through the following process:

<Steps>
  <Step>
    ### Request Access

    Submit a request to the Donutwork team outlining your integration use case.
  </Step>

  <Step>
    ### Review & Provisioning

    Our team will review your requirements and provision the necessary environments.
  </Step>

  <Step>
    ### Environment Keys

    Upon approval, you will be provided with distinct keys for:

    * **Staging**: For development, testing, and sandbox experimentation.
    * **Production**: For live, customer-facing traffic.
  </Step>
</Steps>

## Connectivity and Health Checks

Use these endpoints to validate your authentication credentials and monitor API availability.

### System Ping

Verify the operational status of the Donutwork API environment.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/ping.json"
  responses={[ 
  { 
    status: "200 OK", 
    description: "API is operational and responding.", 
    content: { "status": "success", "env": "production", "RRT": "0.08 ms" } 
  }, 
  { 
    status: "401 Unauthorized", 
    description: "Invalid or revoked API key.", 
    content: { "error": "Invalid token" } 
  } 
]}
/>

### Connection Metadata

Retrieve detailed information about your current connection, including client IP and protocol negotiation.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/connection.json"
  responses={[ 
  { 
    status: "200 OK", 
    description: "Connection metadata retrieved successfully.", 
    content: {
      "client": {
        "userAgent": "axios/1.6.0",
        "ips": { "ipv4": "192.168.1.1" }
      },
      "endpoint": {
        "apiVersion": "2026-02-01",
        "env": "production",
        "protocol": "HTTP3"
      }
    } 
  } 
]}
/>


# Company



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Company

The Company API allows you to retrieve metadata about your own organization and lookup public data for third-party companies using VAT identifiers.

***

## Get Company Profile

Retrieve the core configuration and identification attributes for your company profile. This includes your unique internal identifier and official registered name.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/company.json"
  responses={[
  { 
    status: "200 OK", 
    description: "Company profile retrieved successfully.",
    content: {
      "id": "668ea32f5485467fd7149f48",
      "name": "Acme Corp"
    } 
  }
]}
/>

***

## List Active Modules

Discover and monitor the status of functional modules enabled for your organization. Each module represents a specific capability (e.g., Recurring Payments, Email Gateway) along with its configuration and activation state.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/company/modules.json"
  responses={[
  { 
    status: "200 OK", 
    description: "List of organizational modules.",
    content: [
      {
          "id": "recurring-payments",
          "description": "Automated subscription billing and payment orchestration.",
          "price": 0,
          "active": true
      },
      {
          "id": "email-gateway",
          "description": "Transactional email delivery via unified REST interface.",
          "price": 0,
          "active": true
      },
      {
          "id": "geoip",
          "description": "IPv4 geolocation and regional metadata resolution.",
          "price": 0,
          "active": true
      }
    ] 
  }
]}
/>

***

## Company Intelligence Stats

Retrieve the company intelligence snapshot used by operational dashboards. This endpoint returns KPI data, usage widgets, revenue chart aggregates, and metadata for the current company context.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/company/stats/intelligence.json"
  responses={[
  { 
    status: "200 OK", 
    description: "Company intelligence payload retrieved.",
    content: {
      "kpi": {
        "mrr_growth": { "raw_percent": 12.3, "display_label": "12.30%" },
        "total_customers": 120,
        "active_subscriptions": 93
      },
      "usage": {
        "banner": { "show": false, "status": null, "upgrade_url": null },
        "widgets": []
      },
      "recent_activity": [],
      "revenue_chart": {
        "graph": [],
        "stats": { "one_shot": 0, "subscriptions": 0, "total": 0 }
      },
      "revenue_insights": {
        "visible": false,
        "net_revenue": 0,
        "tax_total": 0,
        "discounts_total": 0,
        "services": [],
        "top_services": []
      },
      "meta": {
        "company_id": "668ea32f5485467fd7149f48",
        "year": 2026,
        "month": 4,
        "generated_at": "2026-04-15T10:00:00+00:00"
      }
    } 
  }
]}
/>

***

## Lookup Registered Company (Open Data)

Retrieve public business information for a company using its VAT number. This is particularly useful for automating KYC (Know Your Customer) workflows and ensuring data accuracy during customer onboarding.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/company/{vatNumber}.json"
  params={[
  { name: "vatNumber", type: "string", required: true, description: "The VAT registration number of the target company.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Public company data found.",
    content: {
      "vatNumber": "IT12345678901",
      "name": "Example Solutions S.r.l.",
      "address": "Corso Vittorio Emanuele II, 1, 00186 Roma RM, Italy",
      "vies_interrogation": { "valid": true }
    } 
  },
  { 
    status: "404 Not Found", 
    description: "No data available for the specified VAT number.",
    content: { "error": "Company not found" } 
  }
]}
/>


# Currency



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Currency

The Currency API provides programmatic access to platform-supported monetary denominations and enables precision-grade currency conversion based on Donutwork's centralized exchange data.

***

## List Enabled Currencies

Retrieve the full collection of ISO 4217 currency codes supported by the platform.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/currencies.json"
  responses={[
  { 
    status: "200 OK", 
    description: "List of supported ISO 4217 currency codes (uppercase).",
    content: ["EUR", "USD", "GBP"] 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "NODEJS"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/currencies.json' \
    --header 'Authorization: Bearer YOUR_API_KEY'
    ```
  </Tab>

  <Tab value="NODEJS">
    ```js
    const currencies = await sdk.currency.list();
    console.table(currencies);
    ```
  </Tab>
</Tabs>

***

## Perform Currency Conversion

Execute a real-time conversion between two supported currencies.\
The response field `amount` is the converted value, not the original request amount.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/currencies/{fromCurrency}/{toCurrency}.json"
  params={[
  { name: "fromCurrency", type: "string", required: true, description: "The source ISO currency code (e.g., EUR).", location: "path" },
  { name: "toCurrency", type: "string", required: true, description: "The target ISO currency code (e.g., USD).", location: "path" }
]}
  body={{
  "amount": 100.00
}}
  properties={[
  { name: "amount", type: "number", required: false, description: "The monetary value to be converted. Defaults to `0` when omitted." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Conversion successfully processed.",
    content: {
      "from": "EUR",
      "to": "USD",
      "rate": 1.085,
      "amount": 108.5
    } 
  },
  { 
    status: "400 Bad Request", 
    description: "Unsupported base or destination currency code.",
    content: { "error": "Invalid currency passed" } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "NODEJS"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request POST \
    'https://api.hub.donutwork.com/2026-02-01/currencies/EUR/USD.json' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --data '{"amount": 100}'
    ```
  </Tab>

  <Tab value="NODEJS">
    ```js
    const conversion = await sdk.currency.convert("EUR", "USD", 100);
    console.log(`Converted: ${conversion.amount} ${conversion.to} @ rate ${conversion.rate}`);
    ```
  </Tab>
</Tabs>


# Customers



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Customers

The Customer API is the central hub for managing your client base. It allows you to synchronize your internal CRM data, manage billing profiles, and monitor subscription health across your organization.

***

## List All Customers

Retrieve a paginated collection of customers associated with your organization. This endpoint is ideal for dashboard overviews and batch synchronization processes.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers.json"
  params={[
  { name: "size", type: "integer", required: false, description: "The number of customer records to return per page (maximum 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "The specific results page to retrieve.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "A paginated list of customers.",
    content: {
      "entities": "Customer",
      "count": 150,
      "per_page": 100,
      "pages": { "current": 1, "max": 2 },
      "elements": [
        {
          "id": "67248941cbe2b1ff8b099a6c",
          "external_id": "CRM-UID-9921",
          "company_name": "Global Logistics S.A.",
          "email": "billing@globallogistics.com"
        }
      ]
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "NODEJS"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/customers.json?size=20' \
    --header 'Authorization: Bearer YOUR_API_KEY'
    ```
  </Tab>

  <Tab value="NODEJS">
    ```js
    const customers = await sdk.customers.list({ size: 20 });
    console.table(customers.elements);
    ```
  </Tab>
</Tabs>

***

## Create a New Customer

Initialize a new customer profile. This is the prerequisite step for attaching subscriptions or processing one-time charges. High-quality data at this stage ensures accurate tax calculation and communication delivery.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/customers.json"
  body={{
  "customer": {
      "company_name": "Acme Corporation",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@acme.com",
      "externalId": "CRM-UID-9921",
      "address": {
          "country": "US",
          "city": "San Francisco",
          "address": "123 Market St"
      }
  }
}}
  properties={[
  { name: "customer.company_name", type: "string", required: true, description: "Official legal name of the organization." },
  { name: "customer.email", type: "string", required: true, description: "Primary contact email for billing and notifications." },
  { name: "customer.first_name", type: "string", required: true, description: "Contact person's first name." },
  { name: "customer.last_name", type: "string", required: true, description: "Contact person's last name." },
  { name: "customer.address.country", type: "string", required: true, description: "ISO 3166-1 alpha-2 country code (e.g., US, IT)." },
  { name: "customer.externalId", type: "string", required: false, description: "Your internal system identifier for cross-referencing." },
  { name: "customer.address.city", type: "string", required: false, description: "City of residence or incorporation." },
  { name: "customer.address.address", type: "string", required: false, description: "Street address including number." },
  { name: "customer.address.postal_code", type: "string", required: false, description: "Postal or ZIP code." },
  { name: "customer.address.state", type: "string", required: false, description: "State, province, or region." },
  { name: "customer.address.vat_number", type: "string", required: false, description: "Tax identifier for business entities." },
  { name: "customer.properties", type: "array", required: false, description: "Custom metadata fields for specialized integration logic." },
  { name: "customer.partner.id", type: "string", required: false, description: "Donutwork identifier for a referring partner." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Customer profile successfully created.",
    content: { "customer": { "id": "67c9...", "partner": null } } 
  },
  { 
    status: "409 Conflict", 
    description: "A profile with this email or externalId already exists.",
    content: { "error": "A customer already exists with this email" } 
  }
]}
/>

***

## Retrieve Customer Details

Fetch the complete profile for a specific customer. This includes organizational metadata, contact information, and summarized subscription status.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Complete customer profile retrieved.",
    content: {
      "id": "672489...",
      "email": "jane.doe@acme.com",
      "company_name": "Acme Corporation",
      "externalId": "CRM-UID-9921"
    } 
  }
]}
/>

***

## Search by External Identifier

Locate a customer profile using your internal system's identifier (externalId). This is essential for maintaining synchronization between Donutwork and your primary CRM/ERP.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/customer.json"
  params={[
  { name: "externalId", type: "string", required: true, description: "The unique identifier from your internal system.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Customer profile found.",
    content: {
      "id": "672489...",
      "email": "jane.doe@acme.com",
      "externalId": "CRM-UID-9921"
    } 
  },
  { 
    status: "404 Not Found", 
    description: "No customer matches the provided externalId.",
    content: { "error": "This customer does not exist" } 
  }
]}
/>

***

## Update Customer Profile

Modify an existing customer record. This endpoint supports partial updates (PATCH-style behavior); only the fields included in the request body will be modified. This is useful for updating contact information or adding organizational tags.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  body={{
  "customer": {
      "email": "updated.contact@acme.com",
      "tags": ["enterprise", "priority-support"]
  }
}}
  properties={[
  { name: "customer.email", type: "string", required: false, description: "The updated primary contact email." },
  { name: "customer.first_name", type: "string", required: false, description: "Updated first name." },
  { name: "customer.last_name", type: "string", required: false, description: "Updated last name." },
  { name: "customer.company_name", type: "string", required: false, description: "Updated legal company name." },
  { name: "customer.tags", type: "array", required: false, description: "A collection of labels for internal classification and reporting." },
  { name: "customer.address.country", type: "string", required: false, description: "Updated ISO country code." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Customer profile successfully updated.",
    content: { "customer": { "id": "6724..." } } 
  }
]}
/>

***

## Decommission Customer Profile

Permanently remove a customer profile and all associated metadata. This action is destructive and irreversible. Ensure that all active subscriptions are terminated before choosing to decommission a profile.

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/customers/{customerId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  responses={[
  { 
    status: "202 Accepted", 
    description: "Deletion request accepted and queued for processing.",
    content: { "id": "67c9...", "deleted": true } 
  }
]}
/>

***

## Customer Properties (Metadata)

Extend the customer profile with custom key-value pairs. Properties are ideal for storing domain-specific data, integration identifiers, or specialized configuration flags that are not captured by standard profile fields.

### Retrieve All Properties

Fetch the complete set of custom metadata associated with a customer.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/properties.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Collection of customer-specific properties retrieved.",
    content: {
      "count": 2,
      "type": "CustomerProperties",
      "elements": {
        "crm_segment": "enterprise",
        "onboarding_status": "completed"
      }
    } 
  }
]}
/>

### Atomic Update/Insert (Upsert) Properties

Update existing property values or append new keys to the customer's property collection. This endpoint performs an "upsert" operation; keys that do not exist will be created, and existing keys will have their values overwritten.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/properties.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  body={{
  "CustomerProperties": {
    "support_tier": "platinum",
    "preferred_language": "en"
  }
}}
  properties={[
  { name: "CustomerProperties", type: "object", required: true, description: "An object containing the key-value pairs to persist." }
]}
  responses={[
  { 
    status: "202 Accepted", 
    description: "Properties successfully updated.",
    content: { 
      "customer": { "id": "6724..." },
      "CustomerProperties": {
          "support_tier": "platinum",
          "preferred_language": "en"
      }
    } 
  }
]}
/>

***

## Secure Hosted Payment Link

Generate a unique, short-lived URL for the Donutwork Hosted Payment Page. This secure interface allow customers to update their sensitive payment information (e.g., Credit Card, SEPA Mandate) without sensitive data passing through your servers.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/payment_link.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Secure payment link generated.",
    content: { "url": "https://pay.donutwork.com/l/xxxxxxxxxx" } 
  }
]}
/>

***

## Subscription Management

Manage recurring billing cycles and plan associations for your customers. Subscriptions automate the generation of invoices and payment processing based on predefined logic.

### List Active and Historical Subscriptions

Retrieve a collection of all subscription entities associated with a customer, including active, canceled, and past-due states.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "A list of customer subscriptions.",
    content: {
      "type": "CustomerSubscriptions",
      "elements": [
        {
          "id": "sub_123",
          "name": "Enterprise SaaS Plan",
          "status": "success",
          "next_renew": "2026-04-01",
          "price": { "amount": 499.00, "vat": { "percentage": 22, "name": "IVA" } }
        }
      ]
    } 
  }
]}
/>

### Attach New Subscription

Provision a new subscription for a customer. This endpoint allows for runtime overrides of plan defaults, such as custom discounts and initial addon quantities.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The unique Donutwork identifier for the customer.", location: "path" }
]}
  body={{
  "subscription": {
    "id": "PLAN_PREMIUM_V2",
    "taxes": "TAX_STANDARD_22",
    "global_discount": { "value": 15, "type": "percentage" },
    "addons": [
      { "element": "api_quota", "quantity": 10000 }
    ]
  }
}}
  properties={[
  { name: "subscription.id", type: "string", required: true, description: "The identifier of the target plan." },
  { name: "subscription.taxes", type: "string", required: true, description: "The tax profile ID to apply to this subscription." },
  { name: "subscription.global_discount.value", type: "number", required: false, description: "The absolute or percentage value of the discount." },
  { name: "subscription.global_discount.type", type: "string", required: false, description: "The type of discount: 'percentage' or 'amount'." },
  { name: "subscription.addons", type: "array", required: false, description: "A list of addon overrides with their respective quantities." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Subscription successfully provisioned.",
    content: { "id": "sub_67c9...", "status": "active" } 
  }
]}
/>

### Detach Subscription

Detach a subscription from the customer profile.

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID to remove from the customer.", location: "path" }
]}
  responses={[
  { 
    status: "202 Accepted", 
    description: "Subscription detached from customer profile.",
    content: { "id": "sub_67c9...", "deleted": true } 
  }
]}
/>

### Retrieve Subscription Status

Read the operational status of a specific customer subscription.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/status.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Current status for the selected subscription.",
    content: { "id": "sub_123", "status": "active", "next_renew": "2026-05-01" } 
  },
  {
    status: "404 Not Found",
    description: "Subscription does not exist for the specified customer.",
    content: { "error": "This subscription does not exists for this customer" }
  }
]}
/>

### Modify Subscription Status

Manually transition a subscription between operational states. This is typically used for administrative overrides or manual churn management.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/status.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  body={{ "subscription": { "status": "dismiss" } }}
  properties={[
  { name: "subscription.status", type: "string", required: true, description: "Target status. Supported values: `active`, `dismiss`." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Status successfully updated.",
    content: { "id": "sub_123", "status": "dismiss", "next_renew": null } 
  }
]}
/>

***

### Advanced Subscription Lifecycle (Additive)

These endpoints extend subscription lifecycle management without replacing existing legacy routes.
Use them when you need pause/resume, plan amendments, scheduled changes, and proration-aware updates.

#### Read Extended Lifecycle State

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/lifecycle.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Extended lifecycle metadata for the subscription.",
    content: {
      "id": "sub_123",
      "status": "success",
      "lifecycle_status": "active",
      "cancel_at_period_end": false,
      "scheduled_change": null,
      "carryover_credit": 0
    } 
  }
]}
/>

#### Pause, Resume, Cancel-at-Period-End

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/pause.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  body={{
  "lifecycle": {
    "idempotency_key": "lifecycle-evt-001"
  }
}}
  properties={[
  { name: "lifecycle.idempotency_key", type: "string", required: false, description: "Optional idempotency key for safe retries." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Lifecycle transition applied.",
    content: {
      "id": "sub_123",
      "lifecycle_status": "paused",
      "amendment": { "action": "pause", "status": "applied" }
    } 
  }
]}
/>

Use the same payload model with:

* `.../lifecycle/resume.json`
* `.../lifecycle/cancel-at-period-end.json`
* `.../lifecycle/undo-cancel-at-period-end.json`

Pause/resume billing behavior:

* No retroactive automatic billing is created when resuming after a long pause.
* If resumed two months later (for example pause on **May 1, 2026** and resume on **July 1, 2026**), renewal is re-anchored to the resume date (or future `resume_at` if provided).

Undo-cancel behavior:

* If a subscription is `cancel_pending`, you can revert it to `active` before renewal boundary.
* Plan/addons remain the current ones on the subscription; cancellation flag is removed.

#### Change Plan or Addons with Immediate/Scheduled Application

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-plan.json"
  body={{
  "lifecycle": {
    "plan_id": "PLAN_ENTERPRISE_V3",
    "taxes": "TAX_STANDARD_22",
    "when": "period_end",
    "proration": true
  }
}}
  properties={[
  { name: "lifecycle.plan_id", type: "string", required: true, description: "Target plan identifier." },
  { name: "lifecycle.taxes", type: "string", required: false, description: "Tax profile override." },
  { name: "lifecycle.when", type: "string", required: false, description: "`immediate` (default) or `period_end`." },
  { name: "lifecycle.proration", type: "boolean", required: false, description: "Enable or disable proration logic." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Plan change accepted (immediate or scheduled).",
    content: {
      "id": "sub_123",
      "scheduled_change": { "type": "plan", "apply_on": "2026-06-01" },
      "amendment": { "action": "change_plan", "status": "applied" }
    } 
  }
]}
/>

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-addons.json"
  body={{
  "lifecycle": {
    "addons": [
      { "element": "workspace_seat", "quantity": 25 }
    ],
    "when": "immediate",
    "proration": true
  }
}}
  responses={[
  { 
    status: "200 OK", 
    description: "Addon amendment applied with optional proration.",
    content: {
      "id": "sub_123",
      "carryover_credit": 18.5,
      "amendment": { "action": "change_addons", "status": "applied" }
    } 
  }
]}
/>

#### Proration Preview (No Mutation)

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/preview.json"
  body={{
  "lifecycle": {
    "action": "change_addons",
    "addons": [
      { "element": "workspace_seat", "quantity": 40 }
    ]
  }
}}
  responses={[
  { 
    status: "200 OK", 
    description: "Economic preview of the amendment without persisting changes.",
    content: {
      "action": "change_addons",
      "proration": { "old_due": 499, "new_due": 679, "delta": 180, "direction": "debit" }
    } 
  }
]}
/>

#### Amendment History

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/amendments.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Max entries per page (1-100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Paginated amendment stream for audit and support operations.",
    content: {
      "type": "CustomerSubscriptionAmendments",
      "elements": [
        { "action": "change_addons", "when": "immediate", "status": "applied" }
      ]
    } 
  }
]}
/>

### Backward Compatibility

Lifecycle endpoints are **additive and opt-in**.
Existing integrations can keep using current routes unchanged.

| Area                     | Legacy Contract        | Lifecycle Extension                              |
| :----------------------- | :--------------------- | :----------------------------------------------- |
| Attach/Detach            | Unchanged              | Still valid                                      |
| Status route             | Unchanged payload keys | Additional lifecycle visibility                  |
| Addons route             | Unchanged              | Optional proration-aware lifecycle change-addons |
| Usage/metering           | Unchanged              | Unchanged                                        |
| Existing panel/API flows | Unchanged              | New actions available when explicitly called     |

***

### Subscription Addons

Manage the quantity of modular features (addons) attached to a specific subscription. Addons allow for flexible, feature-based pricing.

#### Audit Addon Quantities

Retrieve a list of all addons currently active on a subscription along with their provisioned quantities.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/addons.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "List of provisioned addons.",
    content: [
      { "element": "compute_units", "quantity": 10 },
      { "element": "secondary_domains", "quantity": 2 }
    ] 
  }
]}
/>

#### Reconcile Addon Quantities

Update the provisioned quantities for one or more addons. This operation is additive or disruptive based on the provided quantity values.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}/addons.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  body={{
  "addons": [
    { "element": "compute_units", "quantity": 15 }
  ]
}}
  properties={[
  { name: "addons", type: "array", required: true, description: "Addon collection to upsert." },
  { name: "addons[].element", type: "string", required: true, description: "Addon identifier." },
  { name: "addons[].quantity", type: "integer", required: true, description: "Requested addon quantity." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Addon quantities successfully updated.",
    content: { "status": "updated" } 
  }
]}
/>

***

### Simulation Interface (Sandbox Only)

Accelerate development cycles by simulating subscription lifecycle events in non-production environments.

#### Simulate Success Event

Force a successful renewal or provisioning event for a subscription.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/simulate/{subscriptionId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  responses={[
  { status: "200 OK", content: { "status": "simulated_success" } }
]}
/>

#### Simulate Failure Event

Force a failed renewal or payment rejection event.

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/simulate/{subscriptionId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  responses={[
  { status: "200 OK", content: { "status": "simulated_failure" } }
]}
/>

***

## Metered Usage Tracking

For subscriptions with `metering: true`, consumption must be reported via these endpoints. Usage is aggregated and billed at the end of the current billing cycle.

### Report Usage Event

Record a new consumption event (e.g., API requests, data processed, seats occupied). Each record requires a unique `externalId` to prevent idempotent replay errors.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  body={{
  "usage": {
    "amount": 10.50,
    "value": 100,
    "value_type": "api_requests",
    "externalId": "evt_unique_uuid_123"
  }
}}
  properties={[
  { name: "usage.amount", type: "number", required: true, description: "The monetary value or unit count to bill." },
  { name: "usage.value", type: "number", required: true, description: "The raw consumption value." },
  { name: "usage.value_type", type: "string", required: true, description: "The metric identifier (e.g., 'storage_gb', 'api_calls')." },
  { name: "usage.externalId", type: "string", required: true, description: "A unique identifier for idempotency." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Usage successfully recorded.",
    content: { "id": "usage_67c9...", "amount": 10.50 } 
  }
]}
/>

### Audit Usage History

Retrieve a paginated history of all usage events reported for a specific subscription.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/subscriptions/{subscriptionId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "subscriptionId", type: "string", required: true, description: "The subscription ID.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Paginated usage history retrieved.",
    content: { "type": "CustomerSubscriptionUsages", "elements": [] } 
  }
]}
/>

***

## Ad-hoc Charges

Charges represent immediate, non-recurring billable events created independently of a subscription's billing cycle (e.g., setup fees, professional services).

### Create One-Time Charge

Generate an ad-hoc charge. If the `capture` flag is set to `true`, the system will immediately attempt to authorize and capture the funds using the customer's primary payment method.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/customers/{customerId}/charges.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" }
]}
  body={{
  "charge": {
    "capture": true,
    "services": [
      { "name": "Technical Consulting", "amount": 250.00, "taxProfile": "TAX_SERVICES_22" }
    ]
  }
}}
  properties={[
  { name: "charge.capture", type: "boolean", required: false, description: "Whether to attempt immediate payment capture." },
  { name: "charge.services", type: "array", required: true, description: "A list of line items included in the charge." },
  { name: "charge.instruction", type: "string", required: false, description: "Payment instruction (e.g., 'sepa_debit', 'manual')." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Charge created and payment status returned.",
    content: { "status": "success", "id": "ch_777", "captured": true } 
  }
]}
/>

### List Organizational Charges

Retrieve all charges (including pending and failed attempts) associated with a specific customer profile.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/charges.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "List of customer-specific charges.",
    content: { "type": "CustomerCharges", "elements": [] } 
  }
]}
/>

### Charge Details and Reconciliation

Retrieve detailed metadata for a specific charge, including its internal lifecycle state and tax calculations.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/charges/{chargeId}.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "chargeId", type: "string", required: true, description: "The unique charge identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Full charge metadata.",
    content: {
      "id": "ch_777",
      "customer_id": "cust_123",
      "total": 305.00,
      "type": "one-shot",
      "status": "paid",
      "statuses": { "pending": false, "paid": true, "refunded": false },
      "date": { "date": "2026-03-01 10:00:00.000000", "timezone": "+00:00" }
    } 
  }
]}
/>

### External Invoice Synchronization

Manage links to external accounting systems (e.g., Fatture in Cloud) for each charge.

#### Retrieve Invoice Metadata

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/customers/{customerId}/charges/{chargeId}/invoice.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "chargeId", type: "string", required: true, description: "The unique charge identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Invoice synchronization details.",
    content: { "number": "INV-2026-001", "date": "2026-03-01", "source": "accounting-system", "link": "https://docs.acme.com/inv/123.pdf" } 
  }
]}
/>

#### Persist Invoice Metadata

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/customers/{customerId}/charges/{chargeId}/invoice.json"
  params={[
  { name: "customerId", type: "string", required: true, description: "The customer ID.", location: "path" },
  { name: "chargeId", type: "string", required: true, description: "The unique charge identifier.", location: "path" }
]}
  body={{
  "invoice": {
    "number": "INV-2026-001",
    "date": "2026-03-01",
    "source": "erp-system",
    "link": "https://erp.example.com/invoices/991.pdf"
  }
}}
  properties={[
  { name: "invoice.number", type: "string", required: true, description: "Invoice number." },
  { name: "invoice.date", type: "string", required: true, description: "Invoice issue date." },
  { name: "invoice.source", type: "string", required: false, description: "Originating source system identifier." },
  { name: "invoice.link", type: "string", required: false, description: "Public or internal URL to invoice document." }
]}
  responses={[
  { status: "200 OK", content: { "status": "success" } }
]}
/>

***

### Global Charge Resolution

Resolve charge details using only the global unique identifier. This is optimized for callback handlers and webhook reconciliation modules.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/charges/{chargeId}.json"
  params={[
  { name: "chargeId", type: "string", required: true, description: "The global unique identifier for the charge.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Charge metadata resolved globally.",
    content: { "id": "ch_777", "customer_id": "cust_123" } 
  }
]}
/>


# Directory Monitor



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Directory Monitor

The Directory Monitor API enables real-time synchronization and event orchestration for local filesystem changes. It is designed for deep integration with local agents to monitor project directories, capture file events, and trigger remote workflows.

***

## Initialize Monitor (Startup)

Signal the start of a monitoring session for a specific project. This initialization step validates the project configuration and prepares the environment for ingress events.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/directory-monitor/{projectId}.json"
  params={[
  { name: "projectId", type: "string", required: true, description: "The unique identifier for the monitored project.", location: "path" }
]}
  body={{
  "ingressToken": "DM_SECURE_TOKEN_XYZ"
}}
  properties={[
  { name: "ingressToken", type: "string", required: false, description: "Security token for ingress authentication (can also be sent via X-Directory-Monitor-Token header)." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Monitor successfully initialized.",
    content: { "status": "success", "projectId": "proj_123" } 
  }
]}
/>

***

## Synchronize Event (Ingress)

Report a filesystem event (creation, modification, deletion) to the centralized monitor. This endpoint processes file metadata and executes any associated workflow triggers.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/directory-monitor/{projectId}.json"
  params={[
  { name: "projectId", type: "string", required: true, description: "The project identifier.", location: "path" }
]}
  body={{
  "projectId": "proj_123",
  "filename": "src/controllers/UserController.php",
  "event": "modified",
  "filesize": 4096,
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "uid": 1000,
  "pid": 4512
}}
  properties={[
  { name: "projectId", type: "string", required: true, description: "Must match the projectId in the path." },
  { name: "filename", type: "string", required: true, description: "Relative path of the affected file." },
  { name: "event", type: "string", required: true, description: "Type of event (e.g., created, modified, deleted, renamed)." },
  { name: "filesize", type: "integer", required: true, description: "Size of the file in bytes." },
  { name: "filetype", type: "string", required: false, description: "MIME type or file classification." },
  { name: "sha256", type: "string", required: false, description: "SHA-256 hash of the file content for integrity verification." },
  { name: "uid", type: "integer", required: false, description: "User ID of the process owner." },
  { name: "pid", type: "integer", required: false, description: "Process ID that triggered the event." },
  { name: "timestampUtc", type: "string", required: false, description: "ISO 8601 timestamp of the local event." },
  { name: "ingressToken", type: "string", required: false, description: "Authentication token." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Event successfully ingested and indexed.",
    content: { 
      "status": "success", 
      "eventId": "evt_7721...", 
      "projectId": "proj_123", 
      "inserted": true,
      "workflowTriggered": true
    } 
  }
]}
/>

***

## Audit Monitor Events

Retrieve a paginated history of synchronized filesystem events for a specific project. This is used for auditing changes and verifying synchronization state.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/systems/directory-monitor/{projectId}/events.json"
  params={[
  { name: "projectId", type: "string", required: true, description: "The project identifier.", location: "path" },
  { name: "size", type: "integer", required: false, description: "Number of events to return (max 200).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Pagination page number.", location: "query" },
  { name: "event", type: "string", required: false, description: "Filter by event type (e.g., modified).", location: "query" },
  { name: "pathLike", type: "string", required: false, description: "Filter by partial file path.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Collection of project events retrieved.",
    content: {
      "status": "fetch",
      "projectId": "proj_123",
      "page": 1,
      "size": 50,
      "count": 120,
      "items": []
    } 
  }
]}
/>


# DNS



# DNS API

Use DNS endpoints for diagnostic and propagation checks across public resolvers.

## DNS Capabilities

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/dns/capabilities.json"
  responses={[
  {
    status: "200 OK",
    description: "Supported record types, default record types, and resolver catalog.",
    content: {
      "recordTypes": ["A", "AAAA", "CNAME", "TXT", "MX", "NS", "SOA", "CAA", "SRV"],
      "defaultRecordTypes": ["A", "AAAA", "CNAME", "TXT"],
      "resolvers": [
        { "id": "cloudflare_primary", "label": "Cloudflare (1.1.1.1)", "server": "1.1.1.1" },
        { "id": "google_primary", "label": "Google (8.8.8.8)", "server": "8.8.8.8" }
      ]
    }
  }
]}
/>

## DNS Lookup (GET)

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/dns/lookup.json"
  params={[
  { name: "target", type: "string", required: true, description: "Hostname or IP to resolve.", location: "query" },
  { name: "recordTypes", type: "array|string", required: false, description: "Record types list (for example A, MX, TXT).", location: "query" },
  { name: "resolverPreset", type: "array|string", required: false, description: "Resolver preset filter.", location: "query" },
  { name: "customResolvers", type: "string", required: false, description: "Space/comma separated custom resolvers.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "DNS lookup completed.",
    content: {
      "target": "example.com",
      "generated_at": "2026-04-15T10:00:00+00:00",
      "recordTypes": ["A", "AAAA"],
      "resolver_count": 2,
      "resolvers": [
        { "id": "cloudflare_primary", "label": "Cloudflare (1.1.1.1)", "server": "1.1.1.1" },
        { "id": "google_primary", "label": "Google (8.8.8.8)", "server": "8.8.8.8" }
      ],
      "propagation": {
        "A": { "is_consistent": true, "distinct_statuses": 1, "distinct_answers": 1 }
      },
      "queries": {
        "A": [
          {
            "resolver_label": "Cloudflare (1.1.1.1)",
            "resolver": "1.1.1.1",
            "record_type": "A",
            "status": "NOERROR",
            "server": "1.1.1.1#53",
            "query_time_ms": 12,
            "answers": [{ "name": "example.com.", "ttl": 300, "class": "IN", "type": "A", "value": "93.184.216.34" }],
            "answer_signature": "A|93.184.216.34",
            "error": null
          }
        ]
      }
    }
  },
  {
    status: "400 Bad Request",
    description: "Invalid or missing target.",
    content: { "error": "target is required" }
  }
]}
/>

## DNS Lookup (POST)

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/dns/lookup.json"
  body={{
  "target": "example.com",
  "recordTypes": ["A", "AAAA"],
  "resolverPreset": ["public"],
  "customResolvers": "1.1.1.1 8.8.8.8",
  "resolvers": ["9.9.9.9"]
}}
  properties={[
  { name: "target", type: "string", required: true, description: "Hostname or IP to resolve." },
  { name: "recordTypes", type: "array|string", required: false, description: "Record types list (for example A, MX, TXT)." },
  { name: "resolverPreset", type: "array|string", required: false, description: "Resolver preset filter." },
  { name: "customResolvers", type: "string", required: false, description: "Space/comma separated custom resolvers." },
  { name: "resolvers", type: "array", required: false, description: "Additional custom resolver list." }
]}
  responses={[
  {
    status: "200 OK",
    description: "DNS lookup completed.",
    content: {
      "target": "example.com",
      "generated_at": "2026-04-15T10:00:00+00:00",
      "recordTypes": ["A", "AAAA"],
      "resolver_count": 2,
      "resolvers": [
        { "id": "cloudflare_primary", "label": "Cloudflare (1.1.1.1)", "server": "1.1.1.1" },
        { "id": "google_primary", "label": "Google (8.8.8.8)", "server": "8.8.8.8" }
      ],
      "propagation": {
        "A": { "is_consistent": true, "distinct_statuses": 1, "distinct_answers": 1 }
      },
      "queries": {
        "A": [
          {
            "resolver_label": "Cloudflare (1.1.1.1)",
            "resolver": "1.1.1.1",
            "record_type": "A",
            "status": "NOERROR",
            "server": "1.1.1.1#53",
            "query_time_ms": 12,
            "answers": [{ "name": "example.com.", "ttl": 300, "class": "IN", "type": "A", "value": "93.184.216.34" }],
            "answer_signature": "A|93.184.216.34",
            "error": null
          }
        ]
      }
    }
  }
]}
/>


# Content Box



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Content Box API

The Content Box system provides a schematized storage layer for unstructured or custom-structured data. It allows organizations to define complex data models (Types) and instantiate them as managed content entities (Contents), suitable for blogs, product catalogs, and internal metadata repositories.

***

## Content Entity Management

Manage the lifecycle of data entries within your defined content structures.

### List Content Entities

Retrieve a paginated collection of content entities. Results can be filtered by state, content type, or via a full-text search query.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/contentbox/contents.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records to return (up to 100). Default is 50.", location: "query" },
  { name: "page", type: "integer", required: false, description: "The page index for pagination.", location: "query" },
  { name: "type_id", type: "string", required: false, description: "Filter by a specific Content Type ID.", location: "query" },
  { name: "state", type: "string", required: false, description: "Filter by lifecycle state (e.g., 'public', 'draft', 'archived').", location: "query" },
  { name: "search", type: "string", required: false, description: "Perform a text search across content titles and data fields.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Collection of content entities retrieved.",
    content: {
      "entities": "Contents",
      "count": 12,
      "per_page": 50,
      "elements": [
          {
              "id": "6768...",
              "type_id": "6751...",
              "title": "Q1 Product Launch",
              "state": "public",
              "data": {
                  "headline": "Introducing the 2026 Fleet",
                  "hero_image": "https://cdn.acme.com/img/l1.jpg",
                  "featured": true
              }
          }
      ]
    } 
  }
]}
/>

### Create Content Entity

Provision a new content entry. The `data` payload must adhere to the requirements of the associated `type_id`.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/contentbox/contents.json"
  body={{
  "content": {
      "title": "Annual Sustainability Report",
      "type_id": "675112233b498f30",
      "state": "draft",
      "data": {
          "period": "2025",
          "impact_score": 92
      }
  }
}}
  properties={[
  { name: "content.title", type: "string", required: true, description: "Internal-facing title for the content entry." },
  { name: "content.type_id", type: "string", required: true, description: "The unique identifier of the target Content Type schema." },
  { name: "content.state", type: "string", required: false, description: "Operational state (default: 'draft')." },
  { name: "content.data", type: "object", required: false, description: "Dictionary of custom fields defined in the type schema." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Content entity successfully provisioned.",
    content: { "id": "6768..." } 
  }
]}
/>

### Update Content Entity

Modify an existing content entry. This endpoint supports partial updates; only the fields provided in the `content` object will be modified.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/contentbox/contents/{contentId}.json"
  params={[
  { name: "contentId", type: "string", required: true, description: "The unique identifier of the content entry.", location: "path" }
]}
  body={{
  "content": {
      "state": "public",
      "data": {
          "revised_at": "2026-03-01T10:00:00Z"
      }
  }
}}
  properties={[
  { name: "content.title", type: "string", required: false, description: "Update the internal title." },
  { name: "content.state", type: "string", required: false, description: "Transition the lifecycle state." },
  { name: "content.data", type: "object", required: false, description: "Update specific keys within the data object." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Content entity successfully updated.",
    content: { "id": "6768...", "updated": true } 
  }
]}
/>

### Retrieve Content Entity

Fetch the full payload for a single content entry.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/contentbox/contents/{contentId}.json"
  params={[
  { name: "contentId", type: "string", required: true, description: "The unique identifier of the content entry.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Content entity retrieved.",
    content: { "id": "6768...", "title": "Q1 Product Launch", "state": "public", "data": {} } 
  },
  {
    status: "404 Not Found",
    description: "Content entry does not exist.",
    content: { "error": "Content Box not found" }
  }
]}
/>

### Decommission Content Entity

Permanently delete a content entry. This action is irreversible.

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/contentbox/contents/{contentId}.json"
  params={[
  { name: "contentId", type: "string", required: true, description: "The content identifier.", location: "path" }
]}
  responses={[
  { 
    status: "202 Accepted", 
    description: "Deletion request processed.",
    content: { "id": "6768...", "deleted": true } 
  }
]}
/>

***

## Content Type Modeling (Schema Definition)

Define and manage the structural blueprints that govern how content is stored and validated.

### List Content Types

Retrieve the catalog of all defined content schemas for your organization.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/contentbox/types.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Results per page.", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Collection of content type definitions.",
    content: { 
      "entities": "Types", 
      "count": 1, 
      "elements": [
        { "id": "6751...", "title": "Corporate Blog", "description": "Schema for official news", "fields": { "author": { "label": "Author", "type": "string" } } }
      ] 
    } 
  }
]}
/>

### Create Content Type

Define a new organizational schema. Specify the attributes and UI input types for each field in the model.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/contentbox/types.json"
  body={{ 
  "type": { 
    "title": "E-Commerce Product", 
    "description": "Standardized schema for catalog items.",
    "fields": {
      "sku": { "label": "SKU", "type": "string" },
      "price": { "label": "Unit Price", "type": "string" },
      "in_stock": { "label": "Inventory Status", "type": "checkbox" }
    }
  } 
}}
  properties={[
  { name: "type.title", type: "string", required: true, description: "Human-readable name for the schema." },
  { name: "type.description", type: "string", required: false, description: "Internal description of the schema's purpose." },
  { name: "type.fields", type: "object", required: true, description: "A map of field definitions (key -> {label, type})." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Content type definition created.",
    content: { "id": "6751...", "title": "E-Commerce Product" } 
  }
]}
/>

### Retrieve Type Definition

Fetch the precise structural definition for a specific content type.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/contentbox/types/{typeId}.json"
  params={[
  { name: "typeId", type: "string", required: true, description: "The unique identifier for the content type.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Full schema definition retrieved.",
    content: { "id": "6751...", "title": "Corporate Blog", "fields": {  } } 
  }
]}
/>

### Update Type Definition

Update metadata or fields for a specific content schema. When `fields` is provided, each field must include both `label` and `type` and use allowed input types.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/contentbox/types/{typeId}.json"
  params={[
  { name: "typeId", type: "string", required: true, description: "The unique identifier for the content type.", location: "path" }
]}
  body={{
  "type": {
    "title": "Corporate Blog",
    "description": "Schema for official company news",
    "fields": {
      "author": { "label": "Author", "type": "string" },
      "hero_image": { "label": "Hero Image", "type": "url" }
    }
  }
}}
  properties={[
  { name: "type.title", type: "string", required: false, description: "Updated schema title." },
  { name: "type.description", type: "string", required: false, description: "Updated schema description." },
  { name: "type.fields", type: "object", required: false, description: "Updated field map. Each field requires `label` and `type`." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Content type updated.",
    content: { "id": "6751...", "title": "Corporate Blog", "description": "Schema for official company news", "fields": {} } 
  },
  {
    status: "400 Bad Request",
    description: "Invalid fields payload or field type.",
    content: { "error": "Fields must be an associative array" }
  }
]}
/>


# Email Gateway



# Email Gateway API

The Email Gateway API manages template files and transactional sends.

***

## List Templates

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/email-gateway/templates.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index (starting from 1).", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Template list returned.",
    content: {
      "entities": "Email Templates",
      "count": 2,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "welcome.html",
          "endpoint": [
            {
              "type": "POST",
              "action": "Send email using this template",
              "url": "https://api.hub.donutwork.com/2026-02-01/email-gateway/welcome.html/send.json"
            }
          ]
        }
      ]
    }
  }
]}
/>

## Create Template

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/email-gateway/templates.json"
  body={{
  "template": {
    "id": "welcome.html",
    "content": "<h1>Hello FIRST_NAME</h1>"
  }
}}
  properties={[
  { name: "template.id", type: "string", required: true, description: "Template filename identifier." },
  { name: "template.content", type: "string", required: false, description: "Optional initial template content." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Template created.",
    content: { "id": "welcome.html" }
  },
  {
    status: "409 Conflict",
    description: "Template already exists.",
    content: { "error": "Template already exists" }
  }
]}
/>

## Get Template

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/email-gateway/templates/{templateId}.json"
  params={[
  { name: "templateId", type: "string", required: true, description: "Template identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Template returned.",
    content: {
      "id": "welcome.html",
      "content": "<h1>Hello FIRST_NAME</h1>"
    }
  },
  {
    status: "404 Not Found",
    description: "Template not found.",
    content: { "error": "Template not found" }
  }
]}
/>

## Update Template

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/email-gateway/templates/{templateId}.json"
  params={[
  { name: "templateId", type: "string", required: true, description: "Template identifier.", location: "path" }
]}
  body={{
  "template": {
    "content": "<h1>Hello FIRST_NAME</h1><p>Updated</p>"
  }
}}
  properties={[
  { name: "template.content", type: "string", required: true, description: "Template content to persist." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Template updated.",
    content: { "id": "welcome.html", "updated": true }
  }
]}
/>

## Delete Template

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/email-gateway/templates/{templateId}.json"
  params={[
  { name: "templateId", type: "string", required: true, description: "Template identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Template deleted.",
    content: { "id": "welcome.html", "deleted": true }
  }
]}
/>

## Preview Template

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/email-gateway/templates/{templateId}/preview.json"
  params={[
  { name: "templateId", type: "string", required: true, description: "Template identifier.", location: "path" }
]}
  body={{
  "preview": {
    "vars": {
      "first_name": "Alex"
    }
  }
}}
  properties={[
  { name: "preview.vars", type: "object", required: false, description: "Variables used for server-side placeholder rendering." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Rendered HTML preview returned.",
    content: {
      "template_id": "welcome.html",
      "html": "<h1>Hello Alex</h1>"
    }
  }
]}
/>

## Dispatch Transactional Email

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/email-gateway/{templateId}/send.json"
  params={[
  { name: "templateId", type: "string", required: true, description: "Template identifier.", location: "path" }
]}
  body={{
  "email": {
    "to": "recipient@example.com",
    "subject": "Operational Update",
    "from": "notifications@example.com",
    "cc": ["ops@example.com"],
    "vars": {
      "first_name": "Alex"
    },
    "attachments": [
      {
        "content": "SGVsbG8gd29ybGQ=",
        "filename": "summary.txt",
        "type": "text/plain"
      }
    ]
  }
}}
  properties={[
  { name: "email.to", type: "string", required: true, description: "Primary recipient email." },
  { name: "email.subject", type: "string", required: true, description: "Message subject." },
  { name: "email.from", type: "string", required: false, description: "Optional sender email from configured alternative senders." },
  { name: "email.cc", type: "array", required: false, description: "CC recipients." },
  { name: "email.bcc", type: "array", required: false, description: "BCC recipients." },
  { name: "email.vars", type: "object", required: false, description: "Template variables." },
  { name: "email.attachments", type: "array", required: false, description: "Attachments in base64 format." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Email accepted for delivery.",
    content: { "email": { "id": "msg_123" } }
  },
  {
    status: "404 Not Found",
    description: "Template not found.",
    content: { "error": "Template not found or empty" }
  }
]}
/>


# General



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# General API

The General API provides a set of infrastructure-level endpoints designed for environmental diagnostics and the retrieval of global static datasets. These tools are essential for verifying network reachability, inspecting client-server connection properties, and populating standardized geographic data across your application.

***

## Infrastructure Health (Ping)

A high-performance heartbeat endpoint used to verify that the DonutWork API gateway is operational and to measure basic network round-trip time (RTT).

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/ping.json"
  responses={[
  { 
    status: "200 OK", 
    description: "Gateway is responsive.",
    content: { 
      "status": "success", 
      "env": "production", 
      "RRT": "1.42 ms" 
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/ping.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    const heartbeat = await sdk.utils.ping();
    console.log(`System Status: ${heartbeat.status} (${heartbeat.RRT})`);
    ```
  </Tab>
</Tabs>

***

## Connection Diagnostics

Retrieve a detailed diagnostic profile of your current API session. This endpoint is instrumental for debugging network protocols, verifying IP whitelisting, and ensuring the correct API version is being targeted.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/connection.json"
  responses={[
  { 
    status: "200 OK", 
    description: "Diagnostics profile retrieved.",
    content: {
      "client": {
        "userAgent": "PostmanRuntime/7.43.0",
        "ips": { "ipv4": "192.168.1.1" }
      },
      "endpoint": {
        "apiVersion": "2026-02-01",
        "env": "production",
        "protocol": "HTTP2"
      }
    } 
  }
]}
/>

***

## Global Metadata (Countries)

Retrieve a comprehensive, standardized list of countries and their associated ISO 3166-1 alpha-2 codes. This dataset ensures data integrity when capturing geographic information in user profiles or billing addresses.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/countries/countries.json"
  responses={[
  { 
    status: "200 OK", 
    description: "Global country directory retrieved.",
    content: [
      { "code": "US", "name": "United States" },
      { "code": "GB", "name": "United Kingdom" },
      { "code": "IT", "name": "Italy" },
      { "code": "DE", "name": "Germany" },
      { "code": "FR", "name": "France" }
    ] 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/countries/countries.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    const countryList = await sdk.utils.listCountries();
    const italy = countryList.find(c => c.code === 'IT');
    console.log(`Country Name: ${italy.name}`);
    ```
  </Tab>
</Tabs>


# GeoIP (Location Services)



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# GeoIP API

The GeoIP API enables the resolution of IPv4 addresses into rich geographical and jurisdictional datasets. Beyond simple location coordinates, this service provides essential metadata—including currency systems, telecommunication prefixes, and linguistic profiles—enabling automated tax compliance (VAT/GST), regional content personalization, and fraud detection through threat-level auditing.

***

## Intelligence Resolution (Geo-Location)

Retrieve the full intelligence profile for a specific IPv4 address. This includes Autonomous System (AS) data, high-level geolocation, and localized jurisdictional metadata.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/geoip/ip.json"
  params={[
  { 
    name: "ip", 
    type: "string", 
    required: true, 
    description: "The targeted IPv4 address for resolution (e.g., 8.8.8.8).",
    location: "query"
  }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "IP intelligence profile successfully resolved.",
    content: {
      "requested_ip": "8.8.8.8",
      "geolocation": {
          "as_domain": "google.com",
          "as_name": "Google LLC",
          "asn": "AS15169",
          "continent": "NA",
          "country": "US",
          "country_name": "United States"
      },
      "country_metadata": {
          "name": "United States",
          "phone": [1],
          "capital": "Washington D.C.",
          "currency": ["USD", "USN", "USS"],
          "languages": ["en"]
      },
      "threats": ["proxy", "vpn"],
      "_credits": "IP address data powered by https://ipinfo.io"
    } 
  },
  { 
    status: "400 Bad Request", 
    description: "The provided IP address is malformed or resolution failed.",
    content: { "error": "Unable to get info for this IP Address" } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/geoip/ip.json?ip=8.8.8.8' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    const ipAddress = "8.8.8.8";
    try {
      const data = await sdk.geolocation.resolve(ipAddress);
      console.dir(data, { depth: null });
    } catch (error) {
      console.error(`Resolution Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **Business Context:** Use this data to automate tax profile selection for checkout flows or to enforce regional compliance for regulated digital services.
</Callout>


# Identity Provider (IDP) & MFA



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Identity Provider (IDP) API

The Identity Provider (IDP) service centralizes user identity management and provides robust secondary authentication layers. It allows organizations to link external user identifiers to a secure, managed identity capable of Multi-Factor Authentication (MFA) via Time-based One-Time Passwords (TOTP) and advanced risk assessment (Sentinel).

***

## Identity Management

### Provision External User

Provision a new managed identity within the IDP ecosystem. This creates a security context linked to your platform's internal `external_id`.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/idp/user.json"
  body={{
  "user": {
    "external_id": "ORG_USR_9921_AFG"
  }
}}
  properties={[
  { name: "user.external_id", type: "string", required: true, description: "Your system's unique identifier for the user (e.g., UUID or DB ID)." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "User identity successfully provisioned.",
    content: {
      "user": {
          "id": "6908bffd...",
          "external_id": "ORG_USR_9921_AFG",
          "status": "active"
      }
    } 
  },
  { 
    status: "409 Conflict", 
    description: "Identity already exists for the specified external_id.",
    content: { "error": "User with this external_id already exists for this company" } 
  }
]}
/>

### Retrieve Identity Profile

Fetch the security profile for a specific user. This includes authentication capabilities (MFA status), operational status (locked/active), and audit metadata.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/idp/{externalUserId}.json"
  params={[
  { name: "externalUserId", type: "string", required: true, description: "The identifier provided during provisioning.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Identity profile retrieved.",
    content: {
      "id": "6908...",
      "external_id": "ORG_USR_9921_AFG",
      "status": "active",
      "has_otp": true,
      "has_passkeys": false,
      "is_locked": false,
      "failed_attempts": 0,
      "saas_client_id": "67c9..."
    } 
  }
]}
/>

***

## Multi-Factor Authentication (MFA)

### Configuration of TOTP Secret

Generate a new TOTP secret and QR code payload to enable secondary authentication. Scanning this payload into an authenticator application (e.g., Microsoft/Google Authenticator) completes the setup.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/idp/{externalUserId}/otp.json"
  params={[
  { name: "externalUserId", type: "string", required: true, description: "The user identifier.", location: "path" }
]}
  body={{
  "otp": {
    "issuer_name": "Acme Enterprise",
    "account_name": "alexander@enterprise.com"
  }
}}
  properties={[
  { name: "otp.issuer_name", type: "string", required: true, description: "The organization name displayed in the authenticator app." },
  { name: "otp.account_name", type: "string", required: true, description: "The specific account identifier displayed in the app." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "New MFA secret successfully generated.",
    content: {
      "user": {
          "external_id": "ORG_USR_9921_AFG",
          "new_otp_secret": "REDACTED_OTP_SECRET",
          "qrcode_payload": "otpauth://totp/Acme+Enterprise:alexander%40enterprise.com?secret=REDACTED_OTP_SECRET&issuer=Acme+Enterprise",
          "is_setup_complete": true
      }
    } 
  }
]}
/>

### Verify Authentication Code

Validate a 6-digit TOTP code (or a one-time backup code) to finalize the authentication process.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/idp/otp/verify.json"
  body={{
  "otp": {
    "id": "ORG_USR_9921_AFG",
    "code": "552192"
  }
}}
  properties={[
  { name: "otp.id", type: "string", required: true, description: "The unique external user identifier." },
  { name: "otp.code", type: "string", required: true, description: "The 6-digit code or numeric backup code." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Authentication successful.",
    content: { "status": "success", "id": "ORG_USR_9921_AFG", "message": "OTP verified successfully." } 
  },
  { 
    status: "401 Unauthorized", 
    description: "Invalid credentials or code expired.",
    content: { "error": "Invalid credentials or access denied" } 
  }
]}
/>

### Provision Backup Codes

Generate a collection of single-use backup codes. These allow users to regain access if the primary MFA device is unavailable.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/idp/{externalUserId}/backupcodes.json"
  params={[
  { name: "externalUserId", type: "string", required: true, description: "The user identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Set of 10 backup codes generated.",
    content: {
      "user": {
          "id": "ORG_USR_9921_AFG",
          "backupCodes": ["ABCD-1234", "EFGH-5678", "..."]
      }
    } 
  }
]}
/>

***

## Sentinel Risk Assessment

Sentinel provides a sophisticated analytical layer for evaluating authentication risk in real-time.

### Analyze Session Integrity (Discover)

Submit session metadata to Sentinel to perform a risk assessment based on behavioral patterns, network reputation, and environmental context.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/sentinel/verify.json"
  body={{
  "sentinel": {
    "id": "6908bffd...",
    "context": { "ip": "1.1.1.1", "ua": "EnterpriseAgent/1.0" }
  }
}}
  properties={[
  { name: "sentinel.id", type: "string", required: true, description: "External user identifier for the risk evaluation." },
  { name: "sentinel.context.ip", type: "string", required: true, description: "Source IP address of the session." },
  { name: "sentinel.context.ua", type: "string", required: true, description: "User-Agent value for the session." },
  { name: "sentinel.context.user_id", type: "string", required: false, description: "Optional explicit user identifier override." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Risk assessment completed.",
    content: { "status": "authorized", "risk_score": 0.05, "recommendation": "allow" } 
  },
  { 
    status: "403 Forbidden", 
    description: "High-risk indicators detected.",
    content: { "error": "High risk detection", "risk_score": 0.95 } 
  }
]}
/>


# API Reference



import { 
  ShieldCheck, 
  Key, 
  Mail, 
  MapPin, 
  Link, 
  Percent, 
  Share2, 
  Box,
  Layers,
  Zap
} from 'lucide-react';

Initialize your integration with our unified headless architecture. Designed to handle millions of requests with enterprise-grade latency and deterministic execution.

***

## Core Infrastructure

<div className="grid grid-cols-1 md:grid-cols-2 gap-6 mt-10">
  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#7ABA23]/50 transition-all group">
    <ShieldCheck size={40} className="text-[#7ABA23] mb-4" />

    ### Identity Provider (IDP)

    Manage user identities with native MFA and TOTP support.
    [Explore IDP →](/en/docs/api/idp)
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#FECC55]/50 transition-all group">
    <Key size={40} className="text-[#FECC55] mb-4" />

    ### Key Management Service (KMS)

    Store and reveal sensitive credentials with strict IP whitelisting.
    [Explore KMS →](/en/docs/api/kms)
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#7ABA23]/50 transition-all group">
    <Mail size={40} className="text-[#7ABA23] mb-4" />

    ### Email Gateway

    **Transactional Intelligence.** Trigger localized templates with dynamic variable injection. Scale communications via high-deliverability routes.
    [Explore Email →](/en/docs/api/email-gateway)
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#FECC55]/50 transition-all group">
    <MapPin size={40} className="text-[#FECC55] mb-4" />

    ### GeoIP & Metadata

    **Localized Intelligence.** Resolve IPv4 to precise geographic data and rich country metadata for automated compliance and tax logic.
    [Explore GeoIP →](/en/docs/api/geo-ip)
  </div>
</div>

***

## Growth & Operations

<div className="grid grid-cols-1 md:grid-cols-5 gap-4">
  <div className="p-6 rounded-2xl border border-white/5 bg-[#0D0D0D] hover:bg-white/5 transition-all">
    <Share2 size={24} className="text-[#7ABA23] mb-3" />

    #### Share Secrets

    One-time encrypted payload sharing with automatic purge.
  </div>

  <div className="p-6 rounded-2xl border border-white/5 bg-[#0D0D0D] hover:bg-white/5 transition-all">
    <Link size={24} className="text-[#7ABA23] mb-3" />

    #### Shortlinks

    URL redirection with traffic attribution.
  </div>

  <div className="p-6 rounded-2xl border border-white/5 bg-[#0D0D0D] hover:bg-white/5 transition-all">
    <Percent size={24} className="text-[#FECC55] mb-3" />

    #### Taxes

    VAT and sales tax logic for billing compliance.
  </div>

  <div className="p-6 rounded-2xl border border-white/5 bg-[#0D0D0D] hover:bg-white/5 transition-all">
    <Zap size={24} className="text-[#FECC55] mb-3" />

    #### DNS

    Multi-resolver DNS diagnostics and propagation checks.
  </div>

  <div className="p-6 rounded-2xl border border-white/5 bg-[#0D0D0D] hover:bg-white/5 transition-all">
    <Key size={24} className="text-[#7ABA23] mb-3" />

    #### Mobile Push

    Register and revoke iOS push tokens for mobile clients.
  </div>
</div>

***

## Enterprise Orchestration

<div className="grid grid-cols-1 md:grid-cols-2 gap-6">
  <div className="group relative p-8 rounded-[2.5rem] border border-[#7ABA23]/20 bg-gradient-to-br from-[#7ABA23]/5 to-transparent flex flex-col items-start gap-4">
    <Box size={40} className="text-[#7ABA23]" />

    ### Content Box

    Model custom data structures and serve them via a unified JSON API.
    [Explore Content Box →](/en/docs/api/dynamic-content)
  </div>

  <div className="group relative p-8 rounded-[2.5rem] border border-[#FECC55]/20 bg-gradient-to-br from-[#FECC55]/5 to-transparent flex flex-col items-start gap-4">
    <Layers size={40} className="text-[#FECC55]" />

    ### Workflow

    Automate business logic with stage-based auditing and dynamic payload injection.
    [Explore Workflow →](/en/docs/api/workflow)
  </div>
</div>

***

### Integration Architecture

| Metric              | Specification               |
| :------------------ | :-------------------------- |
| **Uptime SLA**      | 99.99% Enterprise Tier      |
| **Auth Protocol**   | Bearer Token (Stateless)    |
| **Default Version** | `2026-02-01`                |
| **Execution**       | Deterministic / Low Latency |


# Integrations & Capabilities



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Integrations & Capabilities API

The Integrations API provides a unified abstraction layer for extending the DonutWork core platform with third-party application functionalites. By declaring "capabilities," applications can expose their own endpoints as managed actions within the DonutWork ecosystem, allowing for seamless cross-platform orchestration, automated authorization handling (app-to-app), and centralized audit logging.

***

## Lifecycle Management

### Audit Active Integrations

Retrieve a paginated directory of all integrations currently authorized for your organization. This includes high-level connectivity status and identification handlers for each service.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/integrations.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Integration directory successfully retrieved.",
    content: {
      "entities": "Integration",
      "count": 1,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "6908bffd...",
          "handler": "STRIPE_CONNECT",
          "name": "Stripe Global Payments",
          "status": "connected"
        }
      ]
    } 
  }
]}
/>

### Declare Functional Capabilities

Register or update the specific actions (capabilities) that your application exposes. This declaration defines the input requirements and contract for each action, enabling DonutWork to proxy requests to your service securely.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/integrations.json"
  body={{
  "app_token": "ext_auth_token_9921",
  "capabilities": [
    { 
      "action": "SYNC_INVENTORY", 
      "method": "POST", 
      "endpoint": "https://api.myapp.com/v1/sync",
      "inputs": [
        { "name": "sku", "type": "string", "required": true },
        { "name": "quantity", "type": "number", "required": true }
      ]
    }
  ]
}}
  properties={[
  { name: "capabilities", type: "array", required: true, description: "Definition list of actions and their schema." },
  { name: "app_token", type: "string", required: false, description: "Authorization token to be used when DonutWork calls your service." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Capabilities successfully registered.",
    content: { 
      "success": true, 
      "message": "Capabilities declared successfully for MY_CUSTOM_APP",
      "app_handler": "MY_CUSTOM_APP",
      "actions_count": 1
    } 
  }
]}
/>

***

## Resource Discovery

### Retrieve Specific Integration

Fetch the full configuration, permission sets, and connectivity health for a specific integration.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/integrations/{appHandler}.json"
  params={[
  { name: "appHandler", type: "string", required: true, description: "The unique string identifier for the integration.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Detailed integration profile retrieved.",
    content: { 
      "id": "6908...",
      "handler": "SLACK_ENT", 
      "status": "connected", 
      "actions": [
        { "name": "SEND_MESSAGE", "method": "POST" }
      ],
      "metadata": { "workspace": "AcmeHQ" }
    } 
  }
]}
/>

***

## Execution (Capability Proxy)

### Dispatch Delegated Action

Execute a capability on a remote integration. DonutWork acts as a secure proxy, handling authorization headers and validating input schemas before relaying the request to the target service.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/integrations/{appHandler}/{appAction}.json"
  params={[
  { name: "appHandler", type: "string", required: true, description: "The integration identifier.", location: "path" },
  { name: "appAction", type: "string", required: true, description: "The capability to execute.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Action executed and external response relayed.",
    content: { 
      "success": true, 
      "integration": "SLACK_ENT", 
      "action": "SEND_MESSAGE",
      "external_status": 200,
      "response": { "ok": true, "ts": "123456789.0001" }
    } 
  }
]}
/>

The request payload for action dispatch is dynamic. Required body fields are validated at runtime using the integration capability declaration (`capabilities[].inputs[]` with `required: true`).

### Read Delegated Action

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/integrations/{appHandler}/{appAction}.json"
  params={[
  { name: "appHandler", type: "string", required: true, description: "The integration identifier.", location: "path" },
  { name: "appAction", type: "string", required: true, description: "The capability to execute.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Action executed using GET forwarding.",
    content: { "success": true, "integration": "SLACK_ENT", "action": "GET_CHANNEL_INFO", "external_status": 200, "response": {} } 
  }
]}
/>

### Update Delegated Action

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/integrations/{appHandler}/{appAction}.json"
  params={[
  { name: "appHandler", type: "string", required: true, description: "The integration identifier.", location: "path" },
  { name: "appAction", type: "string", required: true, description: "The capability to execute.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Action executed using PUT forwarding.",
    content: { "success": true, "integration": "SLACK_ENT", "action": "UPSERT_TEMPLATE", "external_status": 200, "response": {} } 
  }
]}
/>

### Delete Delegated Action

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/integrations/{appHandler}/{appAction}.json"
  params={[
  { name: "appHandler", type: "string", required: true, description: "The integration identifier.", location: "path" },
  { name: "appAction", type: "string", required: true, description: "The capability to execute.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Action executed using DELETE forwarding.",
    content: { "success": true, "integration": "SLACK_ENT", "action": "DELETE_MESSAGE", "external_status": 200, "response": {} } 
  }
]}
/>

### Emit Integration Event

Emit an application-scoped event so workflows and event listeners can react to integration activity.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/integrations/{appHandler}/events/{eventName}/emit.json"
  params={[
  { name: "appHandler", type: "string", required: true, description: "Application handler associated with the integration.", location: "path" },
  { name: "eventName", type: "string", required: true, description: "Declared event name in `<AppHandler>.<EventName>` format.", location: "path" }
]}
  body={{
  "metadata": {
    "message_id": "msg_001",
    "status": "sent"
  },
  "entity_id": "SLACK_ENT"
}}
  properties={[
  { name: "metadata", type: "object", required: false, description: "Event payload metadata object." },
  { name: "entity_id", type: "string", required: false, description: "Entity identifier. If omitted, the app handler is used." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Event accepted and dispatched.",
    content: { "success": true, "app_handler": "SLACK", "event": "Slack.MESSAGE_SENT", "queued_workflows": 1 } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request POST \
    'https://api.hub.donutwork.com/2026-02-01/integrations/SLACK/SEND_MSG.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN' \
    --header 'Content-Type: application/json' \
    --data-raw '{"message": "Automated Deployment Completed"}'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    const payload = { message: "System Alert: Resource threshold reached." };
    try {
      const result = await sdk.integrations.dispatch("SLACK", "SEND_MSG", payload);
      console.log(`Action Result: ${result.success} (Status: ${result.external_status})`);
    } catch (error) {
      console.error(`Dispatch Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>


# Job Runner



# Job Runner API

## List Jobs

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/job-runner.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Records per page (default 50, max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page number starting from 1.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Job runner list returned.",
    content: {
      "entities": "JobRunner",
      "count": 1,
      "per_page": 50,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "681f10...",
          "title": "Sync CRM Contacts",
          "method": "POST",
          "url": "https://api.partner.com/sync",
          "content_type": "application/json",
          "has_body": true,
          "schedulation": ["08:00", "14:30"]
        }
      ]
    }
  }
]}
/>

## Create Job

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/job-runner.json"
  body={{
  "jobrunner": {
    "title": "Sync CRM Contacts",
    "method": "POST",
    "url": "https://api.partner.com/sync",
    "content_type": "application/json",
    "body": "{\"scope\":\"daily\"}",
    "schedulation": ["08:00", "14:30"]
  }
}}
  properties={[
  { name: "jobrunner", type: "object", required: true, description: "Job runner configuration payload." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Job runner created.",
    content: {
      "id": "681f10...",
      "created": true
    }
  },
  {
    status: "422 Unprocessable Entity",
    description: "Validation error on payload.",
    content: { "error": "Invalid schedulation time \"24:30\". Use HH:mm format" }
  }
]}
/>

## Run Job

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/job-runner/{jobRunnerId}/run.json"
  params={[
  { name: "jobRunnerId", type: "string", required: true, description: "Job runner identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Job execution completed.",
    content: {
      "job_runner_id": "681f10...",
      "status": "success",
      "headers": ["HTTP/1.1 200 OK"],
      "response": "{\"ok\":true}",
      "ms": 122.45
    }
  }
]}
/>

## Delete Job

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/job-runner/{jobRunnerId}.json"
  params={[
  { name: "jobRunnerId", type: "string", required: true, description: "Job runner identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Job runner deleted.",
    content: {
      "id": "681f10...",
      "deleted": true
    }
  }
]}
/>


# Key Management Service (KMS)



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Key Management Service (KMS) API

The Key Management Service (KMS) provides a hardened environment for the storage and lifecycle management of sensitive credentials, such as third-party API keys, service accounts, and cryptographic tokens. By using KMS, organizations can eliminate the risk of hardcoded secrets within source code, instead retrieving them dynamically via secure, audited endpoints protected by strict IP-based whitelisting.

***

## Secret Management

### Audit KMS Inventory

Retrieve a paginated directory of all KMS secret handlers associated with your organization. This endpoint provides administrative metadata and is used for secret discovery; it does **not** expose the underlying secret values.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/kms.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index for pagination.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Secret inventory successfully retrieved.",
    content: {
      "entities": "KMSEntry",
      "count": 12,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "6835c2cd...",
          "name": "Production AWS S3 Access",
          "handler": "aws-s3-prod-credentials"
        }
      ]
    } 
  }
]}
/>

### Retrieve Secret Configuration

Fetch the detailed metadata and operational configuration for a unique KMS handler. This includes the registered IP whitelist and custom properties defined for the secret.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/kms/{handler}.json"
  params={[
  { name: "handler", type: "string", required: true, description: "The unique slug/identifier of the KMS entry.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Secret configuration retrieved.",
    content: {
      "id": "6835c2cd...",
      "name": "Production AWS S3 Access",
      "handler": "aws-s3-prod-credentials",
      "whitelist": ["52.1.2.3", "54.0.0.1"],
      "properties": { "region": "us-east-1" }
    } 
  },
  { 
    status: "404 Not Found", 
    description: "The specified handler does not exist in the vault.",
    content: { "error": "This KMSEntry does not exist" } 
  }
]}
/>

***

## Secret Consumption

### Decrypt & Reveal Secret

Securely decrypt and reveal the underlying secret content. Access to this endpoint is strictly enforced via IP-based whitelisting and results in an immediate audit entry. Use this endpoint only within backend environments to dynamically inject credentials.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/kms/reveal/{handler}.json"
  params={[
  { name: "handler", type: "string", required: true, description: "The KMS handler identifying the secret to reveal.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Secret successfully decrypted and returned.",
    content: { "content": "EXAMPLE_ACCESS_KEY_REDACTED" } 
  },
  { 
    status: "403 Forbidden", 
    description: "Requesting IP is not in the authorized whitelist or permissions are insufficient.",
    content: { "error": "Unauthorized to reveal this KMS Entry" } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/kms/reveal/aws-s3-prod-credentials.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    const handler = "aws-s3-prod-credentials";
    try {
      const secret = await sdk.kms.reveal(handler);
      console.log(`Resource Access Granted. Payload: ${secret.content}`);
    } catch (error) {
      console.error(`Vault Access Denied: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

<Callout type="warning">
  **Security Audit:** Every call to the `reveal` endpoint is logged with the requesting IP, User-Agent, and timestamp. Ensure your infrastructure IPs are properly whitelisted in the KMS configuration to avoid 403 authorization failures.
</Callout>


# Media Library



# Media Library API

## Strategy

For large files, use presigned direct upload:

1. Request upload link from API.
2. Upload file directly to storage with `PUT`.
3. Use media list or download-link APIs for retrieval flow.

## List Files

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/media-library/files.json"
  params={[
  { name: "page", type: "integer", required: false, description: "Page number starting from 1.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Media file list returned.",
    content: {
      "entities": "MediaLibraryFile",
      "count": 1,
      "per_page": 60,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "filename": "invoice-apr-2026.pdf",
          "size": 58211,
          "etag": "15d6a30e7a6f0d...",
          "last_modified": "2026-04-20T08:55:10+00:00"
        }
      ]
    }
  }
]}
/>

## Create Upload Link

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/media-library/files/upload-link.json"
  body={{
  "file": {
    "filename": "invoice-apr-2026.pdf",
    "content_type": "application/pdf",
    "size_bytes": 58211
  }
}}
  properties={[
  { name: "file", type: "object", required: true, description: "Upload target metadata (filename/content type/optional size)." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Presigned direct upload link generated.",
    content: {
      "strategy": "direct_presigned_put",
      "file": {
        "filename": "invoice-apr-2026.pdf",
        "content_type": "application/pdf",
        "max_size_bytes": 524288000
      },
      "upload": {
        "method": "PUT",
        "url": "https://storage.example.com/prod-.../invoice-apr-2026.pdf?...",
        "expires_in": 1200,
        "headers": {
          "Content-Type": "application/pdf"
        }
      }
    }
  }
]}
/>

## Upload File (Fallback)

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/media-library/files.json"
  body={{
  "file": {
    "filename": "small-note.txt",
    "content_type": "text/plain",
    "content_base64": "U2NoZWR1bGVkIG5vdGUgZnJvbSBBUEk="
  }
}}
  properties={[
  { name: "file", type: "object", required: true, description: "Fallback upload payload using base64 content." }
]}
  responses={[
  {
    status: "201 Created",
    description: "File uploaded.",
    content: {
      "filename": "small-note.txt",
      "size": 24,
      "uploaded": true
    }
  }
]}
/>

## Create Download Link

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/media-library/files/download-link.json"
  body={{
  "file": {
    "filename": "invoice-apr-2026.pdf"
  }
}}
  properties={[
  { name: "file", type: "object", required: true, description: "Target file descriptor for secure download URL generation." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Download link generated.",
    content: {
      "filename": "invoice-apr-2026.pdf",
      "url": "https://app.example.com/file-download/download?file=..."
    }
  }
]}
/>


# Mobile Push Tokens



# Mobile Push Tokens API

These endpoints are available only when using a mobile-scoped API key.

## Save Device Push Token

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/mobile/push-token.json"
  body={{
  "device": {
    "device_id": "ios_device_001",
    "push_token": "f6ad7d6f0a3b82d91fd89e88d4d4c6f3e0f9a7f6",
    "platform": "ios",
    "app_version": "1.2.3",
    "environment": "production"
  }
}}
  properties={[
  { name: "device.device_id", type: "string", required: true, description: "Device identifier (8-128 chars, allowed: letters, numbers, . _ : -)." },
  { name: "device.push_token", type: "string", required: true, description: "APNs push token (20-1024 chars)." },
  { name: "device.platform", type: "string", required: false, description: "Platform value. Only `ios` is accepted." },
  { name: "device.app_version", type: "string", required: false, description: "Client application version." },
  { name: "device.environment", type: "string", required: false, description: "Push environment (`sandbox` or `production`)." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Push token saved or updated.",
    content: {
      "status": "success",
      "message": "Push token saved",
      "device": {
        "device_id": "ios_device_001",
        "platform": "ios",
        "environment": "production"
      }
    }
  },
  {
    status: "403 Forbidden",
    description: "API key is not mobile-scoped.",
    content: { "error": "Mobile API key required for this endpoint" }
  }
]}
/>

## Delete Device Push Token

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/mobile/push-token.json"
  params={[
  { name: "device_id", type: "string", required: false, description: "Device identifier when passed via query string. Required if not present in `device.device_id` body.", location: "query" }
]}
  body={{
  "device": {
    "device_id": "ios_device_001"
  }
}}
  properties={[
  { name: "device.device_id", type: "string", required: false, description: "Device identifier when passed via JSON body. Required if not present in `device_id` query param." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Push token deleted or already absent.",
    content: {
      "status": "success",
      "message": "Push token removed",
      "deleted": true,
      "device_id": "ios_device_001"
    }
  },
  {
    status: "400 Bad Request",
    description: "Device identifier missing or invalid.",
    content: { "error": "Missing required field: device_id" }
  }
]}
/>


# Newsletter Campaigns



# Newsletter API

The Newsletter API exposes campaign lifecycle, recipient synchronization, dispatch queue controls, analytics, and suppression list management.

***

## List Newsletter Campaigns

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/newsletters.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index (starting from 1).", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Newsletter list returned.",
    content: {
      "entities": "Newsletter",
      "count": 1,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "672489...",
          "title": "Launch Campaign",
          "subject": "New release",
          "template_id": "welcome.html",
          "total_recipients": 210,
          "status": "draft",
          "created_at": 1704067200
        }
      ]
    }
  }
]}
/>

## Create Newsletter Campaign

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/newsletters.json"
  body={{
  "newsletter": {
    "title": "Launch Campaign",
    "subject": "New release",
    "template_id": "welcome.html",
    "contact_ids": ["cust_1", "cust_2"]
  }
}}
  properties={[
  { name: "newsletter.title", type: "string", required: true, description: "Internal campaign name." },
  { name: "newsletter.subject", type: "string", required: true, description: "Subject line used during sending." },
  { name: "newsletter.template_id", type: "string", required: true, description: "Template filename to use for this campaign." },
  { name: "newsletter.contact_ids", type: "array", required: false, description: "Optional initial recipients list." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Newsletter draft created.",
    content: {
      "id": "672489...",
      "status": "draft",
      "skipped_suppressed": 0,
      "skipped_not_found": 1
    }
  }
]}
/>

## Retrieve Campaign Details

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Campaign details returned.",
    content: {
      "id": "672489...",
      "title": "Launch Campaign",
      "subject": "New release",
      "template_id": "welcome.html",
      "total_recipients": 210,
      "status": "queued",
      "scheduled_at": null,
      "created_at": 1704067200
    }
  }
]}
/>

## Update Campaign Metadata

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" }
]}
  body={{
  "newsletter": {
    "title": "Launch Campaign v2",
    "subject": "Release update",
    "template_id": "welcome-v2.html"
  }
}}
  properties={[
  { name: "newsletter.title", type: "string", required: false, description: "Updated title. Allowed only in draft status." },
  { name: "newsletter.subject", type: "string", required: false, description: "Updated subject. Allowed only in draft status." },
  { name: "newsletter.template_id", type: "string", required: false, description: "Updated template id. Allowed only in draft status." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Campaign metadata updated.",
    content: {
      "id": "672489...",
      "title": "Launch Campaign v2",
      "subject": "Release update",
      "template_id": "welcome-v2.html",
      "total_recipients": 210,
      "status": "draft",
      "scheduled_at": null,
      "created_at": 1704067200
    }
  },
  {
    status: "409 Conflict",
    description: "Campaign is not in draft status.",
    content: { "error": "Only newsletters in draft status can be updated" }
  }
]}
/>

## Delete Campaign

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Campaign and related queue entries deleted.",
    content: { "id": "672489...", "deleted": true }
  }
]}
/>

## Get Campaign Recipients Snapshot

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}/recipients.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" },
  { name: "search", type: "string", required: false, description: "Optional search filter by customer name or email.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Recipients snapshot returned.",
    content: {
      "newsletter_status": "draft",
      "selected_ids": ["cust_1", "cust_2"],
      "all_customers": [
        {
          "id": "cust_1",
          "name": "Alex Doe",
          "email": "alex@example.com",
          "tags": ["beta"],
          "subscription_count": 1,
          "has_consent": true,
          "is_suppressed": false
        }
      ]
    }
  }
]}
/>

## Set Campaign Recipients

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}/recipients.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" }
]}
  body={{
  "newsletter": {
    "contact_ids": ["cust_1", "cust_2", "cust_3"]
  }
}}
  properties={[
  { name: "newsletter.contact_ids", type: "array", required: true, description: "Recipient customer IDs to store on the campaign." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Recipients synchronized.",
    content: {
      "newsletter_id": "672489...",
      "saved_recipients": 2,
      "skipped_suppressed": 1,
      "skipped_not_found": 0
    }
  }
]}
/>

## Queue Campaign Dispatch

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}/queue.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Campaign queued for sending.",
    content: {
      "newsletter_id": "672489...",
      "status": "queued",
      "queued_recipients": 150,
      "skipped_suppressed": 0,
      "skipped_not_found": 0
    }
  },
  {
    status: "409 Conflict",
    description: "Invalid state or usage limit reached.",
    content: { "error": "This newsletter is already queued and cannot be queued again" }
  }
]}
/>

## Send Test Email

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}/test.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" }
]}
  body={{
  "newsletter": {
    "test_email": "qa@example.com"
  }
}}
  properties={[
  { name: "newsletter.test_email", type: "string", required: true, description: "Target email for test send." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Test email sent.",
    content: {
      "newsletter_id": "672489...",
      "test_email": "qa@example.com",
      "sent": true
    }
  }
]}
/>

## Get Campaign Stats

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/newsletters/{newsletterId}/stats.json"
  params={[
  { name: "newsletterId", type: "string", required: true, description: "Newsletter identifier.", location: "path" },
  { name: "failure_limit", type: "integer", required: false, description: "Maximum failed/skipped items to include.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Campaign stats returned.",
    content: {
      "newsletter": {
        "id": "672489...",
        "title": "Launch Campaign",
        "subject": "New release",
        "template_id": "welcome.html",
        "total_recipients": 150,
        "status": "queued",
        "scheduled_at": null,
        "created_at": 1704067200
      },
      "stats": {
        "pending": 12,
        "processing": 3,
        "sent": 120,
        "failed": 10,
        "skipped": 5,
        "total": 150
      },
      "progress": {
        "processed": 135,
        "total": 150,
        "overall_progress": 90,
        "delivery_rate": 80
      },
      "failures": []
    }
  }
]}
/>

***

## Suppression List

### List Unsubscribes

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/newsletters/unsubscribes.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Suppression list returned.",
    content: {
      "entities": "Unsubscribes",
      "count": 1,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "email": "user@example.com",
          "reason": "Manual unsubscribe via API",
          "unsubscribed_at": 1704067200
        }
      ]
    }
  }
]}
/>

### Add Unsubscribe

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/newsletters/unsubscribes.json"
  body={{
  "unsubscribe": {
    "email": "user@example.com",
    "reason": "Support request"
  }
}}
  properties={[
  { name: "unsubscribe.email", type: "string", required: true, description: "Email to suppress." },
  { name: "unsubscribe.reason", type: "string", required: false, description: "Optional reason for audit trail." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Email added to suppression list.",
    content: {
      "email": "user@example.com",
      "unsubscribed": true
    }
  }
]}
/>

### Resubscribe Email

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/newsletters/unsubscribes/resubscribe.json"
  body={{
  "unsubscribe": {
    "email": "user@example.com"
  }
}}
  properties={[
  { name: "unsubscribe.email", type: "string", required: true, description: "Email to remove from suppression list." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Email removed from suppression list.",
    content: {
      "email": "user@example.com",
      "resubscribed": true
    }
  },
  {
    status: "404 Not Found",
    description: "Email not found in suppression list.",
    content: { "error": "Email not found in suppression list" }
  }
]}
/>


# Partner Groups



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Partner Groups API

Partner Groups provide an automated logic layer for categorizing partners and enforcing organization-wide distribution policies. These groups define rules that govern revenue sharing percentages, time-based commission tiers, and performance-driven upgrades based on total Lifetime Value (LTV) or charge volume.

***

## Group Inventory

### List Partner Groups

Retrieve a paginated directory of all defined Partner Groups. This directory contains the high-level metadata and administrative identifiers for each group.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/groups.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Partner group directory successfully retrieved.",
    content: {
      "entities": "PartnerGroup",
      "count": 4,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
          {
            "id": "68f76721...",
            "name": "Standard Managed Agency",
            "external_id": "P-GROUP-ADVANCED",
            "default": true
          }
      ]
    } 
  }
]}
/>

### Retrieve Group Configuration & Rules

Fetch the comprehensive configuration for a specific governance group, including the active rules engine parameters that define commission logic.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/groups/{groupId}.json"
  params={[
  { name: "groupId", type: "string", required: true, description: "The unique identifier of the partner group.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Group configuration and rules engine definition retrieved.",
    content: {
      "id": "68f76721...",
      "name": "Standard Managed Agency",
      "external_id": "P-GROUP-ADVANCED",
      "rules": [
          {
              "type": "new_customer_time_tier",
              "max_months": 12,
              "percentage": 50,
              "description": "Introductory 12-month high-incentive tier."
          },
          {
              "type": "recurring",
              "percentage": 15,
              "description": "Standard recurring commission (post-time-tier)."
          },
          {
              "type": "partner_ltv_upgrade",
              "min_ltv_total": 10000,
              "upgrade_percentage": 5,
              "description": "LTV Performance Bonus (Threshold: 10,000€)."
          }
      ],
      "tags": "managed,high-volume",
      "description": "Default group for high-performance managed agencies."
    } 
  }
]}
/>

***

## Group Lifecycle Management

### Create Partner Group

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/partners/groups.json"
  body={{
  "partnerGroup": {
    "name": "Performance Agencies",
    "description": "Tier for high-volume agencies",
    "external_id": "P-GROUP-PERF",
    "tags": "managed,performance",
    "default": false,
    "rules": [
      {
        "type": "new_customer_time_tier",
        "max_months": 6,
        "percentage": 30
      },
      {
        "type": "recurring",
        "percentage": 12
      }
    ]
  }
}}
  properties={[
  { name: "partnerGroup.name", type: "string", required: true, description: "Partner group display name." },
  { name: "partnerGroup.rules", type: "array", required: true, description: "Rules array. Must include one recurring fallback rule." },
  { name: "partnerGroup.description", type: "string", required: false, description: "Optional group description." },
  { name: "partnerGroup.external_id", type: "string", required: false, description: "Optional external identifier." },
  { name: "partnerGroup.tags", type: "string", required: false, description: "Comma-separated tags." },
  { name: "partnerGroup.default", type: "boolean", required: false, description: "Mark this group as default for new partners." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Partner group created.",
    content: { "group": { "id": "68f76721..." } }
  }
]}
/>

### Update Partner Group

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/partners/groups/{partnerGroupId}.json"
  params={[
  { name: "partnerGroupId", type: "string", required: true, description: "Partner group identifier.", location: "path" }
]}
  body={{
  "partnerGroup": {
    "name": "Performance Agencies v2",
    "default": true,
    "rules": [
      {
        "type": "recurring",
        "percentage": 14
      }
    ]
  }
}}
  properties={[
  { name: "partnerGroup.name", type: "string", required: false, description: "Updated group name." },
  { name: "partnerGroup.description", type: "string", required: false, description: "Updated description." },
  { name: "partnerGroup.external_id", type: "string", required: false, description: "Updated external identifier." },
  { name: "partnerGroup.tags", type: "string", required: false, description: "Updated comma-separated tags." },
  { name: "partnerGroup.default", type: "boolean", required: false, description: "Update default flag." },
  { name: "partnerGroup.rules", type: "array", required: false, description: "Updated rules array; if provided, must include recurring fallback." }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Partner group updated.",
    content: { "group": { "id": "68f76721..." } }
  }
]}
/>

### Delete Partner Group

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/partners/groups/{partnerGroupId}.json"
  params={[
  { name: "partnerGroupId", type: "string", required: true, description: "Partner group identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Partner group deleted.",
    content: { "group": { "id": "68f76721...", "deleted": true } }
  }
]}
/>

### Simulate Rules

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/partners/groups/simulate-rules.json"
  body={{
  "partnerGroupSimulation": {
    "rules": [
      { "type": "new_customer_time_tier", "max_months": 3, "percentage": 25 },
      { "type": "recurring", "percentage": 10 }
    ],
    "simulation": {
      "charge_amount": 299.90,
      "customer_months": 2,
      "partner_ltv": 4500,
      "qualified_customers": 12,
      "first_paid_customer_bootstrap": false
    }
  }
}}
  properties={[
  { name: "partnerGroupSimulation.rules", type: "array", required: true, description: "Rules set to simulate. Must include recurring fallback." },
  { name: "partnerGroupSimulation.simulation", type: "object", required: true, description: "Simulation context (charge amount, lifecycle and partner KPIs)." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Rules simulation completed.",
    content: {
      "status": "success",
      "result": {
        "final_fee": 74.98
      }
    }
  }
]}
/>

***

## The Rules Engine

Partner groups are powered by a deterministic rules engine that evaluates transactions in real-time. The following rule types are supported:

### Rule Type Definitions

| Rule Type                | Description                                                                                       | Key Parameters                        |
| :----------------------- | :------------------------------------------------------------------------------------------------ | :------------------------------------ |
| `new_customer_time_tier` | Applies a specific commission for the initial months of a customer's lifecycle.                   | `max_months`, `percentage`            |
| `recurring`              | The baseline commission applied to all transactions when no other specific rule applies.          | `percentage`                          |
| `partner_ltv_upgrade`    | Triggers a commission percentage increase once a partner's total managed LTV exceeds a threshold. | `min_ltv_total`, `upgrade_percentage` |
| `charge_threshold_bonus` | Provides a one-time bonus for transactions exceeding a specific amount.                           | `min_charge_total`, `bonus`           |

<Callout type="info">
  **Evaluation Hierarchy:** Rules are evaluated based on the customer's acquisition date and the partner's historical performance. A `recurring` rule is required for all groups as a fallback mechanism.
</Callout>


# Partners



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Partners API

The Partners API enables organizations to build and scale distribution networks through agencies, resellers, and affiliates. It provides a framework for managing partner identities, commission calculations (fees), and financial settlements (payouts), while maintaining clear attribution for every customer acquired through the channel.

***

## Channel Management

### List Partners

Retrieve a paginated directory of all registered partners. This list includes high-level identification data and current status for each collaborative entity.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Partner directory successfully retrieved.",
    content: {
      "entities": "Partner",
      "count": 24,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        { 
          "id": "675d...", 
          "name": "Global Solutions Agency", 
          "external_id": "GSA-9921",
          "partner_code": "GOLD-PARTNER-X"
        }
      ]
    } 
  }
]}
/>

### Provision New Partner

Onboard a new partner into the ecosystem. This initializes their profile and associates them with a governance group (Partner Group) to define their commission rules.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/partners.json"
  body={{
  "partner": {
      "name": "Apex Marketing Group",
      "email": "channel@apex-marketing.com",
      "external_id": "APEX_001",
      "code": "APEXPROMO",
      "partner_group_id": "66bf22b0...",
      "address": {
          "vat_number": "IT09876543210",
          "country": "IT",
          "city": "Milan"
      }
  }
}}
  properties={[
  { name: "partner.name", type: "string", required: true, description: "Legal entity name of the partner." },
  { name: "partner.email", type: "string", required: true, description: "Primary contact for financial and operational notifications." },
  { name: "partner.partner_group_id", type: "string", required: false, description: "The ID of the Partner Group define rules. If empty, the default group is used." },
  { name: "partner.address.country", type: "string", required: true, description: "ISO 3166-1 alpha-2 country code." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Partner successfully provisioned.",
    content: { "partner": { "id": "6768..." } } 
  }
]}
/>

### Retrieve Partner Profile

Fetch the comprehensive profile of a specific partner, including their fee structure, whitelist configuration, and association metadata.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "The unique identifier of the partner.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Partner profile retrieved.",
    content: {
      "id": "66b136b9...",
      "name": "Apex Marketing Group",
      "status": "active",
      "tags": ["tier-1", "mfa-enabled"],
      "email": "channel@apex-marketing.com",
      "address": { "city": "Milan", "country": "IT", "vat_number": "IT098..." }
    } 
  }
]}
/>

***

## Attribution & Performance

### Audit Attributed Customers

Retrieve a paginated list of all customers currently attributed to a specific partner. This is used to verify channel performance and revenue attribution.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/customers.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "The partner identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Attributed customer list retrieved.",
    content: {
      "entities": "PartnerCustomers",
      "count": 142,
      "elements": [
          { "id": "68d2...", "company_name": "Acme Corp", "email": "procurement@acme.com", "status": "active" }
      ]
    } 
  }
]}
/>

### Performance Analytics

Retrieve high-level performance metrics for a partner, including total attributed revenue and cumulative commissions earned.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/stats.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "The partner identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Aggregated performance statistics retrieved.",
    content: { 
      "total_revenue": "45200.00", 
      "commission_earned": "4520.00",
      "currency": "EUR"
    } 
  }
]}
/>

***

## Financial Settlement (Payouts)

### Audit Commission Ledger (Fees)

Retrieve individual commission entries (fees) generated by attributed customer transactions. These entries serve as the basis for payout generation.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/fees.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "The partner identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Commission ledger retrieved.",
    content: {
      "entities": "PartnerFees",
      "elements": [
        { "id": "fee_991", "source_charge": "ch_123", "fee_value": 15.50, "status": "pending" }
      ]
    } 
  }
]}
/>

### Generate Payout Request

Consolidate multiple 'pending' commission fees into a single Payout request. This initiates the financial settlement cycle and generates a draft settlement record.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/partners/payouts.json"
  body={{
  "payout": {
      "partner_id": "675d...",
      "transactions": ["fee_991", "fee_992"],
      "invoice": {
          "number": "INV-2026-001",
          "date": "2026-03-01"
      },
      "vat_settings": {
          "tax_id": "tax_vat_22"
      }
  }
}}
  properties={[
  { name: "payout.partner_id", type: "string", required: true, description: "The partner identifier." },
  { name: "payout.transactions", type: "array", required: true, description: "Collection of fee entry IDs." },
  { name: "payout.invoice.number", type: "string", required: true, description: "Reference number for the partner settlement invoice." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Payout request successfully generated.",
    content: { "id": "pay_5521", "total": "1250.00" } 
  }
]}
/>

### Retrieve Payout Documentation (PDF)

Retrieve a base64-encoded PDF report (Account Statement) for a specific payout. This document serves as the official settlement record for the partner.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/payouts/{payoutId}/report.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "The partner identifier.", location: "path" },
  { name: "payoutId", type: "string", required: true, description: "The payout identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "PDF documentation retrieved.",
    content: { 
      "stream": {
        "type": "application/pdf",
        "base64_content": "JVBER..."
      }
    } 
  }
]}
/>

### Technical Implementation (Payout Flow)

<Tabs items={["Javascript"]}>
  <Tab value="Javascript">
    ```js
    const payoutData = {
      payout: {
        partner_id: "PARTNER_6621",
        transactions: ["FEE_001", "FEE_002"],
        invoice: { number: "REF-9921", date: "2026-03-03" },
        vat_settings: { tax_id: "VAT_22_IT" }
      }
    };

    try {
      const settlement = await sdk.partners.createPayout(payoutData);
      console.log(`Settlement Processed. ID: ${settlement.id}, Total: ${settlement.total}`);
    } catch (error) {
      console.error(`Settlement Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

***

## Additional Partner Operations

### Search Partner by External ID or Email

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/partner.json"
  params={[
  { name: "externalId", type: "string", required: false, description: "Partner external identifier.", location: "query" },
  { name: "email", type: "string", required: false, description: "Partner email address.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Partner record retrieved.",
    content: { "id": "675d...", "name": "Apex Marketing Group", "email": "channel@apex-marketing.com" }
  },
  {
    status: "422 Unprocessable Entity",
    description: "Neither `externalId` nor `email` was provided.",
    content: { "error": "A valid \"externalId\" or \"email\" must be specified in the request" }
  }
]}
/>

### Update Partner Profile

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/partners/{partnerId}.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "Partner identifier.", location: "path" }
]}
  body={{
  "partner": {
    "name": "Apex Marketing Group - Enterprise",
    "email": "enterprise@apex-marketing.com",
    "description": "Updated profile",
    "external_id": "APEX_001",
    "code": "APEXPROMO",
    "partner_group_id": "66bf22b0...",
    "tags": ["tier-1", "priority"],
    "address": {
      "country": "IT",
      "city": "Milan"
    }
  }
}}
  properties={[
  { name: "partner.name", type: "string", required: false, description: "Updated partner legal name." },
  { name: "partner.email", type: "string", required: false, description: "Updated partner contact email." },
  { name: "partner.description", type: "string", required: false, description: "Updated profile description." },
  { name: "partner.external_id", type: "string", required: false, description: "Updated external identifier." },
  { name: "partner.code", type: "string", required: false, description: "Updated partner code." },
  { name: "partner.partner_group_id", type: "string", required: false, description: "Partner group assignment (empty string removes current group)." },
  { name: "partner.tags", type: "array|string", required: false, description: "Updated tags list." },
  { name: "partner.address", type: "object", required: false, description: "Partial address update object." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Partner updated.",
    content: { "id": "675d...", "name": "Apex Marketing Group - Enterprise" }
  }
]}
/>

### Delete Partner

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/partners/{partnerId}.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "Partner identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Partner deleted.",
    content: { "id": "675d...", "deleted": true }
  },
  {
    status: "406 Not Acceptable",
    description: "Partner has still attached customers.",
    content: { "error": "Unable to remove this partner. Customer attached to partner: ..." }
  }
]}
/>

### Get Partner Fee by ID

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/fees/{feeId}.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "Partner identifier.", location: "path" },
  { name: "feeId", type: "string", required: true, description: "Fee entry identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Partner fee entry retrieved.",
    content: { "id": "fee_991", "partner_id": "675d...", "fee_value": 15.5, "status": "pending" }
  }
]}
/>

### List Global Payouts

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/payouts.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (1-100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index (1-based).", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Paginated payout list across all partners.",
    content: { "entities": "PartnerPayout", "count": 3, "elements": [] }
  }
]}
/>

### List Payouts for One Partner

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/payouts.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "Partner identifier.", location: "path" },
  { name: "size", type: "integer", required: false, description: "Maximum records per page (1-100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index (1-based).", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Paginated payout list for the specified partner.",
    content: { "entities": "PartnerPayout", "count": 2, "elements": [] }
  }
]}
/>

### Get Payout by Partner and ID

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/payouts/{payoutId}.json"
  params={[
  { name: "partnerId", type: "string", required: true, description: "Partner identifier.", location: "path" },
  { name: "payoutId", type: "string", required: true, description: "Payout identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Payout details retrieved.",
    content: { "id": "pay_5521", "partner_id": "675d...", "status": "pending", "total": 1250.0 }
  }
]}
/>

### Get Payout by ID

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/payouts/{payoutId}.json"
  params={[
  { name: "payoutId", type: "string", required: true, description: "Payout identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Payout details retrieved.",
    content: { "id": "pay_5521", "partner_id": "675d...", "status": "pending", "total": 1250.0 }
  }
]}
/>

### Update Payout Status

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/partners/payouts/{payoutId}/status.json"
  params={[
  { name: "payoutId", type: "string", required: true, description: "Payout identifier.", location: "path" }
]}
  body={{
  "payout": {
    "status": "paid",
    "metadata": {
      "reference": "BANK-TRX-2026-8891"
    }
  }
}}
  properties={[
  { name: "payout.status", type: "string", required: true, description: "Next payout status. Allowed values: pending, paid, refused." },
  { name: "payout.metadata", type: "object", required: false, description: "Optional metadata merged into payout metadata." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Payout status updated and related fee entries synchronized.",
    content: { "payout": { "id": "pay_5521", "status": "paid" } }
  },
  {
    status: "409 Conflict",
    description: "Invalid status transition.",
    content: { "error": "Paid payouts cannot be updated" }
  }
]}
/>

### Stream Payout PDF

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/partners/{partnerId}/payouts/{payoutId}/report.pdf"
  params={[
  { name: "partnerId", type: "string", required: true, description: "Partner identifier.", location: "path" },
  { name: "payoutId", type: "string", required: true, description: "Payout identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Inline PDF stream response.",
    content: {
      "note": "Response is streamed as application/pdf."
    }
  }
]}
/>


# Recurring Payments



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Recurring Payments API

The Recurring Payments API provides the operational infrastructure for managing subscription-based revenue models. It allows organizations to define sophisticated billing cycle parameters, configure automated dunning (retry) policies for failed transactions, and monitor the real-time status of all active subscriptions across the platform.

***

## Operational Configuration

### Audit Recurring Settings

Retrieve the global operational parameters governing recurring billing. This includes the current retry logic for failed payments and the timing offsets for subsequent billing cycles.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/recurring-payments/settings.json"
  responses={[
  { 
    status: "200 OK", 
    description: "Operational settings successfully retrieved.",
    content: {
      "status": "success",
      "settings": {
          "retry_policy": "exponential_backoff",
          "max_retries": 5,
          "next_cycle_offset": "24 hours",
          "dunning_notifications": true
      }
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/recurring-payments/settings.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    try {
      const config = await sdk.recurringPayments.getSettings();
      console.log(`Billing Policy: ${config.settings.retry_policy} (Max Retries: ${config.settings.max_retries})`);
    } catch (error) {
      console.error(`Fetch Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

***

## Subscription Lifecycle Monitoring

### Audit Active Subscriptions

Retrieve a comprehensive inventory of all subscriptions currently managed by the recurring payment engine. This endpoint provides crucial visibility into renewal dates, customer associations, and current billing health.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/recurring-payments/subscriptions.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page.", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Subscription inventory retrieved.",
    content: {
      "type": "RecurringSubscriptions",
      "count": 1250,
      "per_page": 100,
      "elements": [
        {
          "id": "67bdf...",
          "customerId": "66a15...",
          "subscription_reference": "sub_premium_9921",
          "status": "active",
          "next_renewal_date": "2026-04-01T00:00:00Z",
          "last_payment_status": "success"
        }
      ]
    } 
  }
]}
/>

### Implementation

<Tabs items={["Javascript"]}>
  <Tab value="Javascript">
    ```js
    const filters = { page: 1, size: 50 };
    try {
      const activeSubs = await sdk.recurringPayments.listSubscriptions(filters);
      activeSubs.elements.forEach(sub => {
        console.log(`Subscription ${sub.id}: Renewal due on ${sub.next_renewal_date}`);
      });
    } catch (error) {
      console.error(`Telemetry Error: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>


# Scheduler



# Scheduler API

## List Events

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/scheduler/events.json"
  params={[
  { name: "start", type: "string", required: true, description: "Start date or datetime (recommended YYYY-MM-DD).", location: "query" },
  { name: "end", type: "string", required: true, description: "End date or datetime (recommended YYYY-MM-DD).", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Events fetched in the requested range.",
    content: {
      "status": "fetch",
      "count": 2,
      "range": {
        "start": "2026-04-01T00:00:00+02:00",
        "end": "2026-04-30T23:59:59+02:00"
      },
      "events": [
        {
          "id": "681f0f...",
          "event_type": "appointment",
          "title": "Quarterly Review",
          "schedule_date": "2026-04-12T09:00:00+02:00",
          "end_date": "2026-04-12T10:00:00+02:00"
        }
      ]
    }
  }
]}
/>

## Create Event

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/scheduler/events.json"
  body={{
  "event": {
    "event_type": "action",
    "title": "Run Workflow Daily",
    "schedule_date": "2026-04-20T07:30:00+02:00",
    "end_date": "2026-04-20T07:30:00+02:00",
    "is_all_day": false,
    "color": "primary",
    "action_type": "workflow",
    "action_details": {
      "workflow_id": "67ffac1f8a3f0f2f88f9dd10",
      "payload": { "source": "api" }
    },
    "recurrence": {
      "type": "week",
      "interval": 1,
      "endDate": "2026-12-31"
    }
  }
}}
  properties={[
  { name: "event", type: "object", required: true, description: "Scheduler event payload." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Event created.",
    content: {
      "id": "681f0f...",
      "event": {
        "id": "681f0f...",
        "event_type": "action",
        "action_type": "workflow"
      }
    }
  },
  {
    status: "422 Unprocessable Entity",
    description: "Validation error on event payload.",
    content: { "error": "Invalid \"action_type\". Allowed values: charge, job_runner, workflow" }
  }
]}
/>

## Update Event

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/scheduler/events/{eventId}.json"
  params={[
  { name: "eventId", type: "string", required: true, description: "Scheduler event identifier.", location: "path" }
]}
  body={{
  "event": {
    "title": "Run Workflow - Updated",
    "recurrence": {
      "type": "month",
      "interval": 1,
      "endDate": "2027-04-30"
    }
  }
}}
  properties={[
  { name: "event", type: "object", required: true, description: "Partial event payload to update." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Event updated.",
    content: {
      "id": "681f0f...",
      "event": {
        "id": "681f0f...",
        "title": "Run Workflow - Updated"
      }
    }
  }
]}
/>

## Delete Event

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/scheduler/events/{eventId}.json"
  params={[
  { name: "eventId", type: "string", required: true, description: "Scheduler event identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Event deleted.",
    content: {
      "id": "681f0f...",
      "deleted": true
    }
  }
]}
/>


# Share Secrets



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Share Secrets API

The Share Secrets API provides a secure mechanism for transmitting sensitive information (such as passwords, private keys, or PII) without leaving a persistent digital footprint. Secrets are encrypted and associated with a unique, short-lived URL. To ensure maximum security, content is **purged immediately after the first successful access**, rendering the link permanently invalid.

***

## Secret Management

### Audit Secret Inventory

Retrieve a paginated directory of all active (unread) or recently expired share secret entries. This allows for administrative tracking of shared links and their current consumption status.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/share-secrets.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Secret directory successfully retrieved.",
    content: {
      "entities": "ShareSecret",
      "count": 5,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
          {
              "id": "6739782b...",
              "name": "Database Migration Credentials",
              "url": "https://hub.donutwork.com/ss/b6a9532aa4a06...",
              "readed": false
          }
      ]
    } 
  }
]}
/>

### Provision Secure Secret Link

Generate a new ephemeral secret link. The `content` provided is encrypted at rest and will be revealed only once. You can optionally trigger an automated email notification to the recipient.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/share-secrets.json"
  body={{
  "shareSecret": {
      "name": "Deployment API Token",
      "content": "secret_value_redacted",
      "sendTo": {
          "email": "engineer@partner-company.com",
          "message": "The requested production API token is now available for one-time retrieval."
      }
  }
}}
  properties={[
  { name: "shareSecret.name", type: "string", required: true, description: "Descriptive label for internal tracking." },
  { name: "shareSecret.content", type: "string", required: true, description: "The sensitive payload to be shared (OTV)." },
  { name: "shareSecret.sendTo.email", type: "string", required: false, description: "Recipient email for automated notification." },
  { name: "shareSecret.sendTo.message", type: "string", required: false, description: "Optional custom message included in notification email." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Secret link successfully provisioned.",
    content: {
      "id": "67397a4c...",
      "name": "Deployment API Token",
      "url": "https://hub.donutwork.com/ss/fb89f610...",
      "readed": false,
      "readerInfo": {
        "ip": null,
        "ua": null,
        "isoDate": null,
        "ts": null
      },
      "sendTo": { "status": true, "messageId": "msg_9921" }
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["Javascript"]}>
  <Tab value="Javascript">
    ```js
    const secretPayload = {
      shareSecret: {
        name: "Inter-Service Auth Key",
        content: "PRIVATE_KEY_CONTENT_HERE",
        sendTo: { email: "security-ops@acme.com", message: "Key Rotation: 2026-Q1" }
      }
    };

    try {
      const response = await sdk.tools.createShareSecret(secretPayload);
      console.log(`Secret Link Generated: ${response.url}`);
    } catch (error) {
      console.error(`Provisioning Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

***

## Access & Revocation

### Audit Access Metadata

Retrieve the access status and reader telemetry for a specific secret link. This endpoint provides audit trails (IP, User-Agent, Timestamp) once the secret has been consumed.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/share-secrets/{secretId}.json"
  params={[
  { name: "secretId", type: "string", required: true, description: "The unique identifier of the secret entry.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Access metadata successfully retrieved.",
    content: {
      "id": "6739782b...",
      "name": "Database Migration Credentials",
      "readed": true,
      "readerInfo": { 
        "ip": "82.1.4.22", 
        "ua": "Mozilla/5.0...", 
        "isoDate": "03/03/2026 11:20:00",
        "ts": 1772536800
      }
    } 
  }
]}
/>

### Revoke Secret Link

Manually revoke a secret link before it is consumed, or purge the audit record of an already read secret.

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/share-secrets/{secretId}.json"
  params={[
  { name: "secretId", type: "string", required: true, description: "The unique identifier to revoke.", location: "path" }
]}
  responses={[
  { 
    status: "202 Accepted", 
    description: "Secret link successfully revoked and record purged.",
    content: { "id": "67397a4c...", "deleted": true } 
  }
]}
/>

<Callout type="warning">
  **Security Policy:** Content retrieval is handled via the specific `url` field returned during provisioning. Once the `readed` flag is set to `true`, the content is physically deleted from the database and cannot be recovered.
</Callout>


# Shortlinks



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Shortlinks API

The Shortlinks API enables organizations to transform complex destination URLs into concise links. Beyond simple redirection, the system provides integrated telemetry for traffic attribution, enabling teams to monitor engagement performance in real time across distribution channels.

***

## Link Lifecycle Management

### Audit Shortlink Directory

Retrieve a paginated directory of all shortlinks associated with your organization. This inventory includes current operational status and destination metadata.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/shortlinks.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Shortlink inventory successfully retrieved.",
    content: {
      "entities": "Shortlink",
      "count": 42,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
          {
              "id": "675d9fea...",
              "title": "Spring 2026 Campaign",
              "original_url": "https://marketing.acme.com/promo/spring",
              "short_code": "k9x2m-spr26",
              "url": "https://d.dw2.it/r/k9x2m-spr26",
              "is_active": true
          }
      ]
    } 
  }
]}
/>

### Provision New Shortlink

Generate a new shortlink for a target destination.\
You can optionally provide a custom `fragment` (bitly-style suffix). The platform always prepends an auto-generated prefix to reduce collision risk.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/shortlinks.json"
  body={{
  "shortlink": {
      "title": "Product Launch Announcement",
      "original_url": "https://acme.com/products/new-gen-ai",
      "fragment": "launch-2026",
      "is_active": true
  }
}}
  properties={[
  { name: "shortlink.title", type: "string", required: true, description: "Administrative label for the link." },
  { name: "shortlink.original_url", type: "string", required: true, description: "The full destination URL (must include protocol)." },
  { name: "shortlink.fragment", type: "string", required: false, description: "Custom shortlink suffix (3-48 chars, letters/numbers/hyphens). Alias: `shortlink.short_code`." },
  { name: "shortlink.is_active", type: "boolean", required: false, description: "Operational status of the link. Defaults to true." }
]}
  responses={[
  { 
    status: "201 Created", 
    description: "Shortlink successfully provisioned.",
    content: {
      "shortlink": { "id": "6768440..." },
      "short_code": "k9x2m-launch-2026",
      "url": "https://d.dw2.it/r/k9x2m-launch-2026"
    } 
  },
  {
    status: "409 Conflict",
    description: "Requested custom fragment is already in use.",
    content: { "error": "This shortlink fragment is already in use" }
  }
]}
/>

### Retrieve Link Configuration

Fetch the detailed configuration and operational status for a specific shortlink.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/shortlinks/{shortlinkId}.json"
  params={[
  { name: "shortlinkId", type: "string", required: true, description: "The unique identifier of the shortlink.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Shortlink configuration retrieved.",
    content: {
      "id": "675d9fea...",
      "title": "Spring 2026 Campaign",
      "original_url": "https://marketing.acme.com/promo/spring",
      "short_code": "k9x2m-spr26",
      "url": "https://d.dw2.it/r/k9x2m-spr26",
      "is_active": true
    } 
  }
]}
/>

***

## Operational Controls

### Update Link Parameters

Modify the destination URL, custom fragment, or operational status of an existing shortlink. Link updates are propagated across the redirection edge in near real-time.\
When updating `fragment`, the existing auto-generated prefix is preserved.

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/shortlinks/{shortlinkId}.json"
  params={[
  { name: "shortlinkId", type: "string", required: true, description: "The unique identifier to update.", location: "path" }
]}
  body={{
  "shortlink": {
      "title": "Revised Spring Campaign",
      "original_url": "https://marketing.acme.com/promo/spring-final",
      "fragment": "spring-final",
      "is_active": true
  }
}}
  properties={[
  { name: "shortlink.title", type: "string", required: true, description: "Updated shortlink title." },
  { name: "shortlink.original_url", type: "string", required: true, description: "Updated destination URL." },
  { name: "shortlink.fragment", type: "string", required: false, description: "Updated custom suffix (3-48 chars, letters/numbers/hyphens). Alias: `shortlink.short_code`." },
  { name: "shortlink.is_active", type: "boolean", required: false, description: "Enable or disable link redirection." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Configuration updated successfully.",
    content: {
      "shortlink": { "id": "675d9fea..." },
      "short_code": "k9x2m-spring-final",
      "url": "https://d.dw2.it/r/k9x2m-spring-final"
    } 
  },
  {
    status: "409 Conflict",
    description: "Requested custom fragment is already in use.",
    content: { "error": "This shortlink fragment is already in use" }
  }
]}
/>

### Revoke Shortlink

Permanently revoke a shortlink and decommission its redirection service.

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/shortlinks/{shortlinkId}.json"
  params={[
  { name: "shortlinkId", type: "string", required: true, description: "The identifier to decompose.", location: "path" }
]}
  responses={[
  { 
    status: "202 Accepted", 
    description: "Shortlink successfully revoked.",
    content: { "id": "675d9fea...", "deleted": true } 
  }
]}
/>

***

## Analytics & Telemetry

### Retrieve Interaction Metrics

Access real-time engagement telemetry for a specific shortlink. This include visit counts, unique interactions, and longitudinal performance data.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/shortlinks/{shortlinkId}/stats.json"
  params={[
  { name: "shortlinkId", type: "string", required: true, description: "The shortlink identifier.", location: "path" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Engagement metrics successfully aggregated.",
    content: {
      "shortlink": {
          "id": "675d9fea...",
          "title": "Spring 2026 Campaign",
          "original_url": "https://marketing.acme.com/promo/spring",
          "short_code": "k9x2m-spr26",
          "is_active": true,
          "url": "https://d.dw2.it/r/k9x2m-spr26",
          "created_at": 1772536800
      },
      "metrics": {
          "summary": { "human": 1530, "bot": 12, "total": 1542 },
          "view_density": [{ "country": "IT", "count": 600 }, { "country": "US", "count": 420 }],
          "referrers": { "Direct": 900, "linkedin.com": 350, "newsletter.acme.com": 292 },
          "bots": { "Google": 7, "Facebook": 5 },
          "browsers": { "Chrome": 1100, "Safari": 320, "Firefox": 110 },
          "os": { "Windows": 620, "macOS": 410, "iOS": 320, "Android": 180 }
      }
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["Javascript"]}>
  <Tab value="Javascript">
    ```js
    const shortlinkId = "675d9fea...";
    try {
      const stats = await sdk.dw2.getStats(shortlinkId);
      console.log(`Campaign Performance: ${stats.metrics.summary.total} total interactions.`);
    } catch (error) {
      console.error(`Telemetry Error: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>


# Taxes



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Taxes API

The Taxes API provides a centralized layer for managing tax profiles and regional tax logic. By defining tax profiles (such as VAT, GST, or Sales Tax), organizations can automate tax calculation during invoicing and subscription renewals, ensuring consistent compliance with local regulations.

***

## Tax Profiles

### List Tax Profiles

Retrieve a comprehensive directory of all tax profiles configured for your organization. These profiles act as the authoritative source for tax percentage calculations and must be referenced when provisiong new customers or products.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/taxes.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index for results.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Tax profile directory successfully retrieved.",
    content: {
      "entities": "Taxes",
      "count": 5,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
          {
              "id": "66a151b7...",
              "name": "Standard EU VAT (22%)",
              "percentage": 22.0,
              "description": "Standard Value Added Tax for European Union member states."
          }
      ]
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/taxes.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    try {
      const taxProfiles = await sdk.taxes.list();
      console.log(`Active Tax Profiles: ${taxProfiles.count}`);
    } catch (error) {
      console.error(`Compliance Check Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **Integration Note:** When orchestrating customer provisioning (via the CRM/Customer API), ensure the `tax_id` from these profiles is correctly mapped. This association is critical for accurate automated invoicing and financial reporting.
</Callout>

***

## Tax Profile Lifecycle

### Create Tax Profile

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/taxes.json"
  body={{
  "tax": {
    "name": "Standard EU VAT (22%)",
    "description": "EU default VAT profile",
    "percentage": 22.0,
    "default": false
  }
}}
  properties={[
  { name: "tax.name", type: "string", required: true, description: "Unique tax profile label." },
  { name: "tax.percentage", type: "number", required: true, description: "Tax percentage value. Must be >= 0." },
  { name: "tax.description", type: "string", required: false, description: "Optional internal description." },
  { name: "tax.default", type: "boolean", required: false, description: "Marks the profile as default when true." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Tax profile created.",
    content: {
      "status": "success",
      "tax": {
        "id": "tax_001",
        "name": "Standard EU VAT (22%)",
        "percentage": 22.0
      }
    }
  }
]}
/>

### Update Tax Profile

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/taxes/{taxId}.json"
  params={[
  { name: "taxId", type: "string", required: true, description: "Tax profile ID.", location: "path" }
]}
  body={{
  "tax": {
    "name": "EU VAT 2026",
    "description": "Updated profile metadata",
    "percentage": 23.0,
    "default": true
  }
}}
  properties={[
  { name: "tax.name", type: "string", required: false, description: "Updated tax profile label." },
  { name: "tax.description", type: "string", required: false, description: "Updated profile description." },
  { name: "tax.percentage", type: "number", required: false, description: "Updated percentage value. Must be >= 0." },
  { name: "tax.default", type: "boolean", required: false, description: "Update default profile flag." }
]}
  responses={[
  {
    status: "200 OK",
    description: "Tax profile updated.",
    content: {
      "status": "success",
      "tax": {
        "id": "tax_001",
        "name": "EU VAT 2026",
        "percentage": 23.0
      }
    }
  }
]}
/>

### Delete Tax Profile

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/taxes/{taxId}.json"
  params={[
  { name: "taxId", type: "string", required: true, description: "Tax profile ID.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Tax profile deleted.",
    content: {
      "status": "success",
      "tax": {
        "id": "tax_001",
        "deleted": true
      }
    }
  },
  {
    status: "404 Not Found",
    description: "Tax profile not found.",
    content: { "error": "This tax profile does not exists" }
  }
]}
/>


# Webhook API



# Webhook API

Use webhooks to receive asynchronous notifications for supported platform events.

***

## List Webhooks

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/webhooks.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (1-100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page index (1-based).", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Paginated list of webhook subscriptions.",
    content: {
      "entities": "Webhook",
      "count": 2,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "wh_001",
          "name": "Billing Events",
          "description": "Receive invoice and payment updates",
          "url": "https://example.com/webhooks/billing",
          "events": ["RecurringPayments.charge.paid"],
          "token": "redacted"
        }
      ]
    }
  }
]}
/>

## Create Webhook

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/webhooks.json"
  body={{
  "webhook": {
    "name": "Billing Events",
    "description": "Receive invoice and payment updates",
    "url": "https://example.com/webhooks/billing",
    "events": ["RecurringPayments.charge.paid"]
  }
}}
  properties={[
  { name: "webhook.name", type: "string", required: true, description: "Display name of the webhook subscription." },
  { name: "webhook.url", type: "string", required: true, description: "HTTPS endpoint that receives webhook payloads." },
  { name: "webhook.events", type: "array|string", required: true, description: "Subscribed event names. A single event string is also accepted." },
  { name: "webhook.description", type: "string", required: false, description: "Optional free-text description for internal use." }
]}
  responses={[
  {
    status: "201 Created",
    description: "Webhook created successfully.",
    content: {
      "id": "wh_001",
      "name": "Billing Events",
      "description": "Receive invoice and payment updates",
      "url": "https://example.com/webhooks/billing",
      "events": ["RecurringPayments.charge.paid"],
      "token": "generated_webhook_token"
    }
  },
  {
    status: "412 Precondition Failed",
    description: "Name, url, or events missing; or TLS certificate validation failed.",
    content: { "error": "A valid \"url\" must be specified." }
  },
  {
    status: "422 Unprocessable Entity",
    description: "URL format invalid or unsupported event specified.",
    content: { "error": "Some events are not available" }
  }
]}
/>

## List Supported Webhook Types

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/webhooks/types.json"
  responses={[
  {
    status: "200 OK",
    description: "List of available webhook event names for the company context.",
    content: [
      "RecurringPayments.charge.paid",
      "RecurringPayments.charge.failed"
    ]
  }
]}
/>

## Get Webhook

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/webhooks/{webhookId}.json"
  params={[
  { name: "webhookId", type: "string", required: true, description: "Webhook unique identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Webhook details.",
    content: {
      "id": "wh_001",
      "name": "Billing Events",
      "description": "Receive invoice and payment updates",
      "url": "https://example.com/webhooks/billing",
      "events": ["RecurringPayments.charge.paid"],
      "token": "redacted"
    }
  },
  {
    status: "404 Not Found",
    description: "Webhook resource not found.",
    content: { "error": "Webhook not found." }
  }
]}
/>

## Delete Webhook

<DonutApi
  method="DELETE"
  version="2026-02-01"
  endpoint="/webhooks/{webhookId}.json"
  params={[
  { name: "webhookId", type: "string", required: true, description: "Webhook unique identifier.", location: "path" }
]}
  responses={[
  {
    status: "202 Accepted",
    description: "Webhook deletion accepted.",
    content: {
      "id": "wh_001",
      "deleted": true
    }
  },
  {
    status: "404 Not Found",
    description: "Webhook resource not found.",
    content: { "error": "Webhook not found. Unable to delete unknown resource" }
  }
]}
/>


# Workflow



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

# Workflow API

The Workflow API provides an engine for orchestrating complex, multi-stage business processes. By defining structured workflows, organizations can automate repetitive operational tasks, ensuring deterministic execution and full auditability. The engine supports dynamic payload injection for contextualized automation across the platform.

***

## Workflow Management

### List Workflows

Retrieve a comprehensive directory of all registered business workflows for your organization. This inventory includes the operational status, task count, and administrative metadata for each automation.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/workflow.json"
  params={[
  { name: "size", type: "integer", required: false, description: "Maximum records per page (max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Target page index.", location: "query" }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Workflow inventory successfully retrieved.",
    content: {
      "entities": "Workflow",
      "count": 12,
      "per_page": 100,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "6724bffd...",
          "name": "Enterprise Onboarding Logic",
          "active": true,
          "tasks_count": 8,
          "description": "Orchestrates account provisioning and initial compliance checks."
        }
      ]
    } 
  }
]}
/>

### Technical Implementation

<Tabs items={["CURL", "Javascript"]}>
  <Tab value="CURL">
    ```sh
    curl --location --request GET \
    'https://api.hub.donutwork.com/2026-02-01/workflow.json' \
    --header 'Authorization: Bearer YOUR_API_TOKEN'
    ```
  </Tab>

  <Tab value="Javascript">
    ```js
    try {
      const inventory = await sdk.workflow.list();
      console.log(`Active Automations: ${inventory.count}`);
    } catch (error) {
      console.error(`Workflow Audit Failed: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

***

## Workflow Execution

### Dispatch Workflow Execution

Trigger the execution of a specific business workflow. This endpoint accepts a dynamic `data` payload that is injected into the execution context, allowing tasks to operate on real-time request data.

<DonutApi
  method="POST"
  version="2026-02-01"
  endpoint="/workflow/{workflowId}.json"
  params={[
  { name: "workflowId", type: "string", required: true, description: "The unique identifier of the workflow to execute.", location: "path" }
]}
  body={{
  "data": {
    "customer_id": "cust_9921",
    "priority": "high",
    "metadata": { "source": "api_v2" }
  }
}}
  properties={[
  { name: "data", type: "object", required: true, description: "Dynamic context data injected into the workflow execution." }
]}
  responses={[
  { 
    status: "200 OK", 
    description: "Workflow execution completed. Detailed stage results returned.",
    content: { 
      "success": true, 
      "execution_id": "exe_8821abd033",
      "stages": [
        { "node": "validate_identity", "status": "completed", "output": { "valid": true } }
      ]
    } 
  },
  { 
    status: "404 Not Found", 
    description: "The specified workflow identifier does not exist.",
    content: { "error": "This workflow does not exists" } 
  }
]}
/>

### Technical Implementation (Execution Flow)

<Tabs items={["Javascript"]}>
  <Tab value="Javascript">
    ```js
    const context = {
      data: {
        userId: "USR-001",
        action: "PROVISION_RESOURCE",
        quota: 100
      }
    };

    try {
      const result = await sdk.workflow.execute("ONBOARD_WF_01", context);
      if (result.success) {
        console.log(`Automation Finished: ${result.execution_id}`);
      }
    } catch (error) {
      console.error(`Execution Halted: ${error.message}`);
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **Auditability:** Every workflow execution generates a unique `execution_id` and provides detailed telemetry for each stage (node) within the sequence, including input/output data and operational latency.
</Callout>

***

## Workflow Tracing

### List Workflow Traces

Retrieve paginated execution traces for a workflow.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/workflow/{workflowId}/traces.json"
  params={[
  { name: "workflowId", type: "string", required: true, description: "Workflow identifier.", location: "path" },
  { name: "size", type: "integer", required: false, description: "Records per page (default 50, max 100).", location: "query" },
  { name: "page", type: "integer", required: false, description: "Page number starting from 1.", location: "query" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Trace list retrieved.",
    content: {
      "entities": "WorkflowTrace",
      "count": 2,
      "per_page": 50,
      "pages": { "current": 1, "max": 1 },
      "elements": [
        {
          "id": "6803f0f1...",
          "workflow_id": "67ffac1f...",
          "uuid": "d76d716e-0f91-4f7f-b37f-4475e573f807",
          "run_date": "2026-04-20T08:41:12+00:00",
          "status": "executed"
        }
      ]
    }
  },
  {
    status: "404 Not Found",
    description: "Workflow not found.",
    content: { "error": "This workflow does not exists" }
  }
]}
/>

### Get Workflow Trace

Load full trace payload for one workflow run.

<DonutApi
  method="GET"
  version="2026-02-01"
  endpoint="/workflow/{workflowId}/traces/{traceId}.json"
  params={[
  { name: "workflowId", type: "string", required: true, description: "Workflow identifier.", location: "path" },
  { name: "traceId", type: "string", required: true, description: "Trace identifier.", location: "path" }
]}
  responses={[
  {
    status: "200 OK",
    description: "Trace retrieved.",
    content: {
      "id": "6803f0f1...",
      "workflow_id": "67ffac1f...",
      "uuid": "d76d716e-0f91-4f7f-b37f-4475e573f807",
      "run_date": "2026-04-20T08:41:12+00:00",
      "status": "executed",
      "response": {
        "input": { "customer_id": "cust_9921" },
        "result": { "workflow_status": "executed" },
        "stages": [
          { "node_name": "validate_identity", "status": "SUCCESS", "duration": 0.1281 }
        ]
      }
    }
  },
  {
    status: "404 Not Found",
    description: "Trace not found for workflow.",
    content: { "error": "Trace not found for this workflow." }
  }
]}
/>


# Autenticazione e Governance Iframe



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';

# Autenticazione e Incorporamento

DonutWork utilizza un solido modello di sicurezza per garantire che le applicazioni di terze parti possano accedere ai dati in modo sicuro fornendo un'esperienza utente unificata. Questa guida copre il flusso di lavoro di Dual-Auth e i requisiti per l'incorporamento di Iframe di livello enterprise.

***

## 1. Il Flusso di Lavoro OAuth 2.0

Le applicazioni utilizzano un flusso standard OAuth 2.0 Authorization Code per ottenere l'accesso autorizzato ai dati di un'azienda.

<Steps>
  ### Step 1: Richiesta di Autorizzazione

  Rindirizza l'utente al server di autorizzazione di DonutWork. Ciò avviene quando un utente installa o accede alla tua app per la prima volta.

  **Endpoint**: `GET /i3/oauth/authorize`

  **Parametri**:

  * `client_id`: Il tuo identificativo univoco dell'applicazione.
  * `redirect_uri`: L'endpoint dove verrà inviato il codice.
  * `response_type`: Sempre `code`.
  * `scope`: Elenco (spazio o virgola) dei permessi nel formato canonico `resource:action` (es. `customers:read charges:write`).
  * requisito minimo `scope`: includere almeno `company:read` per completare correttamente il flusso di connessione OAuth delle app.
  * `state`: Una stringa univoca per prevenire attacchi CSRF.

  ### Step 2: Scambio del Token

  Una volta che l'utente approva la richiesta, DonutWork lo reindirizza al tuo `redirect_uri` con un `code`. Scambia immediatamente questo codice con un token di accesso.

  **Endpoint**: `POST /i3/oauth/token` (Form-Encoded)

  **Corpo**:

  * `client_id`: Il tuo identificativo dell'applicazione.
  * `client_secret`: Il tuo segreto protetto dell'applicazione.
  * `code`: Il codice di autorizzazione ricevuto nel reindirizzamento.
  * `redirect_uri`: Deve corrispondere all'URI utilizzato nello Step 1.

  ### Step 3: Persistenza

  Memorizza in modo sicuro i valori `access_token` e `refresh_token` restituiti. Questi token consentono alla tua app di effettuare chiamate API dirette a DonutWork (es. a `/2026-02-01/customers.json`).
</Steps>

***

## 2. Contesto Iframe e Sicurezza

Quando un'applicazione viene renderizzata all'interno della dashboard di DonutWork, viene incorporata tramite un Iframe. Ogni richiesta al punto di ingresso della tua applicazione include una firma di sicurezza.

### Parametri della Richiesta

DonutWork aggiunge i seguenti parametri di query all'URL della tua applicazione:

* `company`: L'identificativo univoco dell'azienda attiva.
* `hmac`: Una firma crittografica della richiesta.
* `timestamp`: Il timestamp Unix della richiesta.

### Verifica della Firma (HMAC-SHA256)

Per verificare che la richiesta sia autentica e provenga da DonutWork, è necessario convalidare il parametro `hmac` utilizzando il tuo `client_secret`.

**Procedura di Verifica**:

1. Rimuovi il parametro `hmac` dalle coppie chiave-valore.
2. Ordina alfabeticamente i parametri rimanenti per chiave.
3. Concatena le chiavi e i valori ordinati in una stringa di query (es. `company=C123&timestamp=1740000000`).
4. Calcola l'HMAC-SHA256 di questa stringa utilizzando il tuo `client_secret` come chiave.
5. Confronta il risultato con l' `hmac` fornito.

<Tabs items={["Javascript", "Pseudo-Codice"]}>
  <Tab value="Javascript">
    ```js
    const crypto = require('crypto');

    function verifyHmac(queryParams, clientSecret) {
      const { hmac, ...params } = queryParams;
      const message = Object.keys(params)
        .sort()
        .map(key => `${key}=${params[key]}`)
        .join('&');

      const expectedHmac = crypto
        .createHmac('sha256', clientSecret)
        .update(message)
        .digest('hex');

      return hmac === expectedHmac;
    }
    ```
  </Tab>

  <Tab value="Pseudo-Codice">
    ```text
    1. ARGS = QueryString.Remove("hmac")
    2. SORTED_MSG = ARGS.SortByKey().Join("&")
    3. SIGNATURE = HMAC_SHA256(SORTED_MSG, APP_CLIENT_SECRET)
    4. VALIDATE(SIGNATURE == QueryString["hmac"])
    ```
  </Tab>
</Tabs>

***

## 3. Requisiti di Integrazione UI

Poiché l'applicazione viene eseguita in un Iframe cross-site, si applicano le policy standard di sicurezza del browser.

### Gestione della Sessione

I browser moderni bloccano i cookie di terze parti per impostazione predefinita. Per mantenere una sessione all'interno dell'Iframe, i cookie di sessione **devono** utilizzare i seguenti attributi:

* `SameSite=None`: Consente l'invio del cookie in un contesto cross-site.
* `Secure=true`: Richiesto quando viene utilizzato `SameSite=None`.

<Callout type="warning">
  Se i tuoi cookie non hanno `SameSite=None; Secure`, gli utenti verranno disconnessi immediatamente dopo il reindirizzamento o durante la navigazione all'interno dell'app.
</Callout>

### Content Security Policy (CSP)

Assicurati che gli header del tuo server consentano a DonutWork di incorporare la tua applicazione:

```http
Content-Security-Policy: frame-ancestors 'self' https://hub.donutwork.com;
X-Frame-Options: ALLOW-FROM https://hub.donutwork.com
```

***

## 4. Scoperta delle Funzionalità

Come fase finale del flusso di autenticazione, la tua applicazione dovrebbe dichiarare le sue "capability" alla piattaforma. Ciò consente a DonutWork di effettuare il proxy delle richieste alla tua app (Azioni).

**Azione**: `PUT /2026-02-01/integrations.json`

Questa dichiarazione dovrebbe includere il tuo `app_token` (utilizzato da DonutWork per chiamarti) e un manifesto degli endpoint supportati. Fai riferimento alla [Guida alla Scoperta delle Applicazioni](/it/docs/applications/how-to-build#2-scoperta-delle-funzionalità-il-manifesto) per i dettagli.

Per i dettagli del flusso di disinstallazione (`DELETE uninstall_url` con `company_id` + HMAC `verify`), vedi [Come costruire](/it/docs/applications/how-to-build).


# Donutwork Claude Code Skill



import { Callout } from 'fumadocs-ui/components/callout';

# Donutwork Claude Code Skill

Il bundle ufficiale per Claude Code e' pensato per i team che usano Claude Code come copilota implementativo nelle integrazioni Donutwork.
Fornisce contesto operativo pronto all'uso per passare dalla discovery API al rilascio in produzione con meno rework.

***

## Perche' i Team la Adottano

* Accelera la delivery con uno `SKILL.md` strutturato.
* Riduce errori sugli scope grazie a mappe endpoint e ACL.
* Migliora la qualita' dei payload con modelli entita' a livello campo.
* Standardizza l'implementazione AI-assisted tra team diversi.

***

## Cosa Include

* `.claude/skills/donutwork/SKILL.md`: istruzioni della skill Claude Code e workflow operativo.
* `references/api-endpoint-map.json`: inventario metodo/percorso/scope.
* `references/entity-models.json`: catalogo modelli entita' a livello campo.
* `references/openapi.public.json`: snapshot OpenAPI per tooling.
* `references/integration-playbook.md`: blueprint implementativo e lancio.

***

## Download

* Pacchetto latest (`.skill`): [`/downloads/donutwork-claude-code-skill-latest.skill`](/downloads/donutwork-claude-code-skill-latest.skill)
* Checksum latest: [`/downloads/donutwork-claude-code-skill-latest.sha256`](/downloads/donutwork-claude-code-skill-latest.sha256)
* Pacchetto versionato (`v1.1.0`): [`/downloads/donutwork-claude-code-skill-v1.1.0.skill`](/downloads/donutwork-claude-code-skill-v1.1.0.skill)
* Checksum versionato (`v1.1.0`): [`/downloads/donutwork-claude-code-skill-v1.1.0.sha256`](/downloads/donutwork-claude-code-skill-v1.1.0.sha256)

***

## Installazione In 60 Secondi

```bash
unzip -o donutwork-claude-code-skill-latest.skill -d "$HOME"
```

Verifica integrita' (opzionale):

```bash
sha256sum -c donutwork-claude-code-skill-latest.sha256
```

<Callout type="info">
  Questo pacchetto installa `.claude/skills/donutwork/SKILL.md` e i riferimenti sotto home, cosi Claude Code puo' auto-scoprire la skill.
</Callout>

***

## Prompt Rapidi

1. `Map required scopes for customers, charges, and webhooks in our Donutwork integration.`
2. `Generate payload contracts for customer and subscription synchronization.`
3. `Prepare a production readiness checklist for our Donutwork API launch.`

***

## Prossimi Passi

* Parti da [AI Integration Hub](/it/docs/ai-integration) per il percorso completo AI-first.
* Se il tuo team usa Codex, vedi [Donutwork Codex Skill](/it/docs/applications/donutwork-skill).
* Usa [API Authentication](/it/docs/api/authentication) per validare setup key e OAuth.


# Skill Codex Donutwork



import { Callout } from 'fumadocs-ui/components/callout';

# Skill Codex Donutwork

La skill ufficiale `donutwork` per Codex e' un acceleratore pronto all'uso per team di prodotto e integrazione.
Trasforma la documentazione API in output implementabili: mappatura scope, modelli payload e checklist di rilascio.

***

## Perche' i Team la Adottano

* Riduce il tempo di onboarding API da giorni a ore.
* Migliora la sicurezza con guidance sugli scope a privilegio minimo.
* Standardizza i contratti payload tra team tecnici.
* Aumenta la confidenza al go-live con checklist ripetibili.

***

## Cosa Include

* `SKILL.md`: workflow operativo e formato risposta.
* `references/api-endpoint-map.json`: inventario metodo/percorso/scope.
* `references/entity-models.json`: catalogo modelli entita' a livello campo.
* `references/openapi.public.json`: snapshot OpenAPI per tooling.
* `references/integration-playbook.md`: blueprint implementativo e lancio.

***

## Download

* Pacchetto latest: [`/downloads/donutwork-skill-latest.tar.gz`](/downloads/donutwork-skill-latest.tar.gz)
* Checksum latest: [`/downloads/donutwork-skill-latest.sha256`](/downloads/donutwork-skill-latest.sha256)
* Pacchetto versionato (`v1.0.0`): [`/downloads/donutwork-skill-v1.0.0.tar.gz`](/downloads/donutwork-skill-v1.0.0.tar.gz)
* Checksum versionato (`v1.0.0`): [`/downloads/donutwork-skill-v1.0.0.sha256`](/downloads/donutwork-skill-v1.0.0.sha256)

***

## Installazione In 60 Secondi

```bash
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
tar -xzf donutwork-skill-latest.tar.gz -C "${CODEX_HOME:-$HOME/.codex}/skills"
```

Verifica integrita' (opzionale):

```bash
sha256sum -c donutwork-skill-latest.sha256
```

<Callout type="info">
  La cartella estratta si chiama `donutwork`, quindi puoi invocarla direttamente con `$donutwork`.
</Callout>

***

## Prompt Rapidi

1. `Use $donutwork to design an integration plan for syncing customers and subscriptions.`
2. `Use $donutwork to map required scopes for customer, charge, and webhook endpoints.`
3. `Use $donutwork to generate request payload models and a production go-live checklist.`

***

## Prossimi Passi

* Parti da [AI Integration Hub](/it/docs/ai-integration) per un percorso completo AI-first.
* Se il tuo team usa Claude Code, vedi [Donutwork Claude Code Skill](/it/docs/applications/donutwork-claude-code-skill).
* Usa [API Authentication](/it/docs/api/authentication) per validare API key e setup OAuth.
* Usa [API Reference](/it/docs/api) per estendere la copertura endpoint dopo il primo rilascio.


# Come Costruire un'App DonutWork



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

# Costruire per DonutWork

Questa guida fornisce un blueprint concettuale e tecnico per lo sviluppo di applicazioni di terze parti. Il framework DonutWork è esplicitamente **agnostico rispetto al linguaggio di programmazione**, basandosi su protocolli standard HTTP/REST e sull'incorporamento sicuro della UI per facilitare l'orchestrazione tra sistemi.

***

## 1. Registrazione dell'Applicazione

Prima di iniziare lo sviluppo, è necessario registrare l'applicazione per ottenere le credenziali necessarie per l'identità e l'accesso alla piattaforma.

* **Client ID**: L'identificativo pubblico della tua applicazione.
* **Client Secret**: Una credenziale sicura utilizzata per autorizzare la tua app ad agire per conto di un'azienda.
* **Redirect URI**: L'URL dove DonutWork invierà i codici di autorizzazione.

Consulta la [Guida Dettagliata OAuth](/it/docs/applications/auth-and-embedding) per l'handshake tecnico di autenticazione.

***

## 2. Scoperta delle Funzionalità (Il Manifesto)

DonutWork utilizza un **Discovery Pattern** per comprendere le capacità della tua applicazione. Invece di chiamare la tua app alla cieca, la tua app deve "dichiarare" le sue funzionalità (Azioni).

### Dichiarazione delle Funzionalità

La tua applicazione deve inviare una richiesta `PUT` all'endpoint `/integrations.json`. Questo manifesto comunica a DonutWork quali endpoint chiamare quando viene attivata un'azione specifica (ad esempio, tramite un Workflow o la UI).

<DonutApi
  method="PUT"
  version="2026-02-01"
  endpoint="/integrations.json"
  body={{
  "app_token": "YOUR_APP_SHARED_TOKEN",
  "capabilities": [
      {
          "name": "ping",
          "description": "Test della salute della connessione",
          "endpoint": "https://your-app.com/api/ping.json",
          "method": "GET",
          "inputs": []
      },
      {
          "name": "provision_resource",
          "description": "Creazione di una nuova risorsa",
          "endpoint": "https://your-app.com/api/provision.json",
          "method": "POST",
          "inputs": [
              { "name": "resource_name", "type": "string", "required": true }
          ]
      }
  ]
}}
/>

* **app\_token**: DonutWork includerà questo Bearer token in ogni header `Authorization` quando chiamerà la tua applicazione. Ciò consente alla tua app di verificare che la richiesta provenga da DonutWork.
* **capabilities**: Un array di azioni consentite, ciascuna con un `endpoint`, un `method` e gli `inputs` attesi.

***

## 3. Modello di Comunicazione (La Logica dell'Azione)

Quando un utente o un workflow generico attiva un'azione, DonutWork agisce come un **Proxy Sicuro**.

1. **Trigger**: DonutWork identifica l'azione di destinazione (es. `provision_resource`).
2. **Identificazione**: DonutWork recupera l' `endpoint` e l' `app_token` dal manifesto salvato.
3. **Esecuzione**: DonutWork invia una richiesta HTTP al tuo endpoint, includendo l' `app_token` nell'intestazione e i dati richiesti nel corpo.
4. **Risposta**: La tua applicazione elabora la richiesta e restituisce una risposta JSON standard.

***

## 4. Framework UI (L'Iframe)

DonutWork incorpora il frontend della tua applicazione all'interno della propria dashboard tramite un **Iframe**. Per garantire un'esperienza utente fluida e mantenere la sicurezza, è necessario rispettare le seguenti policy:

### Sicurezza dei Cookie (`SameSite=None`)

Poiché la tua applicazione è in esecuzione in un contesto Iframe (cross-site), i cookie di sessione tradizionali potrebbero essere bloccati dai browser moderni. È necessario configurare i cookie di sessione con:

* `SameSite=None`
* `Secure=true`

### Header di Sicurezza

DonutWork consente l'incorporamento di Iframe da applicazioni registrate. Da parte tua, dovresti assicurarti che i tuoi header consentano alla piattaforma di visualizzare i tuoi contenuti. Per approfondire la verifica della firma, vedi [Contesto Iframe e Sicurezza](/it/docs/applications/auth-and-embedding#2-iframe-context--security).

```http
Content-Security-Policy: frame-ancestors 'self' https://hub.donutwork.com;
X-Frame-Options: ALLOW-FROM https://hub.donutwork.com
```

***

## 5. Sincronizzazione degli Eventi (Webhook)

Per reagire agli eventi della piattaforma in tempo reale (ad esempio, quando un utente paga una fattura), dovresti registrare un Webhook.

1. **Endpoint**: La tua applicazione dovrebbe fornire un URL HTTPS dedicato per ricevere i payload POST.
2. **Rotazione delle Chiavi**: Durante la registrazione, riceverai un `token`. Usa questa chiave per verificare l'intestazione `X-SIGNATURE` su ogni richiesta in arrivo.

***

## 6. Callback di Disinstallazione (Pulizia Dati Company)

Quando una company disinstalla la tua app da DonutWork, la piattaforma invia una callback server-to-server verso l'`uninstall_url` configurata.

* **Metodo**: `DELETE`
* **Content-Type**: `application/x-www-form-urlencoded`
* **Body**:
  * `company_id`: identificativo della company da eliminare.
  * `verify`: firma HMAC calcolata come `HMAC_SHA256(company_id, client_secret)`.

Esempio payload:

```http
DELETE /uninstall HTTP/1.1
Content-Type: application/x-www-form-urlencoded

company_id=699ecb44790ac4eea20e9cd3&verify=7c72b2...
```

Regola di verifica lato app:

```php
$expected = hash_hmac('sha256', $companyId, $clientSecret);
$isValid = hash_equals($expected, $verify);
```

Requisiti implementativi:

* Valida `company_id` e `verify` prima di qualsiasi cancellazione.
* Elimina solo i dati tenant-scoped della `company_id` ricevuta.
* Rendi l'endpoint idempotente (chiamate ripetute non devono fallire).
* Restituisci `2xx` solo quando la pulizia e' completata (o gia' completata).

Se il tuo endpoint restituisce status non-2xx, DonutWork considera fallita la callback di uninstall e blocca la disinstallazione locale.

***

## Elenco di Controllo Riassuntivo

* [ ] Registra l'App e ottieni Client ID/Secret.
* [ ] Implementa OAuth 2.0 per ottenere i Platform Access Tokens.
* [ ] Usa `PUT /integrations.json` per dichiarare gli endpoint della tua app.
* [ ] Implementa i tuoi endpoint API per gestire le richieste dal proxy DonutWork.
* [ ] Configura i cookie `SameSite=None` e `Secure` per la tua UI in Iframe.
* [ ] Registra i Webhook per l'elaborazione degli eventi in tempo reale.
* [ ] Implementa `DELETE uninstall_url` con `company_id` + HMAC `verify` e cleanup tenant-safe.


# Framework Applicazioni



import { 
  Puzzle, 
  Settings, 
  Zap, 
  Shield,
  Package
} from 'lucide-react';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';

Il Framework Applicazioni di DonutWork consente agli sviluppatori di estendere le funzionalità principali della piattaforma con servizi specializzati di terze parti. Che tu stia costruendo un connettore finanziario, uno strumento di automazione del marketing o un'integrazione CRM personalizzata, il nostro framework fornisce gli hook necessari per un'orchestrazione senza interruzioni.

***

## Architettura di Integrazione

Le applicazioni DonutWork operano su un modello ibrido che combina l'incorporamento sicuro dell'interfaccia utente (UI) con una solida scoperta delle funzionalità guidata dalle API.

<div className="grid grid-cols-1 md:grid-cols-2 gap-6 mt-10">
  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#7ABA23]/50 transition-all group">
    <Puzzle size={40} className="text-[#7ABA23] mb-4" />

    ### Scoperta delle Funzionalità

    **Registrazione Autonoma.** Le applicazioni dichiarano le loro "Azioni" disponibili tramite un manifesto JSON standard. DonutWork rende quindi queste azioni disponibili al motore principale e ai workflow.
    [Come costruire →](/it/docs/applications/how-to-build)
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#FECC55]/50 transition-all group">
    <Settings size={40} className="text-[#FECC55] mb-4" />

    ### Incorporamento Iframe

    **Esperienza UI Unificata.** Le app sono incorporate direttamente nella dashboard di DonutWork. Ciò garantisce un'esperienza utente coerente mantenendo il contesto di esecuzione indipendente dell'app.
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#7ABA23]/50 transition-all group">
    <Zap size={40} className="text-[#7ABA23] mb-4" />

    ### Hook Orientati agli Eventi

    **Sincronizzazione in Tempo Reale.** Usa i Webhook per reagire agli eventi del ciclo di vita della piattaforma (addebiti, rinnovi, cambi di identità) e mantenere l'integrità dei dati tra i sistemi.
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#FECC55]/50 transition-all group">
    <Shield size={40} className="text-[#FECC55] mb-4" />

    ### Sicurezza Zero-Trust

    **Autorizzazione Gestita.** DonutWork agisce come un proxy sicuro, gestendo l'autorizzazione tra la piattaforma e la tua applicazione con richieste firmate e token con ambito limitato.
  </div>

  <div className="p-8 rounded-[2rem] border border-white/5 bg-zinc-900/40 hover:border-[#7ABA23]/50 transition-all group">
    <Package size={40} className="text-[#7ABA23] mb-4" />

    ### Skill Codex per Integrazioni

    **Implementazione Più Veloce.** Scarica il pacchetto ufficiale della skill `donutwork` con mappa endpoint, modelli entita' e checklist di rilascio.
    [Scarica la skill →](/it/docs/applications/donutwork-skill)
  </div>
</div>

***

## Roadmap per gli Sviluppatori

La creazione di un'applicazione per DonutWork prevede le seguenti fasi chiave:

<Steps>
  ### Registrazione e Autenticazione

  Fornisci la tua applicazione nel Portale Sviluppatori per ottenere un `Client ID` e un `Client Secret` univoci. Usali per implementare il flusso standard [OAuth 2.0 flow](/it/docs/applications/auth-and-embedding).

  ### Dichiarazione delle Funzionalità

  Chiama l'endpoint `/integrations.json` per comunicare a DonutWork cosa può fare la tua app. Questo manifesto definisce i tuoi endpoint, i metodi supportati e i dati di input richiesti.

  ### Implementazione del Ciclo di Vita e dell'Interfaccia Utente

  Costruisci il frontend della tua applicazione, garantendo la compatibilità con il nostro [sistema di incorporamento basato su Iframe](/it/docs/applications/auth-and-embedding#2-iframe-context--security) e le policy di sicurezza (come i requisiti dei cookie `SameSite`).

  ### Prontezza per la Produzione

  Configura i token di sicurezza dei tuoi webhook e distribuisci il tuo servizio in un ambiente di produzione.
</Steps>


# Business Intelligence & Growth



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { TrendingUp, PieChart, Activity, Zap } from 'lucide-react';

# Business Intelligence & Growth

La sezione BI & Growth di Donutwork è progettata per darti una visione cristallina della salute economica del tuo progetto. Non dovrai più incrociare fogli di calcolo: tutto è calcolato automaticamente in tempo reale.

## Metriche Chiave Monitorate

Donutwork aggrega i dati provenienti dal motore di billing e dalle interazioni utenti per offrirti KPI precisi:

<Cards>
  <Card icon={<TrendingUp className="text-blue-500" />} title="MRR & ARR" description="Visualizza i ricavi ricorrenti mensili e annuali con proiezioni di crescita basate sullo storico." />

  <Card icon={<PieChart className="text-purple-500" />} title="Revenue Mix" description="Analisi dettagliata tra ricavi ricorrenti (abbonamenti) e ricavi one-time (add-on, setup fee)." />

  <Card icon={<Activity className="text-green-500" />} title="Growth Rate" description="Monitoraggio della crescita MoM (Month-over-Month) per validare la tua strategia di marketing." />
</Cards>

***

## Analisi dei Ricavi

Donutwork separa intelligentemente le diverse fonti di entrata per permetterti di capire cosa sta guidando davvero la tua crescita.

### Analytics Real-time

Appena accedi alla dashboard, avrai un colpo d'occhio su:

* **Transazioni Recenti:** Storico in tempo reale di ogni acquisto o rinnovo.
* **Customer Lifetime Value (LTV):** Calcolo automatico di quanto vale mediamente un cliente nel tempo.

***

## Strategie di Growth

Utilizza i dati raccolti per alimentare i tuoi processi di crescita:

* **Identifica i Power Users:** Scopri quali clienti sono più costanti e/o in crescita e proponi upgrade a piani superiori.
* **Prevenzione Churn:** Monitora i cali di attività repentini nei tassi di subscription per intervenire prima che l'utente disdica l'abbonamento.
* **Partner Performance:** Incrocia i dati della BI con il [Programma Partner](/it/docs/partner-program) per vedere quali affiliati portano i clienti con il LTV più alto.

***

## Ritmo Operativo Consigliato

Trasforma la BI in decisioni con una cadenza fissa:

1. Ogni settimana: controlla rinnovi falliti e segnali di churn.
2. Ogni due settimane: confronta la retention per coorte e canale acquisizione.
3. Ogni mese: aggiorna pricing, incentivi partner e packaging dei piani in base a margine e LTV.

<Callout type="info" title="Playbook cross-team">
  Per ottenere il massimo, leggi i report BI insieme ai referenti di Customer, Pagamenti Ricorrenti e Programma Partner prima di rilasciare modifiche commerciali.
</Callout>

## Aree Correlate

* [Pagamenti Ricorrenti](/it/docs/recurring-payments)
* [Customer Management](/it/docs/customer)
* [Programma Partner](/it/docs/partner-program)


# Customer Management & Hub Finanziario



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { 
  Users, 
  Fingerprint, 
  CreditCard, 
  Tags, 
  TrendingUp, 
  ShieldAlert, 
  Receipt,
  Layers
} from 'lucide-react';

# Gestione Clienti e Hub Finanziario

Il modulo **Customer** di Donutwork non è solo un database di contatti, ma un centro di controllo finanziario per ogni singolo cliente. Permette di monitorare la salute del business attraverso metriche predittive e di gestire l'intero ciclo di vita dei pagamenti.

## Customer Financial Scorecard (Beta)

Per ogni cliente con almeno una transazione, Donutwork genera automaticamente uno **scorecard finanziario** che aiuta a valutare la stabilità e la crescita:

<Cards>
  <Card icon={<TrendingUp className="text-green-500" />} title="MRR & YRR" description="Calcolo istantaneo del Monthly Recurring Revenue e proiezione annuale basata sugli abbonamenti attivi." />

  <Card icon={<ShieldAlert className="text-red-500" />} title="Risk Assessment" description="Analisi della volatilità e durata dello storico per assegnare una classe di rischio al cliente." />
</Cards>

***

## Gestione Abbonamenti e Add-ons

Donutwork permette una gestione granulare delle ricorrenze direttamente dal profilo cliente:

* **Associazione Piani:** Collega rapidamente nuovi piani di abbonamento esistenti al profilo.
* **Modifica Add-ons:** Gestione dinamica delle quantità e dei prezzi per i componenti aggiuntivi di una sottoscrizione.
* **Agevolazioni Fiscali:** Applicazione di sconti globali (percentuali o fissi) e gestione di diverse aliquote IVA per riga di servizio.
* **Metering:** Monitoraggio dei consumi per i piani basati sull'utilizzo (Metered Billing).

***

## Pagamenti e Transazioni

L'interfaccia divide le attività finanziarie in tre sezioni principali tramite un sistema a tab persistenti:

### 1. Metodi di Pagamento

Gestione delle carte di credito associate (via Stripe). Il sistema supporta:

* **Secure Payment Links:** Generazione di link protetti per permettere al cliente di inserire i propri dati di pagamento in autonomia.
* **Validazione CVC/3DS:** Verifica in tempo reale dello stato di sicurezza del metodo di pagamento.

### 2. Transazioni (Charges)

Storico completo di ogni addebito effettuato o tentato:

* **Creazione Manuale:** Possibilità di creare "One-time charges" (es. costi di setup o consulenza) direttamente dal pannello.
* **Ricevute e Log:** Accesso immediato ai PDF delle ricevute e monitoraggio dello stato (Pending, Succeeded, Failed).

### 3. Sottoscrizioni

Tab dedicato per il controllo dei piani attivi, date di rinnovo e stato del provisioning.

***

## Proprietà Dinamiche (Custom Fields)

Oltre ai dati finanziari, puoi estendere l'anagrafica tramite le **Customer Properties**. Questi metadati sono fondamentali per:

* Configurare limiti API personalizzati per singolo cliente.
* Salvare preferenze specifiche del workflow.
* Mappare ID esterni per integrazioni con sistemi di terze parti.


# Directory Monitor & Automazione Eventi



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import {
  FolderSearch,
  ShieldCheck,
  Activity,
  Workflow,
  FileSearch,
  Timer,
  Fingerprint,
  Zap
} from 'lucide-react';

# Directory Monitor

Il Directory Monitor di Donutwork è un modulo nativo di **sicurezza + automazione** che traccia le attività sui file nelle cartelle osservate e trasforma questi eventi in azioni automatiche.

È pensato per team che hanno bisogno di:

1. Raccolta affidabile degli eventi filesystem
2. Visibilità centralizzata degli eventi
3. Trigger deterministici dei workflow

***

## Architettura del Sistema

Il modulo è composto da quattro livelli connessi:

1. **Agente Locale (Rust):** osserva le directory ed emette eventi normalizzati (`Create`, `Delete`, `WriteFinished`).
2. **API di Ingress Sicura:** riceve i payload del monitor, valida l'autenticazione e deduplica tramite `eventId`.
3. **Event Store:** persiste gli eventi con indici per ricerca operativa e forense.
4. **Workflow Dispatcher:** pubblica trigger sia generici sia tipizzati per eseguire i workflow compatibili.

<Callout type="info" title="Compatibilità Retroattiva">
  I trigger generici restano supportati: <code>DirectoryMonitor.\{projectId}.notify</code>.
  Puoi adottare gradualmente i trigger tipizzati come <code>DirectoryMonitor.\{projectId}.WriteFinished.notify</code>.
</Callout>

***

## Pipeline Eventi

Quando un file cambia, accade quanto segue:

1. Il monitor invia un payload con metadati evento (`filename`, `event`, `filesize`, opzionali `sha256`, `uid`, `pid`, `timestampUtc`, `eventId`).
2. L'ingress valida:
   * API key (`Authorization: Bearer ...`)
   * Token di progetto (`X-Directory-Monitor-Token`)
3. L'evento viene salvato nella collection eventi del monitor.
4. Vengono pubblicate due notifiche:
   * Generica: `DirectoryMonitor.{projectId}.notify`
   * Tipizzata: `DirectoryMonitor.{projectId}.{event}.notify`
5. I workflow corrispondenti vengono messi in coda ed eseguiti tramite la pipeline async esistente.

***

## Log e Osservabilità

Il Directory Monitor include una **vista Log** dedicata per progetto con:

1. Filtri per:
   * Tipo evento
   * Path contiene
   * Stato
   * Intervallo date
2. Lista paginata con:
   * Timestamp
   * Tipo evento
   * Percorso file
   * Dimensione file
   * Badge stato workflow (`queued`, `workflow_triggered`, `workflow_failed`)
3. Link diretti alle trace dei workflow correlati.

<Callout type="info" title="Retention">
  Gli eventi sono salvati con indice TTL (default 90 giorni).
</Callout>

***

## Modello di Trigger Workflow

Per automazioni ad alta precisione, usa i trigger tipizzati:

| Trigger                                             | Scopo                                               | Esempio                                      |
| :-------------------------------------------------- | :-------------------------------------------------- | :------------------------------------------- |
| `DirectoryMonitor.{projectId}.WriteFinished.notify` | Esegue solo dopo la stabilizzazione della scrittura | Avvio scansione malware a upload completato  |
| `DirectoryMonitor.{projectId}.Create.notify`        | Reagisce alla creazione di oggetti                  | Tag/classificazione automatica di nuovi file |
| `DirectoryMonitor.{projectId}.Delete.notify`        | Rileva cancellazioni                                | Alert su rimozioni inattese                  |
| `DirectoryMonitor.{projectId}.notify`               | Trigger generico legacy                             | Compatibilità con workflow esistenti         |

***

## Controlli di Sicurezza

L'ingress del monitor è protetto da controlli a più livelli:

1. **Autenticazione API key aziendale**
2. **Validazione token segreto a livello progetto**
3. **Validazione payload sui campi obbligatori**
4. **Deduplica idempotente tramite `eventId` univoco**

Questo approccio garantisce isolamento tra progetti mantenendo il comportamento attuale del gateway API.

***

## Pattern di Automazione Reali

<Cards>
  <Card icon={<FileSearch className="text-blue-500" />} title="Controlli di Compliance File" description="Su WriteFinished esegui workflow di validazione (policy hash, naming convention, controlli estensione)." />

  <Card icon={<ShieldCheck className="text-green-500" />} title="Risposta di Sicurezza" description="Attiva scansione, quarantena e alert quando compaiono file sospetti nelle cartelle monitorate." />

  <Card icon={<Workflow className="text-yellow-500" />} title="Automazione Business" description="Lancia pipeline di ingestione, enrichment e webhook automatici a partire da eventi filesystem." />
</Cards>

***

## Panoramica Funzionalità

<Cards>
  <Card icon={<FolderSearch className="text-indigo-500" />} title="Monitoraggio Ricorsivo" description="Osserva interi alberi directory e cattura comportamenti di create, modify e delete." />

  <Card icon={<Timer className="text-cyan-500" />} title="Gestione Stabilità Scrittura" description="`WriteFinished` viene emesso dopo la finestra di stabilizzazione per evitare file parziali." />

  <Card icon={<Activity className="text-emerald-500" />} title="Heartbeat e Startup" description="I monitor inviano segnali di avvio e attività, utili per visibilità operativa per progetto." />

  <Card icon={<Fingerprint className="text-purple-500" />} title="Metadata Evento Ricchi" description="Allega `sha256`, `uid` e `pid` (quando disponibili) per audit e investigazioni più solide." />

  <Card icon={<Zap className="text-amber-500" />} title="Workflow Event-Driven" description="Collega direttamente gli eventi filesystem al motore workflow già presente in Donutwork." />
</Cards>


# Dynamic Content Modeling



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { 
  Layout, 
  Database, 
  FileJson, 
  Eye, 
  Settings, 
  FormInput 
} from 'lucide-react';

# Dynamic Content Modeling (Content Box)

Il sistema **Content Box** è progettato per eliminare la rigidità dei database tradizionali. Ti permette di creare dei "Modelli" (Types) che definiscono quali campi deve avere un contenuto, e successivamente di compilare tali contenuti tramite interfacce generate automaticamente.

## Il Concetto: Types vs Contents

Per comprendere il funzionamento, bisogna distinguere due livelli:

1. **Types (Lo Schema):** Definisci la struttura. Esempio: "Il tipo *Membro del Team* ha un nome, una foto, una bio e un ruolo."
2. **Contents (I Dati):** Crei le istanze basate sullo schema. Esempio: "Mario Rossi, Foto.jpg, CTO..."

***

## Tipi di Campi Supportati

Il **Fields Manager** di Donutwork offre una vasta gamma di input per coprire ogni esigenza di data-entry:

| Categoria    | Tipo di Input        | Utilizzo Tipico                                       |
| :----------- | :------------------- | :---------------------------------------------------- |
| **Testuale** | Standard Text        | Titoli, nomi brevi, etichette.                        |
|              | Long Text (Textarea) | Descrizioni, biografie, contenuti ricchi.             |
|              | Password / Secure    | Chiavi API, segreti o dati sensibili (mascherati).    |
|              | URL                  | Link esterni, riferimenti a social media.             |
| **Logica**   | Dropdown Select      | Scelta singola da una lista definita (es. Categoria). |
|              | Multi-select         | Tag, competenze, selezioni multiple.                  |
|              | Toggle / Checkbox    | Stati booleani (Sì/No, Attivo/Inattivo).              |

***

## Esempi di Strutture (Use Cases)

Ecco come puoi configurare i tuoi **Types** per diversi scenari comuni:

### 1. Sezione FAQ

* **Domanda:** Standard Text (Obbligatorio)
* **Risposta:** Long Text
* **Categoria:** Dropdown Select (Opzioni: *Billing, Tecnico, Account*)
* **In evidenza:** Toggle

### 2. Scheda Prodotto (SaaS)

* **Nome Prodotto:** Standard Text
* **Prezzo Mensile:** Standard Text (o Masked se è un ID di Stripe)
* **Feature List:** Multi-select
* **Documentazione URL:** URL Address
* **Stato:** Dropdown Select (*Beta, Stabile, Deprecato*)

### 3. Testimonial Clienti

* **Nome Cliente:** Standard Text
* **Azienda:** Standard Text
* **Citazione:** Long Text
* **Rating:** Dropdown Select (*1, 2, 3, 4, 5 stelle*)

***

## Gestione della Visibilità

Ogni **Content Box** può trovarsi in uno dei seguenti stati:

* 🟡 **Draft (Bozza):** Il contenuto è salvato ma non è accessibile dalle API pubbliche o dal frontend.
* 🟢 **Public (Pubblico):** Il contenuto è live e pronto per essere visualizzato.
* 🔴 **Private (Privato):** Visibile solo all'interno dell'area amministrativa di Donutwork, ideale per dati di configurazione interna.

***

## Funzionalità Avanzate

<Cards>
  <Card icon={<Settings className="text-blue-500" />} title="Generazione Automatica UI" description="Non devi creare i form. Appena modifichi lo schema di un Type, l'interfaccia di inserimento dati si aggiorna istantaneamente." />

  <Card icon={<Layout className="text-green-500" />} title="Ordinamento Drag & Drop" description="Puoi riordinare i campi nello schema per dare priorità visiva alle informazioni più importanti per il tuo team." />

  <Card icon={<FileJson className="text-purple-500" />} title="Headless-Ready" description="Tutti i dati salvati sono pronti per essere consumati tramite API in formato JSON, perfetti per React, Vue o Mobile App." />
</Cards>

<Callout type="info" title="Suggerimento per Sviluppatori">
  Ogni campo ha una **Internal Key (DB)**. Usa nomi chiari e in `snake_case` (es. `hero_image_url`) perché sarà la chiave che troverai nel JSON restituito dalle API di Donutwork.
</Callout>


# Email Gateway



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { Palette, Settings, ShieldCheck } from 'lucide-react';

# Email Gateway

Il modulo **Email Gateway** di Donutwork è l'infrastruttura completa per la gestione delle email del tuo SaaS. Non si occupa solo dell'invio, ma copre l'intero ciclo di vita di una comunicazione: dalla configurazione dei record DNS alla progettazione visuale dei template.

<Cards>
  <Card icon={<Palette className="text-blue-500" />} title="Template Design" href="/it/docs/email-gateway/template" description="Crea email professionali con l'editor Drag & Drop o scrivi il tuo codice HTML personalizzato." />

  <Card icon={<Settings className="text-green-500" />} title="Configurazione SMTP" href="/it/docs/email-gateway/settings" description="Configura i tuoi server di invio (Custom SMTP) o utilizza l'infrastruttura condivisa di Donutwork." />

  <Card icon={<ShieldCheck className="text-purple-500" />} title="Deliverability" href="/it/docs/email-gateway/settings" description="Proteggi la tua reputazione mittente configurando correttamente SPF e DKIM." />
</Cards>

***

## Funzionalità Chiave

### 1. Visual & Code Editor

Scegli come lavorare. Il **Mail Designer** visuale (basato su GrapesJS) permette a chiunque di creare layout responsivi. Per gli sviluppatori, l'**Ace Editor** integrato offre il controllo totale sul codice sorgente, con anteprima in tempo reale.

### 2. Gestione Multi-Mittente

Definisci **Alternative Senders** per inviare comunicazioni da dipartimenti diversi (es. `supporto@`, `amministrazione@`, `info@`) senza dover configurare server SMTP multipli.

### 3. Integrazione Nativa

I template salvati nel Gateway sono immediatamente disponibili in tutta la piattaforma:

* **Workflow:** Invia email automatiche trascinando un semplice nodo.
* **API:** Richiama i template tramite endpoint REST passando variabili dinamiche.

***

## Guide Rapide

L'Email Gateway è diviso in due aree principali:

### [Gestione Template & Design](/it/docs/email-gateway/template)

Scopri come creare nuovi file, organizzare la libreria dei template e utilizzare il designer per rendere le tue email perfette su ogni dispositivo.

### [Impostazioni & Consegna](/it/docs/email-gateway/settings)

Impara a configurare il tuo server SMTP personalizzato, a validare la connessione con lo strumento di test e a impostare i record DNS necessari per evitare che le tue email finiscano in SPAM.

## Sequenza Consigliata Di Go-Live

1. Configura SMTP e autenticazione DNS.
2. Crea almeno un template transazionale e uno operativo.
3. Esegui test di recapito da ambienti di staging.
4. Collega gli invii ai flussi di [Workflow](/it/docs/workflow) e alle chiamate API.

***

<Callout type="info" title="Consiglio Pro">
  Usa sempre la funzione **Test Email** dopo aver modificato le impostazioni SMTP o i record DNS per assicurarti che la configurazione sia valida prima di inviare comunicazioni ai tuoi clienti.
</Callout>


# Settings & Deliverability



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';

# Configurazione Email e Deliverability

Per garantire che le tue email non finiscano nella cartella spam, Donutwork offre strumenti avanzati per la configurazione dei server di invio e l'autenticazione del dominio.

## Impostazioni SMTP

Donutwork ti permette di scegliere tra due modalità di invio:

1. **System SMTP:** Utilizza l'infrastruttura predefinita di Donutwork per un setup immediato.
2. **Custom SMTP:** Configura i tuoi server (es. SendGrid, Mailgun, Amazon SES) inserendo Host, Porta, Username e Password.

***

## Autenticazione del Dominio (SPF & DKIM)

La sicurezza è fondamentale per la consegna delle email. Sentinel e il Gateway Email lavorano insieme per proteggere il tuo dominio.

### Record SPF

Per autorizzare Donutwork a inviare email a tuo nome, aggiungi il seguente valore al tuo record SPF nel DNS:
`include:_spf_hosted.donutwork.com`

### Enforce DKIM

Il DKIM aggiunge una firma digitale alle tue email. Per abilitarlo:

1. Attiva l'opzione **Enforce DKIM** nelle impostazioni.
2. Aggiungi un record **CNAME** nel tuo DNS:
   * **Host:** `donutwork._domainkey.TUO_DOMINIO`
   * **Target:** `smtp._domainkey.donutwork.com`

***

## Mittenti Alternativi (Alternative Senders)

Non sei limitato a un unico indirizzo di invio. Puoi configurare diversi mittenti per scopi differenti:

* `support@yourbrand.com` per l'assistenza.
* `billing@yourbrand.com` per le fatture.
* `newsletter@yourbrand.com` per il marketing.

Ogni mittente può avere un **Nome Visualizzato** personalizzato per aumentare la fiducia dell'utente finale.

***

## Email Tester

Prima di andare in produzione, utilizza il modulo **Email Tester** integrato. Inserisci il tuo indirizzo email e invia un messaggio di prova per verificare istantaneamente se la configurazione SMTP e i record DNS sono corretti.

<Callout type="info" title="Test della Connessione">
  Usa il pulsante **Test Connection** dopo aver inserito i dati SMTP per ricevere un feedback immediato sulla raggiungibilità del server prima di salvare le impostazioni.
</Callout>

***

## Prossimi Passi

<Cards>
  <Card title="Crea Template" href="/it/docs/email-gateway/template" description="Ora che l'invio è configurato, inizia a creare i tuoi template grafici." />
</Cards>


# Gateway & Templates



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Palette, Code } from 'lucide-react';

# Email Gateway

Donutwork centralizza la comunicazione via email del tuo SaaS. Grazie al sistema di template, puoi separare la logica di invio (nel tuo codice o nei [Workflow](/it/docs/workflow)) dal design grafico, permettendo al team marketing di aggiornare i contenuti senza l'intervento degli sviluppatori.

## Due Modalità di Editing

Donutwork offre flessibilità totale nella creazione dei template, supportando due diversi approcci:

<Cards>
  <Card icon={<Palette className="text-blue-500" />} title="Visual Mail Designer" description="Editor drag-and-drop basato su GrapesJS per creare layout responsivi senza toccare una riga di codice." />

  <Card icon={<Code className="text-purple-500" />} title="Advanced Code Editor" description="Editor professionale (Ace Editor) con evidenziazione del codice per sviluppatori che necessitano di HTML/CSS personalizzato." />
</Cards>

***

## Gestione dei Template

Dalla dashboard principale puoi:

* **Creare Nuovi Template:** Definisci nomi file chiari (es. `welcome-email` o `invoice-receipt`).
* **Visual Designer:** Accedi tramite l'icona della tavolozza per un editing visuale con anteprima in tempo reale.
* **Modifica Codice:** Accedi tramite l'icona della matita per scrivere codice HTML puro.
* **Preview Rapida:** Visualizza come apparirà l'email sui diversi dispositivi prima di salvarla.

***

## Utilizzo nei Workflow

Una volta creato un template, puoi richiamarlo istantaneamente all'interno del modulo **Workflow**. Basta trascinare il nodo **Send Email** e selezionare il file desiderato dalla lista a discesa.

> **Regola dei Nomi:** I file devono seguire il pattern `[a-z0-9-]`. Esempio corretto: `newsletter-gennaio-2024`.

***

## Prossimi Passi

<Cards>
  <Card title="Configurazione SMTP" href="/it/docs/email-gateway/settings" description="Imposta i server di invio e proteggi la tua reputazione con DKIM e SPF." />

  <Card title="Workflow Email" href="/it/docs/workflow" description="Scopri come automatizzare l'invio di template basati su eventi utente." />
</Cards>


# Entità Addebito (Charge)



# Entità Addebito (Charge)

Un **Charge** (chiamato anche Transazione) rappresenta un saldo finanziario specifico associato a un **Customer**. Può essere generato automaticamente dal rinnovo di un abbonamento o creato manualmente per servizi una tantum.

## Utilizzo

L'entità Charge viene utilizzata per:

* Processare pagamenti ad-hoc per costi di setup, consulenza o hardware.
* Archiviare lo storico degli eventi di fatturazione ricorrente.
* Gestire l'associazione con documenti legali (fatture e ricevute).
* Tracciare in tempo reale lo stato del pagamento (Pending, Paid, Refunded).

## Flusso Atteso

Ciclo di vita di una transazione finanziaria manuale:

<Mermaid
  chart="graph TD
    A[Inizio: Genera Costo Ad-hoc] --> B[Crea Charge One-shot]
    B --> C{Acquisizione Immediata?}
    C -- Sì --> D[Tenta Elaborazione Pagamento]
    C -- No --> E[Attendi Azione Cliente]
    D --> F{Pagamento Riuscito?}
    E --> D
    F -- Sì --> G[Genera Numero Fattura]
    F -- No --> H[Log Fallimento & Contesto Retry]
    G --> I[Allega Link PDF al Charge]
    I --> J[Fine: Transazione Completata]"
/>

1. **Generazione**: Crea l'oggetto charge con una o più righe di servizio.
2. **Esecuzione**: Se il `capture` è abilitato, il sistema utilizza il metodo di pagamento predefinito del cliente.
3. **Adempimento**: Dopo il successo, i dettagli formali della fattura vengono allegati per la sincronizzazione contabile.

***

## Schema Dati

I campi che definiscono un oggetto Charge:

| Campo         | Tipo     | Descrizione                                                    |
| :------------ | :------- | :------------------------------------------------------------- |
| `id`          | `eid`    | Identificativo univoco esteso.                                 |
| `customer_id` | `string` | Il proprietario della transazione.                             |
| `total`       | `number` | Totale netto della transazione (comprensivo di tasse).         |
| `status`      | `string` | Stato corrente: `pending`, `paid`, `refunded`, `failed`.       |
| `services`    | `array`  | Elenco degli articoli addebitati con relativi profili fiscali. |
| `invoice`     | `object` | Metadati per la contabilità (numero, data, link esterno).      |
| `date`        | `object` | Timestamp preciso dell'evento di creazione.                    |

***

## Grafo delle Chiamate (Relationship)

Come i Charge interagiscono con i gateway di pagamento esterni:

<Mermaid
  chart="sequenceDiagram
    participant App as Tua Applicazione
    participant DW as DonutWork API
    participant Stripe as Stripe Gateway
    
    App->>DW: POST /charges (con capture: true)
    DW->>Stripe: Auth & Capture (usando CC predefinita)
    Stripe-->>DW: Stato: Riuscito
    DW->>DW: Aggiorna Stato a 'paid'
    DW->>App: Webhook: Charge.Paid
    App->>DW: PUT /charges/{id}/invoice (Sincronizza Dati Fattura)
    DW-->>App: Acquisito"
/>


# Entità Cliente



import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { User, Key, CreditCard, Play } from 'lucide-react';

# Entità Cliente

Il **Customer** è il nodo centrale dell'ecosistema DonutWork. Rappresenta l'entità legale o l'individuo che consuma i tuoi servizi e genera fatturato.

## Utilizzo

L'entità Customer viene utilizzata per:

* Tracciare le informazioni di contatto e di fatturazione.
* Associare abbonamenti ricorrenti e addebiti una tantum.
* Memorizzare metadati personalizzati tramite proprietà dinamiche per un'integrazione profonda con la tua piattaforma.
* Monitorare il rischio finanziario e la salute del business (MRR/YRR).

## Flusso Operativo Atteso

Per gestire correttamente l'onboarding e la fatturazione di un cliente, segui questo flusso logico:

<Steps>
  <Step>
    ### Inizializzazione Identità

    Crea l'entità tramite l'endpoint `POST /customers.json`. Assegna un `externalId` univoco dal tuo database interno per mantenere una sincronizzazione perfetta tra i sistemi.
  </Step>

  <Step>
    ### Arricchimento del Contesto

    (Opzionale) Usa `PUT /customers/{id}/properties.json` per salvare dati specifici come tier di fatturazione, lingua preferita o quote API personalizzate.
  </Step>

  <Step>
    ### Onboarding Pagamento Sicuro

    Richiama `GET /customers/{id}/payment_link.json`. Questo genera un URL temporaneo: reindirizza l'utente a questa pagina per permettergli di inserire la carta di credito in modo sicuro e conforme PCI via Stripe.
  </Step>

  <Step>
    ### Attivazione e Billing

    Una volta che il metodo di pagamento è collegato (confermato via Webhook), attiva i servizi. Puoi associare una `Subscription` per ricavi ricorrenti o creare un `Charge` per costi una tantum.
  </Step>
</Steps>

***

## Schema Dati

La seguente tabella definisce la struttura principale dell'oggetto Customer:

| Campo          | Tipo     | Descrizione                                                        |
| :------------- | :------- | :----------------------------------------------------------------- |
| `id`           | `eid`    | Identificativo univoco esteso generato da DonutWork.               |
| `external_id`  | `string` | Il tuo identificativo di sistema interno.                          |
| `email`        | `string` | Email primaria di contatto e fatturazione.                         |
| `company_name` | `string` | Ragione sociale utilizzata per la fatturazione.                    |
| `address`      | `object` | Dati geografici (la nazione è obbligatoria per la logica fiscale). |
| `properties`   | `array`  | Coppie chiave-valore per dati di integrazione personalizzati.      |
| `status`       | `string` | `active`, `suspended`, o `deleted`.                                |

***

## Grafo delle Chiamate (Relationship)

Questo grafo illustra come l'entità Customer interagisce con gli altri componenti del sistema durante il suo ciclo di vita.

<Mermaid
  chart="sequenceDiagram
    participant App as Tua Applicazione
    participant DW as DonutWork API
    participant Provider as Payment Provider
    
    rect rgb(30, 30, 35)
    Note over App, Provider: Fase 1: Identità e Setup
    App->>DW: POST /customers (Crea)
    DW-->>App: Ritorna ID Cliente
    App->>DW: GET /customers/{id}/payment_link
    DW-->>App: Ritorna URL Ospitato
    end

    rect rgb(20, 40, 20)
    Note over App, Provider: Fase 2: Pagamento e Attivazione
    App->>Provider: Utente inserisce carta (Secure)
    Provider-->>DW: Webhook: Metodo Collegato
    DW->>App: Webhook: Pagamento Aggiornato
    App->>DW: POST /customers/{id}/subscriptions
    DW-->>App: Abbonamento Attivato
    end"
/>


# Entità Consegna Email



import { Steps, Step } from 'fumadocs-ui/components/steps';

# Entità Consegna Email

L'**Email Delivery** (o Email Job) rappresenta un singolo evento di comunicazione transazionale. Collega la logica della tua applicazione con l'infrastruttura SMTP professionale di DonutWork.

## Utilizzo

L'entità Email Delivery viene utilizzata per:

* Inviare email transazionali (ricevute, reset password) utilizzando template predefiniti.
* Iniettare dati dinamici in layout responsive tramite variabili.
* Distribuire documenti legali o tecnici come allegati sicuri.
* Orchestrare comunicazioni da mittenti multipli (Supporto, Billing, Sales).

## Flusso Operativo Atteso

L'invio di un'email sicura con allegati segue questo percorso operativo:

<Steps>
  <Step>
    ### Selezione del Template

    Identifica il `templateId` nel tuo Email Gateway. Questo definisce il layout visivo e i segnaposto (placeholder) disponibili per l'iniezione dei dati.
  </Step>

  <Step>
    ### Mapping Variabili e Contesto

    Prepara l'oggetto `vars` contenente i dati dinamici (es. nome cliente, numero ordine) che sostituiranno i segnaposto nel designer.
  </Step>

  <Step>
    ### Codifica Allegati

    Converti i tuoi file (PDF, CSV, Immagini) in stringhe **Base64**. DonutWork elabora queste stringhe per ricreare in modo sicuro gli allegati SMTP.
  </Step>

  <Step>
    ### Invio e Trasmissione

    Invia una richiesta `POST` all'endpoint di consegna. DonutWork valida l'identità del mittente, risolve le variabili, allega i file e trasmette tramite l'SMTP configurato.
  </Step>
</Steps>

***

## Schema Dati (Body JSON)

Il payload per un job di consegna email:

| Campo         | Tipo     | Descrizione                                                         |
| :------------ | :------- | :------------------------------------------------------------------ |
| `to`          | `string` | **Obbligatorio**. Indirizzo email del destinatario principale.      |
| `subject`     | `string` | **Obbligatorio**. L'oggetto dell'email.                             |
| `from`        | `string` | Opzionale. Deve corrispondere a uno dei tuoi "Alternative Senders". |
| `vars`        | `object` | Coppie chiave-valore per i placeholder nel template.                |
| `attachments` | `array`  | Elenco di oggetti allegato (vedi sotto).                            |
| `cc` / `bcc`  | `mixed`  | Stringa o array di destinatari aggiuntivi.                          |

### Oggetto Allegato

| Campo         | Tipo     | Descrizione                                        |
| :------------ | :------- | :------------------------------------------------- |
| `filename`    | `string` | Il nome visualizzato del file (es. `fattura.pdf`). |
| `type`        | `string` | Tipo MIME (es. `application/pdf`).                 |
| `content`     | `string` | Il contenuto del file codificato in **Base64**.    |
| `disposition` | `string` | `attachment` (default) o `inline`.                 |

***

## Grafo delle Chiamate (Relationship)

Come la tua app interagisce con il Gateway per inviare un documento:

<Mermaid
  chart="sequenceDiagram
    participant App as Tua Applicazione
    participant DW as DonutWork API
    participant SMTP as Server SMTP
    
    rect rgb(30, 30, 35)
    Note over App, DW: Fase 1: Preparazione Payload
    App->>App: Codifica PDF in Base64
    App->>DW: POST /email-gateway/{templateId}/send.json
    end

    rect rgb(20, 40, 20)
    Note over DW, SMTP: Fase 2: Elaborazione e Consegna
    DW->>DW: Caricamento Template HTML
    DW->>DW: Risoluzione {{vars}} con contesto
    DW->>DW: Associazione file Base64
    DW->>SMTP: Trasmissione SMTP
    SMTP-->>DW: Successo / MessageID
    DW-->>App: Ritorna successo + MessageID
    end"
/>


# Entità Partner



# Entità Partner

Un **Partner** rappresenta un'agenzia esterna, un rivenditore o un affiliato che gestisce il proprio bacino di clienti. I Partner sono classificati in **Gruppi** (Groups) per gestire commissioni a scaglioni e segmentazione dei servizi.

## Utilizzo

L'entità Partner viene utilizzata per:

* Segmentare la base clienti per agenzia o rivenditore.
* Gestire le strutture di commissione e lo storico dei pagamenti (payouts).
* Distribuire report e capacità di gestione a terze parti.

## Flusso Atteso

Segui questo flusso logico per stabilire un modello di rivendita basato sui partner:

<Mermaid
  chart="graph TD
    A[Inizio: Definisci Tier] --> B[Crea Gruppo Partner]
    B --> C[Crea Entità Partner]
    C --> D[Associa Gruppo a Partner]
    D --> E[Crea Cliente con ID Partner]
    E --> F[Genera Statistiche Partner]
    F --> G[Processa Payout Partner]"
/>

1. **Categorizzazione**: Usa i Partner Groups per definire livelli di servizio o scaglioni di sconto.
2. **Setup**: Crea l'identità del Partner con i propri dettagli legali di fatturazione.
3. **Attribuzione**: Quando crei un nuovo cliente, includi il `partner.id` per collegarlo formalmente.
4. **Monitoraggio**: Traccia le performance e la condivisione dei ricavi tramite il modulo statistiche.

***

## Schema Dati

I campi principali che definiscono un oggetto Partner:

| Campo         | Tipo     | Descrizione                                                      |
| :------------ | :------- | :--------------------------------------------------------------- |
| `id`          | `eid`    | Identificativo univoco esteso.                                   |
| `name`        | `string` | Ragione sociale del partner.                                     |
| `email`       | `string` | Indirizzo email principale per contatti e fatturazione.          |
| `group_id`    | `string` | ID del gruppo di classificazione assegnato.                      |
| `external_id` | `string` | Identificativo di riferimento del tuo sistema interno.           |
| `tags`        | `array`  | Etichette arbitrarie per filtri custom (es. 'gold', 'reseller'). |

***

## Grafo delle Chiamate (Relationship)

Come i Partner interagiscono con il flusso di onboarding dei clienti:

<Mermaid
  chart="sequenceDiagram
    participant App as Tua Applicazione
    participant DW as DonutWork API
    participant Partner as Portale Partner
    
    App->>DW: POST /partners (Crea Partner)
    Partner->>App: Invia Dati Nuovo Cliente
    App->>DW: POST /customers (con partner.id)
    DW-->>DW: Collega Cliente al Partner
    DW->>DW: Attiva Logiche Commissione
    App->>DW: GET /partners/{id}/stats
    DW-->>App: Ritorna Dati Ricavi Cumulativi"
/>


# Entita Sottoscrizione (Subscription)



import { Steps, Step } from 'fumadocs-ui/components/steps';

# Entita Sottoscrizione

L'oggetto **Subscription** rappresenta un accordo ricorrente collegato a un **Customer**.
Combina piano, addon, cadenza di rinnovo e stato lifecycle.

## Utilizzo

Usa la Subscription per:

* Associare un piano al cliente.
* Gestire pricing a seat tramite quantita addon.
* Applicare sconti globali e per addon.
* Tracciare usage metered quando presente.
* Eseguire transizioni lifecycle (`pause`, `resume`, `change`, `cancel-at-period-end`).
* Conservare storico amendments per audit.

## Modello Seat-Based

Nel modello attuale Donutwork i seat sono gestiti tramite **addons**.

* Il costo per seat e il prezzo unitario addon.
* Il numero seat e `addons[].quantity`.
* Il rinnovo include automaticamente la componente seat.

Esempio:

* Addon `workspace_seat`: `12.00`
* Quantita: `25`
* Totale seat: `300.00` (prima di tasse/sconti)

## Flusso Atteso

<Steps>
  <Step>
    ### Associazione Piano

    Associa il piano con `POST /customers/{id}/subscriptions.json`.
  </Step>

  <Step>
    ### Configurazione Runtime

    Aggiorna quantita addon (inclusi seat), sconti e usage.
  </Step>

  <Step>
    ### Transizioni Lifecycle

    Applica opzionalmente operazioni lifecycle (`pause`, `resume`, `change-plan`, `change-addons`, `cancel-at-period-end`).
  </Step>

  <Step>
    ### Boundary di Rinnovo

    Alla data `next_renew`, eventuali modifiche schedulate vengono applicate e parte l'addebito ricorrente.
  </Step>
</Steps>

***

## Stati Lifecycle e Transizioni

| Stato Lifecycle         | Significato                              | Ingresso Tipico                        |
| :---------------------- | :--------------------------------------- | :------------------------------------- |
| `active`                | Subscription rinnovabile e addebitabile  | Attach, resume, change riuscita        |
| `paused`                | Billing sospeso temporaneamente          | Azione pause                           |
| `cancel_pending`        | Cancellazione programmata a fine periodo | Cancel-at-period-end                   |
| `cancelled`             | Contratto non piu attivo                 | Stop a boundary / cancellazione legacy |
| `trialing` / `past_due` | Stati avanzati opzionali                 | Orchestrazioni esterne                 |

### Definizione Stati con Esempi Pratici

* `active`: il cliente viene addebitato regolarmente al rinnovo.
  Esempio: piano mensile con rinnovo al 1 maggio 2026.
* `paused`: fatturazione temporaneamente sospesa.
  Esempio: sospensione richiesta dal cliente per 30 giorni.
* `cancel_pending`: abbonamento impostato per la chiusura a fine periodo.
  Esempio: cancellazione richiesta il 15 aprile 2026, servizio attivo fino al boundary.
* `cancel_pending` puo essere annullato prima del boundary.
  Esempio: il cliente annulla e poi cambia idea dopo 3 giorni; con undo-cancel-at-period-end ritorna in `active`.
* `cancelled`: abbonamento chiuso definitivamente.
  Esempio: boundary raggiunto e chiusura completata.
* `trialing`: periodo prova prima del primo addebito.
  Esempio: trial gratuito di 14 giorni all'associazione del piano.
* `past_due`: problema di pagamento in corso.
  Esempio: rinnovo fallito in attesa di aggiornamento metodo pagamento.

### Semantica Pausa e Ripresa Fatturazione

Quando una subscription viene messa in pausa, Donutwork interrompe i rinnovi e azzera `next_renew`, salvando la data precedente in `pause_state.previous_next_renew`.

Alla ripresa:

* Se `resume_at` e presente e futura, quella data diventa il nuovo `next_renew`.
* Se `resume_at` non e presente, Donutwork prova a riusare `previous_next_renew`.
* Se la data salvata e gia nel passato, `next_renew` viene impostata al giorno di ripresa (oggi), senza recupero retroattivo automatico.

Esempio timeline:

* Pausa il **1 maggio 2026**.
* Riattiva il **1 luglio 2026** (dopo 2 mesi).
* Risultato: nessun addebito automatico arretrato per maggio/giugno; `next_renew` viene riallineata al 1 luglio 2026 (o a `resume_at` se impostata nel futuro).

### Grafico Lifecycle

<Mermaid
  chart="stateDiagram-v2
    [*] --> trialing
    [*] --> active
    trialing --> active: fine trial
    active --> paused: pausa
    paused --> active: ripresa
    active --> cancel_pending: cancella a fine periodo
    cancel_pending --> active: annulla cancellazione
    cancel_pending --> cancelled: boundary raggiunto
    active --> past_due: rinnovo fallito
    past_due --> active: pagamento recuperato"
/>

## Regole Proration

* **Delta positivo** (upgrade): addebito immediato.
* **Delta negativo** (downgrade): credito in `carryover_credit`.
* Il credito viene consumato ai rinnovi successivi prima di nuovi addebiti.

## Scheduled Changes

Per `change-plan` e `change-addons` puoi usare `when: period_end`.
La modifica viene salvata in `scheduled_change` e applicata al prossimo boundary.

## Amendment History

Ogni modifica lifecycle genera un amendment immutabile con before/after e metadati proration.

***

## Schema Dati

| Campo                  | Tipo             | Descrizione                                           |
| :--------------------- | :--------------- | :---------------------------------------------------- |
| `id`                   | `eid`            | Identificativo customer-subscription.                 |
| `subscription_id`      | `string`         | Piano attualmente applicato.                          |
| `status`               | `string`         | Stato legacy (`active`, `dismiss`, `dismissed`, ...). |
| `next_renew`           | `date \| null`   | Prossimo boundary di billing.                         |
| `addons`               | `array`          | Addon con prezzo e `quantity` (inclusi seat).         |
| `global_discount`      | `object`         | Sconto a livello piano.                               |
| `lifecycle`            | `object`         | Metadati stato lifecycle avanzato.                    |
| `pricing_snapshot`     | `object`         | Snapshot pricing usato nelle transizioni.             |
| `scheduled_change`     | `object \| null` | Mutazione differita a fine periodo.                   |
| `pause_state`          | `object \| null` | Metadati pausa/ripresa.                               |
| `carryover_credit`     | `number`         | Credito accumulato da proration negativo.             |
| `cancel_at_period_end` | `boolean`        | Intenzione esplicita di stop a fine periodo.          |

***

## Backward Compatibility

Nessuna route o shape legacy viene rimossa.

### Legacy vs New lifecycle behavior

| Area            | Comportamento Legacy             | Nuovo Comportamento Lifecycle                          |
| :-------------- | :------------------------------- | :----------------------------------------------------- |
| Attach/Detach   | Route esistenti valide           | Invariato, con metadati lifecycle additivi             |
| Update addons   | Mutazione addon legacy invariata | Opzionale `change-addons` con proration/scheduling     |
| Status endpoint | `status` legacy mantenuto        | Visibilita lifecycle aggiuntiva senza rimuovere chiavi |
| Seat pricing    | Addon con quantity               | Stesso modello, ora documentato esplicitamente         |
| Cancellazione   | Flow basato su `dismiss`         | `cancel_at_period_end` mappato in compatibilita legacy |

***

## Call Graph

<Mermaid
  chart="sequenceDiagram
    participant App as Applicazione
    participant DW as API Donutwork
    participant Rec as Renewal Processor

    App->>DW: POST /customers/{id}/subscriptions.json
    DW-->>App: Subscription associata (legacy + lifecycle)
    App->>DW: PUT /lifecycle/change-addons (opzionale)
    DW-->>App: Amendment + dettagli proration
    Rec->>Rec: Applica scheduled change al boundary
    Rec->>DW: Genera/cattura addebito rinnovo
    DW-->>App: Webhook: Customer.subscriptionRenewal.success"
/>


# Media Library



import { Card, Cards } from 'fumadocs-ui/components/card';
import { UploadCloud, HardDrive, FileSearch, Download } from 'lucide-react';

# Media Library

La **Media Library** funge da repository centralizzato per tutti i file del tuo workspace. Sfrutta un'infrastruttura di storage remoto scalabile per garantire che i tuoi asset siano sempre disponibili, sicuri e pronti per essere serviti tramite CDN.

## Caratteristiche Principali

<Cards>
  <Card icon={<UploadCloud className="text-blue-500" />} title="Caricamento Rapido" description="Sistema di upload multi-file con supporto Drag & Drop" />

  <Card icon={<HardDrive className="text-purple-500" />} title="Remote Storage" description="Integrazione nativa con bucket isolati per azienda, garantendo la massima sicurezza dei dati." />

  <Card icon={<FileSearch className="text-green-500" />} title="Riconoscimento Formati" description="Identificazione automatica del tipo di file (Immagini, PDF, Documenti) con icone dedicate." />
</Cards>

***

## Gestione dei File

L'interfaccia della galleria permette un controllo immediato sugli asset caricati:

### 1. Upload e Ingestione

Puoi trascinare più file contemporaneamente nell'area di upload. Il sistema gestisce automaticamente la coda e ti avvisa al termine del caricamento.

### 2. Galleria e Navigazione

I file sono visualizzati in una griglia responsive che mostra:

* **Nome File:** Il nome originale dell'asset (Key).
* **Dimensione:** Calcolo automatico del peso del file (KB, MB, GB).
* **Identificativo (ETag):** L'hash univoco del file per la gestione della cache e del versionamento.

### 3. Paginazione Intelligente

Per workspace con migliaia di file, la Media Library utilizza una paginazione basata su **Continuation Tokens**, ottimizzando i tempi di caricamento e riducendo il consumo di banda.

***

## Casi d'uso Comuni

* **Dynamic Content:** Carica le immagini dei prodotti o i loghi dei partner da richiamare nei tuoi  [Dynamic Content](/it/docs/dynamic-content-modeling).
* **Email Gateway:** Ospita gli asset grafici per i tuoi template email transazionali.
* **Documenti Utente:** Archivia PDF o guide per i tuoi clienti in un ambiente sicuro.


# Programma Partner e Condivisione Ricavi



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { Calculator, Fingerprint, TrendingUp, Zap } from 'lucide-react';

# Programma Partner

Donutwork ti permette di gestire un canale partner come un prodotto, non come un foglio Excel.
Crei gruppi partner strutturati, definisci regole commissioni evolute e validi i risultati prima di pubblicare.

## Cosa puoi fare

1. Segmentare i partner per modello commerciale (agenzie, reseller, canali strategici).
2. Applicare logiche commissioni multilivello per ogni gruppo.
3. Impostare soglie qualità (X clienti paganti in N mesi).
4. Simulare gli esiti prima del rilascio.
5. Gestire payout con piena trasparenza.

***

## Configurazione in 7 passaggi

1. Apri un gruppo partner.
2. Imposta la base con `Scaglione temporale` o `Ricorrente (base)`.
3. Aggiungi leve di crescita opzionali:

* `Importo transazione`
* `Bonus LTV`

4. Aggiungi `Soglia volume clienti` se vuoi imporre requisiti minimi.
5. Prova scenari realistici nel `Simulatore Commissioni`.
6. Controlla il dettaglio calcolo e verifica il comportamento atteso.
7. Salva e applica al gruppo.

<Callout type="info" title="Ordine consigliato di configurazione">
  Parti sempre dalla commissione base, poi aggiungi upgrade/rettifiche e solo alla fine le soglie di eleggibilità. Ottieni una configurazione più chiara e più controllabile.
</Callout>

***

## Catalogo Regole (Come si comportano)

### Scaglione temporale

Ideale per spingere l’acquisizione nei primi mesi.

* Obiettivo: premiare maggiormente la fase iniziale del cliente.
* Campi chiave:
* `Mesi massimi (es. 12)`
* `Percentuale (%)`
* `Bonus (€ - opzionale)`
* Comportamento: si applica se l’età cliente rientra nel limite mesi.
* Esempio tipico: “12% per i primi 12 mesi + bonus iniziale opzionale”.

### Ricorrente (base)

È la base stabile di lungo periodo.

* Obiettivo: definire la commissione standard quando non entra nessuno scaglione temporale.
* Campo chiave:
* `Percentuale ricorrente (%)`
* Comportamento: usata come commissione base predefinita.
* Esempio tipico: “6% continuativo dopo la fase iniziale”.

### Importo transazione

Permette di adattare i margini in base al valore addebito.

* Obiettivo: modificare la commissione quando l’importo supera una soglia.
* Campi chiave:
* `Importo minimo transazione (€)`
* `Detrazione % (es. 1,0)`
* Comportamento: al superamento soglia, la rettifica si applica sulla fee in quel punto del flusso.
* Esempio tipico: “su ticket elevati, applica una detrazione per proteggere margine”.

### Bonus LTV

Premia la crescita reale del partner nel tempo.

* Obiettivo: sbloccare extra commissione al raggiungimento di milestone LTV.
* Campi chiave:
* `LTV minimo totale (€)`
* `Bonus incremento %`
* Comportamento: se sono valide più soglie, si applica il bonus più alto.
* Esempio tipico: “+3% dopo 20.000€ generati”.

### Soglia volume clienti

Garantisce qualità e continuità.

* Obiettivo: richiedere un minimo clienti paganti.
* Campi chiave:
* `Clienti richiesti (X)`
* `Mesi finestra (N)`
* `Modalità finestra`
* `Fonte ancoraggio`
* `Azione sotto soglia`
* `Modalità riduzione`
* Comportamento:
* verifica se il partner raggiunge X clienti paganti nella finestra selezionata.
* se sotto soglia, applica la policy configurata (riduci, posticipa, annulla).

***

## Logica di Calcolo Affidabile

### Base monetaria

Percentuali e soglie vengono valutate sull’importo imponibile della transazione (al netto imposte), per mantenere coerenza finanziaria.

### Ordine deterministico

Le regole sono applicate in questo ordine:

1. Base: `Scaglione temporale` o `Ricorrente (base)`
2. `Importo transazione`
3. `Bonus LTV`
4. `Soglia volume clienti`

### Nessuna retroattività inattesa

Quando aggiorni le regole, i calcoli storici già approvati restano invariati.

***

## Soglia Volume Clienti: Finestra mobile vs ancorata

### Finestra mobile

Ideale per controllare performance continue.

* valuta gli ultimi N mesi a partire da ogni data addebito.

### Finestra ancorata

Ideale per programmi partner con cicli definiti.

* valuta N mesi a partire da un punto di ancoraggio.

### Avvio ancoraggio sul primo pagante

Se la finestra ancorata usa il primo cliente pagante ma non esiste ancora storico pagante, la prima transazione pagata avvia automaticamente la finestra. La regola viene comunque valutata normalmente.

***

## Simulatore Commissioni

Usa il simulatore prima di pubblicare ogni modifica regole.

* Inserisci valori realistici in:
* `Importo Addebito Simulato (€)`
* `Mesi dalla creazione del cliente`
* `LTV Partner Simulato (€)`
* `Clienti qualificati (finestra X)`
* `Primo cliente pagante (avvio finestra)`
* Esegui `Simula Commissione` e analizza `Dettaglio Simulazione Commissioni`.

È il modo più rapido per allineare finance, commerciale e operations prima del rilascio.

***

## Configurazioni pronte all’uso

1. Spinta acquisizione startup:

* scaglione forte nel primo anno
* base ricorrente più bassa
* soglia volume moderata

2. Canale agenzie:

* base ricorrente stabile
* milestone LTV per incentivare upsell
* finestra mobile per continuità

3. Referral enterprise:

* rettifica su ticket elevati
* bonus LTV selettivi
* finestra ancorata per governo del ciclo programma

***

## Perché Donutwork fa la differenza

<Cards>
  <Card icon={<Fingerprint className="text-blue-500" />} title="Spiegabile" description="Ogni payout è giustificabile con sequenza regole e dettaglio simulazione." />

  <Card icon={<Calculator className="text-green-500" />} title="Configurabile" description="Combini ciclo vita, valore transazione, LTV e soglie performance senza sviluppo custom." />

  <Card icon={<TrendingUp className="text-indigo-500" />} title="Scalabile" description="Passi da affiliazione base a economia partner avanzata man mano che cresci." />

  <Card icon={<Zap className="text-yellow-500" />} title="Operativo subito" description="Progetti, testi e pubblichi rapidamente con controllo pieno." />
</Cards>


# Pagamenti Ricorrenti



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { Repeat, Zap, Gift, Settings2, Calculator, GitBranchPlus, ShieldCheck } from 'lucide-react';

# Pagamenti Ricorrenti e Subscription

Donutwork ti permette di gestire abbonamenti ricorrenti con un modello prevedibile:

* definisci il catalogo piani,
* associ il piano al cliente,
* gestisci il pricing a seat con gli addon,
* aggiorni il contratto nel tempo con operazioni lifecycle,
* mantieni la compatibilita con i flussi legacy gia in uso.

Questa pagina spiega il comportamento reale del sistema, con esempi pratici.

## Cosa Contiene Una Subscription

<Cards>
  <Card icon={<Repeat className="text-blue-500" />} title="Cadenza Rinnovo" description="Cicli a giorni o mesi (`renewal_days` / `renewal_months`) con data prossimo rinnovo (`next_renew`)." />

  <Card icon={<Gift className="text-emerald-500" />} title="Gestione Trial" description="Periodo di prova opzionale prima del primo ciclo a pagamento." />

  <Card icon={<Zap className="text-amber-500" />} title="Prezzi Seat + Addon" description="Il seat-based usa `addons[].quantity` (numero seat) e `addons[].price` (costo unitario seat)." />

  <Card icon={<Settings2 className="text-cyan-500" />} title="Sconti e Imposte" description="Sconti addon, sconto globale, carryover credit e tasse sono applicati in ordine deterministico." />
</Cards>

***

## Come Viene Calcolato Il Prossimo Rinnovo

A ogni rinnovo, Donutwork calcola l'importo in questo ordine:

1. Prezzo base del piano.
2. Importi addon (`price * quantity`) per addon con quantita attiva.
3. Sconto addon se configurato e non scaduto (`discount_until`).
4. Sconto globale (`fixed` o `percentage`, se attivo).
5. Credito carryover (`carryover_credit`) da downgrade/proration precedenti.
6. Imposte del profilo fiscale associato.

### Formula (semplificata)

```text
net_subtotal = base + addons_dopo_sconti_addon
net_post_sconto_globale = net_subtotal - sconto_globale
net_due = max(0, net_post_sconto_globale - carryover_credit_usato)
vat_due = net_due * aliquota_iva
gross_due = net_due + vat_due
```

### Esempio

* Piano base: `99.00`
* Addon seat: `12.00` x `8` seat = `96.00`
* Sconto addon 10% attivo => addon effettivo `86.40`
* Subtotale netto = `185.40`
* Sconto globale 15% => `-27.81`
* Credito carryover applicato: `20.00`
* Netto dovuto = `137.59`
* IVA 22% = `30.27`
* Totale lordo = `167.86`

***

## Modello Seat-Based (Importante)

Il pricing a seat non usa uno schema separato.
Nel modello attuale i seat sono addon:

* costo seat: `addons[].price`
* numero seat: `addons[].quantity`
* importo seat: incluso automaticamente nel rinnovo

Questo approccio e stabile e retrocompatibile con i flussi esistenti.

***

## Stati Lifecycle (Significato Billing)

| Stato            | Addebitabile       | Significato                                                           |
| :--------------- | :----------------- | :-------------------------------------------------------------------- |
| `active`         | Si                 | Fatturazione ricorrente normale.                                      |
| `trialing`       | In genere no       | Fase trial prima del primo rinnovo pagato.                            |
| `past_due`       | Condizionale       | Stato di recupero dopo pagamento fallito.                             |
| `paused`         | No                 | Billing in pausa. Nessun addebito durante la pausa.                   |
| `cancel_pending` | Nessun nuovo ciclo | Chiusura programmata a fine periodo (annullabile prima del boundary). |
| `cancelled`      | No                 | Subscription chiusa.                                                  |

<Callout type="info" title="Semantica Della Pausa">
  La pausa non genera arretrati automatici. Se un abbonamento viene riattivato dopo 2 mesi, i mesi in pausa non vengono addebitati retroattivamente. Il ciclo riparte dalla logica di resume.
</Callout>

### Grafico Lifecycle

<Mermaid
  chart="stateDiagram-v2
    [*] --> trialing
    [*] --> active
    trialing --> active: fine trial
    active --> paused: pausa
    paused --> active: resume
    active --> cancel_pending: cancella a fine periodo
    cancel_pending --> active: annulla cancellazione
    cancel_pending --> cancelled: boundary di periodo
    active --> past_due: rinnovo fallito
    past_due --> active: pagamento recuperato"
/>

***

## Operazioni Lifecycle Supportate

Tutte additive (nessuna rimozione route legacy):

| Operazione                | Immediata | Fine Periodo       | Proration | Note                                                  |
| :------------------------ | :-------- | :----------------- | :-------- | :---------------------------------------------------- |
| Pause                     | Si        | No                 | No        | Sospende i rinnovi durante la pausa.                  |
| Resume                    | Si        | No                 | No        | `resume_at` opzionale per definire il nuovo boundary. |
| Change Plan               | Si        | Si                 | Opzionale | Supporta upgrade e downgrade.                         |
| Change Addons             | Si        | Si                 | Opzionale | Include aggiornamento quantita seat.                  |
| Cancel At Period End      | Si (flag) | Effetto a boundary | No        | Comportamento compatibile con legacy.                 |
| Undo Cancel At Period End | Si        | No                 | No        | Ripristina il piano attivo prima del boundary.        |
| Next Renewal Preview      | Read-only | N/A                | N/A       | Mostra breakdown completo del prossimo addebito.      |
| Amendment History         | N/A       | N/A                | N/A       | Storico completo modifiche lifecycle.                 |

***

## Esempi API

### Pianificare Cambio Seat A Fine Periodo

```json
{
  "subscription": {
    "action": "change_addons",
    "when": "period_end",
    "proration": false,
    "addons": [
      {
        "name": "workspace_seat",
        "quantity": 25,
        "price": 12
      }
    ]
  }
}
```

### Anteprima Prossimo Rinnovo (estratto risposta)

```json
{
  "status": "success",
  "data": {
    "subscription_id": "sub_abc123",
    "next_renewal": "2026-07-01",
    "billable": true,
    "pricing": {
      "items": [
        { "service": "Subscription Base: Pro", "net": 99, "tax_rate": 22, "tax": 21.78, "total": 120.78 },
        { "service": "Addon: workspace_seat (Qty: 25)", "net": 300, "tax_rate": 22, "tax": 66, "total": 366 }
      ],
      "net_due": 399,
      "vat_due": 87.78,
      "gross_due": 486.78
    }
  }
}
```

***

## FAQ API (Combinazioni Comuni)

Le combinazioni sotto fanno riferimento alle route Customer API documentate in `/it/docs/api/customer#subscription-management`.

### Come posso fare l'upgrade di un piano?

Usa `change-plan` con applicazione immediata.

```json
{
  "lifecycle": {
    "plan_id": "PLAN_ENTERPRISE_V3",
    "when": "immediate",
    "proration": true
  }
}
```

* Endpoint: `PUT /customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-plan.json`
* Se il delta proration e positivo, viene tentato un addebito immediato.
* Se l'addebito immediato fallisce, la modifica non viene applicata.

### Come posso fare il downgrade di un piano?

Usa sempre `change-plan`, puntando a un piano con prezzo inferiore.

```json
{
  "lifecycle": {
    "plan_id": "PLAN_STARTER_V1",
    "when": "immediate",
    "proration": true
  }
}
```

* Endpoint: `PUT /customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-plan.json`
* Con delta negativo, il sistema genera credito in `carryover_credit`.
* Il credito viene scalato sui rinnovi successivi prima di nuovi addebiti.

### Come posso pianificare upgrade o downgrade dal prossimo rinnovo?

```json
{
  "lifecycle": {
    "plan_id": "PLAN_PRO_V2",
    "when": "period_end",
    "proration": false
  }
}
```

* Endpoint: `PUT /customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-plan.json`
* Nessun addebito immediato: la modifica si applica al boundary di rinnovo.

### Come posso modificare la quantità degli addon (seat inclusi)?

```json
{
  "lifecycle": {
    "addons": [
      { "element": "workspace_seat", "quantity": 25 }
    ],
    "when": "immediate",
    "proration": true
  }
}
```

* Endpoint: `PUT /customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-addons.json`
* Nel modello seat-based, il numero seat e `addons[].quantity`.

### Come posso pianificare una modifica addon a fine periodo?

```json
{
  "lifecycle": {
    "addons": [
      { "element": "workspace_seat", "quantity": 40 }
    ],
    "when": "period_end",
    "proration": false
  }
}
```

* Endpoint: `PUT /customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/change-addons.json`
* Utile per cambi commerciali con decorrenza dal prossimo ciclo.

### Come funziona pausa e ripresa dopo mesi?

* Metti in pausa: `PUT .../lifecycle/pause.json`
* Riprendi: `PUT .../lifecycle/resume.json` (opzionale `resume_at`)

Esempio reale:

* pausa il **1 maggio 2026**
* riprendi il **1 luglio 2026**
* non vengono addebitati retroattivamente maggio/giugno; il ciclo riparte dalla logica di resume.

### Posso annullare una cancellazione gia impostata a fine periodo?

Sì:

* imposta cancellazione: `PUT .../lifecycle/cancel-at-period-end.json`
* annulla cancellazione: `PUT .../lifecycle/undo-cancel-at-period-end.json`

Se annulli prima del boundary, la subscription torna operativa in stato `active`.

### Come posso vedere prima l'impatto economico senza applicare modifiche?

Usa la preview lifecycle (no mutation):

```json
{
  "lifecycle": {
    "action": "change_addons",
    "addons": [
      { "element": "workspace_seat", "quantity": 30 }
    ]
  }
}
```

* Endpoint: `POST /customers/{customerId}/subscriptions/{subscriptionId}/lifecycle/preview.json`
* Risposta con `old_due`, `new_due`, `delta`, `direction`.

### Come gestisco retry sicuri lato integrazione?

Usa `lifecycle.idempotency_key` nelle chiamate mutative.
In caso di retry, eviti doppie applicazioni della stessa operazione.

### Dove trovo lo storico completo delle modifiche?

Usa amendment history:

* Endpoint: `GET /customers/{customerId}/subscriptions/{subscriptionId}/amendments.json`
* Include azione, quando (`immediate`/`period_end`), before/after, metadati proration.

### Tabella rapida combinazioni

| Obiettivo                       | Endpoint                             | `when`       | `proration` |
| :------------------------------ | :----------------------------------- | :----------- | :---------- |
| Upgrade piano subito            | `.../change-plan.json`               | `immediate`  | `true`      |
| Downgrade piano subito          | `.../change-plan.json`               | `immediate`  | `true`      |
| Cambio piano da prossimo ciclo  | `.../change-plan.json`               | `period_end` | `false`     |
| Aumento/diminuzione seat subito | `.../change-addons.json`             | `immediate`  | `true`      |
| Cambio seat da prossimo ciclo   | `.../change-addons.json`             | `period_end` | `false`     |
| Pausa servizio                  | `.../pause.json`                     | N/A          | N/A         |
| Ripresa servizio                | `.../resume.json`                    | N/A          | N/A         |
| Cancella a fine periodo         | `.../cancel-at-period-end.json`      | boundary     | N/A         |
| Annulla cancellazione           | `.../undo-cancel-at-period-end.json` | immediate    | N/A         |
| Simulazione impatto             | `.../preview.json`                   | N/A          | N/A         |
| Storico modifiche               | `.../amendments.json`                | N/A          | N/A         |

***

## Scenari Pratici

### 1) Pausa 2 Mesi, Poi Ripresa

* Pausa il **1 maggio 2026**
* Riprendi il **1 luglio 2026**
* Risultato: nessun addebito arretrato per maggio/giugno, rinnovo riallineato alla ripresa.

### 2) Upgrade Mid-Cycle

* Il cliente passa da 10 a 20 seat con modifica immediata.
* Delta proration positivo => addebito immediato di conguaglio.

### 3) Downgrade Mid-Cycle

* Il cliente riduce seat durante il periodo.
* Delta negativo => credito salvato in `carryover_credit`.
* Il credito viene consumato ai rinnovi successivi prima di nuovi addebiti.

### 4) Cancellazione In Attesa + Ripristino

* Cliente richiede cancellazione a fine periodo.
* Stato passa a `cancel_pending`.
* Se cambia idea prima del boundary, `undo` riporta la subscription in stato attivo.

***

## Backward Compatibility (No Break Changes)

I flussi panel/API legacy restano validi.
Le nuove capability lifecycle sono opt-in.

| Area                       | Comportamento Legacy | Comportamento Attuale          |
| :------------------------- | :------------------- | :----------------------------- |
| Attach/detach subscription | Supportato           | Ancora supportato              |
| Route legacy update addon  | Supportata           | Ancora supportata              |
| Campo status legacy        | Presente             | Ancora presente                |
| Modello seat               | Addon quantity       | Stesso modello ufficiale       |
| Integrazioni esistenti     | Stabili              | Adozione lifecycle progressiva |

<Callout type="info" title="Strategia Di Adozione">
  Se sei gia integrato con le route legacy, puoi lasciarle invariate e attivare gradualmente le route lifecycle dove ti servono pausa/resume, proration e storico amendment.
</Callout>

***

## Checklist Consigliata

<Cards>
  <Card icon={<Calculator className="text-indigo-500" />} title="Modella I Seat Con Addon" description="Configura costo unitario seat sull'addon e aggiorna quantity per il numero seat." />

  <Card icon={<GitBranchPlus className="text-sky-500" />} title="Usa Scheduled Change" description="Per variazioni commerciali future, preferisci `period_end`." />

  <Card icon={<ShieldCheck className="text-emerald-500" />} title="Aumenta Trasparenza" description="Usa renewal preview e amendment history per supporto e audit." />
</Cards>

***

## Documentazione Correlata

<Cards>
  <Card title="Customer API" href="/it/docs/api/customer#subscription-management" description="Route complete customer-subscription, incluse le operazioni lifecycle." />

  <Card title="Entita Subscription" href="/it/docs/entities/subscription" description="Schema dettagliato, transizioni stato e mappatura compatibilita." />
</Cards>


# Sentinel Dashboard



import { Callout } from 'fumadocs-ui/components/callout';

# Security Command Center

La Dashboard di Sentinel è il cuore operativo della sicurezza. Fornisce una visione immediata e ad alto impatto visivo dello stato di salute del tuo ecosistema di autenticazione.

## Metriche in Tempo Reale

La dashboard monitora quattro KPI critici:

* **Threats Detected:** Numero di minacce bloccate attivamente dal sistema.
* **Failed Logins:** Tentativi di accesso non riusciti (potenziali attacchi brute-force).
* **Active Sessions:** Numero di utenti attualmente autenticati globalmente.
* **Avg Response:** Tempo medio di risposta del motore di sicurezza (espresso in millisecondi).

## Global Login Activity

Grazie all'integrazione con **MapLibre GL**, Sentinel visualizza la densità degli accessi su una mappa globale.

* I punti blu indicano attività regolare.
* I punti rossi segnalano aree ad alta densità di tentativi, permettendo di identificare rapidamente attacchi geograficamente mirati.

## Security Alerts & Decisions

In questa sezione vengono elencate le anomalie recenti. Per ogni alert, Sentinel mostra:

1. **Severità:** Da *Low* a *Critical*.
2. **Decisione Presa:** - `Allow`: Accesso consentito.
   * `Challenge MFA`: Richiesta di secondo fattore obbligatoria.
   * `Deny`: Accesso bloccato.
   * `Monitor`: Attività sospetta ma sotto la soglia di blocco.
3. **Trigger:** I motivi specifici che hanno alzato il rischio (es. *New User Agent*, *TOR/VPN Flag*).

<Callout type="info">
  Puoi cliccare su ogni IP o User ID negli alert per approfondire lo storico delle attività di quel profilo.
</Callout>


# Sentinel Security Platform



import { Card, Cards } from 'fumadocs-ui/components/card';
import { ShieldCheck, Lock, Eye, Zap } from 'lucide-react';

# Sentinel Security Platform

**Sentinel** è il modulo di sicurezza intelligente di Donutwork progettato per proteggere il tuo business e i tuoi utenti dalle minacce moderne. A differenza dei sistemi di sicurezza statici, Sentinel analizza ogni tentativo di accesso in tempo reale, assegnando un **Risk Score** dinamico basato su decine di segnali comportamentali e ambientali.

## Pilastri di Sentinel

<Cards>
  <Card icon={<Zap className="text-yellow-500" />} title="Adaptive MFA" description="Richiede l'autenticazione a due fattori solo quando il rischio rilevato supera una soglia predefinita." />

  <Card icon={<Eye className="text-blue-500" />} title="IP Intelligence" description="Analisi automatica di IP malevoli, nodi TOR, VPN e geolocalizzazioni sospette." />

  <Card icon={<ShieldCheck className="text-green-500" />} title="Identity Provider (IDP)" description="Gestione centralizzata delle utenze esterne con supporto a T-OTP e codici di backup." />

  <Card icon={<Lock className="text-red-500" />} title="Risk-Based Decisions" description="Prende decisioni automatiche (Allow, Challenge MFA, Deny) in millisecondi." />
</Cards>

***

## Come funziona il Risk Engine?

Ogni volta che un utente interagisce con il sistema di autenticazione, Sentinel valuta i seguenti fattori:

1. **Reputazione IP:** L'indirizzo proviene da una rete nota per attacchi o bot?
2. **Novità del Dispositivo:** L'utente sta usando un browser o un sistema operativo mai visto prima?
3. **Geolocalizzazione:** L'accesso proviene da un paese insolito per quell'utente?
4. **Continuità della Sessione:** Se l'utente è già loggato e la sessione è stabile, il rischio viene ridotto.

Il risultato è uno score da **0.00** a **1.00**. In base a questo valore e alle tue configurazioni, Sentinel decide come procedere.

***

## Sezioni di Sentinel

* **[Dashboard](/it/docs/sentinel/dashboard):** Monitoraggio in tempo reale delle minacce globali.
* **[Gestione Utenti](/it/docs/sentinel/users):** Controllo granulare sugli accessi e sullo stato della sicurezza degli utenti.
* **[Configurazione](/it/docs/sentinel/settings):** Calibrazione fine delle soglie di rischio e dei trigger.

## Ordine Di Setup Consigliato

1. Imposta le soglie base in [Configurazione](/it/docs/sentinel/settings).
2. Verifica gli scenari ad alto rischio dalla vista [Dashboard](/it/docs/sentinel/dashboard).
3. Gestisci eccezioni e override da [Gestione Utenti](/it/docs/sentinel/users).


# Sentinel Risk Configuration



import { Callout } from 'fumadocs-ui/components/callout';

# Configurazione Sentinel

Sentinel ti permette di "addestrare" il motore di rischio in base alle tue specifiche necessità. Puoi decidere quanto peso dare a ogni singolo evento di sicurezza.

## Score Adjustments (Pesi)

Ogni evento sospetto aggiunge un valore al **Risk Score** totale (da 0.0 a 1.0). Puoi regolare i seguenti parametri:

* **Malware/Threat IP Flag:** Il punteggio massimo per IP presenti in blacklist globali.
* **TOR/VPN Flag:** Rischio associato all'uso di reti anonimizzanti.
* **Unknown IP / Country:** Rischio aggiunto quando un utente accede da una posizione o un IP mai usato prima.
* **New User Agent:** Rischio per l'uso di un nuovo browser o dispositivo.

### Riduzione del Rischio

* **Session Continuity Reduction:** Questo valore (negativo) riduce il rischio se l'utente mantiene una sessione stabile e conosciuta. È fondamentale per evitare "falsi positivi" durante l'uso normale dell'app.

***

## Soglie di Decisione (Thresholds)

Definisci i limiti oltre i quali Sentinel deve intervenire:

| Soglia                      | Descrizione                                                                                                            |
| :-------------------------- | :--------------------------------------------------------------------------------------------------------------------- |
| **Challenge MFA Threshold** | Se lo score è `>=` a questo valore, all'utente verrà richiesto il T-OTP, anche se non obbligatorio per il suo profilo. |
| **Deny Threshold**          | Se lo score è `>=` a questo valore, l'accesso viene negato immediatamente a prescindere dalle credenziali.             |

<Callout type="warn" title="Attenzione alla Calibrazione">
  Impostare una soglia di *Deny* troppo bassa (es. 0.40) potrebbe bloccare utenti legittimi che viaggiano o usano nuovi dispositivi. Si consiglia di iniziare con soglie conservative (MFA a 0.50 e Deny a 0.85).
</Callout>

***

## Integrazione T-OTP

Sentinel permette di abilitare o disabilitare globalmente il servizio di **Time-Based One-Time Password**. Quando abilitato, potrai offrire ai tuoi utenti l'autenticazione tramite app come Google Authenticator o Authy tramite le API di Donutwork.


# User Management (IDP)



# Gestione Utenti Sentinel

Sentinel agisce come un **Identity Provider (IDP)** per le tue applicazioni SaaS. In questa sezione puoi monitorare e gestire la sicurezza di ogni singolo utente registrato.

## Stato della Sicurezza Utente

Per ogni utente, la tabella mostra:

* **CustomerID:** L'identificativo esterno del tuo utente.
* **Status:** Stato dell'account (Attivo o Sospeso).
* **OTP (One-Time Password):** Indica se l'utente ha configurato correttamente l'autenticazione a due fattori (T-OTP).
* **Backup Codes:** Mostra se sono stati generati i codici di emergenza per il recupero dell'account.

## Azioni Amministrative

Come amministratore, hai il controllo totale sulle sessioni:

1. **Sospensione Accesso:** Se rilevi attività compromesse, puoi sospendere istantaneamente l'utente. Questo invaliderà tutte le sessioni attive.
2. **Ripristino Accesso:** Permette di riattivare un utente precedentemente sospeso.
3. **Eliminazione:** Rimuove permanentemente l'utente dal sistema Sentinel.

> **Nota:** La sospensione in Sentinel blocca l'autenticazione a livello di IDP, impedendo l'accesso a tutti i servizi collegati alla piattaforma.


# Directory Monitor



import { Card, Cards } from 'fumadocs-ui/components/card';
import { FolderOpen, Terminal, Bell, Cpu } from 'lucide-react';

# Directory Monitor

Il **Directory Monitor** è un motore di sorveglianza del file system progettato per l'automazione. Ti permette di monitorare cartelle specifiche — sia locali che su server remoti — e di attivare notifiche o flussi di lavoro ogni volta che un file viene creato, modificato o eliminato.

## L'Agente di Monitoraggio

Per abilitare il monitoraggio sulla tua infrastruttura, Donutwork fornisce un **Binary Linux**. Questo agente leggero viene eseguito sul tuo server e comunica in modo sicuro con la piattaforma, garantendo un tracciamento degli eventi a bassa latenza senza esporre il tuo file system a internet.

<Cards>
  <Card icon={<Terminal className="text-blue-500" />} title="Binary Linux" description="Scarica il pacchetto .tar pre-compilato ed eseguilo come servizio sul tuo server." />

  <Card icon={<Bell className="text-orange-500" />} title="Alert in Tempo Reale" description="Ricevi notifiche istantanee via Webhook o Email quando file critici vengono modificati." />
</Cards>

## Casi d'Uso Comuni

1. **Ingestione Dati Automatica:** Carica un CSV in una cartella monitorata per avviare automaticamente un [Workflow](/it/docs/workflow) di elaborazione dati.
2. **Audit di Sicurezza:** Monitora directory sensibili (come `/etc/` o `/bin/`) e ricevi avvisi se avvengono cambiamenti non autorizzati.
3. **Verifica Backup:** Attiva task di post-elaborazione non appena un file di dump del database viene completato in una directory specifica.

## Struttura del Progetto

* **Project ID:** Un identificativo univoco utilizzato dall'agente per sincronizzarsi con la dashboard di Donutwork.
* **Startup Status:** Indica se il processo di monitoraggio è stato inizializzato correttamente ed è in ascolto attivo di eventi.


# Systems & Monitoring



import { Card, Cards } from 'fumadocs-ui/components/card';
import { ShieldCheck, FolderTree, Code2, Key } from 'lucide-react';

# Systems & Monitoring

La sezione **Systems & Monitoring** è il centro di controllo operativo di Donutwork. Fornisce gli strumenti necessari per garantire che l'infrastruttura del tuo SaaS sia sicura, performante e costantemente monitorata. Dalla validazione dei certificati SSL alla gestione dei segreti tramite KMS, Donutwork ti offre una visibilità totale sullo stato dei tuoi sistemi.

## Moduli di Monitoraggio

Esplora le sezioni dedicate per configurare e gestire i vari aspetti della tua infrastruttura:

<Cards>
  <Card icon={<ShieldCheck className="text-blue-500" />} title="TLS Monitor" href="/it/docs/system-and-monitoring/tls-monitor" description="Monitora la validità e la scadenza dei certificati SSL/TLS per evitare interruzioni di servizio." />

  <Card icon={<FolderTree className="text-yellow-500" />} title="Directory Monitor" href="/it/docs/system-and-monitoring/directory-monitor" description="Automatizza i processi e le notifica monitorando i cambiamenti nelle directory critiche." />

  <Card icon={<Code2 className="text-purple-500" />} title="Sources" href="/it/docs/system-and-monitoring/sources" description="Connessioni a SFTP/FTP remoti per lo scambio di files." />

  <Card icon={<Key className="text-red-500" />} title="KMS Keys" href="/it/docs/system-and-monitoring/kms" description="Sistema di gestione delle chiavi (Key Management Service) per la cifratura dei dati sensibili." />
</Cards>

***

## Perché il Monitoraggio è Cruciale?

In un ambiente SaaS moderno, la stabilità non è un optional. Donutwork automatizza i controlli di routine per prevenire i problemi prima che impattino l'utente finale:

1. **Sicurezza Proattiva:** Rileva certificati TLS in scadenza o file di sistema modificati in modo anomalo.
2. **Governance dei Dati:** Gestisci le chiavi crittografiche in modo centralizzato tramite il modulo **KMS**, garantendo la conformità agli standard di sicurezza.
3. **Tracciabilità:** Automatizza i processi e le notifica monitorando i cambiamenti nelle directory critiche.

## Setup Nei Primi 15 Minuti

1. Parti da [TLS Monitor](/it/docs/system-and-monitoring/tls-monitor) per avere visibilità immediata sui certificati.
2. Configura [KMS](/it/docs/system-and-monitoring/kms) prima di caricare segreti nei flussi operativi.
3. Collega [Sources](/it/docs/system-and-monitoring/sources) se importi file da endpoint SFTP/FTP.
4. Attiva [Directory Monitor](/it/docs/system-and-monitoring/directory-monitor) per convertire eventi filesystem in trigger workflow.


# Key Management System (KMS)



import { Callout } from 'fumadocs-ui/components/callout';

# Key Management System (KMS)

Il **KMS** di Donutwork è la cassaforte crittografica del tuo SaaS. Fornisce un sistema centralizzato per l'archiviazione di credenziali sensibili, segreti applicativi e chiavi master che non dovrebbero mai essere scritte nel codice o salvate in testo semplice.

## Struttura delle Chiavi

Ogni voce del KMS è progettata per l'accesso programmatico e un'alta sicurezza:

* **Handler:** Un alias univoco utilizzato dalle tue API o script per recuperare la chiave senza esporne il contenuto reale.
* **Content:** Il valore segreto effettivo (es. Stripe Secret Key, AWS Access Key o un certificato privato).
* **Whitelist (Isolamento di Rete):** Limita l'uso di una chiave a specifici indirizzi IP o range CIDR. Se una richiesta arriva da un IP non autorizzato, il KMS bloccherà l'accesso anche con credenziali valide.

## Audit di Sicurezza

La tracciabilità è integrata nel cuore del KMS. Ogni volta che una chiave viene letta o modificata, viene generato un **Audit Log**.

### Dettagli dell'Audit Log:

* **Identità del Richiedente:** Chi ha effettuato l'accesso alla chiave.
* **Timestamp:** Esattamente quando è avvenuto l'accesso.
* **IP di Origine:** L'origine di rete della richiesta.
* **Esito:** Se la richiesta è andata a buon fine o è stata bloccata dalla policy di whitelist.

<Callout type="info">
  Usa l'**Handler** nel codice della tua applicazione per mantenere i tuoi repository puliti dai segreti. Questo ti permette di ruotare le chiavi nella dashboard di Donutwork senza dover rieseguire il deploy della tua applicazione.
</Callout>


# Connessioni Esterne (Sources)



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Link, Shield, Server, FileCode } from 'lucide-react';

# Sources & Connessioni Esterne

Il modulo **Sources** gestisce i gateway di comunicazione sicura tra Donutwork e la tua infrastruttura esterna. Ti permette di configurare e memorizzare le credenziali per server remoti, abilitando trasferimenti di file automatizzati e sincronizzazione dei dati.

## Protocolli Supportati

Donutwork supporta i protocolli standard di settore per lo scambio sicuro di file:

* **SFTP (SSH File Transfer Protocol):** Il metodo più sicuro, che utilizza SSH per il transito dei dati.
* **FTPS (FTP over SSL/TLS):** Una versione sicura di FTP che cripta sia i comandi che il contenuto.
* **FTP:** Supportato per compatibilità con sistemi legacy (non raccomandato per dati sensibili).

## Sicurezza e Impostazioni Avanzate

* **Cifratura SSL/TLS:** Forza connessioni criptate per assicurare che credenziali e file non siano mai trasmessi in chiaro.
* **Modalità Passiva:** Essenziale per le connessioni FTP/S per superare restrizioni di firewall o NAT lato server.
* **Mascheramento Credenziali:** Per conformità di sicurezza, le password non vengono mai mostrate nell'interfaccia dopo la configurazione iniziale.

## Configurazione Tecnica

Per creare una connessione, avrai bisogno di:

* **Hostname & Porta:** L'indirizzo del server remoto (es. `sftp.partner.com`).
* **Autenticazione:** Username e Password (archiviati in modo sicuro e criptato).
* **Toggle di Sicurezza:** Abilita SSL/TLS e Modalità Passiva a seconda dei requisiti del server.


# TLS Monitor



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { ShieldCheck, Clock, Globe, Lock } from 'lucide-react';

# TLS Monitor

Il **TLS Monitor** è uno strumento di sicurezza dedicato al monitoraggio costante dei tuoi endpoint HTTPS. A differenza dei normali sistemi di uptime, esegue scansioni approfondite della configurazione crittografica per assicurare che i certificati SSL/TLS siano validi, aggiornati e conformi agli standard moderni.

## Funzionalità Chiave

* **Tracciamento Scadenze:** Visualizzazione in tempo reale delle date di scadenza per prevenire interruzioni di servizio impreviste.
* **Verifica Protocolli:** Assicura che i server utilizzino versioni sicure (TLS 1.2, 1.3) e segnala protocolli obsoleti o vulnerabili (SSLv3, TLS 1.0/1.1).
* **Avvisi di Conformità:** Identifica automaticamente configurazioni non a norma basandosi sul GDPR e sulle best practice di settore.
* **Gestione Multi-Host:** Un'unica dashboard per gestire e monitorare decine di domini simultaneamente.

## Panoramica della Dashboard

La tabella del TLS Monitor fornisce un'istantanea completa dei tuoi host:

| Campo           | Descrizione                                                         |
| :-------------- | :------------------------------------------------------------------ |
| **Hostname**    | L'URL completo monitorato (es. `https://api.tuodominio.it`).        |
| **Status**      | Il risultato dell'ultimo controllo automatizzato (Success/Failed).  |
| **TLS Version** | La versione specifica del protocollo attualmente servita dall'host. |
| **Expire Date** | La data esatta in cui il certificato smetterà di essere valido.     |

<Callout type="warn" title="Alert Automatizzati">
  Il sistema genererà un badge di "Warning" se la scansione rileva suite di cifratura insicure o scadenze imminenti, permettendo al tuo team di rinnovare i certificati prima che gli utenti ne risentano.
</Callout>

## Configurazione

Per aggiungere un nuovo monitor, è sufficiente fornire un nome descrittivo e l'hostname completo. Puoi anche assegnare dei **Tag** per organizzare i monitor per ambiente (es. `Production`, `Staging`) o per progetto.


# Automazioni & Workflow



import { Card, Cards } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import { 
  Zap, 
  Code2, 
  Cpu, 
  Workflow, 
  MessageSquare, 
  Bot 
} from 'lucide-react';

# Workflow Automation

Donutwork integra un potente editor visivo basato su nodi che permette di automatizzare processi complessi senza scrivere codice. Grazie all'architettura **event-driven**, puoi attivare sequenze di azioni ogni volta che accade qualcosa nel tuo SaaS (es. la creazione di un cliente o un aggiornamento di pagamento).

## Come Funziona

Ogni Workflow è composto da tre elementi fondamentali:

1. **Trigger (L'Inizio):** L'evento che scatena il flusso (es. `Customer.create`).
2. **Nodi Logici:** Blocchi che elaborano dati, applicano filtri o prendono decisioni (IF/Else).
3. **Azioni (L'Output):** Operazioni concrete come invio email, chiamate Webhook o aggiornamenti di database.

***

## Catalogo dei Nodi Disponibili

L'editor mette a disposizione una vasta libreria di blocchi pronti all'uso, divisi per categoria:

| Categoria     | Nodi Chiave           | Funzione                                                             |
| :------------ | :-------------------- | :------------------------------------------------------------------- |
| **Controllo** | Trigger, Fine         | Gestiscono l'ingresso e l'uscita del flusso.                         |
| **Logica**    | IF, Switch, Filter    | Permettono di creare percorsi condizionali e instradare i dati.      |
| **Dati**      | Math, Merge, Text     | Eseguono calcoli, uniscono oggetti JSON o formattano stringhe.       |
| **CRM**       | Get Customer, Partner | Recuperano in tempo reale i dati completi delle entità dal database. |
| **Azioni**    | Webhook, Email        | Comunicano con il mondo esterno (es. Slack, CRM, Email Gateway).     |

***

## Automazione con Intelligenza Artificiale

Donutwork porta l'automazione al livello successivo integrando strumenti di AI direttamente nell'editor:

<Cards>
  <Card icon={<Bot className="text-purple-500" />} title="AI Build (Copilot)" description="Descrivi il flusso a parole (es: 'Se un cliente non ha un partner, invia una email') e l'AI costruirà il diagramma per te." />

  <Card icon={<MessageSquare className="text-blue-500" />} title="AI Explain" description="Analizza un workflow esistente per ottenere una spiegazione testuale chiara della logica implementata." />
</Cards>

***

## Funzionalità Avanzate

### Cicli e Variabili

Puoi utilizzare il nodo **Set Variable** per salvare dati temporanei durante l'esecuzione o il nodo **For Each** per iterare su liste di oggetti (es. processare tutti i payout di un partner).

### Prevenzione degli Errori

L'editor include un sistema di **Cycle Detection** che impedisce la creazione di loop infiniti, proteggendo la stabilità del sistema e delle tue API.

### Custom Blocks

Donutwork permette agli sviluppatori di registrare blocchi personalizzati (`Custom Blocks`). Questi nodi appaiono nell'interfaccia con icone e badge specifici, permettendo al team non-tech di utilizzare funzioni aziendali proprietarie (es. `Sync CRM Notifier`) in totale sicurezza.

<Callout type="warn" title="Validazione Obbligatoria">
  Prima di poter salvare un Workflow, il sistema verifica che sia presente un nodo iniziale (Trigger) e un nodo finale (End), e che tutti i nodi posizionati siano effettivamente collegati tra loro.
</Callout>

***

## Esempio di Utilizzo: Welcome Kit

1. **Trigger:** `Customer.create`
2. **Logic:** Nodo `IF` per verificare se il cliente ha una Partita IVA.
3. **Action (True):** Invio email con istruzioni per account Business.
4. **Action (False):** Invio email con istruzioni per account Private.
5. **End:** Chiusura del flusso.