Dodawaj kampanie do Vereel z własnych narzędzi

Co potrafi API

Publiczne oferty Vereel może przeglądać każdy: te same informacje, które widzi odwiedzający stronę, bez kwot, bez konta i bez tokena.

Marka może też wysyłać oferty. Tworzysz token w ustawieniach, wysyłasz nim ofertę, a Vereel ją weryfikuje. Po zatwierdzeniu oferta pojawia się na stronie jak każda inna. Do tego czasu nie jest publiczna, ale nadal możesz ją zmieniać i dodawać zdjęcia.

API nie publikuje ofert, nie usuwa ich, nie rozpoczyna kampanii i nie obsługuje płatności. Te czynności zostają w aplikacji.

Szybki start

1. 1

   Użyj konta marki

   Zaloguj się jako marka albo załóż takie konto. Tokeny są tylko dla kont marek.

2. 2

   Utwórz token

   Otwórz Ustawienia › Tokeny API, nazwij token, wybierz odczyt i zapis oraz zaakceptuj Warunki Współpracy dla ofert, które będzie wysyłał. Skopiuj token od razu: pokazujemy go tylko raz.

3. 3

   Wyślij ofertę

   Wykonaj poniższe zapytanie ze swoim tokenem. Identyfikator kategorii weź z GET /categories. Oferta powstaje ze statusem in_review.

4. 4

   Poczekaj na weryfikację

   Vereel zatwierdza ofertę albo zwraca ją do wersji roboczych z uzasadnieniem i w obu przypadkach daje Ci znać. W międzyczasie możesz ją zmieniać i dodawać zdjęcia.

Utwórz ofertę (zamień YOUR_TOKEN, identyfikator kategorii i adres zdjęcia na własne):

curl -X POST https://www.vereel.com/api/v1/public/my/offers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Spring skincare launch",
  "description": "Unbox our new vitamin C serum and show how it fits into your morning routine. One Reel and two Stories.",
  "offerType": "PRODUCT",
  "platforms": [
    "instagram",
    "tiktok"
  ],
  "categoryIds": [
    "00000000-0000-0000-0000-000000000001"
  ],
  "isPayment": true,
  "isBarter": false,
  "productIncluded": true,
  "productServiceValue": 150,
  "additionalPayment": 800,
  "currency": "PLN",
  "includedDescription": "One 30 ml bottle of the serum, shipped before you start.",
  "deliverables": {
    "reels": 1,
    "stories": 2
  },
  "requiresGoodsShipping": true,
  "applyByDays": 21,
  "followerMinimum": 5000,
  "audience": {
    "genders": [
      "WOMEN"
    ],
    "ageGroups": [
      "18-24",
      "25-34"
    ]
  },
  "imageUrls": [
    "https://cdn.example.com/serum.jpg"
  ]
}'

Udane wywołanie zwraca 201 z identyfikatorem oferty i statusem in_review. Jeśli nie podano zdjęcia, pole missing zawiera photo: dodaj je, zanim oferta będzie mogła zostać zatwierdzona.

Uwierzytelnianie

Przeglądanie nie wymaga tokena. Wszystko pod /my/ wymaga tokena marki, wysyłanego jako Authorization: Bearer vrl_… . Token daje sam odczyt albo odczyt i zapis i wygasa po 30, 90 albo 365 dniach, zależnie od Twojego wyboru. Vereel przechowuje tylko skrót, więc nigdy nie pokaże tokena ponownie. Możesz go w każdej chwili unieważnić w Ustawieniach, a przy każdym utworzeniu tokena Vereel wysyła Ci e-mail.

• Trzymaj tokeny na serwerze albo w ustawieniach agenta, nigdy na stronie internetowej. Trasy z tokenem celowo odrzucają zapytania z innych witryn.
• Token działa tylko w imieniu Twojej marki i tylko na ofertach utworzonych przez API.
• Utworzenie tokena oznacza akceptację Warunków Współpracy dla ofert, które będzie wysyłał. Gdy warunki się zmienią, zaakceptuj je ponownie w Ustawieniach › Tokeny API: do tego czasu token może odczytywać, ale nie może tworzyć ofert.

Operacje

Każda operacja, wygenerowana z tej samej definicji, z której powstaje plik OpenAPI. Ścieżki są liczone względem https://www.vereel.com/api/v1/public. Opisy operacji zostają po angielsku, tak jak w definicji.

Zdjęcia

Oferta potrzebuje co najmniej jednego zdjęcia, zanim zostanie zatwierdzona. W trakcie weryfikacji możesz je dodać na dwa sposoby:

• Wyślij link. Podaj imageUrls przy tworzeniu oferty albo wyślij {"url": …} na adres zdjęć oferty. Vereel pobiera obraz samodzielnie: tylko https, z publicznego adresu, do 5 MB.
• Albo wgraj plik. Poproś o adres do wgrania, wyślij plik metodą PUT, a potem w ciągu 15 minut dołącz zwrócony adres.
• Tylko JPEG, PNG lub WebP, rozpoznawane po zawartości pliku, nie po nazwie. Oferta może mieć do 6 zdjęć; pierwsze jest okładką.

Limity

• Treść zapytania ma co najwyżej 64 KB.
• Bez tokena: 60 zapytań na minutę z jednego adresu.
• Z tokenem: 120 zapytań na minutę oraz co najwyżej 30 zmian i 20 pobrań zdjęć w ciągu 10 minut.
• Na markę: co najwyżej 10 aktywnych tokenów, 20 ofert w weryfikacji i 50 nowych ofert z API na dobę.

Po przekroczeniu limitu API odpowiada kodem 429 (RATE_LIMITED lub REVIEW_QUEUE_FULL), a tam, gdzie warto poczekać, dodaje nagłówek Retry-After.

Błędy

Każdy błąd ma ten sam kształt, {"error": {"code", "message", "details"}}, a details wskazuje każde nieprawidłowe pole.

Użycie z własnym GPT w ChatGPT

Własny GPT może dodawać oferty na podstawie briefu wklejonego do czatu. W edytorze GPT w ChatGPT (nazwy opcji podajemy po angielsku):

1. Otwórz Configure i wybierz Create new action.
2. Wybierz Import from URL i wpisz https://www.vereel.com/api/v1/public/openapi.yaml. Operacje pojawią się na liście.
3. W sekcji Authentication wybierz API Key, ustaw Auth Type na Bearer i wklej token do odczytu i zapisu.
4. W instrukcjach każ GPT dopytywać o brakujące dane, sprawdzać identyfikatory kategorii przez listCategories i podawać linki do zdjęć w imageUrls.

Token jest przechowywany w ustawieniach GPT, więc nie udostępniaj go publicznie: każdy, kto może z niego korzystać, może wysyłać oferty w imieniu Twojej marki. Wszystko, co wyśle, nadal czeka na weryfikację, a GPT może przekazać zdjęcie tylko jako link.

Pliki definicji

Definicja OpenAPI 3.1 jest publiczna. Użyj jej, by wygenerować klienta albo połączyć narzędzie. Pozostaje dostępna także wtedy, gdy samo API jest wyłączone.

• openapi.yaml
• openapi.json
• Katalog API