Marmin Embedded Partner Integration: Technical Onboarding Overview

This page provides an explicit, comprehensive step-by-step technical workflow for partners who are deeply embedding Marmin's compliant e-invoicing capability directly into their own software architectures, ERP platforms, or accounting systems.

By following this guide, you will successfully provision end-user accounts, authenticate securely, claim and configure legal business profiles at a Tax Identification Number (TIN) level, and execute your first compliant invoice lifecycle.

Architectural & Concept Groupings

To successfully integrate, you must understand the relational hierarchy of entities within Marmin:

• Partner credentials: Global credentials issued to your software platform via the developer portal, used to authenticate your system across all downstream operations.

• Account (Organization): Every individual business or client company on your system must map precisely to a single, dedicated org_id in Marmin.

• Crucial: Never link multiple distinct companies or independent clients to the same Marmin account.

• Business Profile: A specific legal business entity configured inside an account. Business profiles are strictly established at the TIN (Tax Identification Number) level. If a single customer organization owns 3 distinct TINs, they must have 3 distinct Business Profiles provisioned under their account hierarchy.

Phase 1: Partner Level Authentication

Before executing any client-facing operations, your server must obtain a global partner JWT token. This token authenticates your platform and allows you to initiate account creation routines.

Step 1.1: Retrieve Global API Credentials

Log into your Marmin Developer Portal, https://dev.sandbox.ae.marmin.ai/. Navigate into the Settings panel to retrieve your production or sandbox credentials:

• client_id

• client_secret

Step 1.2: Generate the Partner JWT Token

Execute a GET request against the token access service. You must supply your client credentials within this call to safely issue a short-lived partner token. This token acts as your root authorization key for subsequent account setup tasks.

• Target Operation / API Name: Obtain JWT access token (GET)

• Expected Output: A valid partner_jwt_token. This token must be cached securely on your backend and included in authorization headers for Phase 2 operations.

Phase 2: Account Provisioning

Every time a new merchant or customer entity joins your platform and opts into e-invoicing, you must dynamically provision an independent organization context within Marmin.

Step 2.1: Request Account Onboard OTP

Initiate account set-up by informing Marmin that a new client needs a separate organization. You must provide the business owner's primary email address to bind the account security context.

• Target Operation / API Name: Request Account Onboard OTP (POST)

• Authorization Header: Authorization: Bearer <partner_jwt_token>

• Parameters Required: The primary account email address of the business user.

• Action Triggered: Marmin automatically routes a secure, time-sensitive One-Time Password (OTP) to the specified client email address.

Step 2.2: Solicit and Verify the Onboarding OTP

Your application UI must display a dedicated input prompt requesting the customer to enter the verification OTP received in their mailbox. Once entered, your backend must transmit this verification challenge back to Marmin along with the partner context.

• Target Operation / API Name: Verify Account Onboard OTP (POST)

• Authorization Header: Authorization: Bearer <partner_jwt_token>

• Parameters Required: The partner token, the account email address, and the exact verification OTP code provided by the end user.

• Expected Output (Success Response): A unique, immutable organization identifier: org_id.

Phase 3: Obtain Account-Specific JWT Token

For all remaining actions going forward, you can no longer use your global partner JWT token. You must exchange it for a token that is locked down specifically to that customer's account.

Step 3.1: Call the Account Access Token API

Send a request to get the dedicated tenant token using the org_id you saved in Phase 2.

• API Name: Obtain Account Access Token (POST)

• What to send: Pass your partner_jwt_token and the org_id received in Phase 2.

• What you get back: account_specific_JWT_token.

Phase 4: Legal Business Profile Claim & Set-up

A business profile captures all foundational parameters mandated by tax authorities, including official registered nomenclature, local physical street addressing, and Tax Identification Numbers. Since configurations exist strictly at the TIN level, validation requires cross-checking against state tax registration registries.

Step 4.1: Pre-Requisite Verification

Before launching a profile claim sequence, you must ensure that your end-customer has actively updated their settings within their regional EmaraTax portal. They must formally authorize and explicitly link Marmin as their designated Application Service Provider (ASP).

Step 4.2: Request Business Profile Claim OTP

Once the ASP linkage is done, your system can trigger the profile registration process by transmitting the business's verified TIN and associated official tax email account.

• Target Operation / API Name: Request BP claim OTP (POST)

• Authorization Header: Authorization: Bearer <account_specific_JWT_token>

• Parameters Required: The account_specific_JWT_token, the user's official tax portal registered email address, and the precise target TIN number.

• Action Triggered: Marmin triggers an automated OTP code message sent directly to the client's EmaraTax email. This prevents accidental cross-tenant claims or incorrect data assignment.

Step 4.3: Execute Business Profile Claim Verification

Capture the OTP from the customer and forward it through to complete the official organizational mapping.

• Target Operation / API Name: Claim BP with OTP (POST)

• Authorization Header: Authorization: Bearer <account_specific_JWT_token>

• Parameters Required: account_specific_JWT_token, official tax portal registered email address, target TIN number, and the received OTP code.

• Result: The core legal identity context is successfully created within Marmin's registry framework. You will receive the bp_id which is similar to the org_id but for a business profile.

Step 4.4: Inspect and Update Profile Details

A claimed profile typically contains read-only foundational entities mapped directly from official registries, but missing local business meta-data must be populated before launching invoice sequences.

First, pull current structural attributes by querying the Retrieve a business profile API (GET). This returns the baseline attributes. Keep note of fields that are pre-filled by Marmin as they are legally immutable.

Identify any missing structural elements (such as fine-grained line address descriptors, email, etc.) and submit them to complete the profile.

• Target Operation / API Name for Modification: Update a business profile (PUT)

• Authorization Header: Authorization: Bearer <account_specific_JWT_token>

• Prerequisite Execution Check: Execute another pull via the retrieval engine. The profile status MUST transition explicitly to Completed. If the status is not complete, all invoice issuance calls will fail validation checks.

Phase 5: Invoice Lifecycle Management

With an active, fully validated, and status-completed bp_id, your ERP software can safely begin publishing transactional documents.

Step 5.1: Issuing a Compliant Invoice

Compile transaction records within your application interface, formatting line items according to regional standards. Every submission payload must carry the tenant's context parameters.

• Target Operation / API Name: Create a sales invoice (POST)

• Authorization Header: Authorization: Bearer <account_specific_JWT_token>

• Mandatory URL Attribute: The unique bp_id fetched during the previous profile validation phase.

Step 5.2: Downstream Transaction Monitoring and Data Management

For all subsequent operational tasks, database queries, and ongoing client operations, your system must execute queries against the designated endpoints utilizing the account_specific_JWT_token. These ongoing lifecycle actions include:

• Retrieving granular historical invoice states or processing webhooks.

• Extracting compliant XMLs or PDFs for external archiving.

• Tracking official tax authority confirmation updates, audit trails, and buyer rejection notifications.

Token and Parameter Security Cheat Sheet

Refer to this quick-reference table to maintain proper authorization contexts across your codebase: