Insert invoice including invoice lines

Request

Security

OAuth2(Required scopes: enrichment.write)

Bodyapplication/jsonrequired

externalIdstring^\S+$required

External id of the invoice that is globally unique across the provided invoice data

Example:"SUPPLIER_INVOICE-3-1"

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)

supplierInvoiceNumberstring

Invoice number provided by the issuing supplier

Example:"10000001"

invoiceNumberstring

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

Example:"12345"

externalCompanyIdstring

External unique id of the company in the source system

Example:"DE01"

externalSupplierIdstring

External unique id of the supplier in the source system

Example:"0000100000"

externalBankAccountIdstring

External unique id of the bank account that the invoice payment was transferred to

Example:"12341234"

fiscalYearLabelstring

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

Example:"2023"

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 recieved by the company

Example:"2000-12-31"

postingDatestring, (date)

Date when the invoice was posted in the source system

Example:"2000-12-31"

isCanceledboolean

Indicator if the invoice is canceled

Example:false

isCreditNoteboolean

Indicator if the document is a credit note

externalCustomerIdstring

External unique id of the customer in the source system

relatedInvoicestring

externalInvoiceId of related invoice

Example:"SUPPLIER_INVOICE-3-2"

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

Example:81

totalFreightChargesnumber

Sum of all freight charges

Example:9

totalOtherChargesnumber

Sum of all charges other than freight charges

Example:10

totalTaxAmountnumber

Total tax amount of invoice (sum of all taxes)

Example:19

totalGrossAmountnumber

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

Example:119

paymentTermsobject(paymentTerms)

externalApproverIdstring

External unique id of the first approver of an invoice in the source system

Example:"UserID#1234"

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

headerTextstring

Header Text describing the invoice

Example:"doc header text"

typestring

type of the invoice as defined in th source system

Example:"FI"

invoiceLinesArray of objects, non-empty(invoiceLine)required

withholdingTaxArray of objects(withholdingTax)

documentTypestring

document type as defined in the source system

Example:"supplier invoice"

curl -i -X POST \
  https://api.cloud.hypatos.ai/v2/enrichment/invoices \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "SUPPLIER_INVOICE-3-1",
    "externalClientId": "EXTERNAL_CLIENT_ID",
    "documentId": "63cac12c37bb02accb396cae",
    "documents": [
      {
        "id": "63cac12c37bb02accb396cae",
        "type": "invoice"
      }
    ],
    "supplierInvoiceNumber": "10000001",
    "invoiceNumber": "12345",
    "externalCompanyId": "DE01",
    "externalSupplierId": "0000100000",
    "externalBankAccountId": "12341234",
    "fiscalYearLabel": "2023",
    "issuedDate": "2000-12-31",
    "receivedDate": "2000-12-31",
    "postingDate": "2000-12-31",
    "isCanceled": false,
    "isCreditNote": true,
    "externalCustomerId": "string",
    "relatedInvoice": "SUPPLIER_INVOICE-3-2",
    "currency": "EUR",
    "totalNetAmount": 81,
    "totalFreightCharges": 9,
    "totalOtherCharges": 10,
    "totalTaxAmount": 19,
    "totalGrossAmount": 119,
    "paymentTerms": {
      "paymentTermKey": "T10",
      "descriptions": [
        {
          "text": "Please pay us",
          "language": "en"
        }
      ]
    },
    "externalApproverId": "UserID#1234",
    "customFields": {
      "property1": "string",
      "property2": "string"
    },
    "customMetadata": {
      "someTopLevelProperty": "value1",
      "someNestedProperty": {
        "nestedProperty": "value2"
      },
      "someArrayProperty": [
        "value3",
        "value4"
      ]
    },
    "headerText": "doc header text",
    "type": "FI",
    "invoiceLines": [
      {
        "externalId": "00000001",
        "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",
        "quantity": 2,
        "netAmount": 1.23,
        "totalTaxAmount": 1.23,
        "grossAmount": 100.01,
        "unitOfMeasure": "kg",
        "unitPrice": 19.0123,
        "taxCode": {
          "code": "DEU_Standard",
          "description": "DEU - Standard (19%)"
        },
        "taxJurisdictionCode": "PA0000000",
        "itemText": "Virtual Event ABC",
        "externalPurchaseOrderId": "4500016221",
        "purchaseOrderLineNumber": "00010",
        "salesOrderNumber": "45001234",
        "salesOrderLineNumber": "20",
        "centralBankIndicator": "123",
        "customFields": {
          "property1": "string",
          "property2": "string"
        },
        "customMetadata": {
          "someTopLevelProperty": "value1",
          "someNestedProperty": {
            "nestedProperty": "value2"
          },
          "someArrayProperty": [
            "value3",
            "value4"
          ]
        }
      }
    ],
    "withholdingTax": [
      {
        "key": "WHT-432",
        "baseAmount": 632.78,
        "amount": 21.39,
        "currency": "EUR"
      }
    ],
    "documentType": "supplier invoice"
  }'

Responses

Successfully inserted

Bodyapplication/json

idstringrequired

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

Response

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