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

Παραγγελίες fulfillment

Οι γραμμές μιας παραγγελίας που συσκευάζουμε σε ένα δέμα, με το κουτί όπου μπαίνουν και τον έλεγχό μας για κάθε προϊόν.

Οι περισσότερες παραγγελίες έχουν μία. Μια παραγγελία της οποίας τα προϊόντα φτάνουν με μεγάλη απόσταση, ή που τη χωρίζετε, έχει περισσότερες.
Μια παραγγελία Shopify φτάνει ως αίτημα fulfillment του ίδιου του Shopify. Τη δεχόμαστε όταν κάθε γραμμή αντιστοιχεί σε SKU (Παραλλαγές) και την απορρίπτουμε αναφέροντας τις γραμμές που δεν αντιστοιχούν, ώστε το Shopify να την κρατά σε εσάς.
Ένα προϊόν που αποτυγχάνει στον έλεγχό μας ενεργοποιεί το qc.issue και περιμένει την επιλογή σας πριν αποσταλεί.

Endpoints

GET/v1/fulfillment_ordersΛίστα παραγγελιών fulfillment
GET/v1/fulfillment_orders/{id}Ανάκτηση παραγγελίας fulfillment
POST/v1/fulfillment_orders/{id}/holdΑναμονή
POST/v1/fulfillment_orders/{id}/releaseΑποδέσμευση
POST/v1/fulfillment_orders/{id}/cancelΑκύρωση

Το αντικείμενο Fulfillment order

idstring: Ξεκινά με fo_.
orderstring: Η παραγγελία στην οποία ανήκει.
statusstring: open (περιμένει τα προϊόντα του), in_progress (συσκευάζεται), on_hold, closed (απεστάλη) ή cancelled.
requestobject|null: Για παραγγελία Shopify: η παραγγελία fulfillment του Shopify και η απάντησή μας, αποδεκτή ή απορριφθείσα με τις παραλλαγές καταστήματος που δεν αντιστοιχούν σε SKU.
holdobject|null: reason και note, όσο είναι σε αναμονή.
packagingstring|null: Το κουτί ή ο φάκελος όπου μπαίνει.
lines[].qcobject: Ο έλεγχός μας: pending, passed ή issue, με τις φωτογραφίες και πότε.
shipmentstring|null: Ορίζεται μόλις φύγει.

fulfillment_order

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "in_progress",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

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

GET/v1/fulfillment_orders

Τα νεότερα πρώτα. Φιλτράρισμα ανά παραγγελία ή κατάσταση.

Scopeorders:read

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

orderstring: Προαιρετικό. Ένα id παραγγελίας.
statusstring: Προαιρετικό.
limit, cursor: Pagination

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

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "fo_7k1x",
      "order": "ord_3n6z",
      "status": "on_hold",
      "hold": { "reason": "combine" }
    }
  ],
  "has_more": false,
  "cursor": null
}

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

GET/v1/fulfillment_orders/{id}

Οι γραμμές της, ο έλεγχός μας για καθεμία, η συσκευασία και η αποστολή.

Scopeorders:read

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

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

Σφάλματα

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

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

Response 200

HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "in_progress",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

Αναμονή

POST/v1/fulfillment_orders/{id}/hold

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

Scopeorders:write

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

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

Σώμα

reasonstringυποχρεωτικό: combine, wait_for_stock ή other.
notestring: Προαιρετικό. Μια σημείωση για εσάς, που αποθηκεύεται με την αναμονή.

Σφάλματα

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

curl -X POST "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m/hold" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "combine" }'

Response 200

HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "on_hold",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": {
    "reason": "combine",
    "note": null,
    "since": "2026-11-02T04:00:00Z"
  },
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

Αποδέσμευση

POST/v1/fulfillment_orders/{id}/release

Αφήνει μια παραγγελία fulfillment σε αναμονή να συνεχίσει.

Scopeorders:write

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

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

Σφάλματα

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

curl -X POST "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m/release" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)"

Response 200

HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "in_progress",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

Ακύρωση

POST/v1/fulfillment_orders/{id}/cancel

Ακυρώνει το δέμα όσο δεν έχει συσκευαστεί τίποτα σε αυτό. Τα προϊόντα του μένουν στο ράφι σας, για αποστολή αργότερα ή με άλλη παραγγελία. Για να ακυρώσετε και την αγορά, ακυρώστε την παραγγελία.

Scopeorders:write

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

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

Σφάλματα

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

curl -X POST "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m/cancel" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)"

Response 200

HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "cancelled",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}