E-Invoice Integration API — Integration Guide

This service sits between your application (ERP, POS, billing system) and Marmin, the UAE e-invoicing provider (Accredited Service Provider). You send JSON invoices to this service. It validates them, signs in to Marmin, submits them over Peppol to the buyer and the FTA, and tells you when they are cleared.

 Your app ──X-API-Key──▶ E-Invoice Integration API ──HMAC+JWT──▶ Marmin ──Peppol──▶ Buyer + FTA
    ▲                         │  validates, retries, signs in        │
    └──── forwarded webhook ◀─┴──── stores webhook events ◀──────────┘ (status updates)

This guide covers how to use this service. The document fields (what goes inside an invoice) are exactly Marmin's, so for those follow the official Marmin documentation linked in §6.

Marmin API version: 2026-05-07. Interactive reference: Swagger UI at /docs.

Contents

1. One-time setup
2. Environments
3. Calling this API
4. Endpoint catalogue
5. Document lifecycle and status
6. Document fields (Marmin documentation)
7. Webhooks
8. Errors and retries
9. Open points to confirm with Marmin

1. One-time setup

2. Environments

APP_ENV selects the environment. Each one has a committed settings file without secrets.

Secrets (MARMIN_CLIENT_ID, MARMIN_CLIENT_SECRET, MARMIN_WEBHOOK_SECRET, SERVICE_API_KEYS, WEBHOOK_FORWARD_SECRET) are provided as environment variables on the server, or in a git-ignored .env.<APP_ENV>.local file on a developer machine. Staging and production refuse to start if a required secret is missing. Use different credentials and keys for each environment.

3. Calling this API

• Base URL: https://<host>/api/v1 (locally http://localhost:8000/api/v1).
• Auth: header X-API-Key: <key> on every request. Your app never needs the Marmin Client ID/Secret. This service handles Marmin's HMAC signature and JWT token itself.
• Content type: application/json, UTF-8.
• Which company: pass ?business_profile_id=MBP-..., or leave it out to use DEFAULT_BUSINESS_PROFILE_ID. Always pass it if you issue documents for several legal entities.
• Request body: identical to Marmin's (§6). Don't send totals; Marmin calculates them.
• Defaults added for you if you leave them out: profile_execution_id = 00000000, document_currency_code = AED, invoice_type_code = 380 (sales) / 389 (purchase), credit_note_type_code = 381 (sales) / 261 (purchase), endpoint_scheme_id = 0235, price.base_quantity = 1.
• Checked before sending: the body is validated against Marmin's field rules. Mistakes come back immediately as 422 with the exact field path, and nothing is sent to Marmin.
• Pagination: page (0-based) and size (max 100). Responses are {content, page_number, total_pages, total_elements}.

curl -X POST "http://localhost:8000/api/v1/sales-invoices" \
  -H "X-API-Key: dev-local-key" -H "Content-Type: application/json" \
  -d @sales_invoice.json

Ready-made request bodies are in Swagger UI: open an endpoint, click Try it out, and pick from the Examples dropdown.

4. Endpoint catalogue

All paths are relative to /api/v1.

Sales and purchase documents

The same operations exist for each collection:

Other endpoints

5. Document lifecycle and status

POST ──▶ 201 Created ──▶ PENDING ──▶ APPROVED            (done: delivered to buyer + FTA)
           │                   └──▶ REJECTED            (final)
           └─▶ VALIDATION_FAILED ──▶ PUT /{id} (fix) ──▶ PENDING ...

GET /{collection}/{id}/status returns:

{
  "id": "bd63aefd-df82-430a-858c-ff77108584fe",
  "document_number": "INV-2026-0001",
  "overall_status": "PENDING",
  "participant_status": "PENDING",
  "fta_status": null,
  "is_final": false,
  "can_resubmit": false,
  "guidance": "Accepted by Marmin and in Peppol/FTA processing. Wait for a webhook or poll again later.",
  "validation_results": []
}

6. Document fields (Marmin documentation)

Request bodies are exactly Marmin's. Use the official pages below for every field, rule and code value.

Base: docs.ae.marmin.ai — Businesses overview

Differences from Marmin when calling this service: * Use our URLs (/api/v1/...) and the X-API-Key header, not Marmin's URLs or tokens. * business_profile_id goes in the query string (or comes from the default), not the URL path. * Don't send the party that is you: no accounting_supplier_party on sales documents, no accounting_customer_party on purchase documents. Marmin fills it from the business profile.

7. Webhooks

7.1 Marmin → this service

Marmin calls POST /api/v1/webhooks/marmin when a document changes state. The event types are sale.invoice.*, sale.credit_note.*, purchase.invoice.* and purchase.credit_note.* (.create / .update). Payload details are in Marmin webhooks.

For each webhook, this service: 1. Verifies the X-HMAC-Signature header with MARMIN_WEBHOOK_SECRET (and returns 401 if it's wrong). 2. Ignores duplicates (same webhook_event_id) and stores the event. 3. Replies 200 immediately. 4. Fetches the latest document from Marmin in the background and records its overall_status. 5. Forwards it to your application if WEBHOOK_FORWARD_URL is set.

7.2 This service → your application (optional)

POST {WEBHOOK_FORWARD_URL} with:

{
  "event":    { "event_type": "sale.invoice.update", "resource_id": "<document uuid>", "webhook_event_id": "...", "...": "..." },
  "document": { "...": "full latest document (null if it could not be fetched)" }
}

Reply with any 2xx. Failed deliveries are retried 3 times. Verify the signature over the raw body before parsing it:

import base64, hashlib, hmac

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = base64.b64encode(hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()).decode()
    return hmac.compare_digest(expected, signature)

static bool Verify(byte[] rawBody, string signature, string secret)
{
    using var h = new System.Security.Cryptography.HMACSHA256(System.Text.Encoding.UTF8.GetBytes(secret));
    var expected = Convert.ToBase64String(h.ComputeHash(rawBody));
    return System.Security.Cryptography.CryptographicOperations.FixedTimeEquals(
        System.Text.Encoding.UTF8.GetBytes(expected), System.Text.Encoding.UTF8.GetBytes(signature));
}

7.3 Polling instead

If your app can't receive webhooks, poll GET /api/v1/webhook-events?since=<last ISO time>. Each item has event_type, resource_id, overall_status and the full document.

8. Errors and retries

Automatic retries: * 429 (rate limited) is retried automatically for every request. * 5xx and network errors are retried for GET / PUT only. * A create (POST) is never retried on 5xx, so a failure can't produce a duplicate invoice. Before you try again, check GET /{collection}?document_number=....

Marmin's limits are 60 requests/minute for each document type and 30/minute for business profiles (rate limiting). For bulk uploads, send at most about 1 request per second.

9. Open points to confirm with Marmin