API i Webhooks

Integrisite vašu Mozhe prodavnicu sa eksternim sistemima koristeći webhooks i API integracije. Ovaj vodič pokriva webhook događaje, obrasce integracije i najbolje prakse za izgradnju prilagođenih integracija.

Pregled

Mozhe pruža mogućnosti integracije kroz:

1. Webhooks - Primajte obaveštenja kada se događaji dese u vašoj prodavnici
2. tRPC API - Interni API koji koristi kontrolna tabla (trenutno nije izložen za eksternu upotrebu)
3. Payment webhooks - Callbacks od procesora plaćanja

Razumevanje webhooks

Webhooks su HTTP callbacks koji obaveštavaju vaše eksterne sisteme kada se specifični događaji dese u vašoj prodavnici. Umesto prozivanja za promene, vaš sistem prima obaveštenja u realnom vremenu.

Kako webhooks funkcionišu

1. Događaj se desi u vašoj prodavnici (npr. nova porudžbina)
        ↓
2. Mozhe šalje HTTP POST na vaš webhook URL
        ↓
3. Vaš sistem prima i obrađuje događaj
        ↓
4. Vaš sistem odgovara sa 200 OK

Payment webhooks

Procesori plaćanja šalju webhooks za potvrdu statusa plaćanja. Ovi se automatski konfigurišu na osnovu vaših podešavanja plaćanja.

Chipcard payment webhooks

Za prodavnice koje koriste Chipcard obradu plaćanja, webhooks rukuju:

Tok 3D Secure autentifikacije:

1. Kupac inicira plaćanje
2. Banka preusmerava kupca na 3D Secure autentifikaciju
3. Nakon autentifikacije, banka preusmerava na Mozhe webhook
4. Webhook endpoint obrađuje autorizaciju plaćanja
5. Kupac se preusmerava na stranicu uspeha ili greške

Webhook endpoint:

POST /api/webhooks/chipcard

Polja payload-a:

Kodovi odgovora:

AllSecure payment webhooks

Za prodavnice koje koriste AllSecure obradu plaćanja:

Webhook endpoint:

GET /api/webhooks/allsecure

Query parametri:

KOPA payment webhooks

Za prodavnice koje koriste KOPA obradu plaćanja:

Webhook endpoint:

POST /api/webhooks/kopa

Događaji:

• Plaćanje autorizovano
• Plaćanje zarobljeno
• Plaćanje neuspešno

Resend email webhooks

Obaveštenja o isporuci emaila od Resend:

Webhook endpoint:

POST /api/webhooks/resend

Događaji:

• Email dostavljen
• Email vraćen
• Email označen kao spam

Obrasci integracije

Sinhronizacija porudžbina

Za sinhronizaciju porudžbina sa eksternim sistemom (ERP, fulfillment, itd.):

Preporučeni pristup:

1. Koristite kontrolnu tablu za izvoz porudžbina
2. Implementirajte zakazani posao za upit nedavnih porudžbina
3. Pratite obrađene porudžbine po timestamp-u ili ID-u

Dostupni podaci porudžbine:

• Broj porudžbine i status
• Informacije o kupcu
• Stavke i količine
• Adresa za dostavu
• Status plaćanja

Ažuriranja inventara

Za održavanje sinhronizovanog inventara:

Ručni pristup:

• Izvezite inventar sa kontrolne table
• Uvezite ažuriranja preko upravljanja proizvodima

Grupne operacije:

• Koristite CSV uvoz za velika ažuriranja
• Dostupno u Kontrolna tabla > Proizvodi > Uvoz

Izvoz podataka kupaca

Za CRM integraciju ili marketing alate:

Dostupni podaci:

• Ime i email kupca
• Istorija porudžbina
• Datum kreiranja naloga

Metode izvoza:

• Funkcionalnost izvoza kontrolne table
• Ručna ekstrakcija podataka

Shipping webhooks

Za prodavnice koje koriste integrisane provajdere dostave:

D-Express webhooks

Webhook endpoint:

POST /api/webhooks/dexpress

Događaji:

• Pošiljka kreirana
• Paket u tranzitu
• Paket dostavljen
• Izuzetak pri dostavi

Vercel Analytics webhooks

Za primanje podataka web analitike:

Webhook endpoints:

POST /api/webhooks/vercel-analytics
POST /api/webhooks/vercel-speed-insights

Sigurnost webhooks

Verifikacija webhook zahteva

Da osigurate da su webhook zahtevi legitimni:

1. Proverite izvornu IP - Verifikujte da zahtevi dolaze sa očekivanih IP opsega
2. Validirajte potpise - Neki provajderi uključuju HMAC potpise
3. Koristite HTTPS - Uvek koristite HTTPS endpoints
4. Implementirajte idempotentnost - Rukovodite dupliranim webhook isporukama

Preporučeni sigurnosni headeri

Pri implementiranju webhook prijemnika:

Content-Type: application/json
X-Webhook-Signature: [potpis ako je pruzen]

Rukovanje neuspesima

Ako vaš webhook endpoint vrati grešku:

1. Procesori plaćanja obično pokušavaju više puta
2. Implementirajte logovanje za praćenje neuspelih webhooks
3. Izgradite logiku ponovnog pokušaja za kritične integracije

Izgradnja prilagođenih integracija

API autentifikacija (Buduće)

Javni API pristup trenutno nije dostupan. Za potrebe prilagođene integracije:

1. Kontaktirajte Mozhe podršku
2. Opišite vaše zahteve integracije
3. Razgovarajte o dostupnim opcijama

API-ji za izvoz kontrolne table

Kontrolna tabla pruža funkcionalnost izvoza za:

• Proizvode (CSV)
• Porudžbine (CSV/JSON)
• Kupce (CSV)

Pristupite izvozima preko Kontrolna tabla > Podešavanja > Izvoz.

Prilagođeni razvoj

Za napredne integracije koje zahtevaju prilagođeni razvoj:

1. Partnerski program - Mozhe partneri mogu pristupiti razvojnim alatima
2. Enterprise planovi - Prilagođeni API pristup može biti dostupan
3. Konsultacije - Tehničke konsultacije za složene integracije

Primeri integracija

Primer: Obaveštenje o porudžbini na Slack

Iako direktno prosleđivanje webhooks nije dostupno, možete:

1. Podesiti email obaveštenja za nove porudžbine
2. Koristiti servis kao Zapier za parsiranje emailova
3. Proslediti relevantne podatke na Slack

Primer: Sinhronizacija inventara sa tabelama

1. Izvezite proizvode sa kontrolne table
2. Ažurirajte količine u vašoj tabeli
3. Ponovo uvezite ažurirani CSV

Primer: Izvoz kupaca za email marketing

1. Idite na Kontrolna tabla > Kupci
2. Izvezite listu kupaca
3. Uvezite u vašu email marketing platformu
4. Podesite praćenje saglasnosti odvojeno

Rešavanje problema

Webhook nije primljen

1. Verifikujte da je vaš endpoint javno dostupan
2. Proverite da endpoint vraća 200 status kod
3. Pregledajte logove servera za greške
4. Potvrdite da firewall dozvoljava dolazne konekcije

Neuspesi payment webhook

1. Proverite status porudžbine na kontrolnoj tabli
2. Pregledajte kontrolnu tablu procesora plaćanja za greške
3. Verifikujte da su trgovački akreditivi tačni
4. Kontaktirajte podršku sa ID-jevima transakcija

Duplirane webhook isporuke

1. Implementirajte provere idempotentnosti korišćenjem ID-jeva transakcija
2. Čuvajte obrađene webhook ID-jeve
3. Preskočite već obrađene događaje

Najbolje prakse

1. Odgovorite brzo - Vratite 200 OK u roku od 30 sekundi
2. Obrađujte asinhrono - Stavite dugotrajne zadatke u red čekanja
3. Evidentirajte sve - Održavajte detaljne logove za debagovanje
4. Graciozno rukovodite neuspesima - Izgradite mehanizme ponovnog pokušaja

Ograničenja

Trenutna ograničenja sistema integracije:

• Nema javnog REST API-ja za eksterne aplikacije
• Webhook događaji ograničeni na procesore plaćanja
• Nema prilagođene konfiguracije webhooks za događaje prodavnice
• API ključevi nisu dostupni za eksterni pristup

Zahtevanje novih integracija

Ako vam trebaju mogućnosti integracije koje trenutno nisu dostupne:

1. Kontaktirajte podršku - Opišite vaš slučaj upotrebe
2. Zahtev za funkcionalnost - Pošaljite preko sistema za povratne informacije
3. Upit za partnerstvo - Za mogućnosti razvojnog partnerstva

Sledeći koraci

• Podešavanja plaćanja - Konfigurišite procesore plaćanja
• Upravljanje porudžbinama - Razumite tokove porudžbina
• Početak rada - Završite podešavanje vaše prodavnice