Insert sales order

Request

Security

OAuth2(Required scopes: enrichment.write)

Bodyapplication/jsonrequired

externalIdstring^\S+$required

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

Example:"DE01"

externalClientIdstring

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

Example:"EXTERNAL_CLIENT_ID"

documentIdstring^[0-9a-fA-F]{24}$

Document id that was assigned during upload to Hypatos

Example:"63cac12c37bb02accb396cae"

documentsArray of objects(document)

customerOrderNumberstring

Sales order number provided by the issuing customer

Example:"CUSTOMER_ORDER_NUMBER"

salesOrderNumberstring

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

Example:"SALES_ORDER_NUMBER"

externalCompanyIdstring

External unique id of the company in the source system

Example:"DE01"

externalCustomerIdstring

External unique id of the customer in the source system

Example:"CO01"

salesOrganizationCodestring

Sales organization code

Example:"SO001"

distributionChannelstring

Distribution channel code

Example:"CH1"

divisionstring

Division code

Example:"DIV01"

salesGroupstring

Sales group responsible for the order

Example:"123456"

salesOfficestring

Sales office responsible for the order

Example:"98765"

typestring

Type of the invoice as defined in the source system

Example:"OR"

subTypestring

Sub type of the invoice as defined in the source system

Example:"recurring"

issuedDatestring, (date)

Date when the invoice was issued by the supplier (printed on invoice document)

Example:"2000-12-31"

receivedDatestring, (date)

Date when the invoice was received by the company

Example:"2000-12-31"

fiscalYearLabelstring

Label used in the source system for the fiscal year that the invoice was posted in

Example:"2023"

requestedDeliveryDatestring, (date)

Requested delivery date

Example:"2000-12-31"

isCanceledboolean

Indicator if the invoice is canceled

Example:false

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 sales order (sum of line item net amounts)

Example:100

totalTaxAmountnumber

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

Example:19

totalGrossAmountnumber

Total gross amount of sales order (total net amount + total tax amount)

Example:119

paymentTermsobject(paymentTerms)

headerTextstring

Header Text describing the invoice

Example:"doc header text"

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"
  ]
}

salesOrderLinesArray of objects(salesOrderLine)

curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/enrichment/sales-orders \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "DE01",
    "externalClientId": "EXTERNAL_CLIENT_ID",
    "documentId": "63cac12c37bb02accb396cae",
    "documents": [
      {
        "id": "63cac12c37bb02accb396cae",
        "type": "invoice"
      }
    ],
    "customerOrderNumber": "CUSTOMER_ORDER_NUMBER",
    "salesOrderNumber": "SALES_ORDER_NUMBER",
    "externalCompanyId": "DE01",
    "externalCustomerId": "CO01",
    "salesOrganizationCode": "SO001",
    "distributionChannel": "CH1",
    "division": "DIV01",
    "salesGroup": "123456",
    "salesOffice": "98765",
    "type": "OR",
    "subType": "recurring",
    "issuedDate": "2000-12-31",
    "receivedDate": "2000-12-31",
    "fiscalYearLabel": "2023",
    "requestedDeliveryDate": "2000-12-31",
    "isCanceled": false,
    "currency": "EUR",
    "totalNetAmount": 100,
    "totalTaxAmount": 19,
    "totalGrossAmount": 119,
    "paymentTerms": {
      "paymentTermKey": "T10",
      "descriptions": [
        {
          "text": "Please pay us",
          "language": "en"
        }
      ]
    },
    "headerText": "doc header text",
    "customFields": {
      "property1": "string",
      "property2": "string"
    },
    "customMetadata": {
      "someTopLevelProperty": "value1",
      "someNestedProperty": {
        "nestedProperty": "value2"
      },
      "someArrayProperty": [
        "value3",
        "value4"
      ]
    },
    "salesOrderLines": [
      {
        "plannedDeliveryDate": "2025-08-27",
        "orderLineNumber": "00000001",
        "externalCompanyId": "DE01",
        "externalProductId": "PO01",
        "quantity": 2,
        "unitOfMeasure": "kg",
        "unitPrice": 100,
        "netAmount": 200,
        "totalTaxAmount": 38,
        "grossAmount": 238,
        "taxCode": {
          "code": "DEU_Standard",
          "description": "DEU - Standard (19%)"
        },
        "description": "DEU - Standard (19%)",
        "plant": "PLANT-001",
        "storageLocation": "BOX-001",
        "externalShippingAddressId": "DE-123E",
        "externalBillingAddressId": "DE-123E",
        "itemText": "Sold item ABC",
        "type": "Item type",
        "externalQuoteId": "EQ01",
        "quoteLineNumber": "LN01",
        "externalContractId": "ECID01",
        "customFields": {
          "property1": "string",
          "property2": "string"
        },
        "customMetadata": {
          "someTopLevelProperty": "value1",
          "someNestedProperty": {
            "nestedProperty": "value2"
          },
          "someArrayProperty": [
            "value3",
            "value4"
          ]
        }
      }
    ]
  }'

Responses

Successfully inserted

Bodyapplication/json

idstringrequired

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

Response

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