Επαυξητικός συγχρονισμός με updated_since

Για να κρατάτε ένα αντίγραφο των δεδομένων της Sursa στο δικό σας σύστημα, δεν χρειάζεται να διαβάζετε τα πάντα κάθε φορά. Οι λίστες αντικειμένων που έχουν updated_at δέχονται updated_since και επιστρέφουν μόνο τα αντικείμενα που άλλαξαν τη στιγμή αυτή ή μετά από αυτήν.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "updated_since=2026-10-23T00:00:00Z" \
  --data-urlencode "limit=200"

Με το updated_since, η λίστα ταξινομείται κατά updated_at σε αύξουσα σειρά, στη συνέχεια κατά id, και ο δρομέας συνεχίζει με αυτή τη σειρά. Έτσι διαβάζετε τις αλλαγές με τη σειρά που έγιναν, και ένα όριο σελίδας δεν τις χωρίζει ποτέ με τρόπο που να χάνεται κάποια.

Το updated_since το δέχονται αυτές οι λίστες:

Οι συλλογές, οι χρήστες και οι ανακοινώσεις δεν έχουν updated_at, οπότε οι λίστες τους δεν φιλτράρονται με βάση αυτό: είναι σύντομες, γι’ αυτό διαβάζετέ τες ολόκληρες σε κάθε εκτέλεση. Η χρονική τιμή πρέπει να έχει μετατόπιση ζώνης ώρας, όπως Z ή +02:00· κάθε άλλη τιμή απορρίπτεται, όπως στο GET /v1/cards.

Με το updated_since, ένα δέντρο φακέλων δεν είναι πια δέντρο: το folders κάθε συλλογής περιέχει τους φακέλους που άλλαξαν ως επίπεδη λίστα, με κενό children, και το parent_id δείχνει πού βρίσκεται ο καθένας. Το GET /v1/folders τότε παραλείπει τις συλλογές χωρίς φακέλους που άλλαξαν.

Ένας βρόχος συγχρονισμού

1. Στην πρώτη εκτέλεση, διαβάστε ολόκληρη τη λίστα χωρίς updated_since και κρατήστε τη στιγμή που ξεκίνησε η εκτέλεση.
2. Σε κάθε επόμενη εκτέλεση, περάστε αυτή τη στιγμή ως updated_since, μείον ένα μικρό περιθώριο, όπως ένα λεπτό, και κρατήστε τη νέα ώρα έναρξης.
3. Γράψτε κάθε αντικείμενο στον χώρο αποθήκευσής σας με βάση το id του, αντικαθιστώντας το προηγούμενο αντίγραφο. Τα αντικείμενα που εμφανίζονται δύο φορές λόγω του περιθωρίου απλώς γράφονται ξανά.
4. Ζητήστε κάθε επόμενη σελίδα με τον δρομέα και το ίδιο updated_since. Ένας δρομέας λειτουργεί μόνο με τα φίλτρα της πρώτης σελίδας: χωρίς αυτά το αίτημα επιστρέφει 400 με τον κωδικό api.cursor_invalid.

Η χρήση της ώρας έναρξης της εκτέλεσης, και όχι της ώρας λήξης της, εξασφαλίζει ότι μια αλλαγή που έγινε ενώ εκτελούνταν ο συγχρονισμός θα ληφθεί στην επόμενη εκτέλεση.

Το GET /v1/cards επιστρέφει πίνακα JSON, οπότε η επόμενη σελίδα του έρχεται στην κεφαλίδα X-Next-Cursor (δείτε Λίστες που επιστρέφουν πίνακα):

const BASE = "https://api.sursa.com";
const headers = { Authorization: `Bearer ${process.env.SURSA_API_KEY}` };

async function syncCards(since, saveCard) {
  const startedAt = new Date();
  const params = new URLSearchParams({ limit: "200" });
  if (since) params.set("updated_since", new Date(since.getTime() - 60_000).toISOString());
  let query = params.toString();
  while (query) {
    const response = await fetch(`${BASE}/v1/cards?${query}`, { headers });
    if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    for (const card of await response.json()) await saveCard(card); // write into your store by card.id
    const cursor = response.headers.get("X-Next-Cursor");
    if (cursor) params.set("cursor", cursor); // keep updated_since: the cursor needs the same filters
    query = cursor ? params.toString() : "";
  }
  return startedAt; // pass it as `since` next time
}

Διαγραφές

Μια λίστα επιστρέφει μόνο αντικείμενα που υπάρχουν, οπότε δεν μπορεί να σας πει ότι κάτι διαγράφηκε. Λαμβάνετε τις διαγραφές από την τροφοδοσία συμβάντων:

curl -G https://api.sursa.com/v1/webhook-events \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "type=card.deleted" \
  --data-urlencode "created_since=2026-10-23T00:00:00Z"

Για να διαβάσετε την τροφοδοσία χρειάζεστε ένα κλειδί με τον ρόλο admin και την εμβέλεια webhooks:manage. Τα συμβάντα διατηρούνται για 30 ημέρες. Αν ο συγχρονισμός σας δεν έχει εκτελεστεί για περισσότερο από αυτό το διάστημα, διαβάστε ξανά ολόκληρη τη λίστα και αφαιρέστε από τον χώρο αποθήκευσής σας κάθε αντικείμενο που δεν υπάρχει πια σε αυτήν.

Ο οδηγός Εξαγωγή σε αποθήκη δεδομένων συνδυάζει τις λίστες, το updated_since και την τροφοδοσία συμβάντων σε μία εργασία.