ITE Deploy & Management

Poučení a integrační playbooky — ověřené postupy z reálného zprovoznění Meta / WhatsApp / Commerce / Viber / TestFlight stacku (červenec 2026). Slouží k onboardingu dalších systémů a partnerů: postupuj krok za krokem, každá „lekce" v barevných boxech je zaplacená reálným časem — neopakuj je.

📗 Meta Operations Bible — kanonický fleetový dokument. Tyto playbooky jsou lidský training surface (jak se to nastaví). Souběžný kanonický dokument pro agenty center pokrývá bezpečný provoz Meta stacku (WhatsApp Cloud API, FB/Business Manager, katalog, WA inbox, token recovery, diagnostika + ZÁVAZNÁ pravidla).
Klíčové lekce: jediná správná WABA 3699620903523416 (2 mrtvé nepoužívat); business-initiated = jen schválené šablony; free-text mimo 24h okno = tichý drop (Meta vrátí wamid, ale zprávu zahodí — error 131047); veškerá komunikace s lidmi přes bidirekt comms model (Safe #2442).
📄 Cesta: /opt/handoff/META-OPERATIONS-BIBLE-2026-07-20.md · mirror ~/ite-deploy/docs/meta-operations-bible.md.

Integrační playbooky (7)

1📘

Meta Business Manager — založení a verifikace

BM portfolio · business verification · system user + token · ověření domény

▸

1. Založení BM portfolia

Otevři business.facebook.com → Create a business portfolio. Zadej oficiální název firmy (přesně dle obchodního rejstříku), firemní email a jméno admina.
V Settings → Business info vyplň: právní název, IČO/DIČ, adresu sídla (přesně dle OR), telefon, web, Address a Currency.
Přidej záložní adminy (min. 2 osoby) v Users → People — jediný admin je riziko lockoutu.

⚠ Pole se po verifikaci zamknou. Business info (název, IČO, adresa) po úspěšné business verifikaci NELZE měnit. Vyplň vše přesně podle výpisu z OR ještě PŘED odesláním verifikace.

⚠ „Invite people" wizard si pamatuje access level minulé pozvánky — umí tiše poslat Full access! Před odesláním vždy zkontroluj Review screen, že tam je „Partial access: Basic". A nikdy nepracuj se 2 aktéry (účty) v jednom browser tabu.

2. Business verification (Security Centre)

Settings → Security Centre → Start verification.
Meta porovnává údaje s veřejnými rejstříky — pokud sedí název + adresa s OR, nabídne automatický match (u nás: Domanovická 2480, Praha ✓).
Nahraj doklad: výpis z obchodního rejstříku nebo bankovní výpis s názvem a adresou firmy. Případně doklad totožnosti admina (pas).
Ověření telefonu/emailu domény firmy. Review trvá typicky hodiny až 2 dny.

✓ Ověřeno u nás: IT Enterprise Solution s.r.o. — verifikace schválena 2026-07-16, BM ID 1454412116702110.

3. System user + API token

Settings → Users → System users → Add → jméno ve stylu ite-api, role Admin.
Přiřaď system userovi assety (WABA, stránky, katalog) přes Assign assets s plným oprávněním.
Generate token → vyber aplikaci (např. ITE Business API) → zvol expiraci Never → zaškrtej potřebné scopes.
Token ulož ihned do Safe + lokálně (viz Guide 2) — Meta ho znovu nezobrazí.

✗ Poučení — chybějící scopes v dialogu tokenu: checkboxy oprávnění se odvíjejí od use cases APLIKACE, ne od BM. WhatsApp-only aplikace nabízí pouze whatsapp_* scopes. Pokud potřebuješ business_management, catalog_management nebo pages_*, musíš NEJDŘÍV na developers.facebook.com → App → Use cases → přidat příslušný use case — teprve pak se scopes objeví v dialogu Generate token.

4. Ověření domény (Domain verification)

BM → Brand safety → Domains → Create a domain → zadej doménu (např. it-enterprise.solutions).
Zvol jednu ze 3 metod: meta-tag do <head> webu, DNS TXT záznam, nebo HTML file upload do rootu webu.
Klikni Verify. Ověřená doména je nutná pro webhooky, katalogové feedy a whitelisting odkazů v šablonách.

2💬

WhatsApp Business Cloud API — kompletní zprovoznění

CLOUD_API vs ON_PREMISE · subscribe · register · business profil · šablony · odesílání

▸

✗ KRITICKÉ POUČENÍ — jedno číslo, více WABA: jedno telefonní číslo se může objevit ve VÍCE WABA účtech současně (např. po migraci nebo ručním založení v UI). S API funguje POUZE to, které má platform_type: CLOUD_API. Než začneš cokoliv ladit, VŽDY nejdřív ověř, ve které WABA je API-schopná instance čísla — jinak ztratíš hodiny na "nefunkčním" čísle.

TOKEN=$(cat ~/ite-deploy/secrets/wa-system-token.txt)

# Ověření platform_type — použitelné je POUZE číslo s CLOUD_API:
curl -s "https://graph.facebook.com/v23.0/{WABA_ID}/phone_numbers?fields=platform_type,status,display_phone_number&access_token=$TOKEN" | jq

✓ Naše ověřená funkční konfigurace:

WABA ID (CLOUD_API)	3699620903523416
Phone Number ID	1159965813877092
Číslo	+420 608 958 313
Token	System user `ite-api`, non-expiring — `~/ite-deploy/secrets/wa-system-token.txt` + Safe #2427 / #2432

✗ Meta „API access blocked" (code 200): pokud tahle chyba chodí i na /me a debug_token, je zablokovaná CELÁ aplikace, ne token — typicky Data Use Checkup / nepřijaté terms / automatika po náhlé aktivitě. Fix: developers.facebook.com → appka → banner nahoře → projít checkup. Stalo se 18.7. — user odblokoval za 2 minuty. Neztrácej čas rotací tokenů.

1. Subscribe aplikace k WABA (webhooky)

curl -s -X POST "https://graph.facebook.com/v23.0/{WABA_ID}/subscribed_apps" \
  -H "Authorization: Bearer $TOKEN"
# → {"success": true} — aplikace odebírá webhooky WABA

⚠ Webhook pole messages se MUSÍ subscribovat v App Dashboardu (Use case → Configuration → Webhook → Manage) — bez toho Meta NEDORUČUJE příchozí zprávy, přestože callback URL je nastavená a verify prošel. Přes API to bez app secret nastavit nejde — jedině ručně v dashboardu.

✓ Tok příchozích WA zpráv (text i HLAS) — ověřeno: nginx /wa/webhook → 127.0.0.1:4090 (/opt/comms-inbound/wa_webhook.py na mngmt) → collab_db comms_message. Hlasovky se automaticky přepisují přes Gemini. Starý node server (4080) obsluhuje už jen Viber.

2. Registrace čísla pro Cloud API

curl -s -X POST "https://graph.facebook.com/v23.0/{PHONE_ID}/register" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"messaging_product":"whatsapp","pin":"123456"}'
# pin = 6místný 2FA PIN (nový, nebo existující pokud byl dřív nastaven)

3. Vyplnění business profilu

Logo se nahrává přes resumable upload — výsledný handle (4:...) se použije jako profile_picture_handle:

# a) Upload session (APP_ID = ID Meta aplikace, SIZE = bajty souboru)
curl -s -X POST "https://graph.facebook.com/v23.0/{APP_ID}/uploads?file_length={SIZE}&file_type=image/png&access_token=$TOKEN"
# → {"id": "upload:MTph..."}

# b) Nahrání souboru → vrátí handle "4:..."
curl -s -X POST "https://graph.facebook.com/v23.0/upload:MTph..." \
  -H "Authorization: OAuth $TOKEN" -H "file_offset: 0" \
  --data-binary @logo.png

# c) Zápis profilu
curl -s -X POST "https://graph.facebook.com/v23.0/{PHONE_ID}/whatsapp_business_profile" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "about": "IT Enterprise — vývoj aplikací a IT řešení",
    "description": "Vývoj mobilních a webových aplikací na míru.",
    "email": "info@it-enterprise.pro",
    "websites": ["https://it-enterprise.solutions"],
    "vertical": "PROF_SERVICES",
    "profile_picture_handle": "4:HANDLE_Z_KROKU_B"
  }'

4. Message templates (šablony)

curl -s -X POST "https://graph.facebook.com/v23.0/{WABA_ID}/message_templates" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "objednavka_potvrzeni_v2",
    "language": "cs",
    "category": "UTILITY",
    "components": [{
      "type": "BODY",
      "text": "Dobrý den {{1}}, vaše objednávka {{2}} byla přijata.",
      "example": { "body_text": [["Jan Novák", "#12345"]] }
    }]
  }'

⚠ Pravidla, na která jsme narazili:
• BODY s proměnnými {{1}} MUSÍ obsahovat example.body_text — jinak API vrátí chybu.
• Šablona BEZ proměnných naopak NESMÍ mít example vůbec.
• Kategorii (UTILITY vs MARKETING) si Meta klasifikuje sama podle textu — tvůj údaj může přepsat.
• Opakované odeslání stejného jména s jinou kategorií selže. Řešení: použij nové jméno šablony (např. suffix _v2).

5. Odeslání zprávy ze šablony

curl -s -X POST "https://graph.facebook.com/v23.0/{PHONE_ID}/messages" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "420777123456",
    "type": "template",
    "template": {
      "name": "objednavka_potvrzeni_v2",
      "language": { "code": "cs" },
      "components": [{
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Jan Novák" },
          { "type": "text", "text": "#12345" }
        ]
      }]
    }
  }'

3🛒

Katalog produktů — Commerce Manager

Feed-URL bez API permission · CSV formát · napojení na WhatsApp

▸

✓ Poučení — feed URL nepotřebuje API oprávnění: přes Scheduled feed URL se katalog plní BEZ catalog_management scope (který WhatsApp-only aplikace stejně nemá — viz Guide 1). Katalog se založí ručně v UI a dál se synchronizuje sám z CSV na našem webu.

1. Založení katalogu a feedu

business.facebook.com/commerce → Create catalog → typ E-commerce, vlastník = náš BM.
V katalogu: Data sources → Data feed → Scheduled feed.
Zadej URL feedu, plán Daily a čas synchronizace. Ulož — první sync proběhne hned.
Zkontroluj Issues tab — chybné řádky feed reportuje po každém syncu.

2. Naše konfigurace

Catalog ID	1546545143616577
Feed URL	https://it-enterprise.solutions/assets/products/catalog-feed.csv
Generátor	CSV se generuje z `PRODUCTS` dictu v `~/ite-deploy/scripts/meta-commerce-setup.py`
Obrázky	/assets/products/*.png
Měna / sync	CZK · denně v 6:00

3. Formát CSV

id,title,description,availability,condition,price,link,image_link,brand
ite-dms,DMS — Dokumenty,Správa firemních dokumentů,in stock,new,"25000.00 CZK",https://it-enterprise.solutions/dms,https://it-enterprise.solutions/assets/products/dms.png,IT Enterprise

⚠ Formát ceny: přesně "25000.00 CZK" — částka s dvěma desetinnými místy, mezera, ISO kód měny. Jiné formáty feed odmítne.

4. Napojení katalogu na WhatsApp

WhatsApp Manager → Account tools → Catalog → Connect catalog → vyber katalog.
Zapni toggle Add to cart (košík v chatu) a toggle ikony katalogu v hlavičce chatu.
Ověř v aplikaci WhatsApp: profil firmy nyní zobrazuje záložku katalogu s produkty.

4📄

Facebook stránky a partneři

Classic Pages vs. professional-mode profily · přidání stránky · partneři a sdílení assetů

▸

✗ Poučení — professional-mode profily do BM nepatří: profily v „professional mode" (URL tvaru facebook.com/people/..., ID s prefixem 615...) NELZE přidat do Business Manageru. BM přijímá pouze classic Pages. Zkontroluj typ PŘED tím, než ztratíš čas — pokud partner má jen professional profil, musí si nejdřív vytvořit klasickou stránku.

⚠ Pozor na vyhledávání podle jména: name-search vrací i podobně pojmenované cizí firmy. Reálný případ: „IT-Enterprise" ID 100063755061744 = ukrajinská firma, NENÍ naše. Vždy ověř ID / URL / adresu stránky, než požádáš o přístup.

1. Přidání existující stránky do BM

BM → Settings → Accounts → Pages → Add → Add a Page.
Vlož URL nebo přesný název stránky. Podmínka: účet, který žádá, musí mít na stránce full control.
Stránka se připojí okamžitě (bez schvalování, pokud máš full control).

2. Vytvoření nové stránky

BM → Accounts → Pages → Add → Create a new Page → kategorie, název, popis.
Nová stránka je rovnou vlastněná BM — žádný převod není potřeba.

3. Partneři a sdílení assetů

BM → Users → Partners → Add → buď zadej Business ID partnera, nebo vygeneruj invitation link.
Po připojení partnera přiřaď assety: katalog, WABA, stránky — každý asset zvlášť s vlastní úrovní oprávnění (per-asset permissions).
Zásada minima: partner dostane jen assety a role, které k práci potřebuje. Full control jen výjimečně.

5📲

Viber Business

partners.viber.com · Auth Token · webhook setup skript

▸

Postup zprovoznění

Webhook je nasazený na office.it-enterprise.pro/viber/webhook (server office).
Registruj bota / Public Account na partners.viber.com → v detailu bota zkopíruj Auth Token.
Na serveru spusť setup skript s dosazeným tokenem — zaregistruje webhook u Viberu:

# na serveru office — dosaď skutečný Auth Token z partners.viber.com:
AUTH_TOKEN="xxxxxxxx-xxxx-xxxx" /opt/wa-webhook/viber-setup-commands.sh

# webhook endpoint: https://office.it-enterprise.pro/viber/webhook

⚠ Poučení: Auth Token je vázaný na konkrétní bot/PA. Pokud API vrací invalidAuthToken, bot pod daným číslem už neexistuje nebo byl vytvořen pod jiným účtem — ověř na partners.viber.com, případně založ nový PA (viz stav v záložce Kanály).

6🍎

TestFlight notifikace testerům

/opt/testflight-notifier na ops · apps.json + testers.json · cron 30 min · email 4 jazyky + WhatsApp šablona

▸

Architektura

Server	ops · 157.180.86.49:22770 · /opt/testflight-notifier/
apps.json	Seznam aplikací; admin doplní `tf_url` jakmile Apple build schválí
testers.json	Testeři s emaily a jazyky (RU / UA / HE / CZ)
Cron	*/30 min
Notifikace	Email ve 4 jazycích dle jazyka testera + WhatsApp šablona `ite_testflight_new` (uk/cs/ru/he, params: název appky + TF URL) přes Graph API v21.0, Phone ID 1159965813877092. Dedup přes `state.json` — jedna notifikace na appku, oba kanály najednou.

✗ KRITICKÉ — Apple od 2026-04-28 TIŠE zahazuje uploady se starým SDK: TestFlight build kompilovaný SDK starším než iOS 26 (Xcode 26) Apple po uploadu zahodí. eas submit hlásí úspěch, build se v App Store Connect NIKDY neobjeví — chyba přijde jen emailem na Apple účet. Diagnóza: stáhnout .ipa → zkontrolovat DTXcode/DTSDKName v Info.plist. Fix: Expo SDK ≥ 55 (npm i expo@^55 && npx expo install --fix, smazat newArchEnabled). Takto opraven rabbi-eliyahu 17.7.

Postup při novém buildu

Apple schválí build pro TestFlight → v ASC zkopíruj public link (https://testflight.apple.com/join/XXXXXXXX).
TestFlight code = suffix za /join/ v URL.
Doplň tf_url k aplikaci v /opt/testflight-notifier/apps.json.
Cron do 30 minut rozešle notifikace všem testerům z testers.json v jejich jazyce (email + WhatsApp). Nic dalšího není potřeba.

✓ Ověřený postup zveřejnění nové appky (ShifTora, 18.7.): public link testflight.apple.com/join/Uu4kbThU, beta review schválen za ~1 den. Kroky pro nový build: export compliance (usesNonExemptEncryption=false) + beta localizations + review contact + přiřadit build skupině + POST betaAppReviewSubmissions.

7✅

Checklist — onboarding nového systému / partnera

Univerzální pořadí kroků pro každý další systém (FB / WA / IG / Viber / partner)

▸

Znovupoužitelný postup — projdi shora dolů, každý krok odkazuje na příslušný playbook výše:

Vytvořit / ověřit asset v Business Manageru — BM, stránka, WABA, katalog (Guide 1, 3, 4). U stránek zkontrolovat, že jde o classic Page.
System user + token se správnými scopes — nejdřív zkontrolovat use cases aplikace na developers.facebook.com, pak Generate token (Guide 1 §3).
Webhook subscribe — POST /{waba}/subscribed_apps, resp. platformní webhook (Viber setup skript) (Guide 2 §1, Guide 5).
Vyplnit business profil — about, popis, email, weby, vertical, logo přes resumable upload (Guide 2 §3).
Vytvořit a nechat schválit message templates — pozor na pravidla example/kategorie (Guide 2 §4).
Připojit katalog — Commerce Manager feed → WhatsApp/FB, zapnout Add to cart (Guide 3).
Pozvat partnery a přiřadit assety — Business ID / invitation link, per-asset permissions (Guide 4 §3).
Uložit vše do Safe — tokeny, PINy, ID assetů, webhook secrety. Bez záznamu v Safe není krok hotový.
Aktualizovat memory / wiki / dashboard — ID a stavy zapsat sem do Kanálů/Služeb a do memory.
Hlídat inbox a review fronty — po každé žádosti (Meta review, partner invite, template approval) nastavit monitoring odpovědí.