Dokumentace pro vývojáře

Napojení rezervačních systémů, e-shopů a CRM: předejte kontakt po návštěvě nebo doručení objednávky. Reputive podle nastavení firmy zařadí žádost o recenzi do e-mailové nebo SMS sekvence. Přijetí kontaktu nepotvrzuje odeslání ani doručení zprávy.

Základní URL: https://app.reputive.cz

Stáhnout OpenAPI 3.1 (JSON)

Ověření a oprávnění

Vlastník firmy vytvoří klíč v Nastavení → Integrace → API klíče výběrem typu integrace. Pro vlastní napojení zvolte Vlastní API. Název určuje typ, nezadává se volně. Klíč začíná rep_live_ a celý se zobrazí jen při vytvoření. Uložte jej na serveru; nevkládejte jej do veřejného JavaScriptu. Vlastník jej může odvolat.

Použijte hlavičku Authorization: Bearer rep_live_REPLACE_ME. Jen jednotlivý POST collect přijímá také api_key v JSON těle pro konektory bez podpory hlaviček. Použitelná Bearer hlavička má přednost. GET a batch vyžadují hlavičku.

Klíč patří jedné firmě a má pevný zdroj a schopnosti. collect:write dovoluje příjem kontaktů; WooCommerce navíc product_reviews:write. Klíč Power BI má pouze analytics:read a collect odmítne. Zdroj v těle se musí přesně shodovat se zdrojem klíče. Libovolné názvy zdrojů ani custom nejsou platné; vlastní integrace používá api.

Vlastní API a Zapier: Pro nebo Business. Klíče WooCommerce, Shoptet, Wix a Upgates: od Starter. Power BI: Pro nebo Business a dostupná funkce exportu. Free nemá příjem kontaktů. Platí oprávnění aktuálního tarifu včetně platné zkušební doby; po jejím vypršení bez předplatného se přístup omezí. Samotný úspěšný GET collect tarif nekontroluje.

Správa API klíčů

Příjem zákazníků

`GET /api/integrations/collect`

GET ověří klíč a schopnost collect:write, vrátí firmu a zdroj klíče. Nevytváří zákazníka ani zprávu a nekontroluje tarif ani nastavení odesílání.

curl 'https://app.reputive.cz/api/integrations/collect' \
  -H 'Authorization: Bearer rep_live_REPLACE_ME'

{"success":true,"business":{"id":"11111111-1111-4111-8111-111111111111","name":"Example shop"},"connector":"api","message":"Connection OK"}

`POST /api/integrations/collect`

POST přijímá JSON objekt zákazníka. Neznámá pole jsou ignorována. Odpověď queued znamená naplánovanou sekvenci, skipped znamená vynechání sekvence; důvod je v reason. Odpověď pending_verification vyžaduje vyřešení přiřazení v Reputive a není potvrzením odeslání.

Příjem zákazníků
Pole	Typ	Povinné	Význam a limity
`first_name`	`string`	Ano	Neprázdný řetězec, minimálně 1 znak. Horní délkový limit schéma neurčuje.
`last_name`	`string \| null`	Ne	Příjmení. Prázdný řetězec a null znamenají neuvedeno.
`email`	`string \| null`	E-mail nebo telefon	Platná e-mailová adresa; prázdný řetězec a null znamenají neuvedeno. Je vyžadován e-mail nebo telefon.
`phone`	`string \| null`	E-mail nebo telefon	Telefon jako řetězec. Používejte mezinárodní předvolbu. Schéma formát ani délku neověřuje; prázdný řetězec a null znamenají neuvedeno.
`gdpr_consent`	`true \| 1 \| "1" \| "true"`	Ano	Musí potvrzovat oprávnění k odeslání žádosti. Posílejte true; přijaty jsou i 1, "1" a "true". false, chybějící hodnota a jiné hodnoty jsou odmítnuty.
`source`	`string (enum)`	Ano	Povinný zdroj shodný s klíčem: api, zapier, woocommerce, shoptet, wix nebo upgates. Schéma zná i base, altegio a reenio pro vestavěné konektory; tyto typy nelze vybrat při vytváření veřejného API klíče.
`external_id`	`string \| null`	Ne	Volitelný identifikátor události. Použije se k rozpoznání opakovaného podání čekajícího na ověření, pokud chybí idempotency_key. Nezajišťuje idempotenci běžného příjmu. Prázdný řetězec a null znamenají neuvedeno.
`idempotency_key`	`string`	Ne	1–256 znaků. Má přednost před external_id při rozpoznání opakovaného podání čekajícího na ověření. Běžné zařazení sekvence nepoužívá tento klíč jako zámek proti opakování.
`location_id`	`string \| null`	Ne	ID aktivní pobočky dané firmy. Pro api je možné vynechat jen při jediné aktivní pobočce. Neplatná nebo nejednoznačná pobočka vede k pending_verification bez nové sekvence. Wix vyžaduje výslovnou pobočku. Prázdný řetězec a null znamenají neuvedeno.
`start_delay_hours`	`number \| string`	Ne	Číslo nebo číselný řetězec: hodiny od přijetí požadavku. Desetinná část se odstraní, hodnota se omezí na 0–720; neplatné hodnoty se ignorují. Prodleva se přičítá k prodlevám jednotlivých kroků sekvence. Staré pole delay_hours se ignoruje.
`product`	`object \| null`	Ne	Volitelný produkt v žádosti o recenzi, nikoli import produktových recenzí. Chybné části se zahodí a uvedou ve warnings; příjem zákazníka tím neselže.

product.name: povinný neprázdný text, po sloučení mezer nejvýše 120 znaků (vstup nejvýše 480). product.image_url: volitelná HTTPS URL bez přihlašovacích údajů, nejvýše 500 znaků před i po normalizaci. product.item_count: volitelné celé číslo 1–999, počet různých položek, nikoli kusů. product.url a ostatní neznámá pole se ignorují.

Příklady požadavků a odpovědí

curl 'https://app.reputive.cz/api/integrations/collect' \
  -H 'Authorization: Bearer rep_live_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  --data '{"first_name":"Jana","email":"jana@example.com","gdpr_consent":true,"source":"api","location_id":"22222222-2222-4222-8222-222222222222","start_delay_hours":0,"product":{"name":"Example product","item_count":1}}'

{"success":true,"customerId":"33333333-3333-4333-8333-333333333333","status":"queued"}

`POST /api/integrations/collect/batch`

Tělo obsahuje customers: pole 1–50 stejných zákaznických objektů. Neplatné pole nebo neshodný zdroj odmítne celou dávku před zpracováním. Po zpracování může HTTP 200 a success: true obsahovat jednotlivé chyby. results zachovává pořadí vstupu; kontrolujte success každé položky. sent počítá queued nebo sent, nikoli potvrzené doručení; skipped, quarantined a errors jsou počty dalších výsledků. warnings obsahuje index (od nuly) a issues.

curl 'https://app.reputive.cz/api/integrations/collect/batch' \
  -H 'Authorization: Bearer rep_live_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  --data '{"customers":[{"first_name":"Jana","email":"jana@example.com","gdpr_consent":true,"source":"api","location_id":"22222222-2222-4222-8222-222222222222"}]}'

{"success":true,"sent":1,"skipped":0,"quarantined":0,"errors":0,"results":[{"success":true,"customerId":"33333333-3333-4333-8333-333333333333","status":"queued","email":"jana@example.com"}]}

Stavové kódy collect

200: GET: spojení v pořádku. POST: queued nebo skipped. Batch: dokončené vyhodnocení, možné chyby položek.
202: Jednotlivý POST: pending_verification, receiptId a případně reason/email. Pobočka nebo kontakt potřebují ověření; zvláštní příjem Wix může vrátit pouze potvrzení receiptId.
204: OPTIONS: CORS preflight bez těla.
400: POST/batch: neplatná zákaznická data, chybějící souhlas nebo kontakt; batch vrací details. Jednotlivý POST má také větev pro chybějící pobočku Wix.
401: GET/POST/batch: chybějící nebo neplatný klíč.
403: GET/POST/batch: klíč nepovoluje příjem. POST/batch navíc: zdroj nesouhlasí nebo tarif nepovoluje příjem (upgradeRequired: true).
409: Jednotlivý POST má větev pro konflikt kontaktu Wix. Nejednoznačné kontakty se běžně vracejí jako pending_verification; neřešte konflikt opakovaným odesíláním.
429: POST/batch: překročen limit požadavků.
500: GET/POST/batch: chyba zpracování. V současné implementaci sem patří i neparsovatelné JSON tělo; neočekávejte pro ně automaticky 400.

Chyby vracejí success: false a error; validační chyba dávky navíc details. Text error/reason není stabilní strojový kód a může být lokalizovaný. Rozhodujte podle HTTP stavu, success a status.

Limity a opakování

POST collect a batch sdílejí limit 60 požadavků za klouzavých 60 sekund. U Bearer klíče se limit odvozuje z prvních 23 znaků klíče; bez Bearer hlavičky z IP. Dávka se počítá jako jeden požadavek. GET collect tento limiter nepoužívá. Odpovědi collect neposílají Retry-After ani hlavičky zbývajícího limitu. Kód nestanovuje denní limit příjmu ani maximální počet API klíčů; při nedostupnosti limiteru příjem pokračuje.

Běžný příjem není idempotentní podle události ani hlavičky Idempotency-Key. Kontakt se hledá podle e-mailu, jinak telefonu, v kontextu firmy a pobočky. Zákazník s napsanou recenzí, odhlášením nebo zákazem kontaktování se přeskočí; odstup od posledního odeslání je podle zákazníka, výchozí 90 dní. Způsobilý existující zákazník může dostat nově naplánovanou sekvenci a staré čekající žádosti se zruší. Opakované volání tedy může posunout čas zpráv. U vlastního API je shoda e-mailu nebo telefonu přesná, bez normalizace; běžné vyhledání při uvedeném e-mailu telefon nepoužije. Samostatná normalizovaná kontrola odhlášeného telefonu ale proběhne vždy, když telefon zadáte, i při uvedeném e-mailu, napříč pobočkami stejné firmy. Chyba kontroly nebo překročení limitu 10 000 záznamů vrátí chybu a zákazníka nezařadí. Změna identifikátoru může vést k jinému kontaktu, proto sjednoťte formát na své straně a nepoužívejte změnu údajů k obcházení odhlášení.

Ukládejte vlastní záznam zpracovaných návštěv/objednávek a výsledek požadavku. Při 429 nebo přechodné chybě serveru použijte omezené opakování s rostoucí prodlevou a náhodnou odchylkou. Po timeoutu může být požadavek již zpracovaný: nezaručujeme právě jedno zařazení. Neopakujte automaticky 400/401/403/409, skipped ani pending_verification. U dávky řešte jednotlivé chyby, neposílejte znovu celou úspěšnou část.

Postup napojení

Vlastník vytvoří klíč Vlastní API v každé připojované firmě. Uložte jej bezpečně odděleně pro každého zákazníka integrace.
Ověřte spojení pomocí GET collect. S vlastníkem potvrďte správnou pobočku a nastavení sekvence. GET není zkouška odeslání.
Spouštějte příjem po skutečně uskutečněné návštěvě nebo doručené objednávce. Neposílejte zrušené rezervace ani nedoručené objednávky. Namapujte jméno, kontakt, oprávnění k oslovení a location_id; source nastavte na api.
Nejdříve ověřte mapování lokálně proti OpenAPI. Při schváleném testu POST použijte jen kontakt, který ovládáte a smíte oslovit: API nemá dry-run ani veřejný sandbox a může odeslat skutečné e-maily nebo SMS. Sledujte výsledek i frontu v Reputive.
Veďte evidenci událostí a chyb, nastavte omezené opakování a nikdy nelogujte klíč. Při pending_verification předejte řešení vlastníkovi firmy.

Existující konektory

Altegio: návštěvy přes API a webhooky; samoobslužné připojení závisí na dostupnosti funkce, jinak přes podporu.
Reenio vyžaduje API klíč z tarifu Reenio PREMIUM a webhook z vlastní zprávy.
Upgates: doplněk/API propojení, příjem objednávek webhookem a synchronizace.
WooCommerce/WordPress: plugin s klíčem WooCommerce posílá zákazníky do collect; import produktových recenzí používá samostatné oprávnění.
Wix: automatizace odesílá HTTP POST do collect, klíč může být v api_key v těle; je nutné location_id.
Heureka: připojení zdroje recenzí přes přístupové údaje služby; nejde o příjem zákazníků přes collect.
Power BI poskytuje CSV feed agregovaných metrik kampaní; podrobnosti jsou v OpenAPI.GET /api/exports/power-bi/v1/businesses/{businessId}/campaign-metrics.csv

Další veřejná rozhraní a hranice API

Widget zobrazuje recenze na webu; podrobnosti jsou v OpenAPI.

API pro obecné čtení/úpravu zákazníků, objednávek nebo recenzí, odchozí webhooky pro partnery ani OAuth autorizace třetích stran nejsou implementovány. OAuth připojení Google není partnerské OAuth API. API neobsahuje veřejný dry-run nebo sandbox ani endpoint pro kontrolu doručení konkrétního collect požadavku.

Stáhnout OpenAPI 3.1 (JSON)