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 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).

{
  "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.

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:

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

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

Regola di verifica lato app:

$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.