B2B Invoice Conversion API

Secure REST API for automated invoice exchange

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.

Bidirectional
Parse or generate XML_SDI, UBL, CII, Factur-X, ZUGFeRD
Dual-Layer Auth
Bearer token + per-request SHA-256 signature
Multi-Output
Request multiple target formats in one API call
PDF Rendering
Proprietary stylesheet renders any XML into PDF
Audit Logging
Every conversion persisted to BToBConversion
Plug-and-Play
Base64 in → Base64 out, no file upload needed

Base URL

https://api.xml-babel-converter.com/api/v1/converter

All endpoints are relative to this base URL.

Architecture

AreaWhat You SendWhat You Receive
AuthenticationEmail and password sent to the login endpointA secure access token for all protected API requests
Request SigningRaw JSON request body signed with the login tokenSignature validation before conversion is accepted
Invoice InputSource format, target format, file name, and Base64 invoice dataA validated conversion request ready for processing
Format ConversionOne or more requested output formats such as UBL, CII, Factur-X, ZUGFeRD, PDF, or SKEFConverted invoice files returned in the requested formats
Custom MetadataOptional customParams object for business-specific invoice fieldsAdditional values applied where supported by the selected target format
Response HandlingStandard JSON response envelope with success status and resultDataBase64 output mapped by target format key for easy download or storage

Integration Flow

LoginBuild JSON PayloadSign RequestSend ConversionReceive ResultDecode FilesStore Output

Supported Formats

CodeAliasesDescriptionSourceTarget
XML_SDIFATTURAPAItalian FatturaPA — Sistema di Interscambio
UBLPEPPOLBISOASIS UBL 2.1 / PEPPOL BIS Billing 3.0
CIICII/XMLUN/CEFACT Cross Industry Invoice
FACTUREXFACTUR-XHybrid PDF+XML (CII embedded in PDF) — FR standard
ZUGFERDXRECHNUNGZUGFeRD / German XRechnung — CII in PDF
PDFRendered invoice PDF via proprietary stylesheet
SKEFSKEF invoice XML

Multi-output in one call

Pass multiple target formats separated by , in the targetFormat field.

"targetFormat": "FACTUREX,PEPPOLBIS,PDF"

Security Model

Access Token
Issued by /login and required for every protected API request.
SHA-256 Signature
Computed from the login token plus the exact raw JSON request body. Requests with mismatched signatures are rejected with HTTP 401.
B2B Access
Only active B2B accounts can use these endpoints.
Active Token
Requests must use a token that is still valid for the account.

Authentication — Login

POST/loginNo auth required

Obtain 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

ParameterTypeRequiredDescription
emailStringRequiredRegistered B2B account email
passwordStringRequiredAccount password

Request Example

{
        "email": "client@company.com",
        "password": "SecurePassword123"
      }

Success Response — 200 OK

{
        "success": true,
        "message": "Login successful",
        "data": {
          "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        }
      }
Important: Store the returned token securely. Send it as the Authorization: Bearer value and use it as the prefix when calculating the conversion request signature.

Error Codes

StatusReason
400email or password missing from body
401Invalid credentials or account disabled
500Server-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

  1. 1Obtain token from data.token in the login response. This is your Authorization: Bearer value and the prefix for the SHA-256 signature.
  2. 2Build the JSON body — construct your request object.
  3. 3Serialise deterministically — use JSON.stringify(body) (Node.js) or json.dumps(body, separators=(",",":")) (Python). Must be byte-for-byte identical to what you transmit.
  4. 4Compute the request signature — SHA256(token + bodyStr).
  5. 5Hex-encode (lowercase) — convert the digest to lowercase hex.
  6. 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

POST/convert/invoice

Required Headers

HeaderValueDescription
Content-Typeapplication/jsonMust be strictly set
AuthorizationBearer <token>Access token from /login
X-SHA256<sha256_hex>SHA-256 of token + raw JSON body

Request Body Parameters

ParameterTypeRequiredDescription
sourceFormatStringRequiredSource format: XML_SDI, FATTURAPA, UBL, PEPPOLBIS, CII, CII/XML, FACTUREX, FACTUR-X, ZUGFERD, XRECHNUNG
targetFormatStringRequiredTarget format(s) separated by ,. E.g. FACTUREX,PEPPOLBIS,PDF
fileNameStringRequiredOriginal filename including extension (used for audit logging)
dataBase64RequiredBase64-encoded content of the source file (XML or PDF)
customParamsObjectOptionalKey-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 valuesValidation CheckHow It Is Handled
XML_SDI, FATTURAPAMust contain FatturaElettronica or p:FatturaElettronica invoice contentProcessed as Italian FatturaPA XML
UBL, PEPPOLBISMust contain ubl:Invoice or <Invoice invoice contentProcessed as UBL invoice XML
CII, CII/XMLMust contain CrossIndustryInvoice or rsm:CrossIndustryInvoice root elementTarget output path
FACTUREX, FACTUR-XFile must be a PDF with embedded CrossIndustryInvoice XMLProcessed as hybrid Factur-X PDF
ZUGFERD, XRECHNUNGFile must be a PDF with embedded CrossIndustryInvoice XMLProcessed as hybrid ZUGFeRD/XRechnung PDF
Validation is strict. If the file fails the content check, the request is rejected with HTTP 400. The failed attempt is still logged to the audit collection with status Failed.

Target Formats & Output Types

targetFormat value(s)OutputReturned ContentResponse Key
PDFPDF binaryReadable invoice PDFPDF
FACTUREX, FACTUR-XPDF+XML hybridFactur-X PDF with embedded XMLFACTUREX
XRECHNUNG, ZUGFERDPDF+XML hybridZUGFeRD/XRechnung PDF with embedded XMLXRECHNUNG/ZUGFERD
XML_SDI, FATTURAPAFatturaPA XMLItalian invoice XMLXML_SDI/FATTURAPA
SKEFSKEF XMLSKEF invoice XMLSKEF
CII, CII/XMLCII XMLUN/CEFACT Cross Industry Invoice XMLCII/XML
UBL, PEPPOLBISUBL 2.1 XMLUBL / Peppol BIS invoice XMLUBL/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.

KeyTypeDescriptionExample
buyerReferenceStringBuyer reference (EN16931 BT-10)ORD-2026-0099
paymentMeansCodeStringPayment means code to force into the target30
projectReferenceStringProject or order referencePRJ-2026-12
noteArray<String>Free-text note inserted into the target note fieldAutomatic conversion
contractIdStringContract reference to embed in the target documentCTR-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

StatusTriggerExample Message
200Successful conversionFile Converted Successfully
400Missing mandatory parameterMissing mandatory parameter
400File content does not match declared sourceFormatNot a valid FatturaPA Invoice.
400Unsupported sourceFormat valueUnsupported source format
401No Authorization header / invalid access tokenAuthentication required
401SHA-256 header absentMissing SHA256 signature (X-SHA256)
401Computed SHA-256 hash does not match headerInvalid SHA256 signature
401Account is not authorised for B2B accessFailed to authenticate token
500Exception during format conversionConversion Error
500Unexpected server errorSomething 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.

XML_SDIUBLCIIFactur-XZUGFeRD
↓  Validate Source  ↓
Normalized Invoice Data
↓  Generate Requested Outputs  ↓
XML_SDIUBLCIIFactur-XZUGFeRDPDFSKEF

Conversion Matrix

From \ ToXML_SDIUBLCIIFactur-XZUGFeRDPDFSKEF
XML_SDI
UBL
CII
Factur-X
ZUGFeRD
B2B Invoice Conversion API · Technical Documentation v1.0 · Confidential