Menu

API reference

Purchasing

Suppliers, requests for quotes, purchase orders, goods received, supplier invoices and returns, and the supply graph (needs a graph backend). Suppliers in the demo are simulated.

get

/v1/graph/ingredients/{id}

What a price change of one ingredient touches: its suppliers, the dishes and outlets it reaches, and the open findings and pending drafts on them (owner, manager, judge; outlet scope from the membership). Needs a graph backend: 404 where core-api runs without one, 503 graph_unavailable while the graph database is not answering.

operationId getIngredientReach

Auth

Member token+Tenant header

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

V1GraphIngredientcontract v1.graph.ingredient
  • ingredientobjectrequired
    • idUuid7required
    • namestringrequired
      min length 1max length 300
    • unitstringrequired
      min length 1max length 20
  • sourcesarray of objectrequired
    • supplier_idUuid7required
    • namestringrequired
      min length 1max length 300
    • simulatedbooleanrequired
    • relationenum (2)required
      suppliesquoted
  • dishesarray of objectrequired
    • item_idUuid7required
    • namestringrequired
      min length 1max length 300
    • recipe_idUuid7 | nullrequired
    • outletsarray of objectrequired
      • outlet_idUuid7required
      • namestringrequired
        min length 1max length 300
      • availablebooleanrequired
  • outletsarray of objectrequired
    • outlet_idUuid7required
    • namestringrequired
      min length 1max length 300
  • findingsarray of objectrequired
    • finding_idUuid7required
    • typestringrequired
      pattern ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$
    • severityenum (4)required
      lowmediumhighcritical
    • impact_refstring | nullrequired
      pattern ^⟨snap:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}·(?:0|[1-9][0-9]*)·[a-z_][a-z0-9_]*⟩$
    • about_idsarray of Uuid7required
  • draftsarray of objectrequired
    • draft_idUuid7required
    • command_typestringrequired
      pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
    • about_idsarray of Uuid7required
  • graphobjectrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/graph/suppliers/{id}

What depends on one supplier: each ingredient it supplies, whether it is the only source, who else supplies or quoted, and the dishes and outlets it reaches. Needs a graph backend: 404 where core-api runs without one, 503 graph_unavailable while the graph database is not answering.

operationId getSupplierReach

Auth

Member token+Tenant header

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

V1GraphSuppliercontract v1.graph.supplier
  • supplierobjectrequired
    • supplier_idUuid7required
    • namestringrequired
      min length 1max length 300
    • simulatedbooleanrequired
  • ingredientsarray of objectrequired
    • ingredient_idUuid7required
    • namestringrequired
      min length 1max length 300
    • only_sourcebooleanrequired
    • other_sourcesarray of objectrequired
      • supplier_idUuid7required
      • namestringrequired
        min length 1max length 300
      • simulatedbooleanrequired
    • quoted_byarray of objectrequired
      • supplier_idUuid7required
      • namestringrequired
        min length 1max length 300
      • simulatedbooleanrequired
    • dishesarray of objectrequired
      • item_idUuid7required
      • namestringrequired
        min length 1max length 300
      • outletsarray of objectrequired
        Show fields of outlets
        • outlet_idUuid7required
        • namestringrequired
          min length 1max length 300
        • availablebooleanrequired
    • outletsarray of objectrequired
      • outlet_idUuid7required
      • namestringrequired
        min length 1max length 300
  • findingsarray of objectrequired
    • finding_idUuid7required
    • typestringrequired
      pattern ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$
    • severityenum (4)required
      lowmediumhighcritical
    • impact_refstring | nullrequired
      pattern ^⟨snap:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}·(?:0|[1-9][0-9]*)·[a-z_][a-z0-9_]*⟩$
    • about_idsarray of Uuid7required
  • draftsarray of objectrequired
    • draft_idUuid7required
    • command_typestringrequired
      pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
    • about_idsarray of Uuid7required
  • graphobjectrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/graph/sole-sources

Ingredients of dishes on the menu with one supplier on record or none. Needs a graph backend: 404 where core-api runs without one, 503 graph_unavailable while the graph database is not answering.

operationId listSoleSources

Auth

Member token+Tenant header

Response 200

V1GraphSoleSourcescontract v1.graph.sole-sources
  • ingredientsarray of objectrequired
    • ingredient_idUuid7required
    • namestringrequired
      min length 1max length 300
    • sourcesarray of objectrequired
      • supplier_idUuid7required
      • namestringrequired
        min length 1max length 300
      • simulatedbooleanrequired
  • graphobjectrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/suppliers

Suppliers; simulated ones carry the label "Simulated supplier"

operationId listSuppliers

Auth

Member token+Tenant header

Response 200

V1Supplierscontract v1.suppliers

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/suppliers

purchasing.supplier.upsert.v1 — create or update a supplier (kind is fixed)

operationId upsertSupplier

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "purchasing.supplier.upsert.v1"required
  • payloadPurchasingSupplierUpsertV1required

Response 201

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/suppliers/{id}

One supplier with its price observations

operationId getSupplier

Auth

Member token+Tenant header

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

V1Suppliercontract v1.supplier
  • supplier_idUuid7required
  • namestringrequired
    min length 1max length 200
  • kindenum (2)required
    realsimulated
  • labelconst "Simulated supplier" | nullrequired
  • a2a_card_urlstring | nullrequired
  • payment_daysinteger | nullrequired
    ≥ -9007199254740991≤ 9007199254740991
  • notesstring | nullrequired
  • activebooleanrequired
  • pricesarray of objectrequired
    • price_idUuid7required
    • ingredient_idUuid7required
    • unitstringrequired
      pattern ^[a-z][a-z_]{0,15}$
    • unit_price_minorintegerrequired
      ≥ 0≤ 9007199254740991
    • currencystringrequired
      pattern ^[A-Z]{3}$
    • observed_atIsoDatetimerequired
    • source_refstringrequired
      min length 1max length 200

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/purchase-orders

Purchase orders touching the caller's outlets (a pooled PO shows to each listed outlet's managers)

operationId listPurchaseOrders

Auth

Member token+Tenant header

Response 200

V1PurchaseOrderscontract v1.purchase-orders

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/purchase-orders

purchasing.po.create.v1 — commit a purchase order (single or pooled)

operationId createPurchaseOrder

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "purchasing.po.create.v1"required
  • payloadPurchasingPoCreateV1required

Response 201

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/purchase-orders/{id}

One purchase order with its lines

operationId getPurchaseOrder

Auth

Member token+Tenant header

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

V1PurchaseOrdercontract v1.purchase-order
  • po_idUuid7required
  • supplierobjectrequired
    • supplier_idUuid7required
    • namestringrequired
      min length 1max length 200
    • kindenum (2)required
      realsimulated
    • labelconst "Simulated supplier" | nullrequired
  • outlet_idsarray of Uuid7required
  • statusenum (3)required
    committedreceivedcancelled
  • currencystringrequired
    pattern ^[A-Z]{3}$
  • total_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • expected_onstring (date) | nullrequired
    pattern ^(?:(?:[0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|(?:02)-(?:0[1-9]|1[0-9]|2[0-8])))$
  • negotiation_run_idUuid7 | nullrequired
  • created_atIsoDatetimerequired
  • linesarray of objectrequired
    • po_line_idUuid7required
    • line_nointegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • ingredient_idUuid7required
    • qty_milliintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • unitstringrequired
      pattern ^[a-z][a-z_]{0,15}$
    • unit_price_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/goods-received

Goods received in the caller's outlets

operationId listGoodsReceived

Auth

Member token+Tenant header

Response 200

V1GoodsReceivedListcontract v1.goods-received.list

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/goods-received

purchasing.grn.receive.v1 — receive goods (creates batches, stock movements and postings)

operationId receiveGoods

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "purchasing.grn.receive.v1"required
  • payloadPurchasingGrnReceiveV1required

Response 201

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/goods-received/{id}

One goods-received note with its lines

operationId getGoodsReceived

Auth

Member token+Tenant header

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

V1GoodsReceivedcontract v1.goods-received
  • grn_idUuid7required
  • outlet_idUuid7required
  • supplierobjectrequired
    • supplier_idUuid7required
    • namestringrequired
      min length 1max length 200
    • kindenum (2)required
      realsimulated
    • labelconst "Simulated supplier" | nullrequired
  • po_idUuid7 | nullrequired
  • received_atIsoDatetimerequired
  • received_byUuid7required
  • notestring | nullrequired
  • linesarray of objectrequired
    • grn_line_idUuid7required
    • po_line_idUuid7 | nullrequired
    • ingredient_idUuid7required
    • batch_idUuid7 | nullrequired
    • qty_milliintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • unitstringrequired
      pattern ^[a-z][a-z_]{0,15}$
    • unit_cost_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • currencystringrequired
      pattern ^[A-Z]{3}$

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/supplier-invoices

Supplier invoices (not for staff)

operationId listSupplierInvoices

Auth

Member token+Tenant header

Response 200

V1SupplierInvoicescontract v1.supplier-invoices

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/supplier-invoices

purchasing.invoice.record.v1 — record an invoice; a repeated supplier + number is refused with 409

operationId recordSupplierInvoice

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "purchasing.invoice.record.v1"required
  • payloadPurchasingInvoiceRecordV1required

Response 201

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/supplier-invoices/{id}

One supplier invoice with its lines and derived payable

operationId getSupplierInvoice

Auth

Member token+Tenant header

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

V1SupplierInvoicecontract v1.supplier-invoice
  • supplier_invoice_idUuid7required
  • supplierobjectrequired
    • supplier_idUuid7required
    • namestringrequired
      min length 1max length 200
    • kindenum (2)required
      realsimulated
    • labelconst "Simulated supplier" | nullrequired
  • invoice_nostringrequired
  • invoice_datestring (date)required
    pattern ^(?:(?:[0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|(?:02)-(?:0[1-9]|1[0-9]|2[0-8])))$
  • po_idUuid7 | nullrequired
  • subtotal_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • tax_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • total_minorintegerrequired
    ≥ -9007199254740991≤ 9007199254740991
  • currencystringrequired
    pattern ^[A-Z]{3}$
  • statusenum (4)required
    recordedapproveddisputedvoid
  • created_atIsoDatetimerequired
  • linesarray of objectrequired
    • line_idUuid7required
    • line_nointegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • po_line_idUuid7 | nullrequired
    • ingredient_idUuid7 | nullrequired
    • descriptionstring | nullrequired
    • qty_milliintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • unitstringrequired
      pattern ^[a-z][a-z_]{0,15}$
    • unit_price_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • tax_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • line_total_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
  • payableobject | nullrequired
    • payable_idUuid7required
    • due_onstring (date)required
      pattern ^(?:(?:[0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|(?:02)-(?:0[1-9]|1[0-9]|2[0-8])))$
    • amount_minorintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • statusenum (4)required
      openpaiddisputedvoid

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/supplier-invoices/{id}:approve

purchasing.invoice.approve.v1 — approve a recorded invoice (owner); derives the payable

operationId approveSupplierInvoice

Auth

Member token+Tenant header

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "purchasing.invoice.approve.v1"required
  • payloadPurchasingInvoiceApproveV1required

Response 200

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/supplier-invoices/{id}:dispute

purchasing.invoice.dispute.v1 — record a dispute for the owner to send

operationId disputeSupplierInvoice

Auth

Member token+Tenant header

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "purchasing.invoice.dispute.v1"required
  • payloadPurchasingInvoiceDisputeV1required

Response 201

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/supplier-returns

Supplier returns in the caller's outlets

operationId listSupplierReturns

Auth

Member token+Tenant header

Response 200

V1SupplierReturnscontract v1.supplier-returns

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/supplier-returns

purchasing.supplier_return.create.v1 — return stock to a supplier

operationId createSupplierReturn

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "purchasing.supplier_return.create.v1"required
  • payloadPurchasingSupplierReturnCreateV1required

Response 201

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/rfq-requests

purchasing.rfq.request.v1 — ask the simulated suppliers to quote one ingredient for the chosen outlets; any purchase order comes back as a draft to approve

operationId requestQuotes

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "purchasing.rfq.request.v1"required
  • payloadPurchasingRfqRequestV1required

Response 201

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.