{"openapi":"3.1.0","info":{"title":"tally-api","description":"The tally-api API","version":"v0.1.0"},"servers":[{"url":"http://localhost:8080","description":"Local Server"}],"paths":{"/tally/healthcheck":{"get":{"operationId":"getTallyHealthcheck","description":"Barebones healthcheck endpoint, responds with a pulse","responses":{"200":{"description":"Healthy response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/tally/alerts/supplier-invoice":{"post":{"operationId":"postTallyAlertsSupplierInvoice","description":"Post a Slack alert for a supplier invoice that has been compared against its purchase order. An order whose goods have already been received raises nothing.","responses":{"200":{"description":"What became of the alert. A delivery failure is reported here rather than as an error status.","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"enum":["sent","suppressed","not_configured","failed"],"type":"string"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}]},"ts":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["outcome","detail","ts"]},"example":{"outcome":"sent","detail":null,"ts":"1699999999.000001"}}}},"400":{"description":"The comparison or filename is missing or malformed"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"comparison":{"type":"object","properties":{"reference":{"type":"string"},"invoiceDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrder":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"reference":{"type":"string"},"supplier":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"shipmentState":{"type":"string"},"invoiceState":{"type":"string"},"warehouse":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"operator":{"anyOf":[{"type":"string"},{"type":"null"}]},"site":{"anyOf":[{"type":"string"},{"type":"null"}]},"fulfillment":{"anyOf":[{"enum":["RTS","MTO"],"type":"string"},{"type":"null"}]},"bonded":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","code","operator","site","fulfillment","bonded"]},{"type":"null"}]}},"required":["id","number","reference","supplier","state","shipmentState","invoiceState","warehouse"]},"extraction":{"type":"object","properties":{"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"outcome":{"enum":["extracted","partial","no_totals","no_text_layer","unsupported_type","unreadable"],"type":"string"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","outcome","detail"]},"quantity":{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrder":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta":{"anyOf":[{"type":"string"},{"type":"null"}]},"deltaPercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"outcome":{"enum":["match","differs","not_extracted"],"type":"string"}},"required":["document","purchaseOrder","delta","deltaPercent","outcome"]},"amount":{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrder":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta":{"anyOf":[{"type":"string"},{"type":"null"}]},"deltaPercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"outcome":{"enum":["match","differs","not_extracted"],"type":"string"}},"required":["document","purchaseOrder","delta","deltaPercent","outcome"]}},"required":["reference","invoiceDate","purchaseOrder","extraction","quantity","amount"]},"filename":{"type":"string","minLength":1,"description":"The document the comparison was run against. Shown in the alert, and in its notification text."},"fileId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Drive file id, so the alert can link the document a reviewer will want to open next."}},"required":["comparison","filename"]}}}}}},"/tally/alerts/receipt":{"post":{"operationId":"postTallyAlertsReceipt","description":"Post a Slack alert for a supplier invoice that has been compared against what arrived. An order with nothing received yet raises nothing, and neither does one whose invoice finance has already posted.","responses":{"200":{"description":"What became of the alert. A delivery failure is reported here rather than as an error status.","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"enum":["sent","skipped","suppressed","not_configured","failed"],"type":"string"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}]},"ts":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["outcome","detail","ts"]},"example":{"outcome":"sent","detail":null,"ts":"1699999999.000001"}}}},"400":{"description":"The comparison or filename is missing or malformed"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"comparison":{"type":"object","properties":{"reference":{"type":"string"},"outcome":{"enum":["compared","not_received"],"type":"string"},"invoiceDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrder":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"reference":{"type":"string"},"supplier":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"shipmentState":{"type":"string"},"invoiceState":{"type":"string"},"warehouse":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"operator":{"anyOf":[{"type":"string"},{"type":"null"}]},"site":{"anyOf":[{"type":"string"},{"type":"null"}]},"fulfillment":{"anyOf":[{"enum":["RTS","MTO"],"type":"string"},{"type":"null"}]},"bonded":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","code","operator","site","fulfillment","bonded"]},{"type":"null"}]}},"required":["id","number","reference","supplier","state","shipmentState","invoiceState","warehouse"]},"receipt":{"anyOf":[{"type":"object","properties":{"invoiceId":{"type":"number"},"invoiceState":{"type":"string"},"amount":{"anyOf":[{"type":"string"},{"type":"null"}]},"quantity":{"anyOf":[{"type":"number"},{"type":"null"}]},"shipments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"number":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"quantity":{"anyOf":[{"type":"number"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","number","state","quantity","receivedAt"]}},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["invoiceId","invoiceState","amount","quantity","shipments","receivedAt"]},{"type":"null"}]},"extraction":{"type":"object","properties":{"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"outcome":{"enum":["extracted","partial","no_totals","no_text_layer","unsupported_type","unreadable"],"type":"string"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","outcome","detail"]},"quantity":{"anyOf":[{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta":{"anyOf":[{"type":"string"},{"type":"null"}]},"deltaPercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"outcome":{"enum":["match","differs","not_extracted"],"type":"string"}},"required":["document","receipt","delta","deltaPercent","outcome"]},{"type":"null"}]},"amount":{"anyOf":[{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta":{"anyOf":[{"type":"string"},{"type":"null"}]},"deltaPercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"outcome":{"enum":["match","differs","not_extracted"],"type":"string"}},"required":["document","receipt","delta","deltaPercent","outcome"]},{"type":"null"}]}},"required":["reference","outcome","invoiceDate","purchaseOrder","receipt","extraction","quantity","amount"]},"filename":{"type":"string","minLength":1,"description":"The document the comparison was run against. Shown in the alert, and in its notification text."},"fileId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Drive file id, so the alert can link the document a reviewer will want to open next."}},"required":["comparison","filename"]}}}}}},"/tally/alerts/receipt-line-items":{"post":{"operationId":"postTallyAlertsReceiptLineItems","description":"Reply under a Supplier Shipment alert with the SKUs behind its variance. Always a threaded reply, never a channel message.","responses":{"200":{"description":"What became of the reply. A delivery failure is reported here rather than as an error status.","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"enum":["sent","skipped","not_configured","failed"],"type":"string"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["outcome","detail"]},"example":{"outcome":"sent","detail":null}}}},"400":{"description":"The comparison or `threadTs` is missing or malformed"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"comparison":{"type":"object","properties":{"reference":{"type":"string"},"purchaseOrder":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"supplier":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","number","reference","supplier"]},"invoiceId":{"type":"number"},"outcome":{"enum":["compared","no_table"],"type":"string"},"source":{"anyOf":[{"type":"object","properties":{"sheet":{"type":"string"},"priceHeader":{"type":"string"},"strategy":{"enum":["template","description"],"type":"string"}},"required":["sheet","priceHeader","strategy"]},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"styleNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"colorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"colorName":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"anyOf":[{"type":"string"},{"type":"null"}]},"outcome":{"enum":["agreed","quantity","price","quantity_and_price","unmatched","missing"],"type":"string"},"quantity":{"type":"object","properties":{"document":{"anyOf":[{"type":"number"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"number"},{"type":"null"}]},"delta":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["document","receipt","delta"]},"price":{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["document","receipt","delta"]},"amountDelta":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sku","styleNumber","colorCode","colorName","size","outcome","quantity","price","amountDelta"]}},"groups":{"type":"array","items":{"type":"object","properties":{"colorway":{"type":"string"},"styleNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"colorName":{"anyOf":[{"type":"string"},{"type":"null"}]},"sizes":{"type":"array","items":{"type":"string"}},"skus":{"type":"number"},"quantity":{"type":"object","properties":{"document":{"type":"number"},"receipt":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["document","receipt"]},"price":{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["document","receipt"]},"amountDelta":{"type":"string"}},"required":["colorway","styleNumber","colorName","sizes","skus","quantity","price","amountDelta"]}},"totals":{"type":"object","properties":{"skus":{"type":"number"},"agreed":{"type":"number"},"variances":{"type":"number"},"unmatched":{"type":"number"},"missing":{"type":"number"},"varianceAmount":{"type":"string"},"unmatchedAmount":{"type":"string"},"pricedAbove":{"type":"number"},"pricedBelow":{"type":"number"}},"required":["skus","agreed","variances","unmatched","missing","varianceAmount","unmatchedAmount","pricedAbove","pricedBelow"]}},"required":["reference","purchaseOrder","invoiceId","outcome","source","lines","groups","totals"]},"threadTs":{"type":"string","minLength":1,"description":"The parent alert's `ts`, returned by `/alerts/receipt`. The detail is always a reply."}},"required":["comparison","threadTs"]}}}}}},"/tally/alerts/line-items":{"post":{"operationId":"postTallyAlertsLineItems","description":"Post the SKU-level detail behind a supplier invoice alert as a reply on its thread. A comparison where every SKU agreed, or where the document carried no SKU table, posts nothing.","responses":{"200":{"description":"What became of the reply. A delivery failure is reported here rather than as an error status.","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"enum":["sent","skipped","not_configured","failed"],"type":"string"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["outcome","detail"]},"example":{"outcome":"sent","detail":null}}}},"400":{"description":"The comparison or thread timestamp is missing or malformed"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"comparison":{"type":"object","properties":{"reference":{"type":"string"},"purchaseOrder":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"supplier":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","number","reference","supplier"]},"outcome":{"enum":["compared","no_table"],"type":"string"},"source":{"anyOf":[{"type":"object","properties":{"sheet":{"type":"string"},"priceHeader":{"type":"string"},"strategy":{"enum":["template","description"],"type":"string"}},"required":["sheet","priceHeader","strategy"]},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"styleNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"colorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"colorName":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"anyOf":[{"type":"string"},{"type":"null"}]},"outcome":{"enum":["agreed","quantity","price","quantity_and_price","unmatched","missing"],"type":"string"},"quantity":{"type":"object","properties":{"document":{"anyOf":[{"type":"number"},{"type":"null"}]},"purchaseOrder":{"anyOf":[{"type":"number"},{"type":"null"}]},"delta":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["document","purchaseOrder","delta"]},"price":{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrder":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["document","purchaseOrder","delta"]},"amountDelta":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sku","styleNumber","colorCode","colorName","size","outcome","quantity","price","amountDelta"]}},"groups":{"type":"array","items":{"type":"object","properties":{"colorway":{"type":"string"},"styleNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"colorName":{"anyOf":[{"type":"string"},{"type":"null"}]},"sizes":{"type":"array","items":{"type":"string"}},"skus":{"type":"number"},"quantity":{"type":"object","properties":{"document":{"type":"number"},"purchaseOrder":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["document","purchaseOrder"]},"price":{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrder":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["document","purchaseOrder"]},"amountDelta":{"type":"string"}},"required":["colorway","styleNumber","colorName","sizes","skus","quantity","price","amountDelta"]}},"totals":{"type":"object","properties":{"skus":{"type":"number"},"agreed":{"type":"number"},"variances":{"type":"number"},"unmatched":{"type":"number"},"missing":{"type":"number"},"varianceAmount":{"type":"string"},"unmatchedAmount":{"type":"string"},"pricedAbove":{"type":"number"},"pricedBelow":{"type":"number"}},"required":["skus","agreed","variances","unmatched","missing","varianceAmount","unmatchedAmount","pricedAbove","pricedBelow"]}},"required":["reference","purchaseOrder","outcome","source","lines","groups","totals"]},"threadTs":{"type":"string","minLength":1,"description":"The parent alert's `ts`, returned by `/alerts/supplier-invoice`. The detail is always a reply."}},"required":["comparison","threadTs"]}}}}}},"/tally/alerts/needs-review":{"post":{"operationId":"postTallyAlertsNeedsReview","description":"Post one Slack message naming every invoice a run could not match to a purchase order. An empty list posts nothing.","responses":{"200":{"description":"What became of the alert. A delivery failure is reported here rather than as an error status.","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"enum":["sent","skipped","not_configured","failed"],"type":"string"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}]},"ts":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["outcome","detail","ts"]},"example":{"outcome":"sent","detail":null,"ts":"1699999999.000001"}}}},"400":{"description":"The document list or the mailbox is missing or malformed"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string","minLength":1},"subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"vendor":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmailThreadId":{"anyOf":[{"type":"string"},{"type":"null"}]},"candidatesTried":{"type":"array","items":{"type":"string"}}},"required":["filename","subject","vendor","gmailThreadId","candidatesTried"]},"maxItems":50},"mailbox":{"type":"string","minLength":1,"description":"The mailbox these arrived in. The Gmail link names it, so a reader opens the right account."}},"required":["documents","mailbox"]}}}}}},"/tally/purchase-orders/awaiting-invoice":{"get":{"operationId":"getTallyPurchaseOrdersAwaitingInvoice","description":"List the purchase orders whose goods have arrived and whose supplier invoice finance has not yet posted. Dropship and returns suppliers are excluded, being billed by whoever shipped them. Scope it: unscoped, almost all of the window is marketplace and internal-transfer volume. Order totals and receipt figures are not returned — `/documents/receipt` carries those for the order being compared.","responses":{"200":{"description":"The orders, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"supplier":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"shipmentState":{"type":"string"},"invoiceState":{"type":"string"},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"transportationMode":{"anyOf":[{"type":"string"},{"type":"null"}]},"warehouse":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"operator":{"anyOf":[{"type":"string"},{"type":"null"}]},"site":{"anyOf":[{"type":"string"},{"type":"null"}]},"fulfillment":{"anyOf":[{"enum":["RTS","MTO"],"type":"string"},{"type":"null"}]},"bonded":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","code","operator","site","fulfillment","bonded"]},{"type":"null"}]}},"required":["id","number","reference","supplier","state","shipmentState","invoiceState","type","transportationMode","warehouse"]}}},"required":["count","orders"]},"example":{"count":2,"orders":[{"id":27352,"number":"PO22916","reference":"AL011","supplier":"Lianyungang Aolong Fashion Co.,Ltd","state":"processing","shipmentState":"received","invoiceState":"waiting","type":"standard","transportationMode":"ocean","warehouse":{"id":284,"code":"SM_KY2","operator":"ShipMonk","site":"KY2","fulfillment":"RTS","bonded":false}},{"id":27507,"number":"PO23047","reference":"MB119","supplier":"Suzhou Milly Trade Co., Ltd","state":"processing","shipmentState":"received","invoiceState":"waiting","type":"standard","transportationMode":"ocean","warehouse":{"id":284,"code":"SM_KY2","operator":"ShipMonk","site":"KY2","fulfillment":"RTS","bonded":false}}]}}}},"400":{"description":"A malformed `warehouse` or `fulfillment`","content":{"application/json":{"example":{"success":false,"error":[{"kind":"validation","type":"regex","input":"FS%","expected":null,"received":"\"FS%\"","message":"reference must not contain % or _, which Fulfil treats as wildcards","path":[{"type":"object","origin":"value","key":"reference","value":"FS%"}]}],"data":{"reference":"FS%"}}}}},"429":{"description":"Fulfil throttled us for longer than the retry budget allows","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is rate limiting us; retry shortly"}}}},"500":{"description":"The lookup failed on our side; retrying will not help","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Purchase order lookup failed"}}}},"502":{"description":"Fulfil unreachable after retries","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is unavailable"}}}}},"parameters":[{"in":"query","name":"warehouse","schema":{"type":"string","pattern":"^\\d+$"},"description":"An `inventory_location` id. Takes precedence over `fulfillment`."},{"in":"query","name":"fulfillment","schema":{"enum":["RTS","MTO"],"type":"string"},"description":"Narrows to the warehouses fulfilled that way."}]}},"/tally/purchase-orders":{"get":{"operationId":"getTallyPurchaseOrders","description":"Resolve a vendor reference code or Fulfil purchase order number to its purchase order, including where it is fulfilled.","responses":{"200":{"description":"The matching purchase order","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"reference":{"type":"string"},"supplier":{"type":"object","properties":{"id":{"type":"number"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"]},"state":{"type":"string"},"shipmentState":{"type":"string"},"invoiceState":{"type":"string"},"totalAmount":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A decimal string. Compare it in minor units rather than parsing it to a float."},"totalQuantity":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"transportationMode":{"anyOf":[{"type":"string"},{"type":"null"}]},"warehouse":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"operator":{"anyOf":[{"type":"string"},{"type":"null"}]},"site":{"anyOf":[{"type":"string"},{"type":"null"}]},"fulfillment":{"anyOf":[{"enum":["RTS","MTO"],"type":"string"},{"type":"null"}]},"bonded":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","code","operator","site","fulfillment","bonded"]},{"type":"null"}]},"shipmentIds":{"type":"array","items":{"type":"number"}},"invoiceIds":{"type":"array","items":{"type":"number"}}},"required":["id","number","reference","supplier","state","shipmentState","invoiceState","totalAmount","totalQuantity","currency","transportationMode","warehouse","shipmentIds","invoiceIds"]},"example":{"id":26975,"number":"PO22562","reference":"FS065","supplier":{"id":11,"name":"Fashion Star"},"state":"done","shipmentState":"received","invoiceState":"posted","totalAmount":"18242.10","totalQuantity":648,"currency":"USD","transportationMode":"ocean","warehouse":{"id":284,"code":"SM_KY2","operator":"ShipMonk","site":"KY2","fulfillment":"RTS","bonded":false},"shipmentIds":[6933],"invoiceIds":[5604826]}}}},"400":{"description":"Reference missing, empty, too long, or contains `%` or `_`","content":{"application/json":{"example":{"success":false,"error":[{"kind":"validation","type":"regex","input":"FS%","expected":null,"received":"\"FS%\"","message":"reference must not contain % or _, which Fulfil treats as wildcards","path":[{"type":"object","origin":"value","key":"reference","value":"FS%"}]}],"data":{"reference":"FS%"}}}}},"404":{"description":"No purchase order has that reference","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Purchase order not found"}}}},"409":{"description":"The value matches more than one purchase order","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Reference matches 2 purchase orders; it must identify exactly one"}}}},"429":{"description":"Fulfil throttled us for longer than the retry budget allows","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is rate limiting us; retry shortly"}}}},"500":{"description":"The lookup failed on our side; retrying will not help","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Purchase order lookup failed"}}}},"502":{"description":"Fulfil unreachable after retries","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is unavailable"}}}}},"parameters":[{"in":"query","name":"reference","schema":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[^%_]+$"},"required":true,"description":"A vendor reference code or a Fulfil purchase order number. Case-insensitive, and matched whole — `FS065` and `FS065-1` are different orders."}]}},"/tally/documents/match":{"post":{"operationId":"postTallyDocumentsMatch","description":"Match a document to its Fulfil purchase order. Requires a filename or a subject. Whether a match is in scope is the caller's to decide — read `warehouse` on the purchase order.","responses":{"200":{"description":"What the document matched. `unresolved` and `ambiguous` are 200s too","content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"enum":["resolved","ambiguous","unresolved"],"type":"string"},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"enum":["filename","subject"],"type":"string"},{"type":"null"}]},"purchaseOrder":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"reference":{"type":"string"},"supplier":{"type":"object","properties":{"id":{"type":"number"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"]},"state":{"type":"string"},"shipmentState":{"type":"string"},"invoiceState":{"type":"string"},"totalAmount":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A decimal string. Compare it in minor units rather than parsing it to a float."},"totalQuantity":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"transportationMode":{"anyOf":[{"type":"string"},{"type":"null"}]},"warehouse":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"operator":{"anyOf":[{"type":"string"},{"type":"null"}]},"site":{"anyOf":[{"type":"string"},{"type":"null"}]},"fulfillment":{"anyOf":[{"enum":["RTS","MTO"],"type":"string"},{"type":"null"}]},"bonded":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","code","operator","site","fulfillment","bonded"]},{"type":"null"}]},"shipmentIds":{"type":"array","items":{"type":"number"}},"invoiceIds":{"type":"array","items":{"type":"number"}}},"required":["id","number","reference","supplier","state","shipmentState","invoiceState","totalAmount","totalQuantity","currency","transportationMode","warehouse","shipmentIds","invoiceIds"]},{"type":"null"}]},"matchedNumbers":{"type":"array","items":{"type":"string"}},"candidatesTried":{"type":"array","items":{"type":"string"}}},"required":["outcome","reference","source","purchaseOrder","matchedNumbers","candidatesTried"]},"example":{"outcome":"resolved","reference":"FS071","source":"filename","purchaseOrder":{"id":27354,"number":"PO22918","reference":"FS071","supplier":{"id":11,"name":"Fashion Star"},"state":"processing","shipmentState":"waiting","invoiceState":"none","totalAmount":"25156.58","totalQuantity":737,"currency":"USD","transportationMode":"ocean","warehouse":{"id":284,"code":"SM_KY2","operator":"ShipMonk","site":"KY2","fulfillment":"RTS","bonded":false},"shipmentIds":[],"invoiceIds":[]},"matchedNumbers":["PO22918"],"candidatesTried":["SS7740-FS071","SS7740","FS071","FS076","FS077"]}}}},"400":{"description":"Neither a filename nor a subject was given, or one of them is malformed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"A filename or a subject is required"}}}},"429":{"description":"Fulfil throttled us for longer than the retry budget allows","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is rate limiting us; retry shortly"}}}},"500":{"description":"The match failed on our side; retrying will not help","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Document match failed"}}}},"502":{"description":"Fulfil unreachable after retries","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is unavailable"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","maxLength":500,"description":"Read first. A code here wins, being the document's own rather than its thread's."},"subject":{"type":"string","maxLength":500,"description":"Read only when no code in the filename resolves. Names every purchase order on the thread."}},"required":[]}}}}}},"/tally/documents/classify":{"post":{"operationId":"postTallyDocumentsClassify","description":"Label documents by filename.","responses":{"200":{"description":"One result per filename, each carrying the filename it labels","content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"label":{"enum":["Archive","Packing List","Duty","Invoice","Sample Invoice","Valuation Invoice","Freight Invoice","ASN","Shipping Doc","Unclassified"],"type":"string"}},"required":["filename","label"]}}},"required":["documents"]},"example":{"documents":[{"filename":"FS071 (Ocean) Bulk Invoice - 8.31.26.xlsx","label":"Invoice"},{"filename":"FS069-A-1 Final Packing List - 7.9.26.xlsx","label":"Packing List"},{"filename":"FS065_TOP Invoice - 4.30.26.xlsx","label":"Sample Invoice"},{"filename":"AYF (First Sale) Invoice_MB115-1.pdf","label":"Valuation Invoice"},{"filename":"Invoice-2_FLEX-4054612_2026-08-27.pdf","label":"Freight Invoice"},{"filename":"receiving-SS7740-FS071.pdf","label":"Unclassified"}]}}}},"400":{"description":"No filenames, too many, or one too long","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filenames":{"type":"array","items":{"type":"string","maxLength":500},"minItems":1,"maxItems":100}},"required":["filenames"]}}}}}},"/tally/documents/totals":{"post":{"operationId":"postTallyDocumentsTotals","description":"Compare a supplier invoice's totals against its purchase order. Send the document as `multipart/form-data` with a `reference`, which may be a vendor reference code or a purchase order number. Quantity and amount are reported separately: quantity agreeing while the amount differs distinguishes a pricing divergence from a valuation document.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["document","reference"],"properties":{"document":{"type":"string","format":"binary"},"reference":{"type":"string","example":"PO22756"}}}}}},"responses":{"200":{"description":"The comparison. A figure that could not be read is `not_extracted`, never a guess","content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string"},"invoiceDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrder":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"reference":{"type":"string"},"supplier":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"shipmentState":{"type":"string"},"invoiceState":{"type":"string"},"warehouse":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"operator":{"anyOf":[{"type":"string"},{"type":"null"}]},"site":{"anyOf":[{"type":"string"},{"type":"null"}]},"fulfillment":{"anyOf":[{"enum":["RTS","MTO"],"type":"string"},{"type":"null"}]},"bonded":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","code","operator","site","fulfillment","bonded"]},{"type":"null"}]}},"required":["id","number","reference","supplier","state","shipmentState","invoiceState","warehouse"]},"extraction":{"type":"object","properties":{"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"outcome":{"enum":["extracted","partial","no_totals","no_text_layer","unsupported_type","unreadable"],"type":"string"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","outcome","detail"]},"quantity":{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrder":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta":{"anyOf":[{"type":"string"},{"type":"null"}]},"deltaPercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"outcome":{"enum":["match","differs","not_extracted"],"type":"string"}},"required":["document","purchaseOrder","delta","deltaPercent","outcome"]},"amount":{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrder":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta":{"anyOf":[{"type":"string"},{"type":"null"}]},"deltaPercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"outcome":{"enum":["match","differs","not_extracted"],"type":"string"}},"required":["document","purchaseOrder","delta","deltaPercent","outcome"]}},"required":["reference","invoiceDate","purchaseOrder","extraction","quantity","amount"]},"example":{"reference":"PO22756","invoiceDate":"2026-06-08","purchaseOrder":{"id":27185,"number":"PO22756","reference":"FS066","supplier":"Fashion Star","state":"done","shipmentState":"received","invoiceState":"posted","warehouse":{"id":284,"code":"SM_KY2","operator":"ShipMonk","site":"KY2","fulfillment":"RTS","bonded":false}},"extraction":{"source":"xlsx","outcome":"extracted","detail":null},"quantity":{"document":"950","purchaseOrder":"950","delta":"0","deltaPercent":0,"outcome":"match"},"amount":{"document":"31375.55","purchaseOrder":"31701.45","delta":"-325.90","deltaPercent":-1.03,"outcome":"differs"}}}}},"400":{"description":"No document, no reference, a malformed reference, or a document over the size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"A document is required"}}}},"404":{"description":"No purchase order has that reference","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"The reference matches more than one purchase order","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"413":{"description":"The document is larger than the size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"The document is larger than 20MB"}}}},"422":{"description":"The reference matches a draft purchase order, which carries no number","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Fulfil throttled us for longer than the retry budget allows","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is rate limiting us; retry shortly"}}}},"502":{"description":"Fulfil unreachable after retries","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is unavailable"}}}}}}},"/tally/documents/receipt":{"post":{"operationId":"postTallyDocumentsReceipt","description":"Compare a supplier invoice's totals against what was received. Send the document as `multipart/form-data` with a `reference`. Receiving a shipment makes Fulfil raise a supplier invoice priced at the quantity that arrived, and that is the payable — a supplier who bills the full order on a short shipment agrees with the purchase order and still overcharges. An order whose goods have not arrived returns `not_received`.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["document","reference"],"properties":{"document":{"type":"string","format":"binary"},"reference":{"type":"string","example":"AL011"}}}}}},"responses":{"200":{"description":"The comparison. `not_received` is a 200 as well","content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string"},"outcome":{"enum":["compared","not_received"],"type":"string"},"invoiceDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrder":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"reference":{"type":"string"},"supplier":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"shipmentState":{"type":"string"},"invoiceState":{"type":"string"},"warehouse":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"operator":{"anyOf":[{"type":"string"},{"type":"null"}]},"site":{"anyOf":[{"type":"string"},{"type":"null"}]},"fulfillment":{"anyOf":[{"enum":["RTS","MTO"],"type":"string"},{"type":"null"}]},"bonded":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","code","operator","site","fulfillment","bonded"]},{"type":"null"}]}},"required":["id","number","reference","supplier","state","shipmentState","invoiceState","warehouse"]},"receipt":{"anyOf":[{"type":"object","properties":{"invoiceId":{"type":"number"},"invoiceState":{"type":"string"},"amount":{"anyOf":[{"type":"string"},{"type":"null"}]},"quantity":{"anyOf":[{"type":"number"},{"type":"null"}]},"shipments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"number":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"quantity":{"anyOf":[{"type":"number"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","number","state","quantity","receivedAt"]}},"receivedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["invoiceId","invoiceState","amount","quantity","shipments","receivedAt"]},{"type":"null"}]},"extraction":{"type":"object","properties":{"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"outcome":{"enum":["extracted","partial","no_totals","no_text_layer","unsupported_type","unreadable"],"type":"string"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","outcome","detail"]},"quantity":{"anyOf":[{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta":{"anyOf":[{"type":"string"},{"type":"null"}]},"deltaPercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"outcome":{"enum":["match","differs","not_extracted"],"type":"string"}},"required":["document","receipt","delta","deltaPercent","outcome"]},{"type":"null"}]},"amount":{"anyOf":[{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta":{"anyOf":[{"type":"string"},{"type":"null"}]},"deltaPercent":{"anyOf":[{"type":"number"},{"type":"null"}]},"outcome":{"enum":["match","differs","not_extracted"],"type":"string"}},"required":["document","receipt","delta","deltaPercent","outcome"]},{"type":"null"}]}},"required":["reference","outcome","invoiceDate","purchaseOrder","receipt","extraction","quantity","amount"]},"example":{"reference":"AL011","outcome":"compared","invoiceDate":"2026-07-21","purchaseOrder":{"id":27352,"number":"PO22916","reference":"AL011","supplier":"Lianyungang Aolong Fashion Co.,Ltd","state":"processing","shipmentState":"received","invoiceState":"waiting","warehouse":{"id":284,"code":"SM_KY2","operator":"ShipMonk","site":"KY2","fulfillment":"RTS","bonded":false}},"receipt":{"invoiceId":6211881,"invoiceState":"draft","amount":"114734.02","quantity":4647,"shipments":[{"id":7920,"number":"SS7920","state":"done","quantity":4647,"receivedAt":"2026-09-30"}],"receivedAt":"2026-09-30"},"extraction":{"source":"xlsx","outcome":"extracted","detail":null},"quantity":{"document":"4661","receipt":"4647","delta":"14","deltaPercent":0.3,"outcome":"differs"},"amount":{"document":"115071.76","receipt":"114734.02","delta":"337.74","deltaPercent":0.29,"outcome":"differs"}}}}},"400":{"description":"No document, no reference, or a malformed reference","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"A document is required"}}}},"404":{"description":"No purchase order has that reference","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"The reference matches more than one purchase order","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"413":{"description":"The document is larger than the size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"The document is larger than 20MB"}}}},"422":{"description":"The reference matches a draft purchase order, which carries no number","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Fulfil throttled us for longer than the retry budget allows","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is rate limiting us; retry shortly"}}}},"502":{"description":"Fulfil unreachable after retries","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is unavailable"}}}}}}},"/tally/documents/read":{"post":{"operationId":"postTallyDocumentsRead","description":"Read a document and return what it says: its totals, and every purchase order it names. Unlike `/match`, which resolves one order from a filename, this reads the document itself and returns every order it references — a freight invoice commonly covers several. Codes that reach no order are returned under `unresolved` rather than dropped.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["document"],"properties":{"document":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"What the document says. A figure that could not be read is null, never a guess","content":{"application/json":{"schema":{"type":"object","properties":{"invoiceDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"amount":{"anyOf":[{"type":"string"},{"type":"null"}]},"quantity":{"anyOf":[{"type":"number"},{"type":"null"}]},"lineItemsTotal":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrders":{"type":"array","items":{"type":"object","properties":{"reference":{"type":"string"},"number":{"type":"string"},"supplier":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string"},"shipmentState":{"type":"string"},"invoiceState":{"type":"string"}},"required":["reference","number","supplier","state","shipmentState","invoiceState"]}},"unresolved":{"type":"array","items":{"type":"string"}},"extraction":{"type":"object","properties":{"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"outcome":{"enum":["extracted","partial","no_totals","no_text_layer","unsupported_type","unreadable"],"type":"string"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","outcome","detail"]}},"required":["invoiceDate","amount","quantity","lineItemsTotal","purchaseOrders","unresolved","extraction"]},"example":{"invoiceDate":"2026-09-09","amount":"5067.98","quantity":null,"lineItemsTotal":"5067.98","purchaseOrders":[{"reference":"AL007","number":"PO23061","supplier":"Lianyungang Aolong Fashion Co.,Ltd","state":"processing","shipmentState":"waiting","invoiceState":"none"},{"reference":"AL008","number":"PO22838","supplier":"Lianyungang Aolong Fashion Co.,Ltd","state":"processing","shipmentState":"waiting","invoiceState":"none"}],"unresolved":[],"extraction":{"source":"pdf","outcome":"extracted","detail":null}}}}},"400":{"description":"No document, or one over the size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"A document is required"}}}},"413":{"description":"The document is larger than the size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"The document is larger than 20MB"}}}},"429":{"description":"Fulfil throttled us for longer than the retry budget allows","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is rate limiting us; retry shortly"}}}},"502":{"description":"Fulfil unreachable after retries","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is unavailable"}}}}}}},"/tally/documents/line-items":{"post":{"operationId":"postTallyDocumentsLineItems","description":"Compare a packing list's per-SKU quantities and prices against its purchase order lines. Send the document as `multipart/form-data` with a `reference`. A variance is reported as the SKUs driving it, grouped by style and colorway, rather than as one figure. SKUs on the document with no order line, and order lines with no document row, are reported as their own outcomes and never summed with a price variance.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["document","reference"],"properties":{"document":{"type":"string","format":"binary"},"reference":{"type":"string","example":"FS066"}}}}}},"responses":{"200":{"description":"One row per SKU, plus grouped variances. `no_table` is a 200 as well","content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string"},"purchaseOrder":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"supplier":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","number","reference","supplier"]},"outcome":{"enum":["compared","no_table"],"type":"string"},"source":{"anyOf":[{"type":"object","properties":{"sheet":{"type":"string"},"priceHeader":{"type":"string"},"strategy":{"enum":["template","description"],"type":"string"}},"required":["sheet","priceHeader","strategy"]},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"styleNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"colorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"colorName":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"anyOf":[{"type":"string"},{"type":"null"}]},"outcome":{"enum":["agreed","quantity","price","quantity_and_price","unmatched","missing"],"type":"string"},"quantity":{"type":"object","properties":{"document":{"anyOf":[{"type":"number"},{"type":"null"}]},"purchaseOrder":{"anyOf":[{"type":"number"},{"type":"null"}]},"delta":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["document","purchaseOrder","delta"]},"price":{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrder":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["document","purchaseOrder","delta"]},"amountDelta":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sku","styleNumber","colorCode","colorName","size","outcome","quantity","price","amountDelta"]}},"groups":{"type":"array","items":{"type":"object","properties":{"colorway":{"type":"string"},"styleNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"colorName":{"anyOf":[{"type":"string"},{"type":"null"}]},"sizes":{"type":"array","items":{"type":"string"}},"skus":{"type":"number"},"quantity":{"type":"object","properties":{"document":{"type":"number"},"purchaseOrder":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["document","purchaseOrder"]},"price":{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"purchaseOrder":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["document","purchaseOrder"]},"amountDelta":{"type":"string"}},"required":["colorway","styleNumber","colorName","sizes","skus","quantity","price","amountDelta"]}},"totals":{"type":"object","properties":{"skus":{"type":"number"},"agreed":{"type":"number"},"variances":{"type":"number"},"unmatched":{"type":"number"},"missing":{"type":"number"},"varianceAmount":{"type":"string"},"unmatchedAmount":{"type":"string"},"pricedAbove":{"type":"number"},"pricedBelow":{"type":"number"}},"required":["skus","agreed","variances","unmatched","missing","varianceAmount","unmatchedAmount","pricedAbove","pricedBelow"]}},"required":["reference","purchaseOrder","outcome","source","lines","groups","totals"]},"example":{"reference":"FS066","purchaseOrder":{"id":27185,"number":"PO22756","reference":"FS066","supplier":"Fashion Star"},"outcome":"compared","source":{"sheet":"Size Detail","priceHeader":"FOB (USD)","strategy":"template"},"lines":[{"sku":"BG201PK0015013","styleNumber":"BG201","colorCode":"PK0015013","colorName":"Bubblegum Pink","size":"XXS","outcome":"price","quantity":{"document":6,"purchaseOrder":6,"delta":0},"price":{"document":"24.00","purchaseOrder":"28.6","delta":"-4.60"},"amountDelta":"-27.60"}],"groups":[{"colorway":"AA481PK0015","styleNumber":"AA481","colorName":"Bubblegum Pink","sizes":["XXS","XS","S","M","L","XL","XXL"],"skus":7,"quantity":{"document":38,"purchaseOrder":38},"price":{"document":"39.55","purchaseOrder":"47.4"},"amountDelta":"-298.30"},{"colorway":"BG201PK0015","styleNumber":"BG201","colorName":"Bubblegum Pink","sizes":["XXS"],"skus":1,"quantity":{"document":6,"purchaseOrder":6},"price":{"document":"24.00","purchaseOrder":"28.6"},"amountDelta":"-27.60"}],"totals":{"skus":185,"agreed":177,"variances":8,"unmatched":0,"missing":0,"varianceAmount":"-325.90","unmatchedAmount":"0.00","pricedAbove":0,"pricedBelow":8}}}}},"400":{"description":"No document, no reference, or a malformed reference","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"A document is required"}}}},"404":{"description":"The reference matches no purchase order","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"The reference matches more than one purchase order","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"413":{"description":"The document is larger than 20MB","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"The document is larger than 20MB"}}}},"422":{"description":"The reference matches a draft purchase order, which carries no number","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Fulfil throttled us for longer than the retry budget allows","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is rate limiting us; retry shortly"}}}},"502":{"description":"Fulfil unreachable after retries","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is unavailable"}}}}}}},"/tally/documents/receipt/line-items":{"post":{"operationId":"postTallyDocumentsReceiptLineItems","description":"Compare a supplier invoice's per-SKU quantities and prices against what arrived, rather than against what was ordered. Send the document as `multipart/form-data` with a `reference`. A SKU the receipt does not carry is reported as `missing` — a style that did not arrive at all. An order with nothing received yet is a 422.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["document","reference"],"properties":{"document":{"type":"string","format":"binary"},"reference":{"type":"string","example":"AL011"}}}}}},"responses":{"200":{"description":"One row per SKU, plus grouped variances. `no_table` is a 200 as well","content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string"},"purchaseOrder":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"supplier":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","number","reference","supplier"]},"invoiceId":{"type":"number"},"outcome":{"enum":["compared","no_table"],"type":"string"},"source":{"anyOf":[{"type":"object","properties":{"sheet":{"type":"string"},"priceHeader":{"type":"string"},"strategy":{"enum":["template","description"],"type":"string"}},"required":["sheet","priceHeader","strategy"]},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"styleNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"colorCode":{"anyOf":[{"type":"string"},{"type":"null"}]},"colorName":{"anyOf":[{"type":"string"},{"type":"null"}]},"size":{"anyOf":[{"type":"string"},{"type":"null"}]},"outcome":{"enum":["agreed","quantity","price","quantity_and_price","unmatched","missing"],"type":"string"},"quantity":{"type":"object","properties":{"document":{"anyOf":[{"type":"number"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"number"},{"type":"null"}]},"delta":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["document","receipt","delta"]},"price":{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"string"},{"type":"null"}]},"delta":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["document","receipt","delta"]},"amountDelta":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sku","styleNumber","colorCode","colorName","size","outcome","quantity","price","amountDelta"]}},"groups":{"type":"array","items":{"type":"object","properties":{"colorway":{"type":"string"},"styleNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"colorName":{"anyOf":[{"type":"string"},{"type":"null"}]},"sizes":{"type":"array","items":{"type":"string"}},"skus":{"type":"number"},"quantity":{"type":"object","properties":{"document":{"type":"number"},"receipt":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["document","receipt"]},"price":{"type":"object","properties":{"document":{"anyOf":[{"type":"string"},{"type":"null"}]},"receipt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["document","receipt"]},"amountDelta":{"type":"string"}},"required":["colorway","styleNumber","colorName","sizes","skus","quantity","price","amountDelta"]}},"totals":{"type":"object","properties":{"skus":{"type":"number"},"agreed":{"type":"number"},"variances":{"type":"number"},"unmatched":{"type":"number"},"missing":{"type":"number"},"varianceAmount":{"type":"string"},"unmatchedAmount":{"type":"string"},"pricedAbove":{"type":"number"},"pricedBelow":{"type":"number"}},"required":["skus","agreed","variances","unmatched","missing","varianceAmount","unmatchedAmount","pricedAbove","pricedBelow"]}},"required":["reference","purchaseOrder","invoiceId","outcome","source","lines","groups","totals"]},"example":{"reference":"AL011","purchaseOrder":{"id":27352,"number":"PO22916","reference":"AL011","supplier":"Lianyungang Aolong Fashion Co.,Ltd"},"invoiceId":6211881,"outcome":"compared","source":{"sheet":"invoice","priceHeader":"TTL FOB COST","strategy":"description"},"lines":[{"sku":"AA472BL0016003","styleNumber":"AA472","colorCode":"BL0016003","colorName":"Lydia Chiffon Dress","size":"M","outcome":"quantity","quantity":{"document":36,"receipt":21,"delta":15},"price":{"document":"24.69","receipt":"24.69","delta":"0.00"},"amountDelta":"370.35"}],"groups":[],"totals":{"skus":500,"agreed":483,"variances":17,"unmatched":0,"missing":7,"varianceAmount":"337.74","unmatchedAmount":"0.00","pricedAbove":0,"pricedBelow":0}}}}},"400":{"description":"No document, no reference, or a malformed reference","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"A document is required"}}}},"404":{"description":"The reference matches no purchase order","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"The reference matches more than one purchase order","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"413":{"description":"The document is larger than 20MB","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"The document is larger than 20MB"}}}},"422":{"description":"The order is a draft, or nothing has been received so there is no invoice to compare against","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Fulfil throttled us for longer than the retry budget allows","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is rate limiting us; retry shortly"}}}},"502":{"description":"Fulfil unreachable after retries","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"example":{"error":"Fulfil is unavailable"}}}}}}}},"components":{}}