fluxuri n8n

AI-School poate porni fluxuri n8n printr-un webhook de producție. Acest lucru este util atunci când vrei să pornești un proces automat în afara AI-School, de exemplu crearea unei sarcini, actualizarea unui înregistrări CRM, inițierea unui flux de raportare sau transmiterea datelor dintr-un formular către un alt sistem.

Exemplu: articol de știre pe site-ul școlii

Să presupunem că școala are un flux n8n care postează un articol de știre pe site-ul WordPress al școlii. În AI-School completezi apoi doar un scurt fragment de text, de exemplu câteva enunțuri despre o săptămână de proiect, ziua sportului sau ziua porților deschise. Cu acel text pornești fluxul în n8n.

Fluxul n8n poate apoi, de exemplu:

1. Să transformeți scurtul text într-un text de experiență folosind o nodă LLM și un prompt care se potrivește tonului școlii.
2. Să generezeți o ilustrație potrivită cu a doua nodă LLM, de exemplu în culorile școlii și într-un stil ilustrativ recognoscibil.
3. Să pregătiți sau să publicați textul și imaginea ca articol de blog pe site-ul WordPress.

Așa lucrează AI-School și n8n împreună: în AI-School utilizatorul alege fluxul de lucru și completează informațiile necesare. n8n efectuează apoi pașii automatizați și se asigură că articolul apare în mod corespunzător pe site.

Ce face această integrare?

Pornești un flux de lucru n8n din vizualizarea fluxului de lucru. Doar webhook-ul de producție, POST și autentificarea Header sunt obligatorii. Câmpurile și notificările din n8n sunt opționale și pot fi configurate independent.

• Dacă fluxul de lucru nu are câmpuri, webhook-ul este apelat imediat.
• Dacă fluxul de lucru are câmpuri, se deschide mai întâi un formular. Utilizatorul completează câmpurile și apoi pornește fluxul cu butonul.
• Valorile completate sunt trimise ca JSON în cadrul unui POST către webhook-ul n8n.
• Fără notificări, AI-School confirmă doar că fluxul a fost pornit și continuă în n8n. Fereastra nu afișează un spinner și poate fi închisă imediat.
• Dacă această opțiune este activată la înregistrare, fluxul poate transmite pași intermediari sau finalul înapoi către AI-School.
• Dacă aprobarea este activată la înregistrare, utilizatorul poate alege direct în AI-School. n8n va continua apoi de la pasul în așteptare.

Ce face această integrare?

Pornești un flux de lucru n8n din lista de fluxuri. Doar webhook-ul de producție, POST și autentificarea header sunt obligatorii. Câmpurile și feedback-ul din n8n sunt opționale și pot fi configurate independent.

• Dacă fluxul de lucru nu are câmpuri, webhook-ul este apelat imediat.
• Dacă fluxul de lucru are câmpuri, se deschide mai întâi un formular. Utilizatorul completează câmpurile și apoi pornește fluxul cu butonul.
• Valorile completate sunt trimise ca JSON în cadrul unui POST către webhook-ul n8n.
• Fără feedback, AI-School doar confirmă că fluxul a fost pornit și continuă în n8n. Fereastra nu afișează spinner și se poate închide imediat.
• Dacă această opțiune este activată la înregistrare, fluxul poate trimite pași intermediari sau finalul înapoi către AI-School.
• Dacă aprobarea la înregistrare este activată, utilizatorul poate face o alegere direct în AI-School. n8n va continua apoi de la pasul în așteptare.

Crearea fluxului n8n în AI-School

Un administrator înregistrează fluxul de lucru în felul următor:

1. Mergi la Asistenți.
2. Deschide Fluxuri de lucru.
3. Alege Nou flux de lucru n8n.
4. Completează numele fluxului și URL-ul de producție n8n.
5. Setează Autentificare Header cu un nume de header și o valoare secretă a header-ului.
6. Bifează sub Feedback din n8n doar componentele care au fost efectiv construite în acest flux n8n: progres, aprobare și/sau finalul fluxului.
7. Adaugă eventual câmpurile care trebuie trimise în cadrul POST-request-ului.
8. Salvează fluxul de lucru.

Toate cele trei opțiuni de feedback sunt dezactivate implicit. Dacă mai târziu adaugi callback-uri sau un pas de aprobare în n8n, actualizează înregistrarea în AI-School. Dialogul va ști astfel dacă trebuie să arate doar o confirmare de început sau să aștepte semnale ulterioare.

Câmpuri

• Câmpurile sunt opționale.
• Fiecare câmp are un nume de câmp și un tip.
• Tipuri de câmp acceptate: text scurt, text lung, numeric, da/nu, dată, o singură alegere și multiple alegeri.
• La O singură alegere și Mai multe alegere adaugi opțiunile disponibile. O singură alegere este afișată ca o listă de selecție compactă; Mai multe alegeri afișează casete de selectare. Valorile alese sunt trimise în corpul JSON.
• Câmpurile obligatorii trebuie completate înainte ca fluxul să poată fi pornit.
• Numele câmpului devine cheia în corpul JSON trimis către n8n.

Crearea unui flux de lucru compatibil în n8n

1. Creează în n8n un flux de lucru nou.
2. Adaugă ca prim nod un Webhook.
3. Atribuie acestui nod exact numele Start workflow. Exemplele din continuare folosesc acest nume.
4. Setează HTTP Method la POST.
5. Alege în Authentication opțiunea Header Auth și selectează un credential de Header Auth.
6. completează în acel credential același nume de header și valoarea secretă ca în fluxul din AI-School.
7. Setează Respond sau Response Mode la Immediately. Aplicația primește atunci o confirmare de început imediată, în timp ce n8n continuă să lucreze.
8. Copiază Production URL a nodului Webhook în câmpul n8n producție-url din AI-School. Nu folosi URL-ul de test cu /webhook-test/.
9. Activează fluxul de lucru în n8n.

Datele din AI-School sunt în n8n sub body. Astfel, datele de integrare se regăsesc sub body.integration. Nu șterge aceste date într-un nod Edit Fields-, Set- sau Code. Exemplele de mai jos le citesc întotdeauna direct din nodul Start workflow.

Exemplu de corp JSON

Dacă definești câmpuri cu numele prompt, numeClient, publicuri țintă și dată, n8n va primi de exemplu acest corp JSON. AI-School adaugă obiectul integration în mod automat.

{
  "prompt": "Fă o scurtă sinteză a cererii.",
  "numeClient": "OrganizațieExemplu",
  "publicuri țintă": ["angajați", "părinți"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "token-temporar-pentru-această-executare"
  }
}

Tokenul de callback este pentru o singură execuție. Nu-l stoca în jurnale, configurații sau alte sisteme.

Opțional: transmiterea progresului și a finalizării

AI-School poate afișa doar ceea ce transmite n8n. Folosește aceste callback-uri doar dacă în înregistrare ai activat Notificare progres intermediar și/sau Notificare final flux de lucru.

Configurare nod HTTP Request

1. Adaugă un nod HTTP Request și numește-l de exemplu Notifică progresul.

2. Setează Method la POST.

3. Fă clic pe URL la Expression.

4. Inserează exact această expresie:

   {{ $('Start workflow').first().json.body.integration.callbackUrl }}

5. Alege Authentication ca None. Token-ul temporar va fi adăugat ca header în pasul următor.

6. Activează Send Headers și adaugă aceste două headers:

   Name	Value
   Authorization	Bearer {{ $('Start workflow').first().json.body.integration.callbackToken }}
   Content-Type	application/json

7. Activează Send Body.

8. Alege Body Content Type: JSON și Specify Body: Using JSON.

9. Lipeste JSON-ul de mai jos în câmpul JSON:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "document-creare-inițiată",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_maken",
    "label": "Document realizat"
  },
  "message": "Documentul este în producție."
}

10. Alege Execute step în timp ce testezi fluxul prin aplicație. Nodul ar trebui să răspundă cu status 200.

Copiază această nod HTTP Request pentru fiecare status de notificare. Ajustează în fiecare copie cel puțin eventId, step.id, step.label și message.

Configurarea ultimei notificări

Dacă Notificare final flux de lucru este activată, la finalul fiecărei rute posibile trebuie să existe o ultimă callback. Folosește type: "completed" pentru succes, type: "failed" pentru o eroare pe care o gestionezi, și type: "rejected" când utilizatorul respinge fluxul de lucru.

Exemplu de corp pentru o execuție de succes:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "workflow-finalizat",
  "type": "completed",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "finalizare",
    "label": "Workflow finalizat"
  },
  "message": "Fluxul de lucru a fost finalizat.",
  "output": {
    "rezultat": "Sumar scurt sau link către rezultatul"
  }
}

Folosește în cadrul aceleiași execuții pentru fiecare callback un eventId diferit. De asemenea, asigură-te că întotdeauna eticheta step.label este clar vizibilă pentru utilizator.

Opțional: solicitare aprobării în aplicație

Configurare nod Wait

1. Adaugă la locul unde este necesară aprobarea un nod Wait.
2. Alege la Resume opțiunea On Webhook Call.
3. Setează HTTP Method la POST.
4. Alege Authentication ca Header Auth.
5. Selectează același credential Header Auth ca la nodul Start workflow.
6. Plasează înaintea nodului Wait o copie a nodului HTTP Request configurat anterior și numește-l Solicită aprobare.
7. Folosește în acest nod aceeași URL dinamică și aceleași header-e. Schimbă numai corpul JSON cu:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "control-document",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "controle_document",
    "label": "Controlează documentul"
  },
  "approval": {
    "question": "Poate fluxul să progreseze?",
    "context": "Mai întâi verificați documentul generat.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Aprobă" },
      { "value": "reject", "label": "Respinge" }
    ]
  }
}

Conectează Solicită aprobare la nodul Wait. Utilizatorul va vedea apoi butoanele în AI-School. URL-ul de relansare secret nu este expus în browser; serverul trimite în siguranță alegerea către nodul Wait.

Procesarea opțiunii după Wait

1. Adaugă după nodul Wait un nod Switch.

2. Folosește ca valoare de verificat:

   {{ $json.body.decision }}

3. Creează, de exemplu, o rută pentru approve și una pentru reject.

4. Fiecare rută se încheie cu un callback potrivit: completed, rejected sau failed.

O valoare de alegere poate conține doar litere, cifre, _ și -. Eticheta poate conține text lizibil.

Configurarea URL-ului de callback de producție

URL-ul de callback de producție pentru AI-School este:

https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback

Nu lipi acest URL ca text fix în fiecare nod de callback. Alege în câmpul URL al nodului HTTP Request opțiunea Expression și folosește:

{{ $('Start workflow').first().json.body.integration.callbackUrl }}

Astfel AI-School va livra automat URL-ul de producție corect la fiecare pornire. URL-ul fix de mai sus este folosit doar pentru a verifica în timpul testării dacă expresia se referă la AI-School.

Funcțiile triggerCustomN8nWorkflow, triggerN8nWorkflow și resumeN8nWorkflow sunt chemate de către aplicație în mod intern. Nu este necesar să le configurezi în n8n.

Gestionarea erorilor neprevăzute

Un callback failed obișnuit funcționează doar dacă fluxul de lucru atinge nodul HTTP Request respectiv. Folosește pentru erorile de noduri neașteptate un Workflow de Erori central în n8n.

Crearea unui Workflow de erori central

1. Creează în n8n un flux separat cu numele AI-School - erori de transmis.

2. Adaugă un nod Error Trigger.

3. Adaugă apoi un nod HTTP Request.

4. Setează Method la POST.

5. Completează în URL această adresă de producție fixă:

   https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowExecutionFailed

6. Alege Authentication: None.

7. Activează Send Headers și adaugă:

   Name	Value
   n8n-handihow-name	valoarea secretă standard primită de la administratorul platformei
   Content-Type	application/json

8. Activează Send Body, selectează JSON și inserează corpul:

{
  "executionId": "{{ $json.execution.id }}",
  "workflowId": "{{ $json.workflow.id }}",
  "workflowName": "{{ $json.workflow.name }}",
  "lastNode": "{{ $json.execution.lastNodeExecuted }}",
  "message": "{{ $json.execution.error.message }}"
}

9. Activează Workflow-ul de erori.
10. Deschide setările fluxului de lucru obișnuit și selectează în Error Workflow acest nou Workflow de erori.

Trimite imediat după Start workflow cel puțin un callback de progres cu executionId: "{{ $execution.id }}". Astfel aplicația știe la ce execuție apar o eroare imprevizibilă în n8n.

Limite importante

• Doar declanșatoare webhook sunt suportate.
• Doar URL-urile de webhook de producție sunt suportate.
• URL-urile de test pentru webhook cu /webhook-test/ sunt respinse.
• Doar POST este suportat.
• Doar autentificare header generic este suportată.
• Valoarea header-ului este tratată ca secret în aplicație.
• Token-urile de callback și URL-urile de resume sunt prelucrate doar pe server și nu sunt disponibile direct utilizatorilor.
• Tenant-ul este determinat pe server în funcție de utilizatorul autentificat, nu dintr-o valoare trimisă de browser.

##Soluționarea problemelor

• 404 sau webhook neînregistrat: activează fluxul în n8n și folosește URL-ul de producție.
• Eroare de autentificare: verifică dacă numele header-ului și valoarea sunt identice în ambele sisteme.
• Date lipsă: verifică dacă denumirile câmpurilor din aplicație corespund cu cheile pe care le așteaptă n8n.
• Fără cerere în n8n: verifică dacă fluxul de lucru începe cu un declanșator webhook și utilizează POST.
• Fereastra de execuție se învârte: dacă ai activat finalul fluxului înregistrat, verifică dacă n8n trimite un callback final completed, failed sau rejected. Dacă nu aștepți notificări, dezactivează toate cele trei opțiuni în înregistrare.
• Nicio progresie vizibilă: verifică dacă Notificare progres intermediar este activată în înregistrare, sau dacă obiectul integration este păstrat și dacă fiecare callback are un eventId unic.
• Butoanele de aprobare nu funcționează: verifică nodul Wait, resumeUrl, autentificarea header și caracterele permise în choices[].value.