DDD Invoices | Documentation

Introduction

Integration with the DDD Invoices service can be done in three simple steps.

Call the DDDI_GetNew API to retrieve the initialized invoice JSON object. This API will provide you with an invoice object that is ready to be populated with data.
Fill the invoice object with the necessary data from your software.

Choose the steps that should get executed on the invoice data, as well as the documents of your choice, that should appear in the reponse.

Execute the workflow by calling the DDDI_Save API, which will create the e-invoice using the provided invoice data, as well as perform the chosen steps, return the desired documents and save the invoice.

By following these three steps, you can seamlessly integrate with the DDD Invoices service and leverage its functionalities for your invoice management needs.

In the DDD Invoices service, the e-invoice can be fiscalized, distributed to the tax authority (TA) portal, sent to the Peppol network, sent directly to the buyer or e-archived in a secure cloud. Once the e-invoice is saved, it can be viewed on the interactive e-invoices page.

Requests to the service are generally sent in the following form:

curl -X POST https://dddinvoices.com/api/service/<api-name> -H "Authorization: IoT <connectionKey>:EUeInvoices" -H "Content-Type: application/json" -d "{<parameters>}"
Copied!

Note that all apostrophes in the data object must be escaped.

Authentication

Authenticate using the connection key with each call in the authorization header "Authorization IoT <connectionKey>:<projectName>.

APIs

DDDI_GetNew

Example:

curl -X POST https://dddinvoices.com/api/service/EUeInvoices.DDDI_GetNew -H "Authorization: IoT f24d5eb8-d5bb-11ec-90fd-b2e2095ceb4f:EuEInvoices" -H "Content-Type: application/json" -d "{\"Complexity\":\"Minimal\",\"IncludeInfo\":false}"
Copied!

In response to this call, you will receive an invoice object, which contains an initialized invoice with one item each in its detail; if includeInfo was set to true, you would also receive objectInfo and JSONSchema objects.

Note: In the above and the following samples, the connection key of the demo company is used. Therefore, the sent data will transform into an e-invoice in the demo company and could be seen by all the users entered in the demo. If you don’t want this effect, register your company and do an integration test with your connection key.

DDDI_Save

Example:

curl -X POST https://dddinvoices.com/api/service/EUeInvoices.DDDI_Save -H "Authorization: IoT f24d5eb8-d5bb-11ec-90fd-b2e2095ceb4f:EuEInvoices" -H "Content-Type: application/json" -d "{\"Complexity\":\"Minimal\", \"Object\":{<InvoiceDataJSONObject>}}"
Copied!

If there are no errors in the sent object, you will be able to view the Id of the invoice in the e-invoices service in the response. An example of the response:

{
    "Status": "OK",
    "Result": { 
        "Status": "OK",
        "Result": {
            "Id": "8f9dfad1-d2d2-11ed-9104-d391378bc95e" 
            },
        "ResultType": "Custom" 
    }
}

Save the Id locally as it is a mandatory field in the Invoice Object when sending a correction of an existing invoice or running additional steps for the invoice. Once you have the Id and pass it instead of the Invoice Object, the Steps parameter needs to be defined. You can either pass the steps that need to be executed or simply add an empty array.

Further information on the steps can be found in the table below. However, it is sufficient to know that the combination of 35, 50, 70, and 85 generates country-specific UBL, sends the e-invoice to the buyer via TAP, and generates a PDF with details from TAP.

Step	Description	Required steps
35	Invoice confirmed and locked for editing	/
40	Fiscalized	35
43	Original PDF modified (with fiscalization data)	35, 40
45	Generate PDF, before sending to TAP	35
47	PDF set as primary attachment to invoice	35, 45
50	Generate UBL specific to country	35
55	Generate Peppol UBL	35
70	Send to tax authority (TAP)	35, 50
80	Send to Peppol	35, 55
83	Modify pdf document wih fiscalization and sending data	35, (40), (50, 70), (55, 80)
85	Generate pdf document wih fiscalization and sending data	35, (40), (50, 70), (55, 80)
999	All steps set as default for specific country	/

You can also add the ReturnDoc parameter to all DDDI_Save calls, which determines the documents you want to receive in the ReturnDoc section. For instance, ["PDFP", "XMLS"] returns the URL for the primary invoice PDF and the country-specific UBL.

ReturnDoc	Description
PDFP	Primary PDF document for invoice
PDFO	Original PDF document received by service
XMLS	Country specific XML of e-invoice. (e.g.: UBL 2.1 with country specific extension fields.)
XMLP	Peppol XML for e-invoice

For instance, if we want to send an invoice to the buyer via TAP and also receive the UBL and invoice PDF, we can add the steps 30, 50, 70, and 85, as well as the ReturnDoc parameter to the invoice. We can either include the parameters in the previous call or make a new DDDI_Save call using the invoice Id.

curl -X POST https://dddinvoices.com/api/service/EUeInvoices.DDDI_Save -H "Authorization: IoT f24d5eb8-d5bb-11ec-90fd-b2e2095ceb4f:EuEInvoices" -H "Content-Type: application/json" -d "{\"Complexity\":\"Minimal\", \"Steps\":[35,50,65,85], \"ReturnDoc\":[\"PDFP\",\"XMLS\"], \"Id\":\"8f9dfad1-d2d2-11ed-9104-d391378bc95e\"}"
Copied!

The response looks something like this, which contains the output of the last executed step:

{
    "Status": "OK",
    "Result": {
        "Status": "OK",
        "Step": 85,
        "Result": {
            "PDFPrimary": "File/69a706dc-5a0b-4c89-adf2-02750b25adfc?inline=true",
            "PDFMade": "File/69a706dc-5a0b-4c89-adf2-02750b25adfc?inline=true",
            "Id": "8f9dfad1-d2d2-11ed-9104-d391378bc95e"
            },
        "ResultType": "Custom",
        "ReturnDoc": {
            "PDFP": "https://dddinvoices.com/Public/69a706dc-5a0b-4c89-adf2-02750b25adfc?inline=true",
            "XMLS": "https://dddinvoices.com/Public/d892cddb-3295-4644-993f-142f005e615d?inline=true"
        }
    }
}

API Playground

We have prepared an API playground for registered users. It provides a convenient way to explore the available APIs and obtain detailed instructions on how to use each one. Within the API playground, you'll find pre-filled valid objects, along with the cURL and JavaScript requests and corresponding responses. Upon registration, every company receives a unique connection key that can be utilized for integration tests.

Object Playground

In addition to the API Playground, we provide an object playground where you can experiment with the transformation workflow of your invoice data into an e-invoice.

These playgrounds serve as valuable tools for familiarizing yourself with our services, ensuring seamless integration, and testing various scenarios related to API usage and invoice data transformations.Paragraph

Standard objects

Invoice Object

Is a JSON object, that has contains three properties:

{
    "Invoice" : invoice data,
    "ObjectInfo": Additional information of invoice data entities ie. Invoice, Items, etc.,
    "JSONSchema" : Json schema object,that can be used for invoice object validation.
}

Invoice

Invoice object contains an information about the invoice such as its number, type, issue date, currency, and total amount, as well as details about the buyer and seller. In the details section, there is also an array of items on the invoice called Items, and an array of payment instructions for the invoice called Payments.

It contains the invoice data object, which must be validated with a JSON schema object. Detailed definitions of the fields can be found in the ObjectInfo object.

ObjectInfo

Defines every field in invoice data object with its name, entity, mandatory flag, required regex pattern, JSON type, .NET type, internal DDD type, etc.

Example of a DocDeliveryDate field in an invoice entity

{
    "ObjectInfo": {
        "Invoice": {
            "DocDeliveryDate": {
                "Source": "SYSTEM",
                "Mandatory": false,
                "Type": "date",
                "TypeNET": "DateTime",
                "TypeDDD": "Date",
                "Pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}"
            }, ... /*other fields*/ 
        }, ... /*other entities*/ 
    }
}

JSONSchema

A JSON schema object which defines the structure of the Invoice object. It can also be utilized for generating input forms and performing validation.

Standard response

Extensions have a standard response.

{
    "Status": Response status that determines success of extension.
    "Reason": Reason why extension has failed.
    "Result": Result of an extension in result type.
    "ResultType": Defines result type
}

A call to REST API also has standard response.

{
    "Status": Response status that determines success of API.
    "Reason": Reason why API has failed.
    "Result": Result that is returned from extension.
    "Code": Error code
}

A typical response from the REST API looks like a double wrapped standard response. Extension response wrapped by REST API response.

{
    "Status": "OK", //response of server that auth are ok, and that extension is found
                        and has been executed.
    "Result": {
        "Status": "Error", //response of extension, that describes an error on step 70
        "Step": 70,
        "Reason": "'Invoice' object was expected to contain a document URL, but was not
                    found under expected name 'XMLSpecific'.",
    }
}

Example of a response with invalid credentials:

{
    "Status": "Error",
    "Reason": "Invalid device ID or project name.",
    "Code": 401
}

Status

Response status. Its string represents enum value OK, Warning and Error.

OK: API successfully completed. Result and result type are defined.

Warning: API successfully completed, but with some warnings. Result, result type and reason are defined.

Error: API didn't complete. Reason is defined.

Reason

Reason for warning or error.

ResultType

Defines type of result and is represented with string value of enum Custom, Invoice, Registration.

Custom: Contains key value pairs that are consistent with fields in invoice entity (e.g.: Id).

Invoice : A standard Invoice object.

Examples

Example of a properly prepared Invoice object


{
    "Invoice": {
        "BuyerLegalForm": "LegalEntity",
        "BuyerTypeCode": "Domestic",
        "BuyerCountryCode": "RS",
        "BuyerTaxNum": "112742026",
        "BuyerName": "TailoredSaas d.o.o., Beograd",
        "BuyerPostCode": "11177",
        "BuyerStreet": "Jurija Gagarina 151a T.C. Piramida, sprat 1, lokal 57 ",
        "BuyerCity": "Novi Beograd",
        "BuyerRegNum": "21730326",
        "BuyerId": null,
        "BuyerIsBudget": false,
        "BuyerBudgetNum": null,
        "DocNumber": null,
        "DocIssueDate": null,
        "DocDueDate": null,
        "DocTotalAmount": 2514005.68,
        "DocTotalVatAmount": 27157.06,
        "DocStartDate":
        "2023-04-04T00:00:00.000",
        "DocEndDate":
        "2023-04-04T00:00:00.000",
        "DocDeliveryDate":
        "2023-04-04T00:00:00.000",
        "DocCurrencyCode": "RSD",
        "DocExchangeRate": 0.0085259051,
        "DocAllowPercent": 0,
        "DocSigner": null,
        "DocNote": "This is just a simple comment at the end of the invoice. ",
        "DocBuyerOrderRef": "N-101",
        "OriginalInvNumber": null,
        "OriginalInvIssueDate": null,
        "DocTypeCode": "INVOICE",
        "DocSaleTypeCode": "Wholesale",
        "DocPaymentTypeCode": "NONCASH",
        "OperatorTAPRegistration": null,
        "PDFOriginal": null,
        "_details": {
            "Items": [
                {
                    "ItemName": "Item 1",
                    "ItemQuantity": 1,
                    "ItemUmcCode": "piece",
                    "ItemNetPrice": 100.34,
                    "ItemRetailPrice": null,
                    "ItemAllowancePercent": 5,
                    "ItemVatRate": 0,
                    "ItemVatCode": "20",
                    "ItemExciseAmount": 0 
                },
                {
                    "ItemName": "Item 2",
                    "ItemQuantity": 4, "ItemUmcCode":
                    "piece", "ItemNetPrice": 67845,
                    "ItemRetailPrice": null,
                    "ItemAllowancePercent": 0,
                    "ItemVatRate": 0,
                    "ItemVatCode": "10",
                    "ItemExciseAmount": 0
                },
                {
                    "ItemName": "item 3",
                    "ItemQuantity": 5,
                    "ItemUmcCode": "kg",
                    "ItemNetPrice": 456778,
                    "ItemRetailPrice": null,
                    "ItemAllowancePercent": 3,
                    "ItemVatRate": 0,
                    "ItemVatCode": "R_6-1-1",
                    "ItemExciseAmount": 0
                }
            ],
            "Payments": [
                {
                    "PayCode": "CREDITTRANSFER",
                    "PayNumber": "603-123-56666",
                    "PayAmount": 2514005.68,
                    "PayPayeeAccountType": "BBAN",
                    "PayNetworkProvider": "CONARS22XXX",
                    "PayCardHolderOrReference": null,
                    "PayDocDate": null
                }
            ]
        } 
    }
}

Copied!

Example of a full DDD_GetNewInvoice response


{
    "Status": "OK",
    "Result": {
        "Status": "OK",
        "Result": {
            "Invoice": {
                "Invoice": {
                    "BuyerLegalForm": "LegalEntity",
                    "BuyerTypeCode": "Domestic",
                    "BuyerCountryCode": "RS",
                    "BuyerTaxNum": null,
                    "BuyerName": null,
                    "BuyerPostCode": null,
                    "BuyerStreet": null,
                    "BuyerCity": null,
                    "BuyerRegNum": null,
                    "BuyerId": null,
                    "BuyerIsBudget": false,
                    "BuyerBudgetNum": null,
                    "DocNumber": null,
                    "DocIssueDate": null,
                    "DocDueDate": "2023-05-10",
                    "DocTotalAmount": null,
                    "DocTotalVatAmount": null,
                    "DocStartDate": "2023-04-25",
                    "DocEndDate": "2023-04-25",
                    "DocDeliveryDate": null,
                    "DocCurrencyCode": "RSD",
                    "DocExchangeRate": 1.0,
                    "DocAllowPercent": 0.0,
                    "DocSigner": "Testni potpisnik",
                    "DocNote": null,
                    "DocBuyerOrderRef": "Nar:",
                    "OriginalInvNumber": null,
                    "OriginalInvIssueDate": null,
                    "DocTypeCode": "INVOICE",
                    "DocSaleTypeCode": "Wholesale",
                    "DocPaymentTypeCode": "NONCASH",
                    "DeviceId": "f24d5eb8-d5bb-11ec-90fd-b2e2095ceb4f",
                    "OperatorTAPRegistration": "232323fff",
                    "PDFOriginal": null,
                    "_details": {
                        "Items": [
                            {
                                "ItemName": "Stavka",
                                "ItemQuantity": 1.0,
                                "ItemUmcCode": "piece",
                                "ItemNetPrice": 1.0,
                                "ItemRetailPrice": null,
                                "ItemAllowancePercent": 0.0,
                                "ItemVatRate": null,
                                "ItemVatCode": "20",
                                "ItemExciseAmount": 0.0
                            }
                        ],
                        "Payments": [
                            {
                                "PayCode": "CREDITTRANSFER",
                                "PayNumber": null,
                                "PayAmount": 0,
                                "PayPayeeAccountType": null,
                                "PayNetworkProvider": null,
                                "PayCardHolderOrReference": null,
                                "PayDocDate": null
                            }
                        ],
                        "CreditNoteRefs": [
                            {
                                "CNRefNumber": null,
                                "CNRefIssueDate": null,
                                "CNRefTotalAmount": 0
                            }
                        ]
                    }
                }
            }
        },
        "ResultType": "InvoiceOnly"
    }
}
Copied!

Example of a full DDDI_Save call and response

curl -X POST https://dddinvoices.com/api/service/EUeInvoices.DDDI_Save -H "Authorization: IoT f24d5eb8-d5bb-11ec-90fd-b2e2095ceb4f:EuEInvoices" -H "Content-Type: application/json" -d "{\"Complexity\":\"Minimal\", \"Steps\":[35,50,65,85],\"ReturnDoc\":[\"PDFP\",\"XMLS\"],\"Object\":{ \"Invoice\": { \"BuyerLegalForm\": \"LegalEntity\", \"BuyerTypeCode\": \"Domestic\", \"BuyerCountryCode\": \"RS\", \"BuyerTaxNum\": \"112742026\", \"BuyerName\": \"TailoredSaas d.o.o., Beograd\", \"BuyerPostCode\": \"11177\", \"BuyerStreet\": \"Jurija Gagarina 151a T.C. Piramida, sprat 1, lokal 57 \", \"BuyerCity\": \"Novi Beograd\", \"BuyerRegNum\": \"21730326\", \"BuyerId\": null, \"BuyerIsBudget\": false, \"BuyerBudgetNum\": null, \"DocNumber\": null, \"DocIssueDate\": null, \"DocDueDate\": null, \"DocTotalAmount\": 2514005.68, \"DocTotalVatAmount\": 27157.06, \"DocStartDate\": \"2023-04-04T00:00:00.000\", \"DocEndDate\": \"2023-04-04T00:00:00.000\", \"DocDeliveryDate\": \"2023-04-04T00:00:00.000\", \"DocCurrencyCode\": \"RSD\", \"DocExchangeRate\": 0.0085259051, \"DocAllowPercent\": 0, \"DocSigner\": null, \"DocNote\": \"This is just a simple comment at the end of invoice. \", \"DocBuyerOrderRef\": \"N-101\", \"OriginalInvNumber\": null, \"OriginalInvIssueDate\": null, \"DocTypeCode\": \"INVOICE\", \"DocSaleTypeCode\": \"Wholesale\", \"DocPaymentTypeCode\": \"NONCASH\", \"OperatorTAPRegistration\": null, \"PDFOriginal\": null, \"_details\": { \"Items\": [ { \"ItemName\": \"Item 1\", \"ItemQuantity\": 1, \"ItemUmcCode\": \"piece\", \"ItemNetPrice\": 100.34, \"ItemRetailPrice\": null, \"ItemAllowancePercent\": 5, \"ItemVatRate\": 0, \"ItemVatCode\": \"20\", \"ItemExciseAmount\": 0 }, { \"ItemName\": \"Item 2\", \"ItemQuantity\": 4, \"ItemUmcCode\": \"piece\", \"ItemNetPrice\": 67845, \"ItemRetailPrice\": null, \"ItemAllowancePercent\": 0, \"ItemVatRate\": 0, \"ItemVatCode\": \"10\", \"ItemExciseAmount\": 0 }, { \"ItemName\": \"item 3 \", \"ItemQuantity\": 5, \"ItemUmcCode\": \"kg\", \"ItemNetPrice\": 456778, \"ItemRetailPrice\": null, \"ItemAllowancePercent\": 3, \"ItemVatRate\": 0, \"ItemVatCode\": \"R_6-1-1\", \"ItemExciseAmount\": 0 } ], \"Payments\": [ { \"PayCode\": \"CREDITTRANSFER\", \"PayNumber\": \"603-123-56666\", \"PayAmount\": 2514005.68, \"PayPayeeAccountType\": \"BBAN\", \"PayNetworkProvider\": \"CONARS22XXX\", \"PayCardHolderOrReference\": null, \"PayDocDate\": null } ] } }} }"
Copied!

{
    "Status": "OK",
    "Result": {
        "Status": "OK",
        "Step": 85,
        "Result": {
            "PDFPrimary": "File/bee8da85-d03c-4eb1-946e-21e88c46b0a2?inline=true",
            "PDFMade": "File/bee8da85-d03c-4eb1-946e-21e88c46b0a2?inline=true",
            "Id": "943c5338-d2d1-11ed-9104-d391378bc95e"
        },
        "ResultType": "Custom",
        "ReturnDoc": { 
                "PDFP": "https://dddinvoices.com/Public/bee8da85-d03c-4eb1-946e-21e88c46b0a2?inline=true",
                "XMLS": "https://dddinvoices.com/Public/a0ecd9bd-55ca-47c0-8a00-5b73a7599809?inline=true"
        }
    }
}

API documentation for DDD Invoices