V tomhle článku popisuju řešení, které jsem nasadil u jednoho webu kulturní organizace (nebudu bonzák, neprozradím! 😅).

Jde o malý custom plugin pro WordPress, který si dary z darujme pravidelně stahuje a na webu z nich dělá seznam. Bez Excelu. Bez „nezapomeň to zítra přepsat“. S administrací, aby mohl uživatel příspěvky mazat nebo editovat.

Co bylo cílem (a proč ruční řešení není ono)

Cíl byl jednoduchý:

• Na webu zobrazovat seznam dárců.
• U každého daru mít jméno.
• Zobrazovat částku a případně komentář.

Kdyby se to dělalo ručně, znamenalo by to:

• Někdo musí pravidelně chodit do Darujme.cz.
• Kopírovat data do webu.
• Hlídat, že se některé platby mohou změnit (platba může přijít až za několik dní).

Tohle je přesně typ úkolu, kde automatizace ušetří nervy i chyby.

První kroky: co jsem si potřeboval ujasnit

Než napíšu první řádek kódu, řeším tři věci:

1. Odkud data vezmu. Mají API? Ukazuje se, že ano.
2. Jak poznám nové nebo změněné dary? Budu muset filtrovat podle data.
3. Jak ve WordPressu data uložit, aby šla dobře zobrazit na webu i v administraci, byla filtrovatelná a editovatelná?

Co jsem našel v Darujme API

Darujme má REST API v1, základ tvoří URL:

• https://www.darujme.cz/api/v1

Autentizace je jednoduchá:

• apiId a apiSecret se posílají jako query parametry.
• na webu jsem je šoupnul jako konstanty do wp-config.php.

Klíčový endpoint pro seznam darů byl:

GET /organization/{orgId}/pledges-by-filter

Důležité detaily, na které jsem během implementace narazil:

• API podporuje filtraci dle data poslední změny.
• Částky jsou v haléřích, takže je potřeba dělit 100.
• Dar prochází různými stavy. Ne každý záznam hned znamená „peníze dorazily“.

Co plugin dělá

Chtěl jsem řešení, které bude jednoduché a snadno debugovatelné. Výsledkem je malý plugin (cca 200 řádků PHP), který má tyhle části:

1) API klient

• Sestaví autorizovaný request.
• Stáhne jen nové „přísliby“ (pledges) od poslední synchronizace.
• Vrátí data ve formátu, se kterým se dá dál pracovat.

2) Synchronizace na pozadí

Aby to běželo bez klikání v administraci:

• Script pluginu jsem zavěsil na cron (časovač; na webu běží serverový cron), takže stahování dat probíhá pravidelně.
• Při běhu si plugin vezme timestamp poslední synchronizace z wp_options.
• Stáhne jen nové nebo změněné dary (stav platby).

3) Uložení do WordPressu

Aby šlo dary obsahově editovat uživatelem webu, vytvořil jsem:

• Custom Post Type (např. dary).
• ACF pole pro:
  • jméno
  • částku
  • komentář
  • typ daru
  • datum
  • stav transakce
  • zdroj (API vs. ručně)

Poznámka ke zdroji: Uživatelé na webu mohou v administraci přidat i „ruční“ dary, třeba když firma poslala dar mimo darujme.

Zobrazení na webu

Na webu se zobrazují ty dary, od kterých přišla platba. V tomhle případě je to děláno Oxygen Repeaterem s meta query (filtr na stav nebo zdroj).

V jiných builderech by se použila obdoba - v Gutenberg Query Loop.

Záludnosti: proč mě zdrželo ACF (techničtější)

Nejvíc času (mimo samotné napojení API) padlo na jednu „banální“ věc:

• update_field() mi neaktualizoval hodnoty tak, jak jsem čekal.

Důvod byl v nesouladu mezi:

• meta key (prefixy typu dary_...)
• a tím, co ACF čeká jako název pole

Nakonec jsem to vyřešil pragmaticky:

• Použil jsem update_post_meta().
• A ukládal hodnoty s explicitními referencemi na ACF field keys.

Ponaučení: ACF je super, ale při vyváření CPT kódem je dobré mít jasno, co přesně se ukládá do postmeta.

Výsledek

• Seznam dárců se aktualizuje automaticky.
• Obsahová správa webu se zjednodušila - nemusí se nic kopírovat.
• Pokud se u daru změní stav platby, promítne se to na webu při další synchronizaci.

Časově:

• Základní verze (API klient + cron + CPT + zobrazení): zhruba půl dne včetně studia API dokumentace.
• Ladění ACF: +1 až 2 hodiny navíc.

Chceš na WordPress napojit externí službu přes API?

Pokud chceš na WordPress napojit externí službu (cokoliv, co má API) a nechceš to řešit ručně, ozvi se. Obvykle stačí malý, na míru psaný plugin. Ušetříš si otravnou manuální práci a zamezíš chybám z nepozornosti.