--- title: "What needs doing about one supplier" method: GET path: "/api/v1/inventory/suppliers/{supplier_id}/needs-attention" tags: ["suppliers"] --- # What needs doing about one supplier `GET /api/v1/inventory/suppliers/{supplier_id}/needs-attention` ## Request - Base URL: `https://api.app.tightly.io` - URL: `https://api.app.tightly.io/api/v1/inventory/suppliers/{supplier_id}/needs-attention` - Auth: HTTP bearer What is wrong with one supplier right now, in four sections. `purchase_orders` is a worklist: one item per order needing a look, with `po_id`, the order's display number, its status, a `message_key` of `cancelled`, `delayed`, `shipped`, `quantity_changed` or `expected_delivery_date_passed`, and `email`, the supplier's message the signal was read out of, or null where the order is simply past its expected delivery date. `total_count` counts the items. An `email` is the stored message, and its body belongs to the person whose mailbox it arrived in. A key is nobody's colleague, so it reads each mailbox at the level that mailbox shares: on the default level `body`, `html_body`, `clean_body` and `quoted_body` come back null with `body_withheld` saying so, and a mailbox shared with Tightly only keeps its messages out of the section, leaving `email` null. `says`, `files`, `decision`, `with_party`, `tag` and `waits_on_you` are answered by the Mail reads, not by this one. `replenishment_readiness` counts this supplier's variants with no lead time and with no unit cost, which are the two figures a reorder cannot be computed without. `smart_replenishment` counts the variants at critical stock. `supplier_configuration` says whether a default lead time and a minimum order value are recorded, and how far the configured lead time is from the measured one. Counts and a worklist, never rates. get_supplier_overview is the door for the figures a scorecard prints. Scope: `suppliers:read`. ## Path parameters - `supplier_id` string, required ## Headers - `Tightly-Version` string ## Response `200` The four sections. Every count is a whole number and never null; `purchase_orders.items` is empty when there is nothing to do. An item's `email` is the supplier's message the signal was read out of: its subject, its people, its dates, the files that came with it (`attachments`, each with `id`, `filename` and `mime_type`, and a stored file may carry keys beyond those three, which are ignored rather than refused), and the message itself where this caller may read it. `read_at` is when Tightly read the thread, or null. A connected mailbox carries one of three sharing levels, and a key is never the person who connected it, so a key reads every mailbox at the level that mailbox shares. At the default level the four body fields (`body`, `html_body`, `clean_body`, `quoted_body`) are null and `body_withheld` carries the sentence saying so; at Full messages they are served as they always were; and a mailbox shared with Tightly only has its messages left out of this section altogether, so the item carries `email: null` with the order, its status and its `message_key` unchanged. `says`, `files`, `decision`, `with_party`, `tag` and `waits_on_you` are part of the shared message shape and are null on this operation. They are read from a thread, and this section reads messages one at a time by id. - GetSupplierNeedsAttentionResponse - `data` union - SupplierNeedsAttentionPayload - `purchase_orders` PurchaseOrdersAttentionSection, required - `items` PurchaseOrderAttentionItem[] - `email` union - EmailDict - … - object, nullable - `message_key` string, required - `po_external_id` string, required - `po_id` string, required - `status` string, required - `total_count` integer - `replenishment_readiness` ReplenishmentReadinessSection, required - `missing_lead_time_variants_count` integer - `missing_unit_cost_variants_count` integer - `smart_replenishment` SmartReplenishmentSection, required - `critical_variants_count` integer - `supplier_configuration` SupplierConfigurationSection, required - `average_lead_time_days` integer, nullable - `configured_lead_time_days` integer, nullable - `default_lead_time_configured` boolean, required - `lead_time_diff_days` integer, nullable - `min_order_value_configured` boolean, required - object, nullable - `message` ApiMessage - `desc` string - `service` string - `severity` 'SUCCESS' | 'INFO' | 'ERROR' | 'WARNING' ## Other responses - `401`: No usable key: malformed, unknown, revoked, expired or stopped. One refusal covers all five, telling a caller which is which maps the surface for them. A request with no Authorization header at all is refused 400 before any key is looked for. - `403`: The key may not reach this operation. `scope_missing` when the key does not hold Suppliers; `ip_not_allowed` when the caller's address is outside the key's allowlist. There is no `organization_mismatch` on this resource: no supplier or contact route names an organisation in its path, so there is nothing for a key to disagree with. - `404`: No supplier of this organisation has that id. - `429`: The key has spent its allowance for this minute. 600 reads and 120 writes a minute, counted per key, refused calls included. `Retry-After` says how long to wait. - `503`: The database is briefly out of reach, which is what a failover or a full connection pool looks like from outside. Wait the seconds `Retry-After` names and send the request again. A read is safe to repeat. A write is not, because the connection was lost in the middle of it, so read the object back before sending it a second time. Branch on the status rather than on `code`, which is `POSTGRES_UNAVAILABLE` from one of the two seams that raise this and `SERVICE_UNAVAILABLE` from the other. --- [API](https://skmtc.dev/tightly/apis/tightly-api.md) · [All operations](https://skmtc.dev/tightly/apis/tightly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tightly/apis/tightly-api/revisions/199f7eb35afb?raw)