Μετάβαση στο περιεχόμενο
Sursa Developers

Χρόνος και μορφές

JSON και κείμενο

  • Τα σώματα αιτημάτων και αποκρίσεων είναι JSON σε UTF-8, με Content-Type: application/json. Οι μεταφορτώσεις αρχείων χρησιμοποιούν multipart/form-data.
  • Τα ονόματα των πεδίων και οι τιμές απαρίθμησης είναι σε snake_case: next_retry_at, index_failed.
  • Τα μηνύματα σφάλματος και τα κείμενα του API είναι στα αγγλικά. Τα κείμενα που γράφετε εσείς, όπως οι τίτλοι των καρτών, επιστρέφονται όπως τα γράψατε, σε οποιαδήποτε γλώσσα.

Ώρες

Κάθε χρονική τιμή είναι χρονική σήμανση RFC 3339 σε UTC:

{"created_at": "2026-10-24T10:00:00Z"}
  • Τα νεότερα πεδία χρησιμοποιούν τη σύντομη μορφή με Z, όπως παραπάνω.
  • Ορισμένα πεδία που υπήρχαν παλαιότερα χρησιμοποιούν τη μορφή 2026-10-24T10:00:00.123456+00:00, με έως έξι ψηφία για τα κλάσματα του δευτερολέπτου. Πρόκειται για την ίδια χρονική στιγμή σε UTC. Αναλύετε και τις δύο μορφές με έναν τυπικό αναλυτή RFC 3339· μη συγκρίνετε χρονικές σημάνσεις ως συμβολοσειρές.
  • Κάθε πεδίο του οποίου το όνομα τελειώνει σε _at είναι χρονική σήμανση.

Οι χρονικές τιμές που στέλνετε πρέπει να περιλαμβάνουν μετατόπιση ζώνης ώρας, είτε Z είτε αριθμητική μετατόπιση όπως +02:00. Μια χρονική τιμή χωρίς μετατόπιση είναι αμφίσημη και επιστρέφει 422 με τον κωδικό validation.failed. Η Sursa μετατρέπει κάθε χρονική τιμή που λαμβάνει σε UTC.

const since = new Date(Date.now() - 24 * 3600 * 1000).toISOString(); // "2026-10-23T10:00:00.000Z"

Σε μια συμβολοσειρά ερωτήματος (query string), το + πρέπει να γράφεται ως %2B, αλλιώς διαβάζεται ως κενό. Κωδικοποιείτε τις χρονικές τιμές για URL ή χρησιμοποιείτε Z.

Ημερομηνίες, διάρκειες και πλήθη

ΕίδοςΜορφήΠαράδειγμα
Ημερομηνία χωρίς ώραYYYY-MM-DD, σε πεδίο που τελειώνει σε _date"due_date": "2026-11-01"
ΔιάρκειαΑκέραιος, με τη μονάδα στο όνομα του πεδίου"interval_days": 90, "timeout_seconds": 30
ΠλήθοςΑκέραιος, σε πεδίο που τελειώνει σε _count"part_count": 12
Αληθές ή ψευδέςΛογική τιμή, με όνομα επίθετο χωρίς is_"active": true, "sensitive": false

Χρηματικά ποσά

Τα ποσά στις οικονομικές αποκρίσεις είναι δεκαδικές συμβολοσειρές, όπως "1250.00", ποτέ αριθμοί κινητής υποδιαστολής, ώστε να μη χάνεται ακρίβεια. Το νόμισμα είναι ξεχωριστό πεδίο με κωδικό ISO 4217, όπως "EUR". Αναλύετε τα ποσά με έναν δεκαδικό τύπο της γλώσσας σας.

Αναγνωριστικά

Τα αναγνωριστικά είναι συμβολοσειρές ή ακέραιοι, ανάλογα με το αντικείμενο. Δείτε τον οδηγό Αναγνωριστικά αντικειμένων.

Απαριθμήσεις

Τα πεδία με σταθερό σύνολο τιμών, όπως μια κατάσταση, είναι συμβολοσειρές. Κάθε απαρίθμηση σε μια απόκριση μπορεί να αποκτήσει νέες τιμές σε μια μεταγενέστερη έκδοση: χειριστείτε μια τιμή που δεν γνωρίζετε ως «άλλο». Δείτε τον οδηγό Εκδόσεις και συμβατότητα.

Null και πεδία που λείπουν

  • Το null σημαίνει «καμία τιμή»: μια κάρτα χωρίς υπεύθυνο έχει "owner_id": null.
  • Ένα πεδίο μπορεί να λείπει από μια απόκριση, όταν δεν αφορά αυτό το αντικείμενο ή αυτό το αίτημα. Η αναφορά API επισημαίνει ποια πεδία υπάρχουν πάντα.
  • Σε ένα PATCH, ένα πεδίο που παραλείπετε διατηρεί την τιμή του. Στείλτε null για να καθαρίσετε ένα πεδίο, όπου η αναφορά λέει ότι το null επιτρέπεται.