Transferring master data (d.velop smart invoice)

You can use the master data API to transfer data from an external ERP system to a bucket.

Determining the bucket ID

Jobs

For every entity, there are endpoints for transferring multiple data records at the same time (these endpoints end in /batch). d.velop smart invoice processes the data sent to these endpoints asynchronously. Each of the endpoints listed below for transferring data returns the ID of the generated job. Exactly one job is always returned.

Response

{
  "jobs": [
    {
      "job_id": "65866efa-e8a6-4c9c-ae30-60121b6d039f"
    }
  ]
}

Retrieving the current status of a job

You can use the job ID returned to you by the relevant endpoint to retrieve the status of the job as follows:

Request

GET /smartinvoice/api/v1/masterdata/import_jobs/65866efa-e8a6-4c9c-ae30-60121b6d039f
Accept: application/json

As a response, you receive a JSON object with information about the job.

Response

{
  "job_id": "65866efa-e8a6-4c9c-ae30-60121b6d039f",
  "status": "successful"
}

Property	Description
job_id	String. The ID of the job.
status	String. The current status of the job. The possible options are as follows: queued: The job is still being processed. successful: The job was processed successfully. failed: An error occurred.

Companies

Companies are the recipients of invoices. A company in d.velop smart invoice usually corresponds to a company or company code in the ERP system. Every invoice requires a company. You transfer companies as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/companies/batch
Content-Type: application/json

{
  "companies": [
    {
      "id": "01",
      "name": "docures AG",
      "parent_id": null,
      "address": "Musterstr. 23",
      "city": "Musterstadt",
      "zip_code": "12345",
      "local_currency": "EUR",
      "country": "DE"
    }
  ]
}

Each individual company supports the following properties:

Property	Description
id	String. Mandatory. The ID or number of the company. This value can be seen on the user interface.
name	String. Mandatory. The name of the company. This value can be seen on the user interface. The name of the company is an important criterion for automatically identifying the company in d.velop invoices. Where possible, it should be entered identically to how it is shown on the invoices.
address	String. The company’s address information, e.g street and house number. The address of the company is an important criterion for automatically identifying the company in d.velop invoices.
city	String. The location or city of the company.
zip_code	String. The zip code of the location or city.
local_currency	String. The local currency of the company. This value is used to convert invoice amounts into the local currency for verification in conditions. You must enter this value as a code in accordance with ISO 4217 (for example: EUR or USD).
country	String. The country of the company. This value is used to select the rule set for the automatic check of the local national regulations. You must enter this value as an ISO 3316-1 alpha-2 code (for example, DE or CH).

Vendors

Vendors are the senders of invoices. You transfer vendors as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/vendors/batch
Content-Type: application/json

{
  "vendors": [
    {
      "company_id": "01",
      "id": "50001",
      "name": "Schrauben Meier GmbH",
      "address": "Teststr. 6",
      "city": "Kiel",
      "zip_code": "24145",
      "country": "DE",
      "email": "schraubenmeier@example.com",
      "vat_id": "DE99999999",
      "registration_id": "1028502",
      "payment_terms_id": "10",
      "tax_category_1": "NATIONAL"
    }
  ]
}

Each individual vendor supports the following properties:

Property	Description
company_id	String. Mandatory. The company to which this vendor belongs.
id	String. Mandatory. The ID or number of the vendor in the ERP system. This ID can be viewed by users in d.velop invoices. Must be unique for each company_id.
name	String. Mandatory. The name of the vendor. If possible, with the same spelling used on the invoices for this vendor.
address	String. Mandatory. The address line for the vendor, e.g. street and house number.
city	String. Mandatory. The location or city of the vendor.
zip_code	String. Mandatory. The zip code of the location or city of the vendor.
country	String. Mandatory. The country of the vendor. This value is used to select the rule set for the automatic check of the local national regulations. You must enter this value as an ISO 3316-1 alpha-2 code (for example, DE or CH).
email	String. The e-mail address of the vendor. Where available, the address the vendor enters on his or her invoices.
vat_id	String. The VAT ID number of the vendor. This property is important for automatically determining the vendor in d.velop invoices.
registration_id	String. The tax ID of the vendor. This may be a national tax ID in a non-EU country, for example.
payment_terms_id	String. The ID of the primary payment terms for this vendor.
tax_category_1	String. The first part of the category for automatically determining the correct tax code. You can find a detailed description of this behavior in the section on tax codes.

Vendor Bank Accounts

You can save multiple bank accounts for each vendor. The bank accounts are important for both identifying the vendor while reading the invoice and comparing the information entered on the invoice with the data from the ERP system. You transfer bank accounts as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/vendor_bank_accounts/batch
Content-Type: application/json

{
  "vendor_bank_accounts": [
    {
      "company_id": "01",
      "vendor_id": "50001",
      "iban": "DE02100100100006820101",
      "bic": "PBNKDEFF",
      "primary": true
    }
  ]
}

Each individual vendor bank account supports the following properties:

Property	Description
company_id	String. Mandatory. The company to which this vendor bank account belongs.
vendor_id	String. Mandatory. The vendor to which this bank account belongs.
id	String. Mandatory. The ID of this bank account in the ERP system.
iban	String. Mandatory. The IBAN of the relevant bank account.
bic	String. The BIC of the relevant bank account.
primary	Boolean. Mandatory. Is this bank account the vendor’s primary bank account?

Payment Terms

d.velop smart invoice uses payment terms to calculate escalation times for net payment periods and discount periods. You transfer payment terms as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/payment_terms/batch
Content-Type: application/json

{
  "payment_terms": [
    {
      "company_id": "01",
      "id": "NET30",
      "net_days": 30,
      "cashback_days1": 10,
      "cashback_percentage1": 2.5
    }
  ]
}

Each individual payment term supports the following properties:

Property	Description
company_id	String. Mandatory. The company to which these payment terms belong.
id	String. Mandatory. The ID of the payment terms in the ERP system.
net_days	Number. Mandatory. The net payment period in days. If you enter 0, this is interpreted as “no period.”
cashback_days1	Number. Mandatory. The cash discount period in days. If you enter 0, this is interpreted as “no period.”
cashback_percentage1	Number. Mandatory. The cash discount rate as a percentage.
name	String. The name for these payment terms.

Document Types

The document type identifies the type of the invoice. At minimum, the two document types invoice and credit note should be available. You transfer document types as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/document_types/batch
Content-Type: application/json

{
  "document_types": [
    {
      "company_id": "01",
      "id": "inv",
      "name": "Invoice",
      "credit_note": false
     }
  ]
}

Each individual document type supports the following properties:

Property	Description
company_id	String. The company to which this document type belongs. If you do not make an entry, the document type is valid for all companies.
id	String. Mandatory. The ID of the document type. This value can be viewed by users in d.velop invoices.
name	String. Mandatory. The name of the document type.
credit_note	Boolean. Mandatory. Is the document a credit note?

Currencies

Each document in d.velop smart invoice is assigned to a currency. You transfer the currencies that are transferred by your ERP system. You transfer currencies as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/currencies/batch
Content-Type: application/json

{
  "currencies": [
    {
      "company_id": "01",
      "id": "EUR",
      "name": "Euro",
      "code": "EUR"
    }
  ]
}

Each individual currency supports the following properties:

Property	Description
company_id	String. The company to which this currency belongs. If you do not make an entry, the currency is valid for all companies.
id	String. Mandatory. The ID of the currency in the ERP system. This value can be viewed by users in d.velop invoices.
name	String. Mandatory. The name of the currency.
code	String. Mandatory. The currency code as per ISO 4217.

Tax Codes

A tax code can be assigned to each document line in d.velop smart invoice. You transfer tax codes as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/tax_codes/batch
Content-Type: application/json

{
  "tax_codes": [
    {
      "company_id": "01",
      "id": "S-DE",
      "name": "VSt 19%",
      "percentage": 19.0,
      "tax_category_1": "NATIONAL",
      "tax_category_2": "FULL"
    }
  ]
}

Each individual tax code supports the following properties:

Property	Description
company_id	String. Mandatory. The company to which this tax code belongs. If you do not make an entry, the tax code is valid for all companies.
id	String. Mandatory. The ID of the tax code in the ERP system. This value is displayed for users in d.velop invoices.
name	String. Mandatory. The name of the tax code.
percentage	Number. Mandatory. The percentage of the tax code.
tax_category_1	String. The first part of the tax category for automatically determining the tax code.
tax_category_2	String. The second part of the tax category for automatically determining the tax code.

Automatically determining the tax code

Using the values tax_category_1 and tax_category_2, d.velop smart invoice can automatically determine a suitable tax code based on the detected and/or selected document data. To do so, it compares the tax_category_1 and tax_category_2 values of the vendor and of the G/L account or procurement category. If there is a clear match, the corresponding tax code is entered automatically.

G/L Accounts

You transfer G/L accounts as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/gl_accounts/batch
Content-Type: application/json

{
  "gl_accounts": [
    {
      "company_id": "01",
      "nr": "6300",
      "name": "Sonstige betriebliche Aufwendungen"
    }
  ]
}

Each individual G/L account supports the following properties:

Property	Description
company_id	String. The company to which this G/L account belongs. If you do not make an entry, the G/L account is valid for all companies.
nr	String. Mandatory. The number of the G/L account.
name	String. Mandatory. The name of the G/L account.
tax_category_2	String. The second part of the tax category for automatically determining the tax.

Cost Centers

You transfer cost centers as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/cost_centers/batch
Content-Type: application/json

{
  "cost_centers": [
    {
      "company_id": "01",
      "nr": "1000",
      "name": "Verwaltung"
    }
  ]
}

Each individual cost center supports the following properties:

Property	Description
company_id	String. The company to which this cost center belongs. If you do not make an entry, the cost center is valid for all companies.
nr	String. Mandatory. The number of the cost center.
name	String. Mandatory. The name of the cost center.

Cost Units

You transfer cost units as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/cost_units/batch
Content-Type: application/json

{
  "cost_units": [
    {
      "company_id": "01",
      "nr": "PJ001",
      "name": "Projekt Neubau"
    }
  ]
}

Each individual cost unit supports the following properties:

Property	Description
company_id	String. The company to which this cost unit belongs. If you do not make an entry, the cost unit is valid for all companies.
nr	String. Mandatory. The number of the cost unit.
name	String. Mandatory. The name of the cost unit.

Other Dimensions

Other dimensions are data records that can be used in custom fields in document lines (for custom fields in the header data, see “Custom Entities”). Each additional dimension is identified using a freely definable type (type field). All data records with the same type count as one additional dimension. You can assign an additional dimension to each custom field in d.velop smart invoice. You transfer additional dimensions as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/other_dimensions/batch
Content-Type: application/json

{
  "other_dimensions": [
    {
      "company_id": "01",
      "type": "project",
      "nr": "PJ001",
      "name": "Projekt Neubau",
      "parent_dimension_type": "Projektleiter",
      "parent_dimension_id": "1000"
    }
  ]
}

Each individual dimension value supports the following properties:

Property	Description
company_id	The company to which this dimension value belongs. If you do not make an entry, the dimension value is valid for all companies.
type	String. Mandatory. The type of this dimension value. Types are used to keep all the data for an additional dimension together.
nr	String. Mandatory. The ID or number of the dimension value.
name	String. Mandatory. The name of the dimension value.
parent_dimension_type	String. The type of the additional dimension, which determines this dimension value.
parent_dimension_id	String. The ID of the additional dimension value of the type parent_dimension_type, which determines this dimension value.

Custom Entities

Custom entities are data records that can be used in custom fields in the document header (for custom fields in document lines, see “Other Dimensions”). Each custom entity is identified using a freely definable type (type field). All data records with the same type count as one custom entity. You can assign a custom entity to each custom field in d.velop smart invoice. You transfer custom entities as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/custom_entities/batch
Content-Type: application/json

{
  "custom_entities": [
    {
      "company_id": "01",
      "type": "project",
      "id": "PJ001",
      "name": "Projekt Neubau"
    }
  ]
}

Each individual entity value supports the following properties:

Property	Description
company_id	The company to which this entity value belongs. If you do not make an entry, the entity value is valid for all companies.
type	String. Mandatory. The type of the entity value. Types are used to keep all the data for a custom entity together.
id	String. Mandatory. The ID of this entity value.
name	String. Mandatory. The name of this entity value.

Purchase Orders

Purchase orders and purchase order line items are used to compare invoices and purchase orders in d.velop smart invoice. You transfer purchase orders and purchase order lines as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/purchase_orders/batch
Content-Type: application/json

{
  "purchase_orders": [
    {
      "company_id": "01",
      "id": "PO001",
      "nr": "PO001",
      "name": "Office Supplies",
      "vendor_id": "50001",
      "status": 1,
      "custom1": null,
      "custom2": null, 
      "custom3": null, 
      "custom4": null,  
      "custom5": null,  
      "custom6": null,  
      "custom7": null,  
      "custom8": null,  
      "custom9": null,  
      "custom10": null,  
      "custom11": null,   
      "custom12": null,   
      "custom13": null,   
      "custom14": null,   
      "custom15": null,   
      "custom16": null,   
      "custom17": null,   
      "custom18": null,   
      "custom19": null,   
      "custom20": null,   
      "line_items": [
        {
          "company_id": "01",
          "purchase_order_id": "PO001",
          "id": "PO001_1",
          "line_no": 1,
          "quantity_ordered": 10.0,
          "quantity_received": 5.0,
          "quantity_not_invoiced": 5.0,
          "description": "Printer Paper, A4",
          "subtotal": 200.0,
          "unit": "Box",
          "unit_price": 20.0,
          "price_unit": 1.0,
          "gl_account": "6300",
          "cost_center": "1000",
          "cost_unit": null,
          "item": "102912",
          "tax_code_id": "DE_S",
          "discount_absolute": 0.0,
          "discount_per_unit": 0.0,
          "discount_percent": 0.0,
          "discount2_percent": 0.0,
          "discount3_percent": 0.0,
          "discount4_percent": 0.0,
          "discount5_percent": 0.0,
          "custom1": null,
          "custom2": null,
          "custom3": null,
          "custom4": null,
          "custom5": null,
          "custom6": null,
          "custom7": null,
          "custom8": null,
          "custom9": null,
          "custom10": null,
          "custom11": null,
          "custom12": null,
          "custom13": null,
          "custom14": null,
          "custom15": null,
          "custom16": null,
          "custom17": null,
          "custom18": null,
          "custom19": null,
          "custom20": null,
          "procurement_category": null,
          "erp_id": "100",
          "type": "header_surcharge", 
		  "surcharged_line_item_id": "1", 
		  "surcharge_category": "pcs",
 		  "surcharge_value": "20.00",
 		  "responsible": "email@domain.de",
 		  "goods_receipt_reference_mandatory": true
        }
      ]
    }
  ]
}

Each individual purchase order supports the following properties:

Property	Description
company_id	String. Mandatory. The company to which this purchase order belongs.
id	String. Mandatory. The ID of this purchase order. This is not displayed for users in d.velop invoices.
nr	String. Mandatory. The number of this purchase order.
name	String. Mandatory. A description of the purchase order.
vendor_id	String. Mandatory. The ID of the vendor to which this purchase order belongs.
status	Number. The following values and mapped statuses are possible: 1: Open 2: Approved 3: Confirmed 4: Partially received 5: Received 6: Partially invoiced 7: Invoiced 8: Cancelled
custom1 to custom20	String. Custom fields at header level The values of these fields are transferred to the relevant custom fields in the invoice header as long as the fields are empty on the invoice.

Each individual purchase order line item supports the following properties:

Property	Description
company_id	String. Mandatory. The company to which this purchase order line belongs.
id	String. Mandatory. The ID of the purchase order line. This value must be unique across all the purchase orders. That means that even two different purchase orders must not share the same purchase order line ID.
line_no	Number. Mandatory. The number of the line within the purchase order.
quantity_ordered	Number. Mandatory. The total quantity ordered.
quantity_received	Number. Mandatory. The total quantity received.
quantity_not_invoiced	Number. Mandatory. The quantity that has not been invoiced yet. Caution: d.velop invoices does not use this value for quantity checks.
item	String. Mandatory. The item number of the purchase order line.
procurement_category	String. The procurement category of the purchase order line.
description	String. Mandatory. A text describing the purchase order line, such as the name of the item.
unit	String. Mandatory. The unit for the ordered quantity. For example, pieces.
unit_price	Number. Mandatory. The unit price for the ordered item.
price_unit	Number. Mandatory. The price unit or packaging unit if the supplier bills in a different quantity unit than the one managed in the ERP system. In cases of doubt, enter 1.0.
subtotal	Number. Mandatory. Overall (net) amount of the purchase order line.
gl_account	String. The G/L account for the purchase order line.
cost_center	String. The cost center for the purchase order line.
cost_unit	String. The cost unit for the purchase order line.
tax_code_id	String. The ID of the associated tax code.
discount_absolute	Number. Absolute discount on the overall (net) amount of the purchase order line.
discount_per_unit	Number. Absolute discount on the unit price for the purchase order line.
discount_percent	Number. Percentage discount on the overall (net) amount of the purchase order line.
discount2_percent	Number. Second percentage discount on the overall (net) amount of the purchase order line.
discount3_percent	Number. Third percentage discount on the overall (net) amount of the purchase order line.
discount4_percent	Number. Fourth percentage discount on the overall (net) amount of the purchase order line.
discount5_percent	Number. Fifth percentage discount on the overall (net) amount of the purchase order line.
custom1 to custom20	String. Custom fields. The values in the fields are transferred to the corresponding fields in the invoice line created from the purchase order.
type	String. Mandatory. header_surcharge or line_item_surcharge
surcharged_line_item_id	String. Surcharged order line item
surcharge_category	String. pcs/ fixed /percent If the surcharges are added per piece/at a fixed rate or as a percentage.
surcharge_value	String. Value of the surcharge
responsible	String. User name of the person responsible for the order line item. Case sensitive!
goods_receipt_reference_mandatory	Boolean. Indicates whether the assignment of a goods receipt line to this order line item is mandatory. You can find further information on the use of this feature in the administration manual of d.velop smart invoice in the section Working with goods receipts.

Goods Receipt

Note

Goods receipts are still being previewed at the moment. Please contact d.velop if you would like to use goods receipts.

Goods receipts and goods receipt lines are used by d.velop invoices to compare purchase orders, goods receipts and invoices with each other. You transfer goods receipts and goods receipt lines as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/goods_receipts/batch
Content-Type: application/json

{
  "goods_receipts": [
    {
      "company_id": "01",
      "vendor_id": "50001",
      "id": "GR001",
      "nr": "GR001",
      "creation_date": "2022-04-07",
      "delivery_slip_nr": "LS001",
      "status": 0,
      "line_items": [
        {
          "company_id": "01",
          "id": "GR001_1",
          "line_no": 1,
          "goods_receipt_date": "2022-04-07",
          "quantity": 2.7,
          "purchase_order_line_id": "PO001_1"
        }
      ]
    }
  ]
}

Each individual goods receipt supports the following properties:

Property	Description
company_id	String. Mandatory. The company to which this goods receipt belongs.
vendor_id	String. Mandatory. The vendor to which this goods receipt belongs.
id	String. Mandatory. The ID of the goods receipt. This value is not displayed for users in d.velop invoices.
nr	String. Mandatory. The number of the goods receipt.
creation_date	Date. Mandatory. The date on which the goods receipt was created. Format YYYY-MM-DD.
delivery_slip_nr	String. Mandatory. The vendor delivery slip number for which this goods receipt was posted.

Each individual goods receipt line item supports the following properties:

Property	Description
company_id	String. Mandatory. The company to which this goods receipt line belongs.
id	String. Mandatory. The ID of this goods receipt line. This value must be unique across all the goods receipts. That means that two different goods receipts must not share the same goods receipt line ID.
line_no	Number. Mandatory. The number of this goods receipt line within the goods receipt.
goods_receipt_date	Date. Mandatory. The date on which this goods receipt line was posted. Format YYYY-MM-DD.
quantity	Number. Mandatory. The quantity received.
purchase_order_line_id	String. The ID of the purchase order line belonging to this goods receipt line.

Surcharge types

Surcharge types are used by d.velop invoices to manually add surcharges to an invoice via the dialog. You can transfer surcharge types as follows:

Request

POST /smartinvoice/api/v1/buckets/:bucket_id/surcharge_types /batch
Content-Type: application/json

{
    "surcharge_types": [
        {
            "company_id": "01",
            "nr": "TEST",
            "name": "Test_surcharge",
            "applies_to": "line_item_surcharge",
            "erp_id": "",
            "tenant_id": "",
            "category": "pcs",
            "quantity": "",
            "unit_price": "",
            "gl_account": "",
            "cost_center": "",
            "cost_unit": "",
            "item": "",
            "tax_code_id": "",
            "custom1":"",
            "custom2":"",
            "custom3":"",
            "custom4":"",
            "custom5":"",
            "custom6":"",
            "custom7":"",
            "custom8":"",
            "custom9":"",
            "custom10":"",
            "custom11":"",
            "custom12":"",
            "custom13":"",
            "custom14":"",
            "custom15":"",
            "custom16":"",
            "custom17":"",
            "custom18":"",
            "custom19":"",
            "custom20":"",
            "tax_category":"",
            "procurement_category":""
        }
	]
}

Each individual surcharge type supports the following properties:

Property	Description
company_id	String. The company to which the surcharge type belongs. If you do not specify a company, the cost unit applies for all companies.
nr	String. Mandatory. The ID of the surcharge. The ID must be unique and cannot be left blank.
name	String. Name of the surcharge type.
applies_to	String. Mandatory. Possible values: header_surcharge, line_item_surcharge
erp_id	String.
tenant_id	String. Mandatory.
category	String. Use the values pcs, fixed, percent if the surcharges are added per piece, at a fixed rate or as a percentage.
quantity	String. Number of the surcharge type.
unit_price	String. Unit price of the surcharge type.
gl_account	String. The G/L account of the surcharge type.
cost_center	String. The cost center of the surcharge type.
cost_unit	String. The cost object of the surcharge type.
item	String. The item number of the surcharge type.
tax_code_id	String. The tax code of the surcharge type.
custom1-20	String. Custom fields of the surcharge type.
tax_category	String. The tax category of the surcharge type.
procurement_category	String. The procurement category of the surcharge type.

Help us become better!

Transferring master data (d.velop smart invoice)

Note

Help us become better!