mirror of
https://github.com/Sea-Haven-Industries/procurement-ingest.git
synced 2026-09-30 08:23:14 +00:00
8156b275a9
Some checks are pending
Deploy / deploy (push) Waiting to run
* feat(api): use stock Swagger UI for the /docs page Replaces the custom renderer with vendored stock Swagger UI (swagger-ui-dist 5.17.14, Apache-2.0), kept offline (no CDN) and inlined server-side into the single token-gated /docs response alongside the spec. BaseLayout (topbar hidden); try-it-out disabled since data routes need SigV4 (use Postman for live calls). Breakout guards on the inlined css/js/spec. Bundle-consistency + spec-drift + handler tests updated for the two vendored assets. cdk diff = Lambda code asset only (no IAM/API/policy change). * fix(api): render Swagger UI with the canonical StandaloneLayout recipe The BaseLayout-only init (apis preset, no standalone preset) rendered incorrectly. Switch to the canonical swagger-ui-dist recipe: vendor swagger-ui-standalone-preset.js and init with presets:[apis, SwaggerUIStandalonePreset] + layout:"StandaloneLayout" (topbar hidden, try-it-out disabled). Verified via headless Chrome against the live deployed page: all 9 endpoints + 4 webhooks + models render. Tests/bundling updated for the third vendored asset. * fix(api): declutter the Swagger UI docs page The page rendered (stock Swagger UI, StandaloneLayout) but looked cramped: a dense info.description wall of inline-code chips collided across Swagger UI's tight default line-height, and the Servers box showed a SEE-STACK-OUTPUT placeholder. - Trim info.description to a few concise lines (detail lives in README + the webhook contract doc). - Inject the live invoke URL into servers[0].url per request (from the API Gateway request context; committed literal is the fallback), so the Servers box shows the real endpoint and drops the server-variables section. - CSS: loosen description line-height + inline-code padding so chips never overlap; tidy the scheme container spacing. - Handler: cache the heavy CSS/JS/preset shell once; splice the (server- injected) spec per request. Verified via headless Chrome against the live deployed page.
1017 lines
31 KiB
JSON
1017 lines
31 KiB
JSON
{
|
|
"openapi": "3.1.0",
|
|
"info": {
|
|
"title": "Procurement Ingest API",
|
|
"version": "1.0.0",
|
|
"description": "Read API over the procurement-ingest pipelines (work orders and purchase orders). The outbound SHOC work-order webhook feed is documented under **webhooks** below.\n\nData endpoints use AWS IAM SigV4; the `/docs` and `/openapi.json` routes use a shared token. Listings are unordered, cursor-paginated scans. Endpoints tagged **x-planned** are phase 2 and currently answer `501`.\n\nThis API replaces SHOC's retired SyncController DynamoDB scan as the reconciliation and backfill path. Full detail: the repo README and `docs/shoc-webhook-contract.md`."
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://mvul1efda2.execute-api.us-east-1.amazonaws.com/prod",
|
|
"description": "seahaven-prod (011934824531)"
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"sigv4": []
|
|
}
|
|
],
|
|
"paths": {
|
|
"/work-orders": {
|
|
"get": {
|
|
"operationId": "listWorkOrders",
|
|
"summary": "List work orders (unordered, paginated)",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/Limit"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/Cursor"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "One page of work orders.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["items", "next_cursor"],
|
|
"properties": {
|
|
"items": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/WorkOrder"
|
|
}
|
|
},
|
|
"next_cursor": {
|
|
"$ref": "#/components/schemas/NextCursor"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/work-orders/{workOrderId}": {
|
|
"get": {
|
|
"operationId": "getWorkOrder",
|
|
"summary": "Get one work order",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/WorkOrderId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "The work order.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkOrder"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
}
|
|
}
|
|
},
|
|
"patch": {
|
|
"x-planned": true,
|
|
"operationId": "patchWorkOrder",
|
|
"summary": "PLANNED (phase 2): update dispatch fields on a work order",
|
|
"description": "Not implemented - returns 501. Phase-2 write-back for SHOC dispatch workflow (status/assignment). Writes will stamp `write_origin: shoc-write-api` so the outbound webhook never echoes SHOC's own writes back at it. Ships with its own IAM diff and cross-family review.",
|
|
"responses": {
|
|
"501": {
|
|
"$ref": "#/components/responses/NotImplemented"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/work-orders/{workOrderId}/comments": {
|
|
"get": {
|
|
"operationId": "listWorkOrderComments",
|
|
"summary": "List comments/events for a work order (paginated)",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/WorkOrderId"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/Limit"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/Cursor"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "One page of comments (all source-email event records: comments, updates, cancellations).",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["items", "next_cursor"],
|
|
"properties": {
|
|
"items": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/WorkOrderComment"
|
|
}
|
|
},
|
|
"next_cursor": {
|
|
"$ref": "#/components/schemas/NextCursor"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"x-planned": true,
|
|
"operationId": "createWorkOrderComment",
|
|
"summary": "PLANNED (phase 2): append a SHOC-authored comment",
|
|
"description": "Not implemented - returns 501. Phase-2 write-back: SHOC dispatch notes land in WorkOrderComments with `write_origin: shoc-write-api` (append-only; no field conflicts with the email pipeline). Ships with its own IAM diff and cross-family review.",
|
|
"responses": {
|
|
"501": {
|
|
"$ref": "#/components/responses/NotImplemented"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/purchase-orders": {
|
|
"get": {
|
|
"operationId": "listPurchaseOrders",
|
|
"summary": "List purchase orders (unordered, paginated)",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/Limit"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/Cursor"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "One page of purchase orders.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["items", "next_cursor"],
|
|
"properties": {
|
|
"items": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/PurchaseOrder"
|
|
}
|
|
},
|
|
"next_cursor": {
|
|
"$ref": "#/components/schemas/NextCursor"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/purchase-orders/{poNumber}": {
|
|
"get": {
|
|
"operationId": "getPurchaseOrder",
|
|
"summary": "Get one purchase order",
|
|
"parameters": [
|
|
{
|
|
"name": "poNumber",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Coupa PO number, e.g. `2D-22030794`."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "The purchase order.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PurchaseOrder"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/verified-sites": {
|
|
"get": {
|
|
"operationId": "listVerifiedSites",
|
|
"summary": "List verified Amazon sites (unordered, paginated)",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/Limit"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/Cursor"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "One page of verified sites.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["items", "next_cursor"],
|
|
"properties": {
|
|
"items": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/VerifiedSite"
|
|
}
|
|
},
|
|
"next_cursor": {
|
|
"$ref": "#/components/schemas/NextCursor"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/verified-sites/{siteCode}": {
|
|
"get": {
|
|
"operationId": "getVerifiedSite",
|
|
"summary": "Get one verified site",
|
|
"parameters": [
|
|
{
|
|
"name": "siteCode",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Amazon site code, e.g. `JFK8`."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "The verified site.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/VerifiedSite"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/docs": {
|
|
"get": {
|
|
"operationId": "getDocs",
|
|
"summary": "This documentation page (token-gated)",
|
|
"security": [
|
|
{
|
|
"docsToken": []
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "token",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Browser convenience: the docs token as a query parameter (browsers can't set headers on navigation). Prefer the X-Auth-Token header from tooling."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Self-contained HTML reference page.",
|
|
"content": {
|
|
"text/html": {}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/openapi.json": {
|
|
"get": {
|
|
"operationId": "getOpenApiSpec",
|
|
"summary": "This spec (token-gated)",
|
|
"security": [
|
|
{
|
|
"docsToken": []
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "The OpenAPI 3.1 document.",
|
|
"content": {
|
|
"application/json": {}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"webhooks": {
|
|
"work_order.created": {
|
|
"post": {
|
|
"summary": "Outbound: a work order was created",
|
|
"description": "Sent by `workorder-shoc-emitter` (seahaven-prod) to the configured SHOC endpoint. Full contract incl. HMAC verification, ordering, and retry semantics: `docs/shoc-webhook-contract.md` (Rev 2026-07-23). Requests carry `X-SH-Timestamp`, `X-SH-Key-Id`, and `X-SH-Signature: v1=hex(HMAC_SHA256(secret, \"{timestamp}.{raw_body}\"))`; verify over the raw body, constant-time, +/-300s window, fail closed.",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkOrderEventEnvelope"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"2XX": {
|
|
"description": "Delivered. Respond fast (<10s); accept-and-enqueue if processing is slow. 429/5xx/timeouts are retried in order for 24h; other 4xx park immediately."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"work_order.updated": {
|
|
"post": {
|
|
"summary": "Outbound: a work order changed",
|
|
"description": "Same envelope and semantics as work_order.created; `data` is the full current state, not a diff.",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkOrderEventEnvelope"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"2XX": {
|
|
"description": "Delivered."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"work_order.cancelled": {
|
|
"post": {
|
|
"summary": "Outbound: a work order transitioned to cancelled",
|
|
"description": "A specialization of work_order.updated (same body) emitted when `wo_status` transitions to `cancelled`.",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkOrderEventEnvelope"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"2XX": {
|
|
"description": "Delivered."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"work_order.comment_added": {
|
|
"post": {
|
|
"summary": "Outbound: a comment/event record was ingested",
|
|
"description": "One per source email (comments, updates, and cancellation event records). Dedupe on `delivery_id` or `data.comment_id`. May occasionally arrive before the work order's created event - upsert a skeleton work order and let the state event backfill it.",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CommentEventEnvelope"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"2XX": {
|
|
"description": "Delivered."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"securitySchemes": {
|
|
"sigv4": {
|
|
"type": "apiKey",
|
|
"name": "Authorization",
|
|
"in": "header",
|
|
"x-amazon-apigateway-authtype": "awsSigv4",
|
|
"description": "AWS IAM SigV4 (service execute-api, region us-east-1). Cross-account callers must be allowed by the API resource policy; Postman signs natively via Authorization type 'AWS Signature'."
|
|
},
|
|
"docsToken": {
|
|
"type": "apiKey",
|
|
"name": "X-Auth-Token",
|
|
"in": "header",
|
|
"description": "Shared docs token (secret procurement-ingest/web-ui-auth-token). Docs routes only."
|
|
}
|
|
},
|
|
"parameters": {
|
|
"Limit": {
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 500,
|
|
"default": 100
|
|
},
|
|
"description": "Page size; values outside 1-500 are clamped."
|
|
},
|
|
"Cursor": {
|
|
"name": "cursor",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Opaque pagination cursor from the previous page's `next_cursor`. Malformed cursors return 400."
|
|
},
|
|
"WorkOrderId": {
|
|
"name": "workOrderId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"pattern": "^[0-9]+$"
|
|
},
|
|
"description": "Numeric APM work-order id, e.g. `11144580730`."
|
|
}
|
|
},
|
|
"responses": {
|
|
"BadRequest": {
|
|
"description": "Malformed cursor or limit.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Unauthorized": {
|
|
"description": "Missing or wrong docs token.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Forbidden": {
|
|
"description": "SigV4 auth failed or the caller is not allowed by the API resource policy (returned by API Gateway, not the Lambda)."
|
|
},
|
|
"NotFound": {
|
|
"description": "No record with that id.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"NotImplemented": {
|
|
"description": "Planned phase-2 endpoint; not implemented yet.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"schemas": {
|
|
"Error": {
|
|
"type": "object",
|
|
"required": ["error"],
|
|
"properties": {
|
|
"error": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
},
|
|
"NextCursor": {
|
|
"type": ["string", "null"],
|
|
"description": "Pass as `cursor` to fetch the next page; `null` means this is the last page."
|
|
},
|
|
"WorkOrder": {
|
|
"type": "object",
|
|
"description": "Mirrors the WorkOrders DynamoDB item (PK work_order_id). Fields absent from the source email are absent or null.",
|
|
"required": ["work_order_id"],
|
|
"properties": {
|
|
"work_order_id": {
|
|
"type": "string",
|
|
"pattern": "^[0-9]+$"
|
|
},
|
|
"wo_status": {
|
|
"type": ["string", "null"],
|
|
"enum": ["new", "assigned", "in_progress", "on_hold", "completed", "cancelled", "unknown", null],
|
|
"description": "`unknown` is a real emitted value - map it explicitly."
|
|
},
|
|
"description": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"customer": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"site_code": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"building": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"address": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"severity": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"priority": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"assigned_to": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"date_reported": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"scheduled_start": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"due_date": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"record_type": {
|
|
"type": ["string", "null"],
|
|
"enum": ["new_work_order", "update", "comment", "cancellation", null],
|
|
"description": "Type of the most recent source email."
|
|
},
|
|
"created_at": {
|
|
"type": ["string", "null"],
|
|
"description": "ISO 8601 with UTC offset."
|
|
},
|
|
"updated_at": {
|
|
"type": ["string", "null"],
|
|
"description": "ISO 8601 with UTC offset."
|
|
},
|
|
"source_email_s3_key": {
|
|
"type": ["string", "null"]
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"WorkOrderComment": {
|
|
"type": "object",
|
|
"description": "Mirrors the WorkOrderComments DynamoDB item (PK work_order_id, SK comment_id). One row per source email event.",
|
|
"required": ["work_order_id", "comment_id"],
|
|
"properties": {
|
|
"work_order_id": {
|
|
"type": "string"
|
|
},
|
|
"comment_id": {
|
|
"type": "string",
|
|
"description": "`{work_order_id}#{time|nocomment}#{sha256(s3_key)[:12]}` - unique per source email, stable across retries; a dedupe key."
|
|
},
|
|
"record_type": {
|
|
"type": ["string", "null"],
|
|
"enum": ["new_work_order", "update", "comment", "cancellation", null]
|
|
},
|
|
"commenter": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"text": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"created_at": {
|
|
"type": ["string", "null"],
|
|
"description": "Display timestamp (comment time when the source email carried one)."
|
|
},
|
|
"ingested_at": {
|
|
"type": ["string", "null"],
|
|
"description": "When the pipeline wrote the row; ISO 8601 with UTC offset."
|
|
},
|
|
"source_email_s3_key": {
|
|
"type": ["string", "null"]
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"PurchaseOrder": {
|
|
"type": "object",
|
|
"description": "Mirrors the purchase-orders DynamoDB item (PK po_number). Shape follows the Coupa extraction schema; older records may lack newer fields.",
|
|
"required": ["po_number"],
|
|
"properties": {
|
|
"po_number": {
|
|
"type": "string"
|
|
},
|
|
"po_status": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"email_type": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"source_system": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"submitted_by": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"on_behalf_of": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"order_date": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"revision_date": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"payment_terms": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"requisition_number": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"department": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"view_order_url": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"supplier": {
|
|
"type": ["object", "null"],
|
|
"properties": {
|
|
"name": {
|
|
"type": ["string", "null"]
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"site_code": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"ship_to": {
|
|
"type": ["object", "null"],
|
|
"properties": {
|
|
"name": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"address": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"street": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"city": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"state": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"zip": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"location_code": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"attn": {
|
|
"type": ["string", "null"]
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"total_amount": {
|
|
"type": ["number", "null"],
|
|
"description": "Stored as Decimal; serialized as a JSON number."
|
|
},
|
|
"currency": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"fiscal_year": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"trade": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"coupa_category": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"line_items": {
|
|
"type": ["array", "null"],
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"description": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"quantity": {
|
|
"type": ["number", "null"]
|
|
},
|
|
"unit": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"price": {
|
|
"type": ["number", "null"]
|
|
},
|
|
"amount": {
|
|
"type": ["number", "null"]
|
|
},
|
|
"currency": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"need_by": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"category": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"account_code": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"period": {
|
|
"type": ["string", "null"]
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
}
|
|
},
|
|
"cancelled_at": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"processed_at": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"raw_s3_key": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"data_source": {
|
|
"type": ["string", "null"]
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"VerifiedSite": {
|
|
"type": "object",
|
|
"description": "Mirrors the verified-sites DynamoDB item (PK siteCode), maintained by the PO site extractor.",
|
|
"required": ["siteCode"],
|
|
"properties": {
|
|
"siteCode": {
|
|
"type": "string"
|
|
},
|
|
"address": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"city": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"state": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"zip": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"fullAddress": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"locationCode": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"poCount": {
|
|
"type": ["integer", "null"],
|
|
"description": "Count of POs that referenced this site."
|
|
},
|
|
"sourcePOs": {
|
|
"type": ["array", "null"],
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "PO numbers that referenced this site (string set; serialized sorted)."
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"WebhookEnvelope": {
|
|
"type": "object",
|
|
"description": "Common webhook envelope (contract section 3). Headers: X-SH-Timestamp (unix seconds), X-SH-Key-Id, X-SH-Signature (v1=hex HMAC-SHA256 over '{timestamp}.{raw_body}').",
|
|
"required": ["schema_version", "delivery_id", "event_type", "occurred_at", "source", "replay", "data"],
|
|
"properties": {
|
|
"schema_version": {
|
|
"type": "integer",
|
|
"description": "Reject versions you don't know."
|
|
},
|
|
"delivery_id": {
|
|
"type": "string",
|
|
"description": "Unique per source event, stable across producer retries - the idempotency key."
|
|
},
|
|
"event_type": {
|
|
"type": "string",
|
|
"enum": ["work_order.created", "work_order.updated", "work_order.cancelled", "work_order.comment_added"]
|
|
},
|
|
"occurred_at": {
|
|
"type": "string",
|
|
"description": "ISO 8601 with UTC offset."
|
|
},
|
|
"source": {
|
|
"type": "string",
|
|
"const": "procurement-ingest/workorder-shoc-emitter"
|
|
},
|
|
"replay": {
|
|
"type": "boolean",
|
|
"description": "true when re-sent by the operator replay tool; same idempotency rules."
|
|
},
|
|
"data": {
|
|
"type": "object"
|
|
}
|
|
}
|
|
},
|
|
"WorkOrderEventEnvelope": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/WebhookEnvelope"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"$ref": "#/components/schemas/WorkOrderEventData"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"CommentEventEnvelope": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/WebhookEnvelope"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"$ref": "#/components/schemas/CommentEventData"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkOrderEventData": {
|
|
"type": "object",
|
|
"description": "Full current work-order state (not a diff); contract section 4.1. Same fields as WorkOrder minus source_email_s3_key.",
|
|
"required": ["work_order_id"],
|
|
"properties": {
|
|
"work_order_id": {
|
|
"type": "string",
|
|
"pattern": "^[0-9]+$"
|
|
},
|
|
"wo_status": {
|
|
"type": ["string", "null"],
|
|
"enum": ["new", "assigned", "in_progress", "on_hold", "completed", "cancelled", "unknown", null]
|
|
},
|
|
"description": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"customer": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"site_code": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"building": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"address": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"severity": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"priority": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"assigned_to": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"date_reported": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"scheduled_start": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"due_date": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"record_type": {
|
|
"type": ["string", "null"],
|
|
"enum": ["new_work_order", "update", "comment", "cancellation", null]
|
|
},
|
|
"created_at": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"updated_at": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"write_origin": {
|
|
"type": ["string", "null"],
|
|
"description": "Forward-compat (phase 2): present on records written through the write-back API; the emitter skips those, so receivers should tolerate but never see it."
|
|
}
|
|
}
|
|
},
|
|
"CommentEventData": {
|
|
"type": "object",
|
|
"description": "Contract section 4.2. Same fields as WorkOrderComment minus source_email_s3_key.",
|
|
"required": ["work_order_id", "comment_id"],
|
|
"properties": {
|
|
"work_order_id": {
|
|
"type": "string"
|
|
},
|
|
"comment_id": {
|
|
"type": "string"
|
|
},
|
|
"record_type": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"commenter": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"text": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"created_at": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"ingested_at": {
|
|
"type": ["string", "null"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|