Developers2026-11Προεπισκόπηση

API του NinjaBuy Business

Εισαγάγετε προϊόντα από Taobao, Weidian και 1688, κρατήστε τιμή και απόθεμα συγχρονισμένα και παρακολουθήστε κάθε παραγγελία από τον πωλητή στην Κίνα, μέσα από τον έλεγχο στην αποθήκη μας, ως την πόρτα του πελάτη σας. JSON μέσω HTTPS, ένας λογαριασμός, ένα υπόλοιπο.

Βασικό URL

Κάθε διαδρομή εδώ βρίσκεται κάτω από ένα βασικό URL. Η εφαρμογή Shopify και ό,τι αναπτύσσετε καλούν τις ίδιες διαδρομές, οπότε ό,τι κάνει η εφαρμογή μπορεί να το κάνει και ο κώδικάς σας.

https://www.ninjabuy.com/api/v1

Προτιμάτε να ρωτήσετε έναν βοηθό AI; Ο ίδιος λογαριασμός λειτουργεί μέσω MCP στο https://www.ninjabuy.com/mcp: Βοηθοί AI (MCP).

Κατάλογος

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

Παραγγελίες

ΠαραγγελίεςΜια πώληση που αγοράζουμε, ελέγχουμε και στέλνουμε.
Παραγγελίες fulfillmentΟι γραμμές που φεύγουν σε ένα δέμα.
ΑποστολέςΔέματα καθ' οδόν, με παρακολούθηση.

Λογαριασμός

ΥπόλοιποΤα χρήματα από τα οποία πληρώνονται οι παραγγελίες.
Endpoints webhookΠού στέλνουμε συμβάντα.

Η πρώτη σας κλήση

curl "https://www.ninjabuy.com/api/v1/balance" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Ταυτοποίηση

Στείλτε ένα κλειδί API ως bearer token σε κάθε αίτημα. Τα κλειδιά ξεκινούν με nb_. Κατά την προεπισκόπηση τα εκδίδει η ομάδα μας: μόλις ρυθμιστεί ο λογαριασμός σας Business στέλνουμε κάθε κλειδί μία φορά, από κανάλι της επιλογής σας, με τα scopes που ζητήσατε. Ζητήστε μας να ανακαλέσουμε ένα και σταματά να λειτουργεί από το επόμενο αίτημα.

Κρατήστε τα κλειδιά στον server σας. Ένα κλειδί σε browser, εφαρμογή ή δημόσιο αποθετήριο μπορεί να το διαβάσει οποιοσδήποτε, και μπορεί να ξοδέψει το υπόλοιπό σας.

Μια εφαρμογή που ενεργεί για άλλους πωλητές NinjaBuy χρησιμοποιεί αντί γι' αυτό OAuth 2.1: δυναμική εγγραφή client, ροή authorization code με PKCE (S256) και η οθόνη έγκρισης του ίδιου του πωλητή. Το access token της μπαίνει στην ίδια κεφαλίδα και λειτουργεί στις ίδιες διαδρομές. Τα access tokens διαρκούν μία ώρα· τα refresh tokens τα ανανεώνουν για επτά ημέρες. Οι βοηθοί AI συνδέονται με τον ίδιο τρόπο (MCP).

products:readscope: Ανάγνωση εισαγωγών, προϊόντων, παραλλαγών και κανόνων συγχρονισμού.
products:writescope: Εισαγωγή, επεξεργασία, προώθηση και διαγραφή προϊόντων· αλλαγή κανόνων συγχρονισμού.
inventory:readscope: Ανάγνωση επιπέδων αποθέματος.
orders:readscope: Ανάγνωση παραγγελιών, παραγγελιών fulfillment και αποστολών.
orders:writescope: Δημιουργία, αναμονή, αποδέσμευση και ακύρωση παραγγελιών. Ξοδεύει από το υπόλοιπό σας.
balance:readscope: Ανάγνωση του υπολοίπου και των συναλλαγών του.
webhooks:writescope: Διαχείριση endpoints webhook.

Μια κλήση εκτός των scopes ενός κλειδιού απαντά 403 insufficient-scope και αναφέρει το scope που χρειάζεται.

Κεφαλίδα

Authorization: Bearer nb_7Qk2...vX9e

Response 401

HTTP/2 401

{
  "type": "https://www.ninjabuy.com/api/v1/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The API key is missing, wrong, expired or revoked.",
  "request_id": "req_7Hq2Lw9c"
}

Εκδόσεις

Η διαδρομή φέρει την κύρια έκδοση, /v1. Μέσα σε αυτή, οι χρονολογημένες εκδόσεις αλλάζουν πεδία και συμπεριφορά. Κλειδώστε αυτή πάνω στην οποία αναπτύξατε με την κεφαλίδα NinjaBuy-Version· κάθε απάντηση αναφέρει την έκδοση που χρησιμοποίησε στην ίδια κεφαλίδα.

Η 2026-11 είναι η τρέχουσα έκδοση και είναι προεπισκόπηση: ονόματα και πεδία μπορεί ακόμη να αλλάξουν πριν χαρακτηριστεί σταθερή. Κάθε αλλαγή καταγράφεται στο changelog και ενημερώνουμε με email κάθε κάτοχο κλειδιού πριν από μια αλλαγή που μπορεί να τον επηρεάσει.

Μέσα σε μια έκδοση μόνο προσθέτουμε: νέες διαδρομές, νέες προαιρετικές παραμέτρους, νέα πεδία στις απαντήσεις και νέους τύπους συμβάντων. Φτιάξτε τον client σας ώστε να αγνοεί πεδία που δεν γνωρίζει.

Κλείδωμα έκδοσης

GET /api/v1/orders
NinjaBuy-Version: 2026-11

HTTP/2 200
NinjaBuy-Version: 2026-11

Αιτήματα και απαντήσεις

Στείλτε JSON με Content-Type: application/json· οι απαντήσεις είναι JSON σε UTF-8. Τα σφάλματα είναι application/problem+json.
Τα χρήματα είναι αντικείμενο με δεκαδική συμβολοσειρά και νόμισμα: { "amount": "264.20", "currency": "CNY" }. Ό,τι χρεώνει το NinjaBuy είναι σε CN¥· οι τιμές πώλησής σας είναι στο νόμισμα του καταστήματός σας.
Τα ids είναι συμβολοσειρές με πρόθεμα που δηλώνει το είδος τους (prd_, ord_, shp_). Χειριστείτε τα ως αδιαφανή.
Οι χρόνοι είναι ISO 8601 σε UTC. Οι χώρες είναι κωδικοί ISO δύο γραμμάτων.
Κάθε απάντηση φέρει κεφαλίδα X-Request-Id, και κάθε σφάλμα φέρει το ίδιο id ως request_id. Αναφέρετέ το όταν μας γράφετε.

Χρήματα, ids και ημερομηνίες

{
  "id": "ord_3n7q",
  "created_at": "2026-11-01T09:14:02Z",
  "total": { "amount": "264.20", "currency": "CNY" },
  "suggested_price": { "amount": "49.99", "currency": "USD" }
}

Σελιδοποίηση

Οι λίστες επιστρέφουν τα νεότερα πρώτα, ως data, has_more και cursor. Στείλτε πίσω αυτό το cursor για την επόμενη σελίδα όσο το has_more είναι true. Ένα cursor λειτουργεί μόνο με τα φίλτρα από τα οποία προήλθε.

limitinteger: 1 έως 100. 25 αν παραλειφθεί.
cursorstring: Το cursor της προηγούμενης σελίδας. Παραλείψτε το για την πρώτη σελίδα.

curl "https://www.ninjabuy.com/api/v1/orders?limit=25&cursor=c_2v9kq" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    { "id": "ord_3n7q", "status": "checked" },
    { "id": "ord_3n6z", "status": "shipped" }
  ],
  "has_more": true,
  "cursor": "c_1q4ea"
}

Όρια ρυθμού

Τα όρια είναι ανά λογαριασμό, κοινά για όλα τα κλειδιά του, τα OAuth tokens και τη σύνδεση MCP. Κάθε απάντηση λέει πού βρίσκεστε στις κεφαλίδες IETF RateLimit-Policy και RateLimit· μια απόρριψη είναι 429 rate-limited με Retry-After σε δευτερόλεπτα.

Παράθυρο	Τι μετράει
"create-links";q=30;w=60	Κλήσεις που διαβάζουν μια καταχώριση από την πλατφόρμα: δημιουργία ή ανανέωση εισαγωγής, προώθηση προϊόντος. 30 ανά λεπτό, κοινό όριο με το API συνδέσμων και το MCP.
"default";q=120;w=60	Κάθε άλλη κλήση. 120 ανά λεπτό.

Απάντηση 429

HTTP/2 429
Content-Type: application/problem+json
Retry-After: 12
RateLimit-Policy: "create-links";q=30;w=60
RateLimit: "create-links";r=0;t=12

{
  "type": "https://www.ninjabuy.com/api/v1/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Try again in 12 seconds.",
  "request_id": "req_7Hq2Lw9c"
}

Idempotency

Στείλτε ένα Idempotency-Key (1 έως 255 εκτυπώσιμοι χαρακτήρες ASCII· ιδανικά ένα UUID) σε κάθε POST, και μια νέα προσπάθεια μετά από timeout δεν μπορεί να δημιουργήσει δεύτερη παραγγελία. Για 24 ώρες το ίδιο κλειδί, στην ίδια διαδρομή με το ίδιο σώμα, επιστρέφει ξανά την πρώτη απάντηση byte προς byte, με Idempotent-Replayed: true, χωρίς να εκτελεστεί ξανά ή να μετρήσει σε όριο.

Το ίδιο κλειδί με διαφορετικό σώμα ή διαδρομή: 422 idempotency-key-reused.
Το πρώτο αίτημα εκτελείται ακόμη: 409 idempotency-key-in-progress, με Retry-After.
Μια απόρριψη λόγω ορίου ρυθμού δεν είναι απάντηση: το κλειδί μένει ελεύθερο, οπότε μια νέα προσπάθεια μετά το Retry-After εκτελεί το αίτημα.

Οι παραγγελίες φέρουν επίσης το δικό σας external_id: μια δεύτερη παραγγελία με το ίδιο απορρίπτεται με 409 duplicate-order, με όποιο κλειδί κι αν στάλθηκε.

Ένα επαναλαμβανόμενο αίτημα

POST /api/v1/orders
Idempotency-Key: 4f0c2b4e-9d1a-4e0f-b0a8-5d1d3c7e2f61

HTTP/2 201
Idempotent-Replayed: true
X-Request-Id: req_7Hq2Lw9c

Σφάλματα

Τα σφάλματα είναι problem JSON (RFC 9457): το type είναι σταθερό URL για διακλάδωση, το title το ονομάζει, το detail εξηγεί τη συγκεκριμένη περίπτωση με λόγια που μπορείτε να δείξετε, και το request_id το εντοπίζει στα logs μας. Ένα σώμα που αποτυγχάνει στην επικύρωση προσθέτει errors, το καθένα με JSON pointer προς το πεδίο.

Κατάσταση	Τύπος	Πότε
400	bad-json	Το σώμα δεν είναι JSON.
400	bad-body	Ένα πεδίο λείπει ή είναι λάθος· το errors[] δείχνει ποιο.
400	bad-idempotency-key	Το Idempotency-Key είναι κενό, πολύ μεγάλο ή όχι εκτυπώσιμο ASCII.
401	unauthorized	Το κλειδί ή το token λείπει, είναι λάθος, έχει λήξει ή έχει ανακληθεί.
403	insufficient-scope	Το κλειδί δεν έχει το scope που χρειάζεται η διαδρομή.
404	not-found	Δεν υπάρχει τέτοιο αντικείμενο σε αυτόν τον λογαριασμό. Τα ids άλλου λογαριασμού παίρνουν την ίδια απάντηση.
405	method-not-allowed	Η διαδρομή υπάρχει, όχι με αυτή τη μέθοδο· το Allow αναφέρει όσες δέχεται.
409	duplicate-order	Υπάρχει παραγγελία με αυτό το external_id· το order την αναφέρει.
409	idempotency-key-in-progress	Το πρώτο αίτημα με αυτό το κλειδί εκτελείται ακόμη.
409	invalid-state	Το αντικείμενο δεν μπορεί να το κάνει αυτό τώρα, για παράδειγμα ακύρωση μιας απεσταλμένης παραγγελίας.
415	unsupported-media-type	Το σώμα δεν είναι application/json.
422	idempotency-key-reused	Το κλειδί χρησιμοποιήθηκε για διαφορετικό αίτημα.
422	unprocessable	Έγκυρο JSON στο οποίο δεν μπορούμε να ενεργήσουμε: ένας σύνδεσμος που δεν διαβάστηκε, μια εξαντλημένη παραλλαγή. Το detail λέει ποιο.
429	rate-limited	Πάρα πολλές κλήσεις στο παράθυρο. Περιμένετε όσα δευτερόλεπτα λέει το Retry-After.
500	internal-error	Δικό μας σφάλμα. Δοκιμάστε ξανά με το ίδιο Idempotency-Key.
503	service-unavailable	Δεν μπορέσαμε να ελέγξουμε το κλειδί ή να φτάσουμε σε ένα κατάστημα αυτή τη στιγμή. Δοκιμάστε ξανά μετά το Retry-After.

Response 400

HTTP/2 400

{
  "type": "https://www.ninjabuy.com/api/v1/problems/bad-body",
  "title": "Invalid request body",
  "status": 400,
  "detail": "1 field is invalid.",
  "request_id": "req_7Hq2Lw9c",
  "errors": [
    {
      "pointer": "/ship_to/country",
      "detail": "Must be a two-letter country code."
    }
  ]
}