API dla agencji i serwisów

Zaktualizowano

Finishot wysyła zdjęcia do dowolnego API jako multipart/form-data. Poniższy format działa bez zmian w aplikacji. Adres, sposób logowania i nazwy pól fotograf ustawia w Finishocie: Agencje → wybrana agencja → Wysyłka → API (HTTP).

Żądanie

POST https://twoj-serwis.example/api/photos
Authorization: Bearer <token>
Content-Type: multipart/form-data
Pole Typ Zawartość
file plik JPEG Zdjęcie w pełnej rozdzielczości z wpisanymi metadanymi IPTC i XMP
metadata tekst (JSON) Te same dane w wygodnej formie, opisane niżej
title tekst Tytuł
caption tekst Opis
keywords tekst Słowa kluczowe po przecinku

Nazwy pól można zmienić i dopisać własne, np. gallery=15 albo event={event}. Zamiast tokenu Bearer można użyć własnego nagłówka, np. X-API-Key.

Pole metadata

{
  "app": "Finishot 1.0.0",
  "agency": "Własny serwis (API)",
  "fileName": "IMG_4812.jpg",
  "capturedAt": "2026-01-28T21:02:12-05:00",
  "width": 6000,
  "height": 4000,
  "event": { "name": "NBA", "date": "2026-01-28", "sport": "koszykówka", "venue": "Rocket Arena", "city": "Cleveland", "country": "USA", "countryCode": "USA" },
  "people": [
    { "name": "Luka Dončić", "first": "Luka", "last": "Dončić", "number": "77", "team": "Los Angeles Lakers" }
  ],
  "iptc": {
    "title": "…", "description": "…", "keywords": ["NBA", "koszykówka"],
    "personInImage": ["Luka Dončić"], "creator": ["Imię Nazwisko"], "credit": "Imię Nazwisko/Twój serwis",
    "dateCreated": "2026-01-28T21:02:12-05:00"
  }
}

Odpowiedź

  • Sukces: kod 2xx, najlepiej 201 z JSON-em { "id": "2687", "url": "https://twoj-serwis.example/zdjecie/2687" }. Finishot zapisze url albo id w dzienniku wysyłki.
  • Błąd: kod 4xx lub 5xx z krótkim komunikatem, np. 401 {"error":"invalid token"}. Finishot pokaże go przy zdjęciu i pozwoli ponowić wysyłkę.

Wskazówki dla serwera

  • Rozmiar żądania: co najmniej 50 MB (PHP: upload_max_filesize, post_max_size; nginx: client_max_body_size).
  • Test połączenia w aplikacji wysyła GET pod ten sam adres z tokenem:
    • 200 albo 405 oznacza, że serwer odpowiada;
    • 401 lub 403 oznacza zły token;
    • 404 oznacza zły adres.
  • Ponowna wysyłka tego samego pliku po poprawce opisu powinna aktualizować zdjęcie, a nie tworzyć duplikat. Rozpoznasz je po fileName i capturedAt.
  • Kodowanie: wszystkie pola są w UTF-8.

Masz pytania o integrację? Napisz do nas.