API παραγγελιών2026-11Προεπισκόπηση

Παραγγελίες

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

Παρακολουθήστε μια παραγγελία με webhooks αντί για περιοδικούς ελέγχους: τα συμβάντα παραγγελίας ενεργοποιούνται καθώς γίνεται κάθε βήμα. Το ίδιο το δέμα είναι μια παραγγελία fulfillment και μετά μια αποστολή.

Endpoints

POST/v1/ordersΔημιουργία παραγγελίας
GET/v1/ordersΛίστα παραγγελιών
GET/v1/orders/{id}Ανάκτηση παραγγελίας
POST/v1/orders/{id}/cancelΑκύρωση παραγγελίας

Το αντικείμενο Order

idstring: Ξεκινά με ord_.
external_idstring: Ο αριθμός παραγγελίας του καταστήματός σας. Μοναδικός στον λογαριασμό σας.
sourcestring: api, ή shopify για παραγγελίες που μας έστειλε το κατάστημά σας στο Shopify.
statusstring: Η κατάσταση της γραμμής που έχει προχωρήσει λιγότερο· δείτε τις Καταστάσεις παρακάτω.
payment_statusstring: awaiting_payment, paid, partially_refunded ή refunded.
lanestring: saver ή fast.
lines[]array: Παραλλαγή, ποσότητα, τεμάχια ανά προϊόν, κατάσταση, οι φωτογραφίες αποθήκης μετά τον έλεγχο, και reason όταν απορρίφθηκε.
ship_toobject: Όνομα, διεύθυνση, τηλέφωνο και email του πελάτη σας.
packagingstring|null: Το επώνυμο κουτί ή φάκελός σας· η προεπιλογή σας όταν είναι null.
chargesobject: Πόσο κοστίζει, σε CN¥: η προμήθεια (προϊόντα, χρέωση παραλαβής, φόρος) και το δέμα (αποστολή, χρέωση διαχείρισης, φόρος). Το δέμα είναι εκτίμηση από τα βάρη σας μέχρι να το ζυγίσουμε.
amount_duemoney|null: Τι πρέπει ακόμη να καλύψει το υπόλοιπό σας, όσο είναι awaiting_payment.
fulfillment_orders[]array: Τα δέματα με τα οποία φεύγει.

order

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "shopify",
  "status": "checked",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "checked",
      "photos": [
        "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
        "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
      ],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": ["fo_7k2m"],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

Δημιουργία παραγγελίας

POST/v1/orders

Στείλτε μας μία από τις παραγγελίες του καταστήματός σας. Κάθε γραμμή είναι μια παραλλαγή που αποθηκεύσατε, ή ένας σύνδεσμος καταχώρισης και SKU που αγοράζουμε ως έχει. Η παραγγελία πληρώνεται αμέσως από το υπόλοιπό σας· μια παραγγελία που δεν καλύπτει το υπόλοιπο δημιουργείται κανονικά, ως awaiting_payment με amount_due, και προχωρά μόνη της όταν κάνετε φόρτιση.

Οι παραγγελίες από το κατάστημά σας στο Shopify φτάνουν σε εμάς χωρίς αυτή την κλήση. Χρησιμοποιήστε τη για WooCommerce, Wix, τον δικό σας ιστότοπο ή οτιδήποτε άλλο πουλά.

Scopeorders:write

Σώμα

external_idstringυποχρεωτικό: Ο αριθμός παραγγελίας σας. Μια δεύτερη παραγγελία με αυτόν απορρίπτεται.
lines[]arrayυποχρεωτικό: variant και quantity, ή url, sku και quantity. Το units (προαιρετικό) αγοράζει τόσα ανά τεμάχιο, για πακέτα.
ship_toobjectυποχρεωτικό: name, line1, line2, city, region, postal_code, country (δύο γράμματα), phone, email.
lanestring: saver ή fast. saver αν παραλειφθεί.
packagingstring: Προαιρετικό. Ένα id συσκευασίας· η προεπιλογή σας αν παραλειφθεί.
notestring: Προαιρετικό. Για την ομάδα της αποθήκης μας, έως 500 χαρακτήρες.

Σφάλματα

Κατάσταση	Τύπος	Πότε
400	bad-body	Ένα πεδίο λείπει ή είναι λάθος· το errors[] δείχνει ποιο.
409	duplicate-order	Το external_id είναι ήδη παραγγελία· το order την αναφέρει.
422	unprocessable	Η παραλλαγή μιας γραμμής έχει εξαντληθεί ή ο σύνδεσμός της δεν διαβάζεται.
422	not-shippable	Καμία δημοσιευμένη τιμή δεν φτάνει στο ship_to.country με αυτή τη γραμμή.

curl -X POST "https://www.ninjabuy.com/api/v1/orders" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "1012",
    "lines": [{ "variant": "var_41hz", "quantity": 1 }],
    "ship_to": {
      "name": "Sam Rivera",
      "line1": "500 Congress Ave",
      "city": "Austin",
      "region": "TX",
      "postal_code": "78701",
      "country": "US",
      "phone": "+15125550142",
      "email": "sam@example.com"
    },
    "lane": "saver"
  }'

Response 201

HTTP/2 201 Created

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "api",
  "status": "buying",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "buying",
      "photos": [],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": [],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

Λίστα παραγγελιών

GET/v1/orders

Τα νεότερα πρώτα.

Scopeorders:read

Παράμετροι ερωτήματος

statusstring: Προαιρετικό. Μία από τις παρακάτω καταστάσεις.
sourcestring: Προαιρετικό. api ή shopify.
external_idstring: Προαιρετικό. Βρείτε μία με τον δικό σας αριθμό παραγγελίας.
created_sincestring: Προαιρετικό. Μια χρονική στιγμή.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/orders?status=checked" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "ord_3n7q",
      "external_id": "1012",
      "status": "checked",
      "payment_status": "paid"
    }
  ],
  "has_more": false,
  "cursor": null
}

Ανάκτηση παραγγελίας

GET/v1/orders/{id}

Η κατάσταση κάθε γραμμής, οι φωτογραφίες αποθήκης μετά τον έλεγχο, τι κόστισε και τα δέματά της.

Scopeorders:read

Παράμετροι διαδρομής

idstringυποχρεωτικό: Το id της παραγγελίας.

Σφάλματα

Κατάσταση	Τύπος	Πότε
404	not-found	Δεν υπάρχει τέτοια παραγγελία σε αυτόν τον λογαριασμό.

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

Response 200

HTTP/2 200 OK

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "shopify",
  "status": "checked",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "checked",
      "photos": [
        "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
        "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
      ],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": ["fo_7k2m"],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

Ακύρωση παραγγελίας

POST/v1/orders/{id}/cancel

Πριν αγοράσουμε, όλη η παραγγελία επιστρέφεται στο υπόλοιπό σας. Μετά την αγορά, επιστρέφονται οι γραμμές που παίρνει πίσω ο πωλητής, και οι υπόλοιπες μένουν στο ράφι σας ως απόθεμα αποθήκης. Μια απεσταλμένη παραγγελία δεν ακυρώνεται.

Scopeorders:write

Παράμετροι διαδρομής

idstringυποχρεωτικό: Το id της παραγγελίας.

Σώμα

reasonstring: Προαιρετικό. Διατηρείται στην παραγγελία.

Σφάλματα

Κατάσταση	Τύπος	Πότε
404	not-found	Δεν υπάρχει τέτοια παραγγελία σε αυτόν τον λογαριασμό.
409	invalid-state	Έχει αποσταλεί.

curl -X POST "https://www.ninjabuy.com/api/v1/orders/ord_3n7q/cancel" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer changed their mind" }'

Response 200

HTTP/2 200 OK

{
  "id": "ord_3n7q",
  "status": "cancelled",
  "payment_status": "refunded",
  "refunded": { "amount": "191.52", "currency": "CNY" }
}

Καταστάσεις

Κάθε γραμμή έχει τη δική της κατάσταση· η κατάσταση μιας παραγγελίας είναι αυτή της γραμμής που έχει προχωρήσει λιγότερο. Με τη σειρά:

Κατάσταση	Σημασία
awaiting_payment	Το υπόλοιπό σας δεν την κάλυψε. Κάντε φόρτιση και προχωρά μόνη της.
buying	Πληρώθηκε· το αγοράζουμε από τον πωλητή.
with_seller	Αγοράστηκε· ο πωλητής δεν το έχει στείλει ακόμη στην αποθήκη μας.
checked	Στην αποθήκη μας, ελεγμένο και φωτογραφημένο, περιμένει συσκευασία.
shipped	Καθ' οδόν, με παρακολούθηση.
delivered	Ο μεταφορέας λέει ότι έφτασε.
rejected	Δεν μπορέσαμε να το αγοράσουμε (εξαντλήθηκε, ο σύνδεσμος δεν υπάρχει)· το reason λέει γιατί, και επιστρέφονται τα χρήματα.
cancelled	Την ακυρώσατε.

Χρήματα

Στα δείγματα, η αγορά ενός τεμαχίου κοστίζει 57,00 CN¥ και η αποστολή του 134,52 CN¥, από το υπόλοιπό σας. Τι είναι κάθε γραμμή: Χρεώσεις.