Sales Invoice Integration Guide

This guide provides a comprehensive overview of how to integrate and issue Sales Invoices via the Marmin API. It is designed to be accessible to technical engineers building the integration and business analysts mapping functional workflows.

1. Understanding the Sales Invoice

A Sales Invoice is a legal and compliance document issued by a seller to a buyer when goods or services are sold. It explicitly outlines the details of the transaction, items or services provided, agreed-upon pricing, and applicable taxes (VAT) required under UAE law.

The "Earliest of Three" Tax Liability Rule

Under tax regulations, your legal obligation to generate a tax invoice and report VAT arises at the earliest point of the following three operational milestones:

• Goods/Service Delivery: When the goods are delivered or services are fully rendered to the buyer.

• Payment Collection: When any payment (including partial down payments or advances) is received from the buyer.

• ERP Creation: When the document is first generated within your source accounting/ERP system.

2. Onboarding Prerequisites

Before your integration can successfully issue a sales invoice through the API pipeline, your account must clear three operational checkpoints:

• Active Marmin Account: Your parent developer space must be active with valid API authentication keys. See Obtain JWT access token.

• Completed Business Profile (Status: COMPLETED):

• When you first link your corporate Tax Identification Number (TIN) via EmaraTax, your account enters a temporary LINKED status. In this state, invoicing is disabled. See About Business Profile.

• You must furnish all remaining operational details (addresses, legal names, etc.) to transition the profile status from LINKED to COMPLETED. See Business Profile Management.

• Retrieve your `business_profile_id`: Every sales invoice payload must include the unique ID of the business profile issuing the document. You can extract this ID string directly from your Marmin Web App dashboard settings or fetch it via the Retrieve a business profile or List business profiles API.

3. The Document Transmission Lifecycle

The Marmin API relies on an asynchronous processing loop to ensure high performance and zero dropped messages during peak business hours.

Step 1: Submission

Your system pushes the formatted transaction object to the Create a sales invoice endpoint (POST /api/sales-invoices/{business_profile_id}).

Step 2: Ingestion Acceptance (201 Created)

If the payload passes basic authentication and structural formatting checks, Marmin's gateway immediately returns an HTTP status code of 201 Created. This means Marmin has securely accepted the file into its queue and is now running deep schema checks, digital signing, and transmission loops with the Federal Tax Authority (FTA).

Step 3: Result Retrieval

Because validation happens asynchronously, you cannot read the compliance outcome directly from the initial 201 response. You must discover the final status using one of two methods:

• The Pull Method (Polling): Your integration regularly queries the document state via the Retrieve a sales invoice API (GET /api/sales-invoices/{id}).

• The Push Method (Webhooks - Recommended): You expose an endpoint (a webhook listener) on your corporate network, and Marmin pushes real-time status updates directly to your system the instant processing completes. See Webhooks Overview and Webhook configuration.

4. Status Decoding & Core Financial Operations

Every time you retrieve a document's details via API or webhook, you must parse the `meta_info` object block to read the overall_status. The overall_status dictates exactly how your backend ERP must handle the transaction ledger.

Statuses are split into Intermediate States (temporary processing processing states) and End States (final compliance outcomes).

Invoice Type Code

All sales invoices created through this API are issued as Standard Tax Invoices or Invoice out of scope of tax.

Invoice Type Code: 380 (Commercial invoice) , 480 (Invoice out of scope of tax)

• This code is mandatory under invoicing standards

• It is assigned automatically and must not be provided or modified by the client

See the Sale invoice object for full field definitions.

Related Document Types

The invoicing system also supports related document types for adjustments and special billing scenarios:

Each document type has its own API endpoint and lifecycle.