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

Εισαγωγές

Επικολλήστε έναν σύνδεσμο καταχώρισης και πάρτε πίσω τις παραλλαγές της και πόσο σας κοστίζει η πώληση καθεμιάς: τα προϊόντα, η χρέωση παραλαβής 12,00 CN¥ για το δέμα του πωλητή προς εμάς, ο σταθερός φόρος 14%, μετά η γραμμή αποστολής, η χρέωση διαχείρισης 50,00 CN¥ ανά δέμα και ο φόρος σε αυτά, την προμήθεια της πλατφόρμας και την τιμή που διατηρεί το περιθώριό σας.

Η εισαγωγή είναι δωρεάν, χωρίς όριο προϊόντων. Πληρώνετε μόνο ό,τι παραγγέλνετε.
Κάθε ποσό αφορά ένα τεμάχιο, αγορασμένο σε δική του παραγγελία και απεσταλμένο σε δικό του δέμα: μία πώληση dropshipping. Πολλά τεμάχια σε μία παραγγελία ή ένα δέμα κοστίζουν λιγότερο από ό,τι δείχνει εδώ.
Οι προμήθειες πλατφόρμας είναι εξ ορισμού το δημόσιο βασικό ποσοστό κάθε πλατφόρμας. Στείλτε το δικό σας όταν η κατηγορία ή το πρόγραμμά σας διαφέρει.

Endpoints

POST/v1/importsΕισαγωγή από σύνδεσμο
POST/v1/imports/{id}/analysisΝέα τιμολόγηση
GET/v1/imports/{id}Ανάκτηση εισαγωγής
GET/v1/importsΛίστα εισαγωγών
POST/v1/imports/{id}/saveΑποθήκευση ως προϊόν

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

Μια καταχώριση όπως τη διαβάζουμε, με το κόστος μιας πώλησης ως την πόρτα του αγοραστή σας: τα προϊόντα, η χρέωση παραλαβής 12,00 CN¥ για το δέμα του πωλητή προς εμάς, ο σταθερός φόρος 14%, μετά η γραμμή αποστολής, η χρέωση διαχείρισης 50,00 CN¥ ανά δέμα και ο φόρος σε αυτά. Σε US$, είναι όσο χρεώνεται μια κάρτα σε US$, μαζί με τη μετατροπή νομίσματος.

idstring: Ξεκινά με imp_.
statusstring: running (ένα φύλλο ευρημάτων διαβάζεται ακόμη), ready ή failed.
urlstring: Ο σύνδεσμος που στείλατε.
marketplacestring: taobao, tmall, weidian ή 1688.
title, seller, images[]string: Όπως τα έγραψε ο πωλητής, συνήθως στα κινεζικά.
read_atstring: Πότε διαβάσαμε τελευταία την καταχώριση από την πλατφόρμα.
analysis.ship_to, lane, weight_g: Οι παράμετροι για τις οποίες τιμολογήθηκε.
analysis.coveredboolean: False όταν καμία δημοσιευμένη τιμή δεν αποστέλλει σε αυτή τη χώρα με αυτή τη γραμμή· τότε καμία παραλλαγή δεν έχει συνολικό κόστος.
analysis.marketplace_feeobject: percent και fixed: τι κρατά η πλατφόρμα από μια πώληση. Το default είναι true όταν δεν στείλατε κάτι και χρησιμοποιήσαμε το δημόσιο βασικό ποσοστό της, μια εκτίμηση, ποτέ ο πραγματικός λογαριασμός σας.
analysis.margin_reachableboolean: False όταν η χρέωση και το περιθώριο μαζί καλύπτουν όλη την τιμή: καμία τιμή δεν μπορεί να το πετύχει.
analysis.brand_hintobject|null: Λέξεις μάρκας ή replica στον τίτλο, στα αγγλικά ή στα κινεζικά. Ένδειξη, ποτέ ετυμηγορία: δεν βλέπει λογότυπο σε φωτογραφία, και ένα καθαρό αποτέλεσμα δεν αποδεικνύει τίποτα.
analysis.variants[].procurementobject: goods, intake_fee, tax και total της παραγγελίας που αγοράζει ένα τεμάχιο.
analysis.variants[].seller_shippingobject|null: Τα μεταφορικά του πωλητή ως την αποθήκη μας. Καμία καταχώριση δεν τα αναφέρει, οπότε είναι null: άγνωστα, όχι δωρεάν.
analysis.variants[].parcelobject|null: lane, shipping, handling_fee, tax και total του δέματος που το αποστέλλει.
analysis.variants[].landedobject: Είδος και δέμα μαζί: σε CN¥, σε US$, με την προμήθεια μετατροπής μέσα στο ποσό σε US$.
analysis.variants[].minimum_priceobject|null: Η χαμηλότερη τιμή που διατηρεί το περιθώριό σας μετά την προμήθεια της πλατφόρμας.
analysis.variants[].suggestedobject|null: Η χαμηλότερη τιμή x.99 ίση ή πάνω από την ελάχιστη, με την προμήθεια, το κέρδος και το περιθώριο που αφήνει.
productstring|null: Το προϊόν που έγινε μετά την αποθήκευση.

import

{
  "id": "imp_2c9d",
  "status": "ready",
  "url": "https://weidian.com/item.html?itemID=7750970856",
  "marketplace": "weidian",
  "title": "Heavyweight washed hoodie",
  "seller": "Ruoyi Studio",
  "images": [
    "https://media.ninjabuy.com/listings/weidian-7750970856/1.webp"
  ],
  "read_at": "2026-11-04T09:12:40Z",
  "analysis": {
    "ship_to": "US",
    "lane": "saver",
    "weight_g": 180,
    "covered": true,
    "marketplace": "ebay",
    "marketplace_fee": {
      "percent": "13.6",
      "fixed": { "amount": "0.40", "currency": "USD" },
      "default": true
    },
    "margin_percent": "30",
    "margin_reachable": true,
    "brand_hint": null,
    "variants": [
      {
        "sku": "5187209554",
        "label": "Black / M",
        "in_stock": true,
        "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" }
        },
        "seller_shipping": null,
        "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" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      },
      {
        "sku": "5187209555",
        "label": "Black / L",
        "in_stock": false,
        "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" }
        },
        "seller_shipping": null,
        "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" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      }
    ]
  },
  "product": null,
  "created_at": "2026-11-04T09:12:41Z"
}

Εισαγωγή από σύνδεσμο

POST/v1/imports

Διαβάζει μια καταχώριση Taobao, Tmall, Weidian ή 1688 (λειτουργεί και σύντομος σύνδεσμος ή σύνδεσμος άλλου πράκτορα αγορών προς αυτή) και την επιστρέφει αναλυμένη, στην ίδια κλήση. Μια καταχώριση που διαβάσαμε τα τελευταία πέντε λεπτά δεν ανακτάται ξανά.

Ένας σύνδεσμος φύλλου ευρημάτων (https://www.ninjabuy.com/spreadsheets/d/…) εισάγει κάθε προϊόν του: 202 με status: running, και μετά ελέγχετε περιοδικά την εισαγωγή.

Scopeproducts:write

Σώμα

urlstringυποχρεωτικό: Ένας σύνδεσμος προϊόντος ή ένα φύλλο ευρημάτων.
ship_tostring: Χώρα δύο γραμμάτων για την τιμολόγηση του δέματος. US αν παραλειφθεί.
lanestring: saver ή fast. saver αν παραλειφθεί.
weight_gintegerυποχρεωτικό: Το βάρος ενός τεμαχίου συσκευασμένου, σε γραμμάρια. Οι καταχωρίσεις δεν αναφέρουν βάρος, οπότε το δέμα τιμολογείται με το δικό σας.
marketplacestring: Πού το πουλάτε: ebay, shopify, amazon ή tiktok. shopify αν παραλειφθεί.
marketplace_feeobject: Προαιρετικό. percent και fixed (US$) για χρήση αντί του βασικού ποσοστού της πλατφόρμας, για την κατηγορία ή το πρόγραμμά σας.
margin_percentstring: Το περιθώριο-στόχος, επί της τιμής πώλησης. 30 αν παραλειφθεί.

Σφάλματα

Κατάσταση	Τύπος	Πότε
400	bad-body	Λείπει το weight_g ή ένα πεδίο είναι εκτός ορίων.
422	unprocessable	Δεν είναι σύνδεσμος που μπορούμε να διαβάσουμε, ή η καταχώριση δεν υπάρχει πια.
429	rate-limited	Το παράθυρο κλήσεων πλατφόρμας εξαντλήθηκε· δείτε Όρια ρυθμού.

curl -X POST "https://www.ninjabuy.com/api/v1/imports" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "ship_to": "US",
    "weight_g": 180,
    "marketplace": "ebay",
    "margin_percent": "30"
  }'

Response 201

HTTP/2 201 Created

{
  "id": "imp_2c9d",
  "status": "ready",
  "url": "https://weidian.com/item.html?itemID=7750970856",
  "marketplace": "weidian",
  "title": "Heavyweight washed hoodie",
  "seller": "Ruoyi Studio",
  "images": [
    "https://media.ninjabuy.com/listings/weidian-7750970856/1.webp"
  ],
  "read_at": "2026-11-04T09:12:40Z",
  "analysis": {
    "ship_to": "US",
    "lane": "saver",
    "weight_g": 180,
    "covered": true,
    "marketplace": "ebay",
    "marketplace_fee": {
      "percent": "13.6",
      "fixed": { "amount": "0.40", "currency": "USD" },
      "default": true
    },
    "margin_percent": "30",
    "margin_reachable": true,
    "brand_hint": null,
    "variants": [
      {
        "sku": "5187209554",
        "label": "Black / M",
        "in_stock": true,
        "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" }
        },
        "seller_shipping": null,
        "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" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      },
      {
        "sku": "5187209555",
        "label": "Black / L",
        "in_stock": false,
        "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" }
        },
        "seller_shipping": null,
        "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" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      }
    ]
  },
  "product": null,
  "created_at": "2026-11-04T09:12:41Z"
}

Νέα τιμολόγηση

POST/v1/imports/{id}/analysis

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

Scopeproducts:write

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

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

Σώμα

ship_tostring: Χώρα δύο γραμμάτων για την τιμολόγηση του δέματος. US αν παραλειφθεί.
lanestring: saver ή fast. saver αν παραλειφθεί.
weight_gintegerυποχρεωτικό: Το βάρος ενός τεμαχίου συσκευασμένου, σε γραμμάρια. Οι καταχωρίσεις δεν αναφέρουν βάρος, οπότε το δέμα τιμολογείται με το δικό σας.
marketplacestring: Πού το πουλάτε: ebay, shopify, amazon ή tiktok. shopify αν παραλειφθεί.
marketplace_feeobject: Προαιρετικό. percent και fixed (US$) για χρήση αντί του βασικού ποσοστού της πλατφόρμας, για την κατηγορία ή το πρόγραμμά σας.
margin_percentstring: Το περιθώριο-στόχος, επί της τιμής πώλησης. 30 αν παραλειφθεί.

Σφάλματα

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

curl -X POST "https://www.ninjabuy.com/api/v1/imports/imp_2c9d/analysis" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ship_to": "GB",
    "lane": "fast",
    "weight_g": 180,
    "marketplace": "tiktok",
    "margin_percent": "35"
  }'

Response 200

HTTP/2 200 OK

{
  "ship_to": "GB",
  "lane": "fast",
  "weight_g": 180,
  "covered": true,
  "marketplace": "tiktok",
  "marketplace_fee": {
    "percent": "6",
    "fixed": { "amount": "0.00", "currency": "USD" },
    "default": true
  },
  "margin_percent": "35",
  "margin_reachable": true,
  "brand_hint": null,
  "variants": [
    {
      "sku": "5187209554",
      "label": "Black / M",
      "in_stock": true,
      "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" }
      },
      "seller_shipping": null,
      "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" }
      },
      "landed": {
        "cny": { "amount": "191.52", "currency": "CNY" },
        "usd": { "amount": "27.71", "currency": "USD" },
        "fx_fee": { "amount": "5.75", "currency": "CNY" }
      },
      "minimum_price": { "amount": "49.84", "currency": "USD" },
      "suggested": {
        "price": { "amount": "49.99", "currency": "USD" },
        "marketplace_fee": { "amount": "7.20", "currency": "USD" },
        "profit": { "amount": "15.08", "currency": "USD" },
        "margin_percent": "30.16"
      }
    },
    {
      "sku": "5187209555",
      "label": "Black / L",
      "in_stock": false,
      "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" }
      },
      "seller_shipping": null,
      "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" }
      },
      "landed": {
        "cny": { "amount": "191.52", "currency": "CNY" },
        "usd": { "amount": "27.71", "currency": "USD" },
        "fx_fee": { "amount": "5.75", "currency": "CNY" }
      },
      "minimum_price": { "amount": "49.84", "currency": "USD" },
      "suggested": {
        "price": { "amount": "49.99", "currency": "USD" },
        "marketplace_fee": { "amount": "7.20", "currency": "USD" },
        "profit": { "amount": "15.08", "currency": "USD" },
        "margin_percent": "30.16"
      }
    }
  ]
}

Ανάκτηση εισαγωγής

GET/v1/imports/{id}

Διαβάστε ξανά μια εισαγωγή ή ελέγχετε περιοδικά ένα φύλλο ευρημάτων όσο εκτελείται.

Scopeproducts:read

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

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

Σφάλματα

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

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

Response 200

HTTP/2 200 OK

{
  "id": "imp_6t1b",
  "status": "running",
  "url": "https://www.ninjabuy.com/spreadsheets/d/1aBcD3fGh",
  "progress": { "done": 41, "total": 120 },
  "poll_after_seconds": 10
}

Λίστα εισαγωγών

GET/v1/imports

Τα νεότερα πρώτα. Οι εισαγωγές που δεν αποθηκεύσατε ποτέ μένουν εδώ για να επιστρέψετε σε αυτές.

Scopeproducts:read

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

statusstring: Προαιρετικό. running, ready ή failed.
savedboolean: Προαιρετικό. true για όσες έγιναν προϊόντα.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/imports?saved=false&limit=2" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "imp_2c9d",
      "status": "ready",
      "title": "Heavyweight washed hoodie",
      "product": null
    },
    {
      "id": "imp_2c7a",
      "status": "ready",
      "title": "Canvas tote, 3 colours",
      "product": null
    }
  ],
  "has_more": true,
  "cursor": "c_2c7a"
}

Αποθήκευση ως προϊόν

POST/v1/imports/{id}/save

Κρατά τις παραλλαγές που επιλέγετε ως προϊόν, στις τιμές που ορίζετε ή στις προτεινόμενες. Προσθέστε push_to: shopify για να το καταχωρίσετε στο κατάστημά σας με την ίδια κλήση (Προώθηση στο Shopify).

Scopeproducts:write

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

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

Σώμα

variants[]array: Προαιρετικό. sku και price κάθε παραλλαγής που κρατάτε. Αν παραλειφθεί, κάθε διαθέσιμη παραλλαγή στην προτεινόμενη τιμή της.
titlestring: Προαιρετικό. Δικός σας τίτλος· του πωλητή είναι συνήθως στα κινεζικά.
push_tostring: Προαιρετικό. shopify.

Σφάλματα

Κατάσταση	Τύπος	Πότε
409	invalid-state	Έχει ήδη αποθηκευτεί· το product το αναφέρει.
422	unprocessable	Κάθε παραλλαγή που κρατήσατε έχει εξαντληθεί.

curl -X POST "https://www.ninjabuy.com/api/v1/imports/imp_2c9d/save" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Heavyweight Washed Hoodie",
    "variants": [
      {
        "sku": "5187209554",
        "price": { "amount": "49.99", "currency": "USD" }
      }
    ],
    "push_to": "shopify"
  }'

Response 201

HTTP/2 201 Created

{
  "import": "imp_2c9d",
  "product": "prd_8f2k",
  "status": "draft",
  "channels": [{ "channel": "shopify", "status": "draft" }]
}