B2B Invoice Conversion API
Connect your ERP, billing platform, or partner portal to convert invoice files into the format your customer, supplier, or compliance process requires. The API accepts Base64 invoice data, applies secure request signing, and returns ready-to-store output for single-format or multi-format delivery workflows.
Base URL
All endpoints are relative to this base URL.
Architecture
| Area | What You Send | What You Receive |
|---|---|---|
| Authentication | Email and password sent to the login endpoint | A secure access token for all protected API requests |
| Request Signing | Raw JSON request body signed with the login token | Signature validation before conversion is accepted |
| Invoice Input | Source format, target format, file name, and Base64 invoice data | A validated conversion request ready for processing |
| Format Conversion | One or more requested output formats such as UBL, CII, Factur-X, ZUGFeRD, PDF, or SKEF | Converted invoice files returned in the requested formats |
| Custom Metadata | Optional customParams object for business-specific invoice fields | Additional values applied where supported by the selected target format |
| Response Handling | Standard JSON response envelope with success status and resultData | Base64 output mapped by target format key for easy download or storage |
Integration Flow
Supported Formats
| Code | Aliases | Description | Source | Target |
|---|---|---|---|---|
| XML_SDI | FATTURAPA | Italian FatturaPA — Sistema di Interscambio | ✓ | ✓ |
| UBL | PEPPOLBIS | OASIS UBL 2.1 / PEPPOL BIS Billing 3.0 | ✓ | ✓ |
| CII | CII/XML | UN/CEFACT Cross Industry Invoice | ✓ | ✓ |
| FACTUREX | FACTUR-X | Hybrid PDF+XML (CII embedded in PDF) — FR standard | ✓ | ✓ |
| ZUGFERD | XRECHNUNG | ZUGFeRD / German XRechnung — CII in PDF | ✓ | ✓ |
| — | Rendered invoice PDF via proprietary stylesheet | ✗ | ✓ | |
| SKEF | — | SKEF invoice XML | ✗ | ✓ |
Multi-output in one call
Pass multiple target formats separated by , in the targetFormat field.
"targetFormat": "FACTUREX,PEPPOLBIS,PDF"Security Model
Authentication — Login
/loginNo auth requiredObtain an access token for protected B2B API calls. The same token is also used when building the SHA-256 request signature for invoice conversion.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| String | Required | Registered B2B account email | |
| password | String | Required | Account password |
Request Example
{
"email": "client@company.com",
"password": "SecurePassword123"
}Success Response — 200 OK
{
"success": true,
"message": "Login successful",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}token securely. Send it as the Authorization: Bearer value and use it as the prefix when calculating the conversion request signature. Error Codes
| Status | Reason |
|---|---|
| 400 | email or password missing from body |
| 401 | Invalid credentials or account disabled |
| 500 | Server-side error |
SHA-256 Request Signing
Every call to the conversion endpoint must carry an X-SHA256 header. The value is the lowercase SHA-256 hex digest of token + rawBodyString, where rawBodyString is the exact JSON string sent in the request. Any whitespace or field-order difference produces a different hash and returns HTTP 401.
Formula
X-SHA256 = HEX_LOWERCASE( SHA256( token + rawBodyString ) )Step-by-Step
- 1Obtain
tokenfromdata.tokenin the login response. This is yourAuthorization: Bearervalue and the prefix for the SHA-256 signature. - 2Build the JSON body — construct your request object.
- 3Serialise deterministically — use
JSON.stringify(body)(Node.js) orjson.dumps(body, separators=(",",":"))(Python). Must be byte-for-byte identical to what you transmit. - 4Compute the request signature —
SHA256(token + bodyStr). - 5Hex-encode (lowercase) — convert the digest to lowercase hex.
- 6Set the header —
X-SHA256: <computed_hash>.
const crypto = require('crypto');
const axios = require('axios');
// token from login - used for Authorization and SHA-256 signing
const token = 'eyJhbGciOiJIUz...';
const payload = {
sourceFormat: 'XML_SDI',
targetFormat: 'FACTUREX',
fileName: 'IT12345678901_00001.xml',
data: '<base64-encoded-xml>',
};
// 1 – Serialise (must match transmitted bytes exactly)
const bodyStr = JSON.stringify(payload);
// 2 - Compute SHA-256 over token + raw JSON body
const sig = crypto
.createHash('sha256')
.update(token + bodyStr)
.digest('hex')
.toLowerCase();
// 3 – Send
const res = await axios.post(
'https://api.xml-babel-converter.com/api/v1/converter/convert/invoice',
bodyStr,
{
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`,
'X-SHA256': sig,
},
}
);Invoice Conversion Endpoint
/convert/invoiceRequired Headers
| Header | Value | Description |
|---|---|---|
| Content-Type | application/json | Must be strictly set |
| Authorization | Bearer <token> | Access token from /login |
| X-SHA256 | <sha256_hex> | SHA-256 of token + raw JSON body |
Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| sourceFormat | String | Required | Source format: XML_SDI, FATTURAPA, UBL, PEPPOLBIS, CII, CII/XML, FACTUREX, FACTUR-X, ZUGFERD, XRECHNUNG |
| targetFormat | String | Required | Target format(s) separated by ,. E.g. FACTUREX,PEPPOLBIS,PDF |
| fileName | String | Required | Original filename including extension (used for audit logging) |
| data | Base64 | Required | Base64-encoded content of the source file (XML or PDF) |
| customParams | Object | Optional | Key-value object for extended metadata. See customParams section. |
Success Response — 200 OK
{
"success": true,
"message": "File Converted Successfully",
"data": {
"resultData": {
"FACTUREX": "JVBERi0xLjcKJYGBgY...", // Base64 PDF
"PEPPOLBIS": "PD94bWwgdmVyc2lvbj...", // Base64 XML
"PDF": "JVBERi0xLjQKJ..." // Base64 PDF
}
}
}Decoding Output (Node.js)
const { FACTUREX, PEPPOLBIS, PDF } = response.data.data.resultData;
// Save Factur-X hybrid PDF
fs.writeFileSync('invoice_facturex.pdf', Buffer.from(FACTUREX, 'base64'));
// Save UBL XML
fs.writeFileSync('invoice_ubl.xml', Buffer.from(PEPPOLBIS, 'base64').toString('utf8'));
// Save plain PDF
fs.writeFileSync('invoice_plain.pdf', Buffer.from(PDF, 'base64'));Source Format Detection Logic
| sourceFormat values | Validation Check | How It Is Handled |
|---|---|---|
| XML_SDI, FATTURAPA | Must contain FatturaElettronica or p:FatturaElettronica invoice content | Processed as Italian FatturaPA XML |
| UBL, PEPPOLBIS | Must contain ubl:Invoice or <Invoice invoice content | Processed as UBL invoice XML |
| CII, CII/XML | Must contain CrossIndustryInvoice or rsm:CrossIndustryInvoice root element | Target output path |
| FACTUREX, FACTUR-X | File must be a PDF with embedded CrossIndustryInvoice XML | Processed as hybrid Factur-X PDF |
| ZUGFERD, XRECHNUNG | File must be a PDF with embedded CrossIndustryInvoice XML | Processed as hybrid ZUGFeRD/XRechnung PDF |
Target Formats & Output Types
| targetFormat value(s) | Output | Returned Content | Response Key |
|---|---|---|---|
| PDF binary | Readable invoice PDF | ||
| FACTUREX, FACTUR-X | PDF+XML hybrid | Factur-X PDF with embedded XML | FACTUREX |
| XRECHNUNG, ZUGFERD | PDF+XML hybrid | ZUGFeRD/XRechnung PDF with embedded XML | XRECHNUNG/ZUGFERD |
| XML_SDI, FATTURAPA | FatturaPA XML | Italian invoice XML | XML_SDI/FATTURAPA |
| SKEF | SKEF XML | SKEF invoice XML | SKEF |
| CII, CII/XML | CII XML | UN/CEFACT Cross Industry Invoice XML | CII/XML |
| UBL, PEPPOLBIS | UBL 2.1 XML | UBL / Peppol BIS invoice XML | UBL/PEPPOLBIS |
customParams — Extended Metadata
Use customParams for optional business metadata that may not exist in the source invoice. Supported targets apply matching values where possible; unsupported keys are ignored.
| Key | Type | Description | Example |
|---|---|---|---|
| buyerReference | String | Buyer reference (EN16931 BT-10) | ORD-2026-0099 |
| paymentMeansCode | String | Payment means code to force into the target | 30 |
| projectReference | String | Project or order reference | PRJ-2026-12 |
| note | Array<String> | Free-text note inserted into the target note field | Automatic conversion |
| contractId | String | Contract reference to embed in the target document | CTR-2026-001 |
Usage Example
{
"sourceFormat": "XML_SDI",
"targetFormat": "PEPPOLBIS",
"fileName": "IT12345678901_00001.xml",
"data": "PD94bWwgdmVyc2lvbj0iMS4wIi...",
"customParams": {
"buyerReference": "ORD-2026-0099",
"paymentMeansCode": "30",
"note": ["Automatic conversion via B2B API"]
}
}Error Handling
| Status | Trigger | Example Message |
|---|---|---|
| 200 | Successful conversion | File Converted Successfully |
| 400 | Missing mandatory parameter | Missing mandatory parameter |
| 400 | File content does not match declared sourceFormat | Not a valid FatturaPA Invoice. |
| 400 | Unsupported sourceFormat value | Unsupported source format |
| 401 | No Authorization header / invalid access token | Authentication required |
| 401 | SHA-256 header absent | Missing SHA256 signature (X-SHA256) |
| 401 | Computed SHA-256 hash does not match header | Invalid SHA256 signature |
| 401 | Account is not authorised for B2B access | Failed to authenticate token |
| 500 | Exception during format conversion | Conversion Error |
| 500 | Unexpected server error | Something went wrong |
Error Response Envelope
{
"success": false,
"message": "Invalid SHA256 signature",
"data": null
}Integration Examples
Full Flow: XML_SDI → Factur-X + UBL + PDF (Node.js)
End-to-end example: login, calculate the SHA-256 signature, convert, and save all output files.
const fs = require('fs');
const crypto = require('crypto');
const axios = require('axios');
const BASE = 'https://api.xml-babel-converter.com/api/v1/converter';
async function convertInvoice() {
// 1. Login
const { data: loginRes } = await axios.post(`${BASE}/login`, {
email: 'client@company.com',
password: 'SecurePass123',
});
// Use token for Authorization and SHA-256 signing
const { token } = loginRes.data;
// 2. Load and Base64-encode the source file
const fileB64 = fs.readFileSync('IT12345678901_00001.xml').toString('base64');
// 3. Build payload
const payload = {
sourceFormat: 'XML_SDI',
targetFormat: 'FACTUREX,PEPPOLBIS,PDF',
fileName: 'IT12345678901_00001.xml',
data: fileB64,
customParams: { buyerReference: 'ORD-2026-0099' },
};
// 4. Serialize and sign using SHA-256(token + bodyStr)
const bodyStr = JSON.stringify(payload);
const sig = crypto
.createHash('sha256')
.update(token + bodyStr)
.digest('hex')
.toLowerCase();
// 5. Send
const { data: convRes } = await axios.post(
`${BASE}/convert/invoice`,
bodyStr,
{
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`,
'X-SHA256': sig,
},
}
);
// 6. Decode and save outputs
const { FACTUREX, PEPPOLBIS, PDF } = convRes.data.resultData;
fs.writeFileSync('invoice_facturex.pdf', Buffer.from(FACTUREX, 'base64'));
fs.writeFileSync('invoice_ubl.xml', Buffer.from(PEPPOLBIS, 'base64').toString('utf8'));
fs.writeFileSync('invoice_plain.pdf', Buffer.from(PDF, 'base64'));
console.log('Conversion complete.');
}
convertInvoice().catch(console.error);cURL — XML_SDI → UBL
Quick command-line test. Replace TOKEN, COMPUTED_SHA256, and BASE64_XML with real values.
# Step 1: Login — obtain token
curl -s -X POST https://api.xml-babel-converter.com/api/v1/converter/login \
-H "Content-Type: application/json" \
-d '{"email":"client@company.com","password":"SecurePass123"}' \
| jq .data.token
# Step 2: Convert
# COMPUTED_SHA256 = sha256(TOKEN + exact JSON body below)
curl -X POST https://api.xml-babel-converter.com/api/v1/converter/convert/invoice \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-H "X-SHA256: COMPUTED_SHA256" \
-d '{
"sourceFormat": "XML_SDI",
"targetFormat": "PEPPOLBIS",
"fileName": "invoice.xml",
"data": "BASE64_XML"
}'B2B Conversion Working Flow
The conversion endpoint validates the uploaded invoice, reads the business fields it can recognise, applies any supported customParams, and generates the requested output files. Each result is returned in resultData under the response key listed in the target format table.
Conversion Matrix
| From \ To | XML_SDI | UBL | CII | Factur-X | ZUGFeRD | SKEF | |
|---|---|---|---|---|---|---|---|
| XML_SDI | — | ✓ | ✓ | ✓ | ✓ | ✓ | — |
| UBL | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ |
| CII | ✓ | ✓ | — | — | — | ✓ | — |
| Factur-X | ✓ | ✓ | — | — | — | — | — |
| ZUGFeRD | ✓ | ✓ | — | — | — | — | — |