Insert purchase order including purchase order lines

Request

Security

OAuth2(Required scopes: enrichment.write)

Bodyapplication/jsonrequired

externalIdstring^\S+$required

External id of the purchase order that is globally unique across the provided purchase order data

Example:"4500016221"

externalClientIdstring

Identifier of the client entity in the source system which can be used to separate data

Example:"EXTERNAL_CLIENT_ID"

purchaseOrderNumberstring

Number of the purchase order in the source system (not unique across clients)

Example:"PoNumber123"

createdDatestring, (date)

Date when the purchase order was created in the external system

Example:"2000-12-31"

fiscalYearLabelstring

Label used in the source system for the fiscal year that the purchase order was created in

Example:"2023"

languagestring or null(LanguageCode)

Two letter language code as defined in ISO 639-1

Enum:"aa""ab""ae""af""ak""am""an""ar""as""av"

Example:"en"

externalCompanyIdstring

Company that the purchase order is assigned to

Example:"DE01"

typestring

type of the purchase order as defined in the source system

Example:"Service"

externalSupplierIdstring

External unique id of the supplier in the source system

Example:"0000100000"

statusstring

Status of purchase order as defined in source system

Example:"OPEN"

invoicingStatusstring(invoicingStatus)

Indicates the invoicing progress of the purchase order (line) based on invoices posted against it

Enum:"outstanding""partial""complete"

Example:"partial"

deliveryStatusstring(deliveryStatus)

Indicates the delivery progress of the purchase order (line) based on goods receipts or service confirmations

Enum:"outstanding""partial""complete"

Example:"partial"

currencystring or null(CurrencyCode)

Three letter currency code as defined in ISO 4217

Enum:"AED""AFN""ALL""AMD""ANG""AOA""ARS""AUD""AWG""AZN"

Example:"EUR"

totalNetAmountnumber

Total net amount of purchase order (sum of line item net amounts)

Example:81

totalFreightChargesnumber

Sum of all freight charges as defined on the purchase order

Example:9

totalOtherChargesnumber

Sum of all charges other than freight charges as defined on the purchase order

Example:10

totalTaxAmountnumber

Total tax amount of purchase order (sum of all taxes)

Example:19

totalGrossAmountnumber

Total gross amount of purchase order (total net amount + total freight charges + total other charges + total tax amount)

Example:119

totalInvoicedNetAmountnumber

Total net amount invoiced for this purchase order, calculated as the sum of the net amounts of all invoices posted against it

Example:119

paymentTermsobject(paymentTerms)

customFieldsobject(customFields)

List of key value pairs containing custom fields from the source system

customMetadataobject(JsonObject)

Any nested structure with metadata that source system needs to send

Example:

{
  "someTopLevelProperty": "value1",
  "someNestedProperty": {
    "nestedProperty": "value2"
  },
  "someArrayProperty": [
    "value3",
    "value4"
  ]
}

purchaseOrderLinesArray of objects(purchaseOrderLine)

productNumberstring

Number of the product as defined by the purchaser

Example:"123456789"

externalPurchaserIdstring

External unique id of the responsible purchaser in the source system

Example:"PUR-88293-X"

deliveryTermsobject(deliveryTerms)

Object containing delivery terms information as defined in the source system

curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/enrichment/purchase-orders \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "4500016221",
    "externalClientId": "EXTERNAL_CLIENT_ID",
    "purchaseOrderNumber": "PoNumber123",
    "createdDate": "2000-12-31",
    "fiscalYearLabel": "2023",
    "language": "string",
    "externalCompanyId": "DE01",
    "type": "Service",
    "externalSupplierId": "0000100000",
    "status": "OPEN",
    "invoicingStatus": "partial",
    "deliveryStatus": "partial",
    "currency": "EUR",
    "totalNetAmount": 81,
    "totalFreightCharges": 9,
    "totalOtherCharges": 10,
    "totalTaxAmount": 19,
    "totalGrossAmount": 119,
    "totalInvoicedNetAmount": 119,
    "paymentTerms": {
      "paymentTermKey": "T10",
      "descriptions": [
        {
          "text": "Please pay us",
          "language": "en"
        }
      ]
    },
    "customFields": {
      "property1": "string",
      "property2": "string"
    },
    "customMetadata": {
      "someTopLevelProperty": "value1",
      "someNestedProperty": {
        "nestedProperty": "value2"
      },
      "someArrayProperty": [
        "value3",
        "value4"
      ]
    },
    "purchaseOrderLines": [
      {
        "purchaseOrderLineNumber": "00010",
        "externalCompanyId": "DE01",
        "accountAssignments": [
          {
            "externalGlAccountId": "0000100GL1",
            "externalCostCenterId": "0000100CO1",
            "glAccountCode": "GL1",
            "costCenterCode": "CO1",
            "quantity": 2,
            "externalProjectId": "EPI1",
            "externalOrderId": "EOI1",
            "costElementCode": "CE1",
            "externalProfitCenterId": "EPCI1",
            "profitCenterCode": "PCC1"
          }
        ],
        "type": "Service",
        "subType": "Extra Qualifier",
        "quantity": 2,
        "status": "OPEN",
        "invoicingStatus": "partial",
        "deliveryStatus": "partial",
        "netAmount": 1.23,
        "totalTaxAmount": 1.23,
        "grossAmount": 100.01,
        "unitOfMeasure": "kg",
        "orderUnit": {
          "unitOfMeasure": "KAR",
          "conversionFactorToBaseUnit": 30
        },
        "unitPrice": 19.0123,
        "taxCode": {
          "code": "DEU_Standard",
          "description": "DEU - Standard (19%)"
        },
        "itemText": "Dell Laptop Latitude D630",
        "material": {
          "externalId": "2a6300181f08402e710ea3f180214bc1",
          "supplierNumber": "123456789",
          "type": "Operating Supplies",
          "group": "Electronics",
          "description": "Dell Laptop Latitude D630",
          "manufacturer": "Acme Corporation",
          "manufacturerNumber": "ACME-12345",
          "unspsc": "43211508",
          "ean": "4006381333931",
          "baseUnitOfMeasure": "PCE"
        },
        "plant": "PLANT-001",
        "delivered": true,
        "completelyInvoiced": true,
        "approved": true,
        "plannedDeliveryDate": "2025-08-27",
        "customFields": {
          "property1": "string",
          "property2": "string"
        },
        "customMetadata": {
          "someTopLevelProperty": "value1",
          "someNestedProperty": {
            "nestedProperty": "value2"
          },
          "someArrayProperty": [
            "value3",
            "value4"
          ]
        },
        "deliveryAddress": {
          "street": "123 Industrial Way",
          "addressAdditional": "Suite 500, Dock 4",
          "postcode": "90001",
          "city": "Los Angeles",
          "state": "CA",
          "countryCode": "DE"
        },
        "deliveredQuantity": 55,
        "orderConfirmations": [
          {
            "lineNumber": "0090",
            "deliveryDate": "2024-10-15",
            "quantity": 95,
            "supplierReference": "SUP-REF-00192",
            "createdAt": "2024-09-01"
          }
        ],
        "externalPlannerId": "PLAN-4410-B",
        "accountAssignmentType": "K",
        "conditions": [
          {
            "conditionType": "ZL01",
            "description": "Alloy surcharge",
            "amount": 12.5,
            "currency": "EUR"
          }
        ]
      }
    ],
    "productNumber": "123456789",
    "externalPurchaserId": "PUR-88293-X",
    "deliveryTerms": {
      "deliveryTermKey": "FOB",
      "descriptions": [
        {
          "text": "Free on Board - Port of Los Angeles",
          "language": "en"
        },
        {
          "text": "Franco a bordo - Puerto de Los Ángeles",
          "language": "es"
        }
      ],
      "additionalInfo": "Some additional info"
    }
  }'

Responses

Successfully inserted

Bodyapplication/json

idstringrequired

Example:"3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"

Response

{
  "id": "3a429dc8-56d4-42ef-a4cf-2ebc9ad1ef38"
}