Batch Import using API

What this does

Instead of starting and stopping batches by hand in Factbird, your system — SAP or another ERP — can send us a small XML file whenever a batch starts, changes, or ends. We read that file and update your production line automatically; no one needs to log in and click anything.

This guide is for whoever sets up that integration on your end, usually someone on your IT or SAP team.

You can send:

• A new batch to create
• Updates to a batch already in progress
• A signal that a batch has finished
• A signal to remove a batch that shouldn't be there

Endpoint & authentication

Factbird provides an API Gateway endpoint for accepting batch data:

https://batch-import.factbird.com/<filename>.xml

Private Cloud installations use https://batch-import.<tenant>.factbird.com/<filename>.xml instead.

• URL: https://batch-import.factbird.com/<filename>.xml (<filename> should be changed out with a unique filename)
• Method: POST
• Body: XML content
• Port: 443 (just standard SSL/TLS)
• Batch Import key: xxxxxxXXXXXXXxxxxxxxXXXXXXxxxxxxx
• Headers (contains the Batch Import key):
  • Content-Type: application/xml
  • x-api-key: xxxxxxXXXXXXXxxxxxxxXXXXXXxxxxxxx

Note: The Batch Import API key is different from the API tokens that may be created through the dashboard. If you need to request a Batch Import API key, please email support@factbird.com.

Example cURL call:

curl -X POST -H "Content-Type: application/xml" \\
     -H 'x-api-key: xxxxxxXXXXXXXxxxxxxxXXXXXXxxxxxxx' \\
     '<https://batch-import.factbird.com/test-file.xml>' \\
     -d '<batch><product>....</batch>' # XML contents here

The above call will send the XML data to our API Gateway endpoint, which will validate the Batch Import key

The following parts should change according to your need:

• test-file.xml to a unique filename
• the value in x-api-key with your Batch Import key
• the data in '<batch><product>....</batch>' with your actual batch XML data

The basics of the XML data

Each file can contain one or more batches.

Single batch:

<?xml version="1.0" encoding="UTF-8"?>
<batch>
    <externalLineId>640-2</externalLineId>
    <batchNumber>000001214991</batchNumber>
    <product>
        <productExternalId>SKU-12345</productExternalId>
    </product>
</batch>

Multiple batches:

<?xml version="1.0" encoding="UTF-8"?>
<batches>
    <batch>
        ...
    </batch>
</batches>

Every batch needs at least three things:

• externalLineId — which production line this batch belongs to, using your own system's ID for that line (find Factbird's side of the mapping in Administration → Line → Identifier)
• batchNumber — your batch number
• product → productExternalId — which product is running

Everything else is optional — add it if you have the information and want Factbird to show it. XML tags are case-sensitive and use camelCase.

Fields you can include

About the batch

About the product

About the packaging (if relevant)

Notes

• The externalLineId is used to map which line the batch is on. If you’d like IDs that are easier to read, you can ask us to set up custom identifiers for your line. You can then use that custom identifier instead of the line ID from Administration. Please contact support@factbird.com if this could be of interest to you.
• productExternalId is used to find a matching product
  • It will be created if none are found
• packagingExternalId is used to find a matching packaging
  • It will be created if none are found
• batchNumber is used to find a matching batch
  • It will be created if none are found
• To start or stop the batch, simply add a value for the optional actualStart and actualStop fields.
• XML tags are case sensitive. As a rule of thumb, Factbird always uses "camelCase". See https://en.wikipedia.org/wiki/Camel_case

Special cases

Starting a new batch while one is still running

Normally, Factbird expects one batch to finish before the next one starts. But we know that's not always how things go on the floor — sometimes a new order comes in and the old batch just needs to be closed out automatically.

To do that, include actualStart for the new batch and set:

<forceStop>1</forceStop>

This tells Factbird to stop whatever's currently running on the line and start the new batch instead. Two conditions have to be met:

• The new batch needs a different batch number than the one currently running.
• The new batch's start time can't be earlier than the currently running batch's start time.

If either isn't true, Factbird leaves things as they are rather than guessing what you meant.

Removing a batch

If a batch was sent by mistake, or shouldn't exist for some reason, you can remove it:

<deleted>1</deleted>

Heads up: once a batch is deleted, there's no quick way to bring it back. Double-check the batch number before sending <deleted>1</deleted>.

Cleaning up leftover batches

If a schedule changes and some planned batches are no longer valid, you can have Factbird automatically clear out any batch that hasn't started yet and isn't mentioned in your latest file. Add this to the outer <batches> tag:

<batches removePending="true">

This only affects batches that haven't started — anything already running or finished is left alone.

Heads up: cleared-out batches can't be quickly restored either. Make sure removePending="true" is only set when you're sure those planned batches really shouldn't be there.

A complete example

<batches removePending="false">
    <batch>
        <externalLineId>25221be4-ac95-4a7f-b472-99cb8c69b540</externalLineId>
        <batchNumber>000001214992</batchNumber>
        <actualStart>2026-09-22T13:30:00.000Z</actualStart>
        <plannedAmount>150</plannedAmount>
        <comment>New order released, replaces whatever was running</comment>
        <forceStop>1</forceStop>
        <product>
            <productExternalId>SKU-67890</productExternalId>
            <productName>Next product</productName>
        </product>
    </batch>
</batches>

Getting help

Not sure how to structure a file for your specific setup? Reach out to your Factbird contact, or email support@factbird.com — we're happy to look at a sample file together and make sure it's set up right before it goes live. Custom line identifiers and schema files for validation are also available on request.