zippendo 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d7f234b7677274f2f26670fd5739a7eac9ca5c5120aebc415ec52fecbe2f1f2
-  data.tar.gz: db9c126e99ac7c9584d612e68ee03a15f6910e0a1c160e3bf776a1fda97e9a3b
+  metadata.gz: 6aaf1baa2de3d223d92918b490e2b49ac9afa412885ea42ede4696e60e5f2b26
+  data.tar.gz: ffe470a730eca79b84f43cfd585e85b6c9b69763227bf47a0207bb4fd16c9fef
 SHA512:
-  metadata.gz: 5475abce49b134a82a8d7464479fd29e491a5dc57d0e86cdbd0f75b0ea8ec4dd3db0762d70af26e862ebde10f728e9886a159167d18df0182f2659b6aafc673b
-  data.tar.gz: fbc1721e9fb0adbc00bb4de22ac25e04a832fe0c5595a1b3a9f618b37b3580dfa07a3ddade32acecc8221835e67f9a5b8b4c68798df09eef60b95d2104e1377b
+  metadata.gz: 432cb92d03d9346172fb92c6515418ddc03cb07b61dd624c3ced733715091211ed8cc7517bd7269f344f2224a01ec6b241c76e277c4438ad67e8ae1a9ef6af28
+  data.tar.gz: 9e0102de45be5372af45c788e95addf49712d1f1ae8afbf18fee53545e1d8b945d1f03d2094eaf02b6dc303d15269486c32a94dea87695410a3beb62902322dc

data/README.md

@@ -40,6 +40,69 @@ Every call takes an `org_id` (your organization ID, found in the dashboard). It
 call by design: one API token can be granted access to multiple organizations, and `org_id` selects
 which one the request acts on.
 
+## Brands
+
+A brand is a sub-account inside your organization — one company running several consumer-facing labels
+(Acme, Globex) keeps each label's orders and shipments separate, with its own company name, address and
+logo on the documents its shipments produce. Any call can be scoped to one brand by sending the
+`X-Zippendo-Brand` header with the brand's ID or slug.
+
+The header is not a method argument: it applies uniformly to every operation, so set it once as a default
+header on the client and every call inherits it.
+
+```ruby
+Zippendo.configure do |config|
+  config.access_token = ENV["ZIPPENDO_API_TOKEN"]
+end
+
+Zippendo::ApiClient.default.default_headers["X-Zippendo-Brand"] = "acme"  # brand ID or slug
+
+shipments = Zippendo::ShipmentsApi.new
+shipments.list_shipments("org_8f3kd92ld0", limit: 50)   # Acme's shipments only
+```
+
+To address two brands from one process, give each its own `ApiClient`:
+
+```ruby
+globex = Zippendo::ApiClient.new
+globex.default_headers["X-Zippendo-Brand"] = "brnd_8f3kd92ld0"
+Zippendo::OrdersApi.new(globex).list_orders("org_8f3kd92ld0")
+```
+
+Omit the header and the request covers the whole organization — the behaviour of every existing token.
+A header naming a brand that does not exist in the organization is rejected with `404 BRAND_NOT_FOUND`.
+
+A token created with a `brand_id` (see `CreateApiTokenRequest`) is permanently confined to that brand and
+needs no header. Sending `X-Zippendo-Brand` naming a *different* brand on such a token is refused with
+`403 BRAND_ACCESS_DENIED` — the binding is never widened.
+
+### Managing brands
+
+Brands are managed with `BrandsApi`. Use an organization-wide client for this — you are administering
+brands, not acting inside one:
+
+```ruby
+brands = Zippendo::BrandsApi.new
+
+created = brands.create_org_brand(
+  "org_8f3kd92ld0",
+  Zippendo::CreateOrgBrandRequest.new(name: "Acme", company_name: "Acme ApS")
+)
+
+page = brands.list_org_brands("org_8f3kd92ld0")
+brands.update_org_brand(
+  "org_8f3kd92ld0",
+  created.id,
+  Zippendo::UpdateOrgBrandRequest.new(vat_number: "DK12345678")
+)
+brands.archive_org_brand("org_8f3kd92ld0", created.id)
+```
+
+Retire a brand with `archive_org_brand` — archived brands keep their slug and can be restored with
+`unarchive_org_brand`. Permanent deletion is dashboard-only: it is refused while any order, shipment,
+member or token still references the brand. Brands require a plan that includes them; creating one past
+your plan's limit returns `403`.
+
 ## Listing & pagination
 
 List endpoints accept `:page` (1-based) and `:limit`, and return a page with `data` plus `total`,