Προγραμματιστές / REST API

Αναφορά API

Όλα στο MyProductPassport είναι διαθέσιμα μέσω REST API με πιστοποίηση κλειδιού: δημιουργήστε προϊόντα, δημιουργήστε και δημοσιεύστε ψηφιακά διαβατήρια προϊόντων, στείλτε ζωντανά δεδομένα μπαταριών και ελέγξτε τη συμμόρφωση απευθείας από το ERP, το PIM ή τη ροή build σας.

v1 https://myproductpassport.eu/api/v1 Ξεκινήστε δωρεάν Προδιαγραφή OpenAPI ↓

01 / Πρώτα βήματαΈλεγχος ταυτότητας

Κάθε αίτημα πιστοποιείται με κλειδί API που αποστέλλεται ως Bearer token. Τα κλειδιά δημιουργούνται στην εφαρμογή στην ενότητα Κλειδιά API, εμφανίζονται μία φορά και αποθηκεύονται κατακερματισμένα· κάθε κλειδί έχει το δικό του σύνολο δικαιωμάτων, προαιρετική λίστα επιτρεπόμενων IP και προαιρετική ημερομηνία λήξης. Τα κλειδιά μπορούν να εναλλάσσονται χωρίς διακοπή λειτουργίας.

Κεφαλίδα αιτήματος

Authorization: Bearer pk_your_api_key

Σε κάθε πρόγραμμα. Τα κλειδιά API δημιουργούνται και χρησιμοποιούνται σε κάθε πρόγραμμα, και στο δωρεάν. Το πρόγραμμα ορίζει πόσα αιτήματα ανά λεπτό μπορεί να κάνει ένα κλειδί (παρακάτω) και πόσα προϊόντα και διαβατήρια μπορεί να έχει ο χώρος εργασίας.

Λειτουργία δοκιμής. Ένα δοκιμαστικό κλειδί (pk_test_...) εκτελεί κάθε κλήση ακριβώς όπως ένα κλειδί παραγωγής, με τον ίδιο έλεγχο εγκυρότητας, τα ίδια αναγνωριστικά και τις ίδιες αποκρίσεις, και στη συνέχεια την αναιρεί: δεν αποθηκεύεται τίποτα, δεν αποστέλλεται κανένα email ή webhook και δεν διατηρείται κανένα αρχείο. Οι αποκρίσεις περιέχουν "test_mode": true και την κεφαλίδα X-MPP-Mode: test. Δημιουργήστε και δοκιμάστε μια ενσωμάτωση με τα πραγματικά σας δεδομένα και, στη συνέχεια, χρησιμοποιήστε ένα κλειδί παραγωγής.

Τα δικαιώματα εκχωρούνται ανά κλειδί, ώστε μια ενσωμάτωση να λαμβάνει μόνο ό,τι χρειάζεται:

Δικαίωμα	Εκχωρήσεις πρόσβασης
products:read	Ανάγνωση προϊόντων
products:write	Δημιουργία, ενημέρωση και διαγραφή προϊόντων
passports:read	Ανάγνωση διαβατηρίων
passports:write	Δημιουργία διαβατηρίων
passports:publish	Δημοσίευση και αρχειοθέτηση διαβατηρίων
webhooks:manage	Δημιουργία, δοκιμή και αφαίρεση τελικών σημείων webhook
items:read	Read individual items and their history
items:write	Add, update and flag individual items
aftersales:read	Read owner registrations and service requests
aftersales:write	Update service requests and reply to customers

02 / Πρώτα βήματαΌρια αιτημάτων

Τα όρια ισχύουν ανά κλειδί, ανά λεπτό, και ορίζονται από το πρόγραμμα:

Πρόγραμμα	Αιτήματα / λεπτό
Δωρεάν	30
Micro	60
Ηλεκτρονική ετικέτα	60
Starter	120
Professional	300
Business	600
Battery	600

Κάθε απάντηση περιέχει τις κεφαλίδες X-RateLimit-Limit και X-RateLimit-Remaining. Η υπέρβαση του ορίου επιστρέφει 429:

429 Too Many Requests

{ "error": "Rate limit exceeded.", "limit": 300, "retry_after": 60 }

03 / Πρώτα βήματαΣφάλματα

Τα σφάλματα είναι JSON με συνήθη κωδικό κατάστασης. Τα πιο συνηθισμένα:

Κατάσταση	Σημασία	Παράδειγμα σώματος
401	Κλειδί που λείπει, είναι άκυρο, ανακλημένο ή έχει λήξει	`{"error": "Invalid or revoked API key."}`
403	Λείπει μια άδεια από το κλειδί, η IP δεν είναι στη λίστα επιτρεπόμενων ή εξαντλήθηκε το όριο του προγράμματος	`{"message": "API key does not have 'products:write' permission."}`
404	Ο πόρος δεν υπάρχει στον χώρο εργασίας σας	`{"message": "Not found."}`
422	Η επικύρωση απέτυχε	`{"message": "…", "errors": {"gtin": ["…"]}}`
429	Υπέρβαση ορίου αιτημάτων	`{"error": "Rate limit exceeded."}`

04 / Πρώτα βήματαΣελιδοποίηση

Τα τελικά σημεία λίστας επιστρέφουν 25 στοιχεία ανά σελίδα με τα τυπικά αντικείμενα links και meta. Περάστε ?page=2 για να μετακινηθείτε στη συλλογή.

05 / Πρώτα βήματαΣύνδεση βοηθού ΤΝ (MCP)

Συνδέστε το Claude, το Cursor ή οποιονδήποτε βοηθό υποστηρίζει το Model Context Protocol και ζητήστε του με απλά λόγια να δημιουργεί προϊόντα, να συμπληρώνει διαβατήρια με όσα του λέτε και να ελέγχει τι λείπει ακόμη. Χρησιμοποιεί ένα κλειδί API με τις άδειες και το όριο αιτημάτων του. Μπορεί να δημιουργεί προσχέδια και να συμπληρώνει πεδία· ποτέ δεν δημοσιεύει, αρχειοθετεί ή διαγράφει τίποτα: αυτά μένουν σε εσάς στην εφαρμογή.

Διεύθυνση διακομιστή (Streamable HTTP)

https://myproductpassport.eu/api/mcp

Claude Code

claude mcp add --transport http myproductpassport https://myproductpassport.eu/api/mcp \
  --header "Authorization: Bearer pk_live_your_key"

Cursor (mcp.json)

{
  "mcpServers": {
    "myproductpassport": {
      "url": "https://myproductpassport.eu/api/mcp",
      "headers": { "Authorization": "Bearer pk_live_your_key" }
    }
  }
}

Claude Desktop και άλλοι πελάτες που εκκινούν τοπικό διακομιστή

{
  "mcpServers": {
    "myproductpassport": {
      "command": "npx",
      "args": ["mcp-remote", "https://myproductpassport.eu/api/mcp", "--header", "Authorization: Bearer pk_live_your_key"]
    }
  }
}

Τα εργαλεία που προσφέρει:

Εργαλείο	Τι κάνει
list_products	Τα προϊόντα του χώρου εργασίας, τα νεότερα πρώτα, 25 ανά σελίδα, με τον τομέα και το τελευταίο διαβατήριο.
get_product	Ένα προϊόν με τα στοιχεία, τον τομέα, τις ρυθμιστικές ενότητες και το τελευταίο διαβατήριο.
list_sectors	Τα πρότυπα τομέων που μπορεί να χρησιμοποιήσει ένα προϊόν (κλωστοϋφαντουργικά, ηλεκτρονικά, μπαταρίες, κρασί και άλλα), με τα αναγνωριστικά τους. Ο τομέας ενός προϊόντος καθορίζει ποια πεδία του διαβατηρίου είναι υποχρεωτικά.
create_product	Προσθέτει ένα προϊόν στον χώρο εργασίας. Χρησιμοποιήστε ένα sector_id από το list_sectors. Το compliance_sections προσθέτει ρυθμιστικές ενότητες στο διαβατήριο: gpsr, epr, france, chemicals, eudr.
list_passports	Τα διαβατήρια του χώρου εργασίας, τα νεότερα πρώτα, 25 ανά σελίδα, με κατάσταση (draft, published, archived), ποσοστό πληρότητας και δημόσια διεύθυνση.
get_passport	Ένα διαβατήριο: κατάσταση, έκδοση, ποσοστό πληρότητας, δημόσια διεύθυνση και σύνδεσμοι κωδικού QR.
create_passport	Δημιουργεί προσχέδιο διαβατηρίου για ένα προϊόν. Δεν δημοσιεύεται: το δημοσιεύει ένα πρόσωπο στην εφαρμογή.
get_passport_fields	Τι ζητά ένα διαβατήριο: τα κλειδιά των υποχρεωτικών και προαιρετικών πεδίων, τι σημαίνει το καθένα (ετικέτα, περιγραφή, παράδειγμα), οι τιμές που έχει και ποια υποχρεωτικά λείπουν.
update_passport_fields	Γράφει τιμές πεδίων σε προσχέδιο ή δημοσιευμένο διαβατήριο (το δημοσιευμένο ενημερώνεται επί τόπου: ίδια διεύθυνση, ίδιος κωδικός QR). Κλειδιά από το get_passport_fields· κενό κείμενο αφαιρεί μια τιμή. Γράφετε μόνο γεγονότα που δηλώνει ο χρήστης ή τα έγγραφά του.
get_compliance	Η πληρότητα ενός διαβατηρίου: ποσοστό, κατάσταση και τα υποχρεωτικά πεδία που λείπουν ακόμη.

Δοκιμάστε το με κλειδί δοκιμής. Με κλειδί δοκιμής (pk_test_...) οι αλλαγές του βοηθού ελέγχονται και μετά αναιρούνται, ώστε να δείτε τι θα έκανε πριν του δώσετε πραγματικό κλειδί.

06 / Τελικά σημείαΛογαριασμός

GET /me

Επιστρέφει τον πιστοποιημένο λογαριασμό, το επίπεδο συνδρομής του και πόσο από το όριο προϊόντων έχει χρησιμοποιηθεί. Χρήσιμο ως έλεγχος σύνδεσης.

Αίτημα

curl https://myproductpassport.eu/api/v1/me \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{
  "data": {
    "id": 42,
    "name": "Jane Doe",
    "email": "[email protected]",
    "company_name": "Acme Ltd",
    "subscription_tier": "professional",
    "product_count": 128,
    "product_limit": 500,
    "passport_count": 96,
    "organization": {"id": 7, "name": "Acme Ltd"},
    "api_key": {"name": "ERP sync", "permissions": ["*"], "rate_limit_per_minute": 1000, "expires_at": null},
    "webhooks_available": true
  }
}

07 / Τελικά σημείαΠροϊόντα

GET /products απαιτεί products:read

Εμφανίζει τα προϊόντα του χώρου εργασίας σας, νεότερα πρώτα, 25 ανά σελίδα. Κάθε προϊόν περιλαμβάνει τον τομέα του και σύνοψη του πιο πρόσφατου διαβατηρίου.

Παράμετρος	Τύπος		Περιγραφή
page	integer		Αριθμός σελίδας.

Αίτημα

curl "https://myproductpassport.eu/api/v1/products?page=1" \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{
  "data": [
    {
      "id": 512,
      "name": "Alpine Merino Crew Sweater",
      "sku": "AM-CREW-01",
      "gtin": "05012345678900",
      "brand": "Northloom",
      "category": "textiles",
      "status": "active",
      "country_of_origin": "PT",
      "weight": 0.4,
      "weight_unit": "kg",
      "materials": [
        { "name": "Merino wool (RWS)", "percentage": 78 },
        { "name": "Recycled nylon (GRS)", "percentage": 20 },
        { "name": "Elastane", "percentage": 2 }
      ],
      "sector": { "id": 3, "name": "Textiles" },
      "latest_passport": {
        "id": 96, "version": 1,
        "status": "published", "compliance_percentage": 100
      },
      "created_at": "2026-08-14T09:21:00+00:00",
      "updated_at": "2026-09-01T16:02:11+00:00"
    }
  ],
  "links": { "next": null },
  "meta": { "current_page": 1, "per_page": 25, "total": 1 }
}

POST /products απαιτεί products:write

Δημιουργεί ένα προϊόν. Επιστρέφει 403 αν έχει εξαντληθεί το όριο προϊόντων του προγράμματος.

Παράμετρος	Τύπος		Περιγραφή
name	string	υποχρεωτικό	Όνομα προϊόντος, έως 255 χαρακτήρες.
sku	string		Το εσωτερικό σας SKU, έως 100 χαρακτήρες.
gtin	string		GTIN-8, 12, 13 ή 14 (μόνο ψηφία).
brand	string		Μάρκα που εμφανίζεται στο δημόσιο διαβατήριο.
description	string		Έως 2.000 χαρακτήρες.
category	string		Κατηγορία ελεύθερου κειμένου. Προεπιλογή "general".
sector_id	integer		Αναγνωριστικό τομέα, που επιλέγει το πρότυπο πεδίων του διαβατηρίου.
country_of_origin	string		Κωδικός χώρας, π.χ. "PT".
weight	number		Καθαρό βάρος.
weight_unit	string		Ένα από kg, g, lb, oz. Προεπιλογή kg.
materials	array		Αντικείμενα {name, percentage 0-100}.
has_packaging	boolean		Προσθέτει στο διαβατήριο τα πεδία του προτύπου συσκευασίας (κλειδιά που αρχίζουν με pkg_), με τον ίδιο κωδικό QR.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/products \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alpine Merino Crew Sweater",
    "sku": "AM-CREW-01",
    "gtin": "05012345678900",
    "sector_id": 3,
    "materials": [
      {"name": "Merino wool (RWS)", "percentage": 78},
      {"name": "Recycled nylon (GRS)", "percentage": 22}
    ]
  }'

Απάντηση

{
  "data": {
    "id": 513,
    "name": "Alpine Merino Crew Sweater",
    "sku": "AM-CREW-01",
    "status": "active",
    "sector": { "id": 3, "name": "Textiles" },
    "created_at": "2026-09-07T18:40:00+00:00"
  }
}

POST /products/bulk απαιτεί products:write

Δημιουργεί έως 100 προϊόντα με μία κλήση. Ολόκληρη η παρτίδα απορρίπτεται με 403 αν υπερβαίνει το υπόλοιπο όριο προϊόντων σας. Για καταλόγους χιλιάδων προϊόντων, καλέστε επαναληπτικά αυτό το τελικό σημείο ή χρησιμοποιήστε την εισαγωγή CSV στην εφαρμογή.

Παράμετρος	Τύπος		Περιγραφή
products	array	υποχρεωτικό	1 έως 100 αντικείμενα προϊόντων με τα ίδια πεδία με τη «Δημιουργία προϊόντος» (χωρίς υλικά).

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/products/bulk \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {"name": "PSL-BT-122000", "sku": "PSL-BT-122000", "sector_id": 5},
      {"name": "PSL-BT-123000", "sku": "PSL-BT-123000", "sector_id": 5}
    ]
  }'

Απάντηση

{
  "message": "2 product(s) created.",
  "products": [
    { "id": 514, "name": "PSL-BT-122000", "status": "active" },
    { "id": 515, "name": "PSL-BT-123000", "status": "active" }
  ]
}

GET /products/{id} απαιτεί products:read

Επιστρέφει ένα προϊόν με τον τομέα του και σύνοψη του πιο πρόσφατου διαβατηρίου. 404 αν το id δεν ανήκει στον χώρο εργασίας σας.

Αίτημα

curl https://myproductpassport.eu/api/v1/products/512 \
  -H "Authorization: Bearer pk_your_key"

PUT /products/{id} απαιτεί products:write

Ενημερώνει μερικώς ένα προϊόν. Στείλτε μόνο τα πεδία που θέλετε να αλλάξετε· η λίστα πεδίων είναι ίδια με τη Δημιουργία προϊόντος.

Αίτημα

curl -X PUT https://myproductpassport.eu/api/v1/products/512 \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"brand": "Northloom"}'

DELETE /products/{id} απαιτεί products:write

Διαγράφει ένα προϊόν με δυνατότητα ανάκτησης. Τα δημοσιευμένα διαβατήρια του προϊόντος συνεχίζουν να λειτουργούν, ώστε οι τυπωμένοι κωδικοί QR να μη μένουν ποτέ χωρίς σελίδα.

Αίτημα

curl -X DELETE https://myproductpassport.eu/api/v1/products/512 \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{ "message": "Product deleted." }

08 / Τελικά σημείαΔιαβατήρια

GET /passports απαιτεί passports:read

Εμφανίζει τα διαβατήρια, νεότερα πρώτα, 25 ανά σελίδα, με σύνοψη προϊόντος και όλα τα πεδία του διαβατηρίου.

Παράμετρος	Τύπος		Περιγραφή
page	integer		Αριθμός σελίδας.

Αίτημα

curl https://myproductpassport.eu/api/v1/passports \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{
  "data": [
    {
      "id": 96,
      "uuid": "36ff3776-d517-4228-8cde-9208136ea84a",
      "version": 1,
      "status": "published",
      "compliance_status": "compliant",
      "compliance_percentage": 100,
      "public_url": "https://myproductpassport.co.uk/p/36ff3776-…",
      "gs1_url": "https://myproductpassport.co.uk/01/05012345678900",
      "product": { "id": 512, "name": "Alpine Merino Crew Sweater", "sku": "AM-CREW-01" },
      "fields": [
        { "key": "material_composition", "value": "…", "verification_status": "verified" }
      ],
      "published_at": "2026-08-16T10:00:00+00:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1 }
}

POST /products/{productId}/passports απαιτεί passports:write

Δημιουργεί ένα πρόχειρο διαβατήριο για ένα προϊόν, προσυμπληρώνοντας πεδία από τα δεδομένα του προϊόντος και το πρότυπο του τομέα. Επιστρέφει το πρόχειρο με τη βαθμολογία συμμόρφωσής του. Για προϊόν που έχει ήδη ενεργό διαβατήριο επιστρέφεται 409 με αυτό το διαβατήριο: διορθώστε το με PUT /passports/{id}/fields, που διατηρεί τη διεύθυνση και τον κωδικό QR του.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/products/512/passports \
  -H "Authorization: Bearer pk_your_key"

GET /passports/{id} απαιτεί passports:read

Επιστρέφει ένα διαβατήριο με προϊόν, πεδία, δημόσιο URL και GS1 Digital Link.

Αίτημα

curl https://myproductpassport.eu/api/v1/passports/96 \
  -H "Authorization: Bearer pk_your_key"

POST /passports/{id}/publish απαιτεί passports:publish

Δημοσιεύει ένα πρόχειρο διαβατήριο, ενεργοποιώντας τη δημόσια σελίδα και τον κωδικό QR του. Μόνο πρόχειρα μπορούν να δημοσιευθούν· οτιδήποτε άλλο επιστρέφει 404.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/passports/96/publish \
  -H "Authorization: Bearer pk_your_key"

POST /passports/{id}/archive απαιτεί passports:publish

Αρχειοθετεί ένα διαβατήριο και αποσύρει τη δημόσια σελίδα του.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/passports/96/archive \
  -H "Authorization: Bearer pk_your_key"

POST /passports/bulk-publish απαιτεί passports:publish

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

Παράμετρος	Τύπος		Περιγραφή
passport_ids	array	υποχρεωτικό	1 έως 50 αναγνωριστικά διαβατηρίων.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/passports/bulk-publish \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"passport_ids": [96, 97, 98]}'

Απάντηση

{
  "published": 2,
  "failed": 1,
  "published_ids": [96, 97],
  "errors": [
    { "id": 98, "error": "Compliance below the publishing threshold." }
  ]
}

POST /passports/{id}/successor απαιτεί passports:write

Για προϊόν που έχει προετοιμαστεί για επαναχρησιμοποίηση, έχει επαναπροσδιοριστεί ή ανακατασκευαστεί, ο Κανονισμός για τις μπαταρίες (άρθρο 77 παράγραφος 7) απαιτεί νέο διαβατήριο συνδεδεμένο με το αρχικό. Αυτό δημιουργεί νέα εγγραφή προϊόντος και πρόχειρο διαβατήριο προσυμπληρωμένο από το δημοσιευμένο, με σύνδεσμο προς αυτό. Το αρχικό παραμένει ενεργό και τα δύο διαβατήρια εμφανίζουν τον σύνδεσμο. Δημοσιεύστε το νέο με POST /passports/{id}/publish.

Παράμετρος	Τύπος		Περιγραφή
stage	string	υποχρεωτικό	prepared_for_reuse, repurposed ή remanufactured.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/passports/96/successor \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "repurposed" }'

Απάντηση

{
  "data": {
    "id": 131, "status": "draft", "version": 1,
    "lineage": {
      "stage": "repurposed",
      "original": { "id": 96, "url": "https://myproductpassport.co.uk/p/..." },
      "originals": [{ "passport_id": 96, "product_id": 40, "stage": "repurposed", "status": "published", "url": "https://myproductpassport.co.uk/p/..." }],
      "successors": []
    }
  }
}

GET /passports/{id}/fields απαιτεί passports:read

Επιστρέφει τα κλειδιά πεδίων που ζητά το πρότυπο τομέα του διαβατηρίου (υποχρεωτικά και προαιρετικά), τις τρέχουσες τιμές και ποια υποχρεωτικά κλειδιά λείπουν ακόμη. Χρησιμοποιήστε το για να δημιουργήσετε το σώμα για PUT /passports/{id}/fields.

Αίτημα

curl https://myproductpassport.eu/api/v1/passports/96/fields \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{
  "passport_id": 96,
  "sector": "batteries",
  "compliance_percentage": 84,
  "required": ["battery_category", "carbon_footprint", "..."],
  "optional": ["energy_round_trip_efficiency", "..."],
  "missing_required": ["carbon_footprint_class", "recycled_content"],
  "values": { "battery_category": "Industrial", "...": "..." }
}

PUT /passports/{id}/fields απαιτεί passports:write

Γράφει οποιοδήποτε σύνολο τιμών πεδίων σε πρόχειρο ή ενεργό διαβατήριο: το πλήρες σύνολο του παραρτήματος XIII για μια μπαταρία, τα πεδία ενός προτύπου τομέα ή δικά σας κλειδιά. Στείλτε μόνο τα κλειδιά που θέλετε να αλλάξετε· μια τιμή null ή κενή αφαιρεί το πεδίο. Ένα ενεργό διαβατήριο ενημερώνεται επί τόπου, η διεύθυνση και ο κωδικός QR του δεν αλλάζουν και οι μηχανικές του μεταφράσεις δημιουργούνται ξανά. Η συμμόρφωση βαθμολογείται εκ νέου. Ένα πρόχειρο δεν δημοσιεύεται με αυτή την κλήση· χρησιμοποιήστε POST /passports/{id}/publish.

Παράμετρος	Τύπος		Περιγραφή
fields	object	υποχρεωτικό	Αντιστοίχιση κλειδιού πεδίου σε τιμή. Τα κλειδιά είναι πεζά γράμματα, ψηφία και κάτω παύλες· οι τιμές έως 5.000 χαρακτήρες. Έως 200 κλειδιά ανά κλήση.

Αίτημα

curl -X PUT https://myproductpassport.eu/api/v1/passports/96/fields \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "carbon_footprint": "61.2 kg CO2e/kWh",
      "carbon_footprint_class": "C",
      "recycled_content": "Cobalt 16%, lithium 6%, nickel 6%, lead 0%"
    }
  }'

Απάντηση

{
  "message": "3 field(s) changed, 0 removed.",
  "changed": ["carbon_footprint", "carbon_footprint_class", "recycled_content"],
  "removed": [],
  "passport": { "id": 96, "status": "published", "compliance_percentage": 92 }
}

POST /passports/{id}/state-of-health απαιτεί passports:write

Στέλνει τα δεδομένα αυτής της μπαταρίας (σημείο 4 του Παραρτήματος XIII του Κανονισμού (ΕΕ) 2023/1542) σε δημοσιευμένο διαβατήριο, για συστήματα BMS και στόλων. Στείλτε οποιοδήποτε υποσύνολο των παρακάτω πεδίων· η συμμόρφωση ελέγχεται ξανά μετά την ενημέρωση. Οι τιμές αυτές εμφανίζονται μόνο σε επισκέπτες που έχει εγκρίνει ο κάτοχος του διαβατηρίου (άρθρο 77 παράγραφος 2), ποτέ στη δημόσια σελίδα. Τα capacity_fade, power_capability και internal_resistance αποθηκεύονται ως τρέχουσες μετρήσεις αυτής της μπαταρίας (current_*), χωριστά από τις αρχικές τιμές του μοντέλου.

Παράμετρος	Τύπος	Περιγραφή
state_of_health	string	π.χ. "97% στους 412 κύκλους".
state_of_certified_energy	string	Εναπομένουσα πιστοποιημένη ενέργεια (μπαταρίες ΗΟ).
battery_status	string	original, repurposed, re-used, remanufactured ή waste.
capacity_fade	string	Απώλεια χωρητικότητας έως σήμερα. Αποθηκεύεται ως current_capacity_fade.
power_capability	string	Τρέχουσα ικανότητα ισχύος. Αποθηκεύεται ως current_power_capability.
internal_resistance	string	Μετρημένη εσωτερική αντίσταση. Αποθηκεύεται ως current_internal_resistance.
use_data	string	Κύκλοι, αρνητικά συμβάντα, θερμοκρασία και κατάσταση φόρτισης, έως 5.000 χαρακτήρες.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/passports/96/state-of-health \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "state_of_health": "97% at 412 cycles",
    "capacity_fade": "3% from initial rated capacity"
  }'

Απάντηση

{
  "message": "2 field(s) updated.",
  "updated_fields": ["state_of_health", "current_capacity_fade"],
  "passport": { "id": 96, "status": "published", "compliance_percentage": 100 }
}

POST /passports/{id}/units απαιτεί passports:write

Κάθε μπαταρία χρειάζεται το δικό της διαβατήριο (Κανονισμός (ΕΕ) 2023/1542, άρθρο 77 παράγραφος 1). Καταχωρίστε έως 10.000 μπαταρίες ενός μοντέλου με μία κλήση, καθεμία με τον δικό της σειριακό αριθμό (έως 20 γράμματα, ψηφία, τελείες, παύλες ή κάτω παύλες) και προαιρετικά manufacturing_date, battery_status και τα δεδομένα της κατά το σημείο 4 του Παραρτήματος XIII. Οι υπάρχοντες σειριακοί αριθμοί ενημερώνονται· οι τιμές που παραλείπετε διατηρούνται. Αν το προϊόν έχει GTIN, η διεύθυνση κάθε μπαταρίας είναι το GS1 Digital Link της, /01/{gtin}/21/{serial}. Τα δεδομένα του σημείου 4 εμφανίζονται μόνο σε επισκέπτες που εγκρίνει ο κάτοχος.

Παράμετρος	Τύπος		Περιγραφή
units[].serial	string	υποχρεωτικό	Ο σειριακός αριθμός της μπαταρίας.
units[].manufacturing_date	string		Μήνας και έτος, π.χ. "2026-09".
units[].battery_status	string		original ή waste. Μια αλλαγή κατάστασης απαιτεί τις τιμές που μετρήθηκαν κατά την αλλαγή (παράρτημα XIII, σημείο 4 στοιχείο α)). Για το waste απαιτούνται επίσης τα responsible_party_type (producer, pro ή waste_operator), responsible_party_name και responsible_party_contact (άρθρο 77 παράγραφος 7). Το recycled, με recycled_at και recycler_name, τερματίζει το διαβατήριο (άρθρο 77 παράγραφος 8). Μια μπαταρία με αλλαγή χρήσης, επαναχρησιμοποιημένη ή ανακατασκευασμένη λαμβάνει νέο διαβατήριο: POST /passports/{id}/units/{serial}/successor.
units[].state_of_health	string		Επίσης state_of_certified_energy, current_capacity_fade, current_power_capability, current_internal_resistance, remaining_capacity_ah, power_fade, internal_resistance_increase, round_trip_efficiency, round_trip_efficiency_fade, expected_lifetime_cycles_remaining, self_discharge_rate, ohmic_resistance και use_data.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/passports/96/units \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"units": [{"serial": "KES-00001", "manufacturing_date": "2026-09", "state_of_health": "100%"}]}'

Απάντηση

{ "created": 1, "updated": 0, "skipped": 0, "errors": [] }

PATCH /passports/{id}/units/{serial} απαιτεί passports:write

Για σύστημα διαχείρισης μπαταρίας που στέλνει τα δεδομένα μίας μπαταρίας: οποιοδήποτε από battery_status, state_of_health, state_of_certified_energy, current_capacity_fade, current_power_capability, current_internal_resistance και use_data. Χρησιμοποιήστε GET στην ίδια διαδρομή για ανάγνωση ή GET /passports/{id}/units για τη λίστα (per_page έως 500).

Αίτημα

curl -X PATCH https://myproductpassport.eu/api/v1/passports/96/units/KES-00001 \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"state_of_health": "96% at 412 cycles"}'

Απάντηση

{
  "data": { "serial": "KES-00001", "public_url": "https://myproductpassport.co.uk/01/05012345678900/21/KES-00001", "battery_status": "original", "data": { "state_of_health": "96% at 412 cycles" } }
}

GET /passports/{id}/units/{serial}/snapshots απαιτεί passports:read

Το παράρτημα XIII σημείο 4 στοιχείο α) απαιτεί τις τιμές απόδοσης και ανθεκτικότητας κατά τη διάθεση της μπαταρίας στην αγορά και όταν αλλάζει η κατάστασή της. Οι μετρήσεις αυτές διατηρούνται όπως ήταν, ό,τι κι αν αποσταλεί αργότερα· στείλτε record_snapshot: true με ένα PATCH για να διατηρηθεί και μια περιοδική μέτρηση.

Αίτημα

curl https://myproductpassport.eu/api/v1/passports/96/units/KES-00001/snapshots \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{
  "data": [
    { "event": "placed_on_market", "status": "original", "values": { "state_of_health": "100%" }, "measured_at": "2026-09-26T09:00:00+00:00", "source": "api" },
    { "event": "status_change", "status": "waste", "values": { "remaining_capacity_ah": "71 Ah", "power_fade": "14%", "internal_resistance_increase": "22%", "expected_lifetime_cycles_remaining": "0" }, "measured_at": "2029-03-02T10:00:00+00:00", "source": "bms" }
  ]
}

POST /passports/{id}/units/{serial}/successor απαιτεί passports:write

Άρθρο 77 παράγραφος 7: μια μπαταρία που έχει προετοιμαστεί για επαναχρησιμοποίηση, έχει υποστεί αλλαγή σκοπού ή έχει ανακατασκευαστεί αποκτά νέο διαβατήριο συνδεδεμένο με το αρχικό της. Αυτό καταχωρίζει ξανά την μπαταρία, με νέο σειριακό αριθμό και αναγνωριστικό, σε μοντέλο μπαταρίας δεύτερης ζωής του χώρου εργασίας σας (που δημιουργείται από αυτό το μοντέλο αν δεν υπάρχει ακόμη), συνδέει τα δύο και διατηρεί τις τιμές που μετρήθηκαν κατά την αλλαγή. Η αρχική μπαταρία διατηρεί το διαβατήριό της. Συμπληρώστε και δημοσιεύστε το μοντέλο δεύτερης ζωής με POST /passports/{id}/publish.

Παράμετρος	Τύπος		Περιγραφή
stage	string	υποχρεωτικό	prepared_for_reuse, repurposed ή remanufactured.
values	object	υποχρεωτικό	Οι τιμές που μετρήθηκαν κατά την αλλαγή: τουλάχιστον ένα από τα remaining_capacity_ah ή current_capacity_fade, ένα από τα current_power_capability ή power_fade, ένα από τα current_internal_resistance ή internal_resistance_increase, καθώς και το expected_lifetime_cycles_remaining (παράρτημα IV μέρος Α).
serial	string		Ο νέος αριθμός σειράς. Προεπιλογή: ο αρχικός αριθμός σειράς με την προσθήκη -RU, -RP ή -RM.
measured_at	string		Πότε μετρήθηκαν οι τιμές.
member_state	string		Κωδικός δύο γραμμάτων του κράτους μέλους όπου ελέγχθηκε η κατάσταση υγείας (άρθρο 73 παράγραφος 1 στοιχείο α)).
target_passport_id	integer		Υπάρχον μοντέλο δεύτερης ζωής αυτού του μοντέλου μπαταρίας, στο οποίο θα καταχωριστεί.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/passports/96/units/KES-00001/successor \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"stage": "repurposed", "values": {"remaining_capacity_ah": "82 Ah", "power_fade": "9%", "internal_resistance_increase": "15%", "expected_lifetime_cycles_remaining": "2000"}}'

Απάντηση

{
  "data": {
    "serial": "KES-00001-RP", "battery_status": "repurposed", "passport_id": 131,
    "lineage": { "originals": [{ "serial": "KES-00001", "passport_id": 96, "stage": "repurposed" }], "successors": [] }
  }
}

POST /passports/{id}/registry απαιτεί passports:write

Αποθηκεύει στο διαβατήριο την υποβολή στο Μητρώο DPP της ΕΕ και το αποτέλεσμά της: κατάσταση, αναγνωριστικό συσχέτισης, το αναγνωριστικό καταχώρισης που επιστρέφει το Μητρώο και προαιρετικό σύνδεσμο προς εφεδρικό αντίγραφο που φιλοξενεί πάροχος υπηρεσιών DPP. Η ίδια η καταχώριση γίνεται στο Μητρώο της Επιτροπής (διαδικτυακή φόρμα ή μεταφόρτωση αρχείου)· αυτό διατηρεί το αποτέλεσμα μαζί με το διαβατήριο. Το GET /passports/{id} επιστρέφει το ίδιο μπλοκ στο registry.

Παράμετρος	Τύπος	Περιγραφή
status	string	not_submitted, submitted, registered ή failed.
product_group	string	Ομάδα προϊόντων του μητρώου, για παράδειγμα batteries.
granularity	string	μοντέλο, παρτίδα ή τεμάχιο.
upi	string	Μοναδικό αναγνωριστικό προϊόντος ως https URL. Από προεπιλογή, το URL του δημόσιου διαβατηρίου.
correlation_id	string	Αναγνωριστικό συσχέτισης που αποδίδεται από το μητρώο κατά την υποβολή.
uri	string	Αναγνωριστικό εγγραφής που επέστρεψε το μητρώο.
backup_url	string	Σύνδεσμος https προς το αντίγραφο ασφαλείας που φιλοξενείται από πάροχο υπηρεσιών DPP.
submitted_at	date	Ημερομηνία υποβολής.
registered_at	date	Ημερομηνία εγγραφής.
error	string	Περιγραφή σφάλματος για αποτυχημένη υποβολή.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/passports/96/registry \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "registered",
    "correlation_id": "7f3a2c1e-0b4d-4f8e-9a6b-2d1c3e4f5a6b",
    "uri": "urn:eu:dpp:reg:00000001",
    "registered_at": "2027-02-18"
  }'

Απάντηση

{
  "message": "Registry details updated.",
  "passport": {
    "id": 96,
    "registry": {
      "status": "registered",
      "upi": "https://myproductpassport.co.uk/p/552fbb4e-5d9a-41da-9050-cc9005d8b66b",
      "correlation_id": "7f3a2c1e-0b4d-4f8e-9a6b-2d1c3e4f5a6b",
      "uri": "urn:eu:dpp:reg:00000001",
      "registered_at": "2027-02-18T00:00:00+00:00"
    }
  }
}

GET /passports/{id}/qr απαιτεί passports:read

Ο κωδικός QR του διαβατηρίου ως αρχείο: svg (προεπιλογή), png (με την επωνυμία, έτοιμο για εκτύπωση) ή pdf (φύλλο ετικετών).

Παράμετρος	Τύπος		Περιγραφή
format	string		svg \| png \| pdf

Αίτημα

curl "https://myproductpassport.eu/api/v1/passports/96/qr?format=png" \
  -H "Authorization: Bearer pk_your_key" -o passport-96.png

09 / Τελικά σημείαΣυμμόρφωση

GET /passports/{passportId}/compliance απαιτεί passports:read

Εκτελεί ζωντανό έλεγχο συμμόρφωσης ενός διαβατηρίου έναντι των υποχρεωτικών πεδίων του τομέα του και αναφέρει ακριβώς τι λείπει.

Αίτημα

curl https://myproductpassport.eu/api/v1/passports/96/compliance \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{
  "data": {
    "passport_id": 96,
    "product_name": "Alpine Merino Crew Sweater",
    "status": "compliant",
    "percentage": 100,
    "completed_fields": 12,
    "total_fields": 12,
    "missing_fields": []
  }
}

10 / Τελικά σημείαΤομείς

GET /sectors

Οι τομείς στους οποίους μπορεί να καταχωριστεί ένα προϊόν: οι τομείς συστήματος της πλατφόρμας συν όσοι έχουν οριστεί στον χώρο εργασίας σας. Χρησιμοποιήστε το id κατά τη δημιουργία προϊόντων και τα κλειδιά πεδίων κατά την εγγραφή πεδίων διαβατηρίου.

Αίτημα

curl https://myproductpassport.eu/api/v1/sectors \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{
  "data": [
    {
      "id": 4,
      "slug": "batteries",
      "name": "Batteries",
      "system": true,
      "regulations_finalised": true,
      "deadline": "2027-02-18",
      "deadline_label": "18 Feb 2027",
      "required_fields": ["battery_category", "battery_weight", "..."],
      "optional_fields": ["energy_round_trip_efficiency", "..."]
    }
  ]
}

11 / Τελικά σημείαΈγγραφα

GET /products/{productId}/documents απαιτεί products:read

Δηλώσεις συμμόρφωσης, εκθέσεις δοκιμών και πιστοποιητικά συνημμένα στο προϊόν. Ένα δημόσιο έγγραφο συνδέεται από κάθε δημοσιευμένο διαβατήριο του προϊόντος.

Αίτημα

curl https://myproductpassport.eu/api/v1/products/512/documents \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{
  "data": [
    {
      "id": 31,
      "product_id": 512,
      "filename": "declaration-of-conformity.pdf",
      "mime_type": "application/pdf",
      "file_size": 184322,
      "is_public": true,
      "processing_status": "completed",
      "public_url": "https://myproductpassport.co.uk/p/3f0c.../document/31",
      "created_at": "2026-09-22T10:12:00+00:00"
    }
  ]
}

POST /products/{productId}/documents απαιτεί products:write

Μεταφόρτωση multipart. PDF, Word, Excel, CSV, κείμενο, PNG και JPEG έως 10 MB, το πολύ 20 ανά προϊόν. Το κείμενο εξάγεται στο παρασκήνιο.

Παράμετρος	Τύπος		Περιγραφή
file	file	υποχρεωτικό	Το έγγραφο.
is_public	boolean		Εμφάνιση στο δημόσιο διαβατήριο (προεπιλογή false).

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/products/512/documents \
  -H "Authorization: Bearer pk_your_key" \
  -F "[email protected]" \
  -F "is_public=1"

PATCH /products/{productId}/documents/{id} απαιτεί products:write

Ενεργοποιεί ή απενεργοποιεί τη σύνδεση του εγγράφου από το δημόσιο διαβατήριο.

Παράμετρος	Τύπος		Περιγραφή
is_public	boolean	υποχρεωτικό

Αίτημα

curl -X PATCH https://myproductpassport.eu/api/v1/products/512/documents/31 \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"is_public": false}'

DELETE /products/{productId}/documents/{id} απαιτεί products:write

Αφαιρεί το αρχείο και τον σύνδεσμό του με το διαβατήριο.

Αίτημα

curl -X DELETE https://myproductpassport.eu/api/v1/products/512/documents/31 \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{ "message": "Document deleted." }

12 / Τελικά σημείαΕφοδιαστική αλυσίδα

GET /products/{productId}/supply-chain απαιτεί products:read

Τα βήματα που εμφανίζονται στο διαβατήριο του προϊόντος, με τη σειρά.

Αίτημα

curl https://myproductpassport.eu/api/v1/products/512/supply-chain \
  -H "Authorization: Bearer pk_your_key"

PUT /products/{productId}/supply-chain απαιτεί products:write

Αντικαθιστά όλα τα βήματα με τη λίστα που στέλνετε, με τη σειρά αποστολής. Στείλτε κενή λίστα για εκκαθάριση. Τύποι βημάτων: raw_material, processing, manufacturing, assembly, packaging, distribution.

Παράμετρος	Τύπος		Περιγραφή
steps	array	υποχρεωτικό	Έως 50 βήματα.
steps[].step_type	string	υποχρεωτικό
steps[].supplier_name	string	υποχρεωτικό
steps[].supplier_location	string
steps[].supplier_country	string		ISO 3166-1 alpha-2.
steps[].lat / lng	number
steps[].description	string
steps[].certifications	array
steps[].date	date

Αίτημα

curl -X PUT https://myproductpassport.eu/api/v1/products/512/supply-chain \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"steps": [{"step_type": "raw_material", "supplier_name": "Merino Growers Co-op", "supplier_country": "NZ", "certifications": ["RWS"]}, {"step_type": "manufacturing", "supplier_name": "Northloom Mill", "supplier_location": "Biella", "supplier_country": "IT"}]}'

13 / Τελικά σημείαΜεταφράσεις

GET /passports/{id}/translations απαιτεί passports:read

Κάθε μεταφρασμένη τιμή πεδίου ανά γλώσσα, με την πηγή της: auto (μηχανική, δημιουργείται κατά τη δημοσίευση) ή manual.

Αίτημα

curl https://myproductpassport.eu/api/v1/passports/96/translations \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{
  "data": {
    "passport_id": 96,
    "available_locales": ["bg", "cs", "da", "de", "..."],
    "translations": {
      "de": {"care_instructions": {"value": "Kalt waschen", "source": "manual"}}
    }
  }
}

PUT /passports/{id}/translations/{locale} απαιτεί passports:write

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

Παράμετρος	Τύπος		Περιγραφή
fields	object	υποχρεωτικό	field_key: μεταφρασμένη τιμή

Αίτημα

curl -X PUT https://myproductpassport.eu/api/v1/passports/96/translations/de \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"care_instructions": "Kalt waschen, nicht bleichen"}}'

Απάντηση

{ "message": "1 translation(s) written, 0 removed.", "locale": "de", "written": 1, "removed": 0 }

14 / Τελικά σημείαΑκεραιότητα και εξαγωγές

GET /passports/{id}/integrity απαιτεί passports:read

Κάθε δημοσιευμένη κατάσταση του διαβατηρίου ως εγγραφή συνδεδεμένη σε αλυσίδα κατακερματισμού και υπογεγραμμένη με Ed25519: αποτύπωμα (SHA-256), τιμή αλυσίδας και υπογραφή. Τα δημόσια κλειδιά βρίσκονται στο /.well-known/mpp-integrity-keys.json, ώστε οποιοσδήποτε να μπορεί να επαληθεύσει την αλυσίδα.

Αίτημα

curl https://myproductpassport.eu/api/v1/passports/96/integrity \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{ "data": { "state": "intact", "hash_algorithm": "SHA-256", "signature_algorithm": "Ed25519", "records": [ { "sequence": 1, "event": "published", "content_hash": "8f3a...", "chain_hash": "c21e...", "signature": "MEUC...", "key_id": "3fa9c21e0b7d4a11" } ], "problems": [] } }

GET /passports/{id}/integrity/{sequence} απαιτεί passports:read

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

Αίτημα

curl https://myproductpassport.eu/api/v1/passports/96/integrity/1 \
  -H "Authorization: Bearer pk_your_key"

GET /passports/{id}/epcis απαιτεί passports:read

Το διαβατήριο ως έγγραφο GS1 EPCIS 2.0 JSON-LD: η θέση του είδους σε λειτουργία (commissioning), κάθε βήμα της εφοδιαστικής αλυσίδας ως παρατήρηση, οι μεμονωμένες μπαταρίες και ένα διαβατήριο δεύτερης ζωής ως μετασχηματισμός. Τα αναγνωριστικά είναι URI GS1 Digital Link όταν το προϊόν διαθέτει GTIN.

Αίτημα

curl https://myproductpassport.eu/api/v1/passports/96/epcis \
  -H "Authorization: Bearer pk_your_key"

15 / Τελικά σημείαΑιτήματα προς προμηθευτές

POST /passports/{id}/supplier-requests απαιτεί passports:write

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

Παράμετρος	Τύπος		Περιγραφή
supplier_name	string	υποχρεωτικό
supplier_email	string	υποχρεωτικό
field_keys	array	υποχρεωτικό	Κλειδιά πεδίων από το πρότυπο του διαβατηρίου.
locale	string		Γλώσσα του email και της φόρμας, π.χ. de.
due_at	date		Προθεσμία απάντησης· 14 ημέρες αν παραλειφθεί.
message	string

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/passports/96/supplier-requests \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"supplier_name": "Mei Chen", "supplier_email": "[email protected]", "field_keys": ["recycled_content_cobalt", "carbon_footprint"], "locale": "de"}'

GET /passports/{id}/supplier-requests απαιτεί passports:read

Κάθε αίτημα για το διαβατήριο με την κατάστασή του.

Αίτημα

curl https://myproductpassport.eu/api/v1/passports/96/supplier-requests \
  -H "Authorization: Bearer pk_your_key"

GET /supplier-requests/{id} απαιτεί passports:read

Ένα αίτημα με τις απαντήσεις του προμηθευτή, τη σημείωση και τα ονόματα των συνημμένων αρχείων.

Αίτημα

curl https://myproductpassport.eu/api/v1/supplier-requests/12 \
  -H "Authorization: Bearer pk_your_key"

16 / Τελικά σημείαΜετά την πώληση

POST /passports/{id}/items απαιτεί items:write

Δώστε στα τεμάχια ενός προϊόντος (οποιουδήποτε τομέα εκτός από τις μπαταρίες, που χρησιμοποιούν το /units) τον δικό τους σειριακό αριθμό: το καθένα αποκτά δική του διεύθυνση και κωδικό QR, κρυφό κωδικό γνησιότητας για την ετικέτα, και ο ιδιοκτήτης μπορεί να το καταχωρίσει. Στείλτε έως 10.000 τεμάχια ή ένα εύρος. Με GTIN η διεύθυνση είναι GS1 Digital Link /01/{gtin}/21/{serial}.

Παράμετρος	Τύπος		Περιγραφή
items[].serial	string	υποχρεωτικό	Έως 20 γράμματα, ψηφία, τελείες, παύλες ή κάτω παύλες.
items[].batch	string		Παρτίδα, έως 20 χαρακτήρες.
items[].manufactured_on	string		Ημερομηνία παραγωγής, ΕΕΕΕ-ΜΜ-ΗΗ.
range	object		Αντί για items: prefix, start, count, digits και batch, για παράδειγμα SN-00001 έως SN-00500.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/passports/96/items \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"range": {"prefix": "SN-", "start": 1, "count": 500, "digits": 5, "batch": "B2026-10"}}'

Απάντηση

{ "created": 500, "updated": 0, "skipped": 0, "over_limit": 0, "errors": [] }

GET /passports/{id}/items/{serial} απαιτεί items:read

Το τεμάχιο με τη διεύθυνσή του, την κατάσταση, αν είναι καταχωρισμένο και έως πότε ισχύει η εγγύηση, τους ελέγχους γνησιότητας και το ιστορικό του. Ένα κλειδί με items:write λαμβάνει επίσης τον κρυφό κωδικό για εκτύπωση. Το GET /passports/{id}/items τα απαριθμεί (φίλτρα status και batch, per_page έως 500).

Αίτημα

curl https://myproductpassport.eu/api/v1/passports/96/items/SN-00001 \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{
  "data": { "serial": "SN-00001", "status": "active", "url": "https://myproductpassport.co.uk/01/05012345678900/21/SN-00001", "registered": true, "warranty_ends_on": "2028-10-02", "events": [ { "type": "registered", "country": "IE", "at": "2026-10-03T09:12:00+00:00" } ] }
}

PATCH /passports/{id}/items/{serial} απαιτεί items:write

Ορίστε την κατάσταση σε stolen ή recalled και η σελίδα του προειδοποιεί όποιον το σαρώνει, με το status_note σας· ένα κλεμμένο τεμάχιο δεν μπορεί να καταχωριστεί. Το retired απενεργοποιεί τη σελίδα. Μπορούν επίσης να αλλάξουν τα batch και manufactured_on.

Παράμετρος	Τύπος		Περιγραφή
status	string		active, stolen, recalled ή retired.
status_note	string		Εμφανίζεται στη σελίδα του τεμαχίου, έως 500 χαρακτήρες.

Αίτημα

curl -X PATCH https://myproductpassport.eu/api/v1/passports/96/items/SN-00001 \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "stolen", "status_note": "Reported stolen on 2 October 2026."}'

GET /owner-registrations απαιτεί aftersales:read

Τα άτομα που καταχώρισαν τα προϊόντα σας: όνομα, email, χώρα, ημερομηνία αγοράς, έμπορος, ημερομηνίες εγγύησης και αν συναίνεσαν σε νέα και προσφορές (το marketing_consent=1 απαριθμεί μόνο αυτούς). Από προεπιλογή οι ενεργές καταχωρίσεις· status=pending, transferred ή ended για τις υπόλοιπες· since= για αλλαγές μετά από μια ημερομηνία.

Αίτημα

curl "https://myproductpassport.eu/api/v1/owner-registrations?marketing_consent=1&since=2026-10-01" \
  -H "Authorization: Bearer pk_your_key"

GET /service-requests απαιτεί aftersales:read

Επισκευές, αξιώσεις εγγύησης, επιστροφές, ανταλλακτικά και ερωτήσεις από τα διαβατήριά σας, τα νεότερα πρώτα, με φίλτρα status και type. Το GET /service-requests/{reference} προσθέτει τη συνομιλία.

Αίτημα

curl "https://myproductpassport.eu/api/v1/service-requests?status=new" \
  -H "Authorization: Bearer pk_your_key"

POST /service-requests/{reference}/replies απαιτεί aftersales:write

Η απάντησή σας αποστέλλεται στον πελάτη με email με σύνδεσμο προς τη σελίδα του αιτήματός του, στη γλώσσα του. Το internal: true προσθέτει σημείωση που βλέπει μόνο η ομάδα σας. Το PATCH /service-requests/{reference} με status το προωθεί (ο πελάτης ειδοποιείται όταν είναι σε επεξεργασία, επιλυμένο ή κλειστό).

Παράμετρος	Τύπος		Περιγραφή
body	string	υποχρεωτικό	Η απάντηση, έως 5.000 χαρακτήρες.
internal	boolean		Σημείωση για την ομάδα σας αντί για απάντηση.
status	string		new, in_progress, waiting, resolved ή closed.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/service-requests/SR-7K3F9Q/replies \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"body": "A new lid is on its way today.", "status": "waiting"}'

17 / Τελικά σημείαΜαζικές επεξεργασίες και εικόνες

PATCH /products/bulk-fields απαιτεί products:write

Ορίζει ένα στοιχείο προϊόντος ή ένα πεδίο διαβατηρίου σε έως 5.000 προϊόντα. Το mode είναι set, fill (μόνο όπου είναι κενό) ή clear. Έως 100 προϊόντα ενημερώνονται μέσα στο ίδιο το αίτημα· τα μεγαλύτερα σύνολα μπαίνουν σε ουρά (202).

Παράμετρος	Τύπος		Περιγραφή
product_ids	array	υποχρεωτικό
target	string	υποχρεωτικό	product \| field
key	string	υποχρεωτικό
value	string
mode	string		set \| fill \| clear

Αίτημα

curl -X PATCH https://myproductpassport.eu/api/v1/products/bulk-fields \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"product_ids": [12, 13, 14], "target": "field", "key": "warranty_period", "value": "10 years", "mode": "fill"}'

Απάντηση

{ "data": { "changed": 2, "skipped": 1, "errors": [] } }

POST /products/{id}/images απαιτεί products:write

Μεταφόρτωση multipart αρχείου JPG, PNG ή WebP (έως 15MB, 8 ανά προϊόν). Η πρώτη εικόνα είναι η εικόνα εξωφύλλου στο δημόσιο διαβατήριο.

Παράμετρος	Τύπος		Περιγραφή
image	file	υποχρεωτικό
alt	string		Περιγραφή της εικόνας.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/products/12/images \
  -H "Authorization: Bearer pk_your_key" \
  -F [email protected] -F alt="Front of the battery"

PUT /products/{id}/images/order απαιτεί products:write

Δώστε τα image_ids με τη σειρά που επιθυμείτε· η πρώτη εικόνα γίνεται εικόνα εξωφύλλου.

Παράμετρος	Τύπος		Περιγραφή
image_ids	array	υποχρεωτικό

Αίτημα

curl -X PUT https://myproductpassport.eu/api/v1/products/12/images/order \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"image_ids": [31, 30]}'

DELETE /products/{id}/images/{imageId} απαιτεί products:write

Αφαιρεί την εικόνα και το αρχείο της.

Αίτημα

curl -X DELETE https://myproductpassport.eu/api/v1/products/12/images/31 \
  -H "Authorization: Bearer pk_your_key"

18 / Τελικά σημείαWebhooks

GET /webhooks απαιτεί webhooks:manage

Τα endpoints που έχουν καταχωριστεί για τον χώρο εργασίας σας. Τα μυστικά δεν περιλαμβάνονται εδώ· ανακτήστε ένα endpoint για να δείτε το μυστικό του.

Αίτημα

curl https://myproductpassport.eu/api/v1/webhooks \
  -H "Authorization: Bearer pk_your_key"

POST /webhooks απαιτεί webhooks:manage

Καταχωρίζει δημόσιο URL HTTPS για ένα ή περισσότερα συμβάντα. Η απάντηση περιλαμβάνει το μυστικό υπογραφής. Ιδιωτικοί ή εσωτερικοί διακομιστές απορρίπτονται.

Παράμετρος	Τύπος		Περιγραφή
url	string	υποχρεωτικό
events	array	υποχρεωτικό	Οποιοδήποτε από τα παρακάτω συμβάντα.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/webhooks \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://erp.acme.example/mpp", "events": ["passport.published", "product.updated"]}'

Απάντηση

{
  "data": {
    "id": 3,
    "url": "https://erp.acme.example/mpp",
    "events": ["passport.published", "product.updated"],
    "is_active": true,
    "failure_count": 0,
    "secret": "9f1c...64 hex characters...",
    "created_at": "2026-09-22T10:12:00+00:00"
  }
}

GET /webhooks/{id} απαιτεί webhooks:manage

Αίτημα

curl https://myproductpassport.eu/api/v1/webhooks/3 \
  -H "Authorization: Bearer pk_your_key"

PUT /webhooks/{id} απαιτεί webhooks:manage

Αλλάξτε το URL ή τα συμβάντα, ή θέστε σε παύση και επαναφέρετε το τελικό σημείο. Η επαναφορά μηδενίζει τον μετρητή αποτυχιών· ένα τελικό σημείο τίθεται αυτόματα σε παύση μετά από 10 διαδοχικές αποτυχημένες παραδόσεις.

Παράμετρος	Τύπος		Περιγραφή
url	string
events	array
is_active	boolean

Αίτημα

curl -X PUT https://myproductpassport.eu/api/v1/webhooks/3 \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"is_active": true}'

POST /webhooks/{id}/test απαιτεί webhooks:manage

Βάζει σε ουρά μια παράδοση webhook.test ώστε να ελέγξετε τον δέκτη και τον κώδικα υπογραφής.

Αίτημα

curl -X POST https://myproductpassport.eu/api/v1/webhooks/3/test \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{ "message": "Test delivery queued." }

GET /webhooks/{id}/deliveries απαιτεί webhooks:manage

Πρόσφατες παραδόσεις, νεότερες πρώτα, με την κατάσταση HTTP που επέστρεψε το τελικό σας σημείο και τους πρώτους 500 χαρακτήρες της απάντησης.

Παράμετρος	Τύπος		Περιγραφή
per_page	integer		Έως 100.

Αίτημα

curl https://myproductpassport.eu/api/v1/webhooks/3/deliveries \
  -H "Authorization: Bearer pk_your_key"

DELETE /webhooks/{id} απαιτεί webhooks:manage

Αίτημα

curl -X DELETE https://myproductpassport.eu/api/v1/webhooks/3 \
  -H "Authorization: Bearer pk_your_key"

Απάντηση

{ "message": "Webhook endpoint deleted." }

19 / ΣυμβάνταWebhooks

Αντί για περιοδικά ερωτήματα, καταχωρίστε ένα τελικό σημείο webhook στην εφαρμογή (σελίδα Webhooks, διαθέσιμη από το πρόγραμμα Starter και πάνω) και το MyProductPassport θα στέλνει JSON με POST στο URL σας καθώς συμβαίνουν τα γεγονότα:

Συμβάν	Ενεργοποιείται όταν
product.created	Δημιουργείται προϊόν (εφαρμογή, API ή εισαγωγή CSV)
product.updated	Ενημερώνεται προϊόν
product.deleted	Διαγράφεται προϊόν
passport.created	Ένα διαβατήριο δημιουργείται
passport.published	Ένα διαβατήριο γίνεται ενεργό
passport.archived	Ένα διαβατήριο αρχειοθετείται
supplier_request.submitted	Ένας προμηθευτής στέλνει τις πληροφορίες που ζητήσατε
owner.registered	Ένας ιδιοκτήτης επιβεβαιώνει την καταχώρισή του
owner.transferred	Ένα τεμάχιο περνά σε νέο καταχωρισμένο ιδιοκτήτη
service_request.created	Ένας πελάτης στέλνει αίτημα εξυπηρέτησης από ένα διαβατήριο
service_request.updated	Ένα αίτημα εξυπηρέτησης λαμβάνει απάντηση ή νέα κατάσταση
item.status_changed	Ένα τεμάχιο επισημαίνεται ως κλεμμένο, ανακληθέν ή εκτός χρήσης, ή η επισήμανση αφαιρείται
item.verification_failed	Μια ανάγνωση ασφαλούς ετικέτας αποτυγχάνει, οι λάθος κωδικοί συσσωρεύονται ή ένας σειριακός αριθμός εμφανίζεται σε πάρα πολλά σημεία
webhook.test	Στέλνετε μια δοκιμαστική παράδοση από την εφαρμογή

Κάθε παράδοση είναι ένας φάκελος JSON: ένα αναγνωριστικό παράδοσης (το ίδιο αναγνωριστικό αποστέλλεται ξανά στις επαναλήψεις, ώστε να αφαιρείτε διπλότυπα), το συμβάν, ο αριθμός προσπάθειας, μια χρονοσφραγίδα και τα δεδομένα του συμβάντος. Τα συμβάντα διαβατηρίων περιέχουν το uuid και το δημόσιο URL του διαβατηρίου, οπότε σπάνια χρειάζεστε δεύτερο αίτημα:

Σώμα παράδοσης

{
  "id": 8123,
  "event": "passport.published",
  "attempt": 1,
  "created_at": "2026-09-22T10:12:00+00:00",
  "data": {
    "passport_id": 96,
    "uuid": "3f0c8f1e-...",
    "version": 2,
    "status": "published",
    "public_url": "https://myproductpassport.co.uk/p/3f0c8f1e-...",
    "product_id": 512,
    "product": {"id": 512, "name": "Alpine Merino Crew Sweater", "sku": "NL-AMC-001", "gtin": "5012345678900"}
  }
}

Οι κεφαλίδες περιέχουν το όνομα του συμβάντος, το αναγνωριστικό παράδοσης, μια χρονοσφραγίδα Unix και μια υπογραφή HMAC του ακατέργαστου σώματος, ώστε να επαληθεύετε ότι προέρχεται από εμάς και να απορρίπτετε επαναλήψεις:

Κεφαλίδες παράδοσης

Content-Type: application/json
User-Agent: MyProductPassport-Webhooks/1.0
X-MPP-Event: passport.published
X-MPP-Delivery: 8123
X-MPP-Timestamp: 1790084320
X-MPP-Signature: sha256=<hex hmac of the raw body, keyed with your endpoint secret>

Απαντήστε με οποιονδήποτε κωδικό 2xx μέσα σε 10 δευτερόλεπτα. Οτιδήποτε άλλο επαναλαμβάνεται πέντε φορές σε περίπου 90 λεπτά (30 s, 1 min, 5 min, 15 min, 1 h)· μετά από 10 διαδοχικές αποτυχίες το τελικό σημείο τίθεται σε παύση μέχρι να το ενεργοποιήσετε ξανά.

Επαλήθευση (PHP)

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $endpointSecret);
abort_unless(hash_equals($expected, $request->header('X-MPP-Signature')), 401);

Cookie	Σκοπός	Λήξη
myproductpassport-session	Σας κρατά συνδεδεμένους και τον ιστότοπο ασφαλή	2 ώρες
XSRF-TOKEN	Προστατεύει τις φόρμες από την πλαστογράφηση αιτημάτων μεταξύ ιστοτόπων	2 ώρες
cookie_consent	Θυμάται την επιλογή σας για τα cookies	12 μήνες
locale_suggested countdown_dismissed exit_intent_dismissed	Θυμάται ότι κλείσατε ένα μήνυμα, ώστε να μην εμφανιστεί ξανά	Έως 30 ημέρες

Cookie	Σκοπός	Λήξη
_ga, _ga_*	Google Analytics: μετρά τις επισκέψεις και δείχνει πώς χρησιμοποιείται ο ιστότοπος	2 χρόνια
_gcl_au	Google Ads: μετρά ποιες διαφημίσεις οδηγούν σε εγγραφές	90 ημέρες
mpp_ref	Θυμάται τον συνεργάτη του οποίου τον σύνδεσμο ακολουθήσατε, ώστε να του πιστωθεί αν εγγραφείτε αργότερα	90 ημέρες

Αναφορά API

01 / Πρώτα βήματαΈλεγχος ταυτότητας

02 / Πρώτα βήματαΌρια αιτημάτων

03 / Πρώτα βήματαΣφάλματα

04 / Πρώτα βήματαΣελιδοποίηση

05 / Πρώτα βήματαΣύνδεση βοηθού ΤΝ (MCP)

06 / Τελικά σημείαΛογαριασμός

07 / Τελικά σημείαΠροϊόντα

08 / Τελικά σημείαΔιαβατήρια

09 / Τελικά σημείαΣυμμόρφωση

10 / Τελικά σημείαΤομείς

11 / Τελικά σημείαΈγγραφα

12 / Τελικά σημείαΕφοδιαστική αλυσίδα

13 / Τελικά σημείαΜεταφράσεις

14 / Τελικά σημείαΑκεραιότητα και εξαγωγές

15 / Τελικά σημείαΑιτήματα προς προμηθευτές

16 / Τελικά σημείαΜετά την πώληση

17 / Τελικά σημείαΜαζικές επεξεργασίες και εικόνες

18 / Τελικά σημείαWebhooks

19 / ΣυμβάνταWebhooks

Πριν φύγετε…

Είστε στη λίστα!