Skip to main content

Build your own Invoiced-based ERP integration

Sometimes you want to use TRAEDE in combination with an accounting system for which TRAEDE does not have a built-in integration for. In such a case you can build your own ERP integration. Follow this guide to learn best practice and a recommended structure.

caution

NOTE This guide is for when you want to deliver and invoice your orders in TRAEDE and want to synchronize invoices and credit notes from TRAEDE to your accounting system. If this is not what you want and what you are looking for is to synchronize orders instead of invoices then you should look at our guide for building your own order-based ERP integration.

Flows to implement​

There are multiple flows that can be implemented where some are recommended and some are optional

  1. Sync invoices from TRAEDE -> ERP (recommended)
  2. Sync credit notes from TRAEDE -> ERP (recommended)
  3. Sync COGS and inventory adjustments from TRAEDE -> ERP (recommended)

Each flow is described in detail further down

1 Sync invoices from TRAEDE -> ERP​

Whenever an invoice is created in TRAEDE it should be synchronized to the ERP system. To synchronize an invoice you should follow 2 steps

  1. Use TRAEDE export API to get a list of all invoices that have not been exported yet
  2. For each invoice import it into your ERP and if it was imported successfully mark it as exported in TRAEDE

It's important to mark invoices as exported in TRAEDE so that you will not import them again

1.1 Get list of all invoices that have not been exported yet​

TRAEDE has built-in export APIs that keeps track of which invoices that have been exported and which have not. Read more about the export APIs here.

You should use the Invoice Export API to fetch all invoices that have not been exported yet.

1.2 Import invoice into ERP and mark it as synced​

The next step is to iterate over all the invoices and import them into your ERP. If the import is successful you should send a call back marking the invoices as exported. This is also done using the export API. You can read more about this here

Full pseudo-example in PHP​

This example assumes we have a client class that can make HTTP requests (e.g. could be made using Guzzle). The example also assumes you have a class named InvoiceImporter that actually imports the invoice into your system.

<?php

// Just a fake class for making HTTP requests. Replace with something like guzzle or similar
// Notice our fake client class implements `requestAllPages` that makes sure to iterate
// through all pages of new/updated invoices
$client = new Client();

// Just a fake class to simulate actually saving the invoice in our own system. Replace
// with your own implementation
$importer = new InvoiceImporter();

$requestOptions = [
    'system_id' => 'my_system',
    'include_non_booked' => 0,

    // details we need to import the invoice
    'includes' => [
        'customer',
        'lines',
        'lines.product',
        'lines.variant'
    ]
];

$invoicesThatShouldBeImported = $client->requestAllPages(
    '/v10/invoices/export',
    $requestOptions
);

foreach ($invoicesThatShouldBeImported as $invoice) {
    $importStatus = $importer->importInvoiceIntoErp($invoice);

    // The import succeeded. So we should mark the invoice as synced
    // to tell TRAEDE to close the invoice
    if ($importStatus === true) {
        $client->request(
            '/v10/invoices/mark-as-exported',
            'POST',
            [
                'invoices' => [
                    [
                        'invoice_id' => $invoice->id,
                        'system_id' => 'my_system',
                        'note' => 'Invoice was imported!'
                    ]
                ]
            ]
        );

    // Import failed. Throw error?
    } else {

    }
}

2 Sync credit notes from TRAEDE -> ERP​

Whenever an credit note is created in TRAEDE it should be synchronized to the ERP system. To synchronize an credit note you should follow 2 steps

  1. Use TRAEDE export API to get a list of all credit notes that have not been exported yet
  2. For each credit note import it into your ERP and if it was imported successfully mark it as exported in TRAEDE

It's important to mark credit notes as exported in TRAEDE so that you will not import them again

2.1 Get list of all credit notes that have not been exported yet​

TRAEDE has built-in export APIs that keeps track of which credit notes that have been exported and which have not. Read more about the export APIs here.

You should use the Credit Note Export API to fetch all credit notes that have not been exported yet.

2.2 Import credit note into ERP and mark it as synced​

The next step is to iterate over all the credit notes and import them into your ERP. If the import is successful you should send a call back marking the credit notes as exported. This is also done using the export API. You can read more about this here

Full pseudo-example in PHP​

This example assumes we have a client class that can make HTTP requests (e.g. could be made using Guzzle). The example also assumes you have a class named CreditNoteImporter that actually imports the invoice into your system.

<?php

// Just a fake class for making HTTP requests. Replace with something like guzzle or similar
// Notice our fake client class implements `requestAllPages` that makes sure to iterate
// through all pages of new/updated credit notes
$client = new Client();

// Just a fake class to simulate actually saving the credit note in our own system. Replace
// with your own implementation
$importer = new CreditNoteImporter();

$requestOptions = [
    'system_id' => 'my_system',
    'include_non_booked' => 0,

    // details we need to import the invoice
    'includes' => [
        'customer',
        'lines',
        'lines.product',
        'lines.variant'
    ]
];

$creditNotesThatShouldBeImported = $client->requestAllPages(
    '/v10/credit-notes/export',
    $requestOptions
);

foreach ($creditNotesThatShouldBeImported as $creditNote) {
    $importStatus = $importer->importCreditNoteIntoErp($creditNote);

    // The import succeeded. So we should mark the creditNote as synced
    // to tell TRAEDE to close the creditNote
    if ($importStatus === true) {
        $client->request(
            '/v10/credit-notes/mark-as-exported',
            'POST',
            [
                'credit_notes' => [
                    [
                        'credit_note_id' => $creditNote->id,
                        'system_id' => 'my_system',
                        'note' => 'Credit note was imported!'
                    ]
                ]
            ]
        );

    // Import failed. Throw error?
    } else {

    }
}

3 Sync accounting entries from TRAEDE -> ERP​

Accounting entries is entries generated by TRAEDE that should be booked directly in the accounting system as entries as well. These are typically COGS and Inventory Adjustments.

  1. Use TRAEDE export API to get a list of all accounting entries that have not been exported yet
  2. For each accounting entry import it into your ERP and if it was imported successfully mark it as exported in TRAEDE

It's important to mark accounting entries as exported in TRAEDE so that you will not import them again

3.1 Get list of all accounting entries that have not been exported yet​

TRAEDE has built-in export APIs that keeps track of which accounting entries that have been exported and which have not. Read more about the export APIs here.

You should use the Accounting Entry Export API to fetch all accounting entries that have not been exported yet.

3.2 Import accounting entry into ERP and mark it as synced​

The next step is to iterate over all the accounting entries and import them into your ERP. If the import is successful you should send a call back marking the accounting entries as exported. This is also done using the export API. You can read more about this here

Full pseudo-example in PHP​

This example assumes we have a client class that can make HTTP requests (e.g. could be made using Guzzle). The example also assumes you have a class named AccountingEntryImporter that actually imports the invoice into your system.

<?php

// Just a fake class for making HTTP requests. Replace with something like guzzle or similar
// Notice our fake client class implements `requestAllPages` that makes sure to iterate
// through all pages of new/updated accounting entries
$client = new Client();

// Just a fake class to simulate actually saving the accounting entry in our own system. Replace
// with your own implementation
$importer = new AccountingEntryImporter();

$requestOptions = [
    'system_id' => 'my_system'
];

$accountingEntriesThatShouldBeImported = $client->requestAllPages(
    '/v10/accounting-entries/export',
    $requestOptions
);

foreach ($accountingEntriesThatShouldBeImported as $accountingEntry) {
    $importStatus = $importer->importAccountingEntryIntoErp($accountingEntry);

    // The import succeeded. So we should mark the accountingEntry as synced
    // to tell TRAEDE to close the accountingEntry
    if ($importStatus === true) {
        $client->request(
            '/v10/accounting-entries/mark-as-exported',
            'POST',
            [
                'credit_notes' => [
                    [
                        'credit_note_id' => $accountingEntry->id,
                        'system_id' => 'my_system',
                        'note' => 'Accounting entry was imported!'
                    ]
                ]
            ]
        );

    // Import failed. Throw error?
    } else {

    }
}