Skip to content
PPWR Link
Book a demo
PLEN
☰
HomeAPI for integration teams
API for integration teams

PPWR API for packaging, documents and reporting

Connect an online store, ERP, WMS or custom application to PPWR Link through its public REST API. Browse Swagger documentation and OpenAPI schemas without signing in. Organisation data is accessed with a scoped API key.

Open API documentation Book a demo Create an account
API for integration teams

What can you connect?

One contract describes application data and operations. Integrations follow organisation permissions and the same validation rules as the dashboard.

Catalogue and packaging sets

Retrieve packaging, identifiers, specifications and sets needed for order fulfilment.

Documents and evidence

Upload files and work with versions, statuses and links to packaging records.

Usage and reporting

Record material movements and prepare data for organisation reports.

01

A catalogue for stores, ERP and WMS

An integration should refer to the same packaging as a dashboard user. Public identifiers and internal codes connect packaging records with warehouse SKUs. Material, mass, dimensions and usage units give quantities their meaning. Catalogue access can support a store dashboard, a packing application or a purchasing system.

  • Packaging and individual components
  • Sets, units and conversions
  • Dictionaries shared with the application
Explore packaging record structure
02

From catalogue retrieval to a usage event

A typical workflow selects the organisation, retrieves packaging or a set and records actual consumption against an order reference. Integrators should handle split shipments and distinguish material reservations from use. After a network error, do not blindly create a new stock movement: operations documented in the contract use an idempotency key to support safe retries of the same request.

  • Stable order and parcel references
  • Quantity and unit validation
  • Retries and operation results
Follow a packing example
03

OpenAPI and Swagger for implementation

Swagger documentation is public and available below without an account or sign-in. Browse operations, data schemas, permissions and error responses. Download the OpenAPI 3.1 contract in Polish or English to build your integration client. Once you have an API key, send authorised requests without a panel session.

  • Public Swagger and OpenAPI in Polish and English
  • Request, response, filter and pagination schemas
  • Authorization: Bearer authentication and revision checks
04

Keep access to data under control

An API key belongs to a user and an organisation. Configure its scope, expiry or unlimited validity and permitted IP addresses. Revoke a key to stop a connection. Keep the secret on the integration server rather than in storefront code visible to customers.

  • A separate key for each connection
  • Read and write scopes matched to the workflow
  • Handling revoked access, rate limits and validation errors
REST API · OpenAPI 3.1

Swagger documentation

Public documentation for integrators — browse operations and schemas or download the contract without signing in. API requests require a Bearer key; a panel session is not needed.

Download OpenAPI

1. Create an integration key

An authorised person creates a key under Administration → Organizations → API keys. Select the organisation, scopes, expiry and optional IP restrictions. Store the key on your integration server.

2. Retrieve your organisation

Send GET /api/v1/organizations with the Authorization: Bearer header. Use the returned organisation UUID as organizationId in subsequent catalogue, packaging set and other resource requests.

3. Connect your workflows

Select an operation below and check its required scopes, fields and responses. Handle pagination, errors and rate limits. Retry writes requiring Idempotency-Key with the same key and request body.

Your first API request

curl 'https://ppwrlink.pl/api/v1/organizations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Locale: en'

Integrator guide — choose your workflow

Paths below are relative to /api/v1/organizations/{organizationId}, unless stated otherwise. Each Swagger operation lists its exact fields and permissions.

Download the integration guide

Order packing and inventory

Catalogue + available stock → set configuration → reservation → consume or release. Alternatively consume a set without a reservation or submit explicit packing-consumptions lines. Choose one path per parcel.

  1. GET /catalog-items
  2. GET /catalog-items/{catalogItemId}/inventory
  3. GET /packaging-systems/{recordId}/configuration
  4. POST /packaging-systems/{recordId}/reservations
  5. POST /packing-reservations/{recordId}/consume
  6. GET /packaging-systems/{systemId}/usages
Files, evidence and links

Upload → version processing state → document review → analysis/proposals → fact decision → evidence linkage. Documents, versions and facts have distinct IDs/statuses.

  1. POST /documents
  2. GET /document-versions/{recordId}
  3. POST /document-versions/{recordId}/decision
  4. POST /document-versions/{recordId}/analyze
  5. GET /evidence-proposals?item={catalogItemId}
  6. POST /evidence-proposals/{proposalId}/decision
Imports and templates

Retrieve an available template → upload → wait for preview → inspect rows → apply → read status/errors. Upload alone does not commit changes.

  1. POST /imports
  2. GET /imports/{recordId}
  3. GET /imports/{importId}/rows
  4. POST /imports/{recordId}/apply
  5. GET /imports/{recordId}/result.csv
Passports and recipient access

Data/evidence → draft → publish → recipient grant. New versions need separate access. Subscriptions/updates belong to the key’s user; following is not data adoption.

  1. POST /passports
  2. POST /passports/{recordId}/publish
  3. POST /passports/{recordId}/shares
  4. GET /sharing-grants
  5. POST /sharing-grants/{recordId}/revoke
Reports, EPR, BDO and recycled content

Catalogue/assessment/flow exports are queued. EPR/waste: header → lines → review → export. BDO: sources → classification → snapshot → export. None automatically files a declaration with an authority.

  1. POST /reports
  2. GET /reports/{recordId}
  3. GET /reports/{recordId}/download
Factors and material carbon footprint

Read sources → prepare factors → select item/set and optional historical basis → calculate → read snapshot. Results do not automatically cover the entire life cycle.

  1. GET /carbon-factors/reference
  2. POST /carbon-factors
  3. POST /carbon-calculations
  4. GET /carbon-calculations/{recordId}
Packaging catalogue and structure

Order: partners and optional folders/families → catalogue → components and markets. Data history later identifies operation inputs.

  1. GET /dictionaries
  2. POST /parties
  3. POST /catalog-items
  4. POST /catalog-items/{catalogItemId}/components
  5. PUT /catalog-items/{catalogItemId}/markets
  6. GET /catalog-items/{catalogItemId}/data-versions
Physical movements and reporting flows

supply-events tracks events/balance; flows represents reporting data. A movement can already generate a flow: do not submit both for the same activity.

  1. POST /catalog-items/{catalogItemId}/supply-events
  2. GET /catalog-items/{catalogItemId}/supply-summary
  3. GET /catalog-items/{catalogItemId}/inventory
  4. GET /flows
Supplier collaboration and gaps

Create request → inspect lines → send email → receive files → review responses. Suppliers use a public link; integrators use an organisation key.

  1. GET /issues
  2. POST /supplier-requests
  3. GET /supplier-requests/{requestId}/lines
  4. POST /supplier-requests/{recordId}/send
  5. POST /supplier-requests/{recordId}/lines/{lineId}/review
PPWR assessments and technical evidence

Establish packaging, market and role; prepare reviewed sources. Create registers relevant to the use case. Recording, review and rule results are separate stages. A dossier precedes its EU declaration.

  1. GET /catalog-items/{catalogItemId}/markets
  2. POST /assessments
  3. GET /assessments/{recordId}
  4. POST /assessments/{recordId}/review
  5. GET /catalog-items/{catalogItemId}/ppwr-summary
Reuse systems and returnable units

Circulation system → evidence/market confirmations → units → circulation events/review → aggregates and periodic targets. A circulation system is not a packing recipe.

  1. POST /ppwr/reuse-systems
  2. POST /catalog-items/{catalogItemId}/ppwr/reuse-units
  3. GET /ppwr/reuse-statistics
Deposits, hospitality and information

Specialised documentary registers. Deposit records describe packaging/membership without handling money; hospitality/end-user information records store assessments/evidence.

  1. POST /ppwr/deposit-schemes
  2. GET /ppwr/deposit-schemes/{recordId}
  3. POST /ppwr/deposit-schemes/{recordId}/review
Cases, submissions and audit

Register request/case → add responses/events and delivery evidence → review where exposed. External submissions document actions performed outside the application.

  1. POST /ppwr/authority-requests
  2. GET /ppwr/authority-requests/{recordId}
  3. GET /audit-log
Dossier and EU declaration

A dossier organises packaging technical evidence. A reviewed dossier can support an EU declaration; PDF generation is separate. EU declarations linked to the item’s dossier, contents, signatory and evidence. Creating a record does not sign for the manufacturer.

  1. POST /catalog-items/{catalogItemId}/ppwr/conformity-dossiers
  2. POST /catalog-items/{catalogItemId}/ppwr/conformity-dossiers/{recordId}/review
  3. POST /catalog-items/{catalogItemId}/ppwr/eu-declarations
  4. POST /catalog-items/{catalogItemId}/ppwr/eu-declarations/{recordId}/review
  5. POST /catalog-items/{catalogItemId}/generated-documents
Annual EPR report

Annual EPR reports with lines and review. Export uses the recorded result; it does not file into a national portal.

  1. POST /ppwr/epr-reports
  2. POST /ppwr/epr-reports/{parentId}/lines
  3. GET /ppwr/epr-reports/{parentId}/lines
  4. POST /ppwr/epr-reports/{recordId}/review
  5. GET /ppwr/epr-reports/{recordId}/export
BDO source data and export

BDO packaging report preparation: sources, classification, snapshot and export. Does not automatically file the annual BDO report or pay fees.

  1. GET /bdo-reports/sources?year=2025
  2. POST /bdo-reports/classifications
  3. POST /bdo-reports
  4. GET /bdo-reports/{recordId}
  5. GET /bdo-reports/{recordId}/download?format=xlsx
Receiving webhooks

An authorised user configures the HTTPS endpoint, events and signing secret under Administration → Integrations. Verify X-PPWR-Signature as t=TIMESTAMP,v1=HEX: HMAC-SHA256 over timestamp + dot + raw body, using the complete whsec_… secret without decoding. Compare in constant time and allow at most 300 seconds of clock skew. Durably deduplicate on body event id, validate schema_version and organization_id, and return 2xx only after enqueueing durably. Ordering is not guaranteed. Retries keep event id/body but use fresh signatures. Fetch changed resource state through the API; events do not carry complete document contents. See the contract’s Webhooks section for payload schema and event types.

To send a request, select Authorize and enter your API key. Try it out uses real organisation data — write operations make changes. The key is not retained after a page refresh.

Questions and answers

Good to know before you start

Answers to questions about everyday work with the platform.

Is API documentation public?

Yes. Swagger and the OpenAPI 3.1 contract are available on this page without signing in. You can also open ppwrlink.pl/api/documentation or download ppwrlink.pl/api/openapi.json. Browsing requires no key; reading or writing organisation data requires a valid API key and appropriate permissions.

Can I connect custom software?

Yes. A custom application can use documented REST operations with network access, a valid key and the required permissions.

Does the API automatically approve packaging compliance?

The API exposes data and assessment workflows. Saving information or uploading a document does not replace required evidence or an authorised review.

Does an integration need a PPWR Link panel session?

No. External systems authenticate requests through the Authorization: Bearer header using a key created by an authorised person in administration. Keys have scopes, an expiry policy and optional IP restrictions. Integrations do not use the user’s password or browser session.

Explore more

Data flow Documents and AI analysis Packaging for e-commerce Plugins and store platforms
Let’s talk about your business

Plan the connection to your system

Describe the source system and the information to exchange. We will identify API operations and how to map packaging codes and orders.

  1. 1We will learn how your business works.
  2. 2We will demonstrate relevant features with a practical example.
  3. 3We will discuss data import and implementation scope.
Prefer to contact us directly? kontakt@ppwrlink.pl +48 661 552 272

Fields marked * are required.