Appearance
PCT Data Contract v2: Changelog vs v1
What changed in the PCT Data Contract v2 compared to the PCT Data Contract v1.
Breaking and semantic changes
- Record status semantics (NORMAL, BLOCKED, HIDDEN and the ProductVariants-only richer product statuses) are now documented in the shared Record Status Values section of both contract versions. status must never be empty; records delivered without a status are treated as NORMAL.
- Brands (breaking): narrowed to unique_id, resource_id, display_id, name, description, status, created_at, updated_at. name_1 is renamed to name; all removed columns were NULL placeholders in v1, so no data is lost.
- Customers (breaking): the denormalized industry_, sales_area_, branch_* and customer_class_* columns are removed and replaced by the CommercialScopes / CustomerToCommercialScopes model.
- The ERP-native erp_header_status / erp_line_status display fields on transaction lines are supported contract columns, alongside erp_header_status_id/_name and erp_line_status_id/_name. A delivery that fills only the native display field conforms to the contract.
- Not in this contract: quote validity / expiry dates beyond QuoteLines.quote_valid_from_date; quantity-unit payload columns on SalesDocumentHeaderRelations / SalesDocumentLineRelations; payment terms / tax number fields on CustomerEntities; Customers.last_order_date; created-by audit fields; a generic reason field on transaction tables; delivery information beyond the shipping type (to be covered by the Delivery & Shipping RFC). To deliver one of these, raise it with Plato as a new data request.
- CommercialScopeToCommercialScopes, CustomerGroupsToCustomerGroups, SalesRepToCommercialScopes and ClerkToCommercialScopes (new): bridges that nest commercial scopes (e.g. branch to region) and customer groups (e.g. buying group to purchasing association), and assign sales reps and clerks to commercial scopes. They are link tables rather than a parent column on the entity, so a record can have several parents or scopes. In v1 there was no way to deliver a scope or customer-group hierarchy, or which sales reps and clerks belong to a scope. All four are optional.
- ProductVariantToProductVariantGroupings (new): bridge that assigns product variants to product variant groupings, many-to-many (a variant can belong to several groupings). In v1 there was no way to deliver which variants belong to a ProductVariantGrouping.
- SalesDocumentTypes (breaking): sales_document_type_family now allows the eight Plato document families QUOTE, ORDER, INVOICE, CREDIT_MEMO, RETURN, CONTRACT, CREDIT_MEMO_REQUEST and DEBIT_MEMO_REQUEST, so the new v2 contract, return and credit / debit memo request documents can be classified. CREDITMEMO is renamed to CREDIT_MEMO.
- price_scale_factor (all line tables and ProductVariants): defaults to 1 when not provided, and must be greater than 0 when sent. 0 is invalid; send 1 or leave the column empty when the ERP has no pricing unit. Plato reads a 0 as 1, which v1 only documented on ProductVariants.
- Delivery and success file (breaking, applies to v1 as well): a delivery is one export session of the data provider, with all the tenants and operations that export sends. It ends with exactly one success file at data/success, uploaded after every other upload of the session has finished. This replaces one success file per tenant and operation at data/{tenant}/success/{operation}.
- ShippingTypes (new) and shipping_type_unique_id on OrderLines, QuoteLines, InvoiceLines and CreditMemoLines (new): shipping types (e.g. DHL Paket, Abholung) with the carrier that ships them (dispatcher), referenced from the document lines like the other header values. In v1 there was no way to deliver how a document ships. Both are optional.
Added entities
- ClerkToCommercialScopes
- CommercialScopes
- CommercialScopeToCommercialScopes
- ContractLines
- CreditMemoRequestLines
- CustomerGroups
- CustomerGroupsToCustomerGroups
- CustomerToCommercialScopes
- CustomerToCustomerGroups
- DebitMemoRequestLines
- PartsListLines
- ProductVariantToProductVariantGroupings
- ProductVariantToUnits
- ProductVariantUnitConversion
- Projects
- ReturnLines
- SalesRepToCommercialScopes
- ShippingTypes
- StorageGroups
- UnitConversion
- Units
Column changes
| Entity | Added columns | Removed columns |
|---|---|---|
| Brands | description, name, position | address_line_1, address_line_2, address_line_3, city, country, country_code, email, fax_number, legal_entity_name, mobile_number, name_1, name_2, name_3, post_box, state_or_province, telephone_number, zip_code, zip_code_post_box |
| Categories | position | — |
| CategoriesToCategories | position | — |
| Clerks | position, title | — |
| CreditMemoLines | erp_header_status_id, erp_header_status_name, erp_line_status_id, erp_line_status_name, header_line_unique_id, package_unit_unique_id, project_unique_id, shipping_type_unique_id, source_channel_name, source_channel_unique_id, unit_sales_unique_id, unit_storage_unique_id | — |
| Currencies | position | — |
| CustomerContacts | birthday, position, title | — |
| CustomerEntities | delivery_address_comment, is_late_delivery_possible, is_parcel_delivery_possible, position | — |
| CustomerEntityRoleAssignments | position | — |
| Customers | first_order_date, position | branch_id, branch_name, customer_class_id, customer_class_name, industry_id, industry_name, sales_area_id, sales_area_name |
| CustomerToSalesReps | position | — |
| EntityAttributeValues | position | — |
| InvoiceLines | erp_header_status_id, erp_header_status_name, erp_line_status_id, erp_line_status_name, header_line_unique_id, package_unit_unique_id, project_unique_id, shipping_type_unique_id, source_channel_name, source_channel_unique_id, unit_sales_unique_id, unit_storage_unique_id | — |
| Manufacturers | position | — |
| OrderLines | erp_header_status_id, erp_header_status_name, erp_line_status_id, erp_line_status_name, header_line_unique_id, package_unit_unique_id, project_unique_id, shipping_type_unique_id, source_channel_name, source_channel_unique_id, unit_sales_unique_id, unit_storage_unique_id | — |
| ProductsToCategories | position | — |
| ProductVariantAndProductVariantGroupAttributes | position | — |
| ProductVariantAttributeValues | position | — |
| ProductVariantGroupAttributeValues | position | — |
| ProductVariantGrouping | position | — |
| ProductVariantRelations | position | — |
| ProductVariants | package_unit_unique_id, position, unit_sales_unique_id, unit_storage_unique_id | — |
| ProductVariantToSuppliers | position | — |
| QuoteLines | alternative_to_line, erp_header_status_id, erp_header_status_name, erp_line_status_id, erp_line_status_name, header_line_unique_id, package_unit_unique_id, project_unique_id, quote_valid_from_date, shipping_type_unique_id, source_channel_name, source_channel_unique_id, unit_sales_unique_id, unit_storage_unique_id | — |
| SalesDocumentTypes | position | — |
| SalesReps | position, title | — |
| StorageLocations | country, position, storage_group_unique_id | — |
| Suppliers | position | — |