Custom ERP E-Invoicing Integration: API-First Guide

Not every business runs QuickBooks, Xero, Odoo, or Sage — plenty run a custom-built system, an industry-specific platform, or an ERP with no existing e-invoicing connector at all. For those businesses, the path to NRS compliance is the API-first integration: no marketplace app to install, but full control over exactly how the integration works.

When You Need a Custom Integration

You’re in API-first territory if:

• Your ERP is fully custom or in-house built
• You use an ERP or platform without a ZUTAX marketplace app (SAP, Microsoft Dynamics, industry-specific software, spreadsheets-as-a-system)
• You need integration logic beyond what a pre-built marketplace app supports

The Core Pattern: One Endpoint, Three Steps

ZUTAX’s composite invoice endpoint handles issuing, signing, and transmitting an invoice in a single call:

1. Your system creates an invoice in its normal workflow
2. Your integration maps that invoice to ZUTAX’s format and calls the API
3. ZUTAX validates the data, generates the IRN, signs it, and transmits through the Peppol network — returning the result directly

import requests

def submit_invoice_to_zutax(erp_invoice):
    zutax_invoice = {
        "invoice_number": erp_invoice["doc_number"],
        "issue_date": erp_invoice["date"],
        "customer": {
            "legal_name": erp_invoice["customer_name"],
            "tax_id": erp_invoice["customer_tin"],
        },
        "lines": transform_line_items(erp_invoice["items"]),
        "currency_code": "NGN"
    }

    response = requests.post(
        "https://api.getzutax.com/v1/invoices",
        json=zutax_invoice,
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    return response.json()

A successful response returns the IRN, status, and QR code URL directly — no separate polling step required for the common case.

Use an Official SDK Instead of Raw HTTP

Rather than building the request/response handling from scratch, ZUTAX provides official SDKs for Python, PHP, JavaScript/TypeScript, .NET, and Java — with typed payloads, automatic retries, and built-in idempotency handling. For most custom integrations, starting from an SDK rather than raw HTTP calls saves significant development time. See the developer hub for SDK downloads and the quickstart guide.

Handling Status Updates with Webhooks

For asynchronous status changes — an invoice moving from validated to transmitted, or getting rejected — implement a webhook listener rather than polling the API repeatedly:

@app.post("/webhooks/zutax")
async def handle_zutax_webhook(payload: dict):
    event_type = payload["event"]
    invoice_id = payload["invoice_id"]

    if event_type == "invoice.transmitted":
        update_erp_invoice_status(invoice_id, "TRANSMITTED")
    elif event_type == "invoice.rejected":
        handle_rejection(invoice_id, payload["reason"])

    return {"received": True}

See the full webhooks guide for the complete event list and payload structure.

Choosing API vs. Webhook vs. Batch

• API-first: best when your ERP can make outbound calls and you want real-time results
• Webhook-driven: best when you want ZUTAX to notify your ERP of status changes rather than polling
• Batch file integration: best for legacy systems or very high invoice volumes, using CSV/XML export processed through ZUTAX’s batch processor

For the full breakdown of when to use each, see the ERP integration architecture guide.

Test in Sandbox Before Going Live

ZUTAX provides a sandbox environment (sandbox.api.getzutax.com) for testing your custom integration — submission, data transformation, validation error handling, and high-volume scenarios — without transmitting real invoices to NRS. Don’t skip this step; validation errors are far cheaper to catch in sandbox than after a customer has disputed a live invoice.

Build Your Custom Integration

Explore the API reference and create a free ZUTAX account to get your sandbox credentials and start building.