¶ Real-Time API Integration with Marmin
For businesses handling a high volume of documents, Marmin offers a seamless API integration for real-time invoice processing. Our API is designed for simplicity, with two key endpoints:
- Create Invoice – Generates and submits an invoice.
- Retrieve Invoice – Fetches invoice details.
¶ API Documentation
For a detailed reference, visit our API documentation: Marmin API Docs
¶ Authentication and API Versioning
API access requires an API key, which can be found under Settings in your Marmin account. Ensure your key is included in every API request header for authentication.
¶ API Versioning Strategy
To support continuous innovation and the delivery of new features, we periodically release updated API versions. Each version ensures that new capabilities are made available to users while maintaining the stability of existing integrations.
¶ Key Guidelines
- Version Selection: Users must explicitly set their intended API version to ensure consistency with their development environment.
- Best Practice: We strongly recommend staying on the latest API version to benefit from the most recent performance improvements, security patches, and feature sets.
- Environment Parity: If you are operating across both Staging and Production environments, it is critical to ensure that the API versions are identical in both accounts to prevent unexpected behavior during deployment.
Setting the API version is handled under Organization Settings as shown below.
¶ Invoice Creation
To create an invoice, you must specify the seller details using the Business Profile ID in the request header. You can find this ID under Business Details in your account settings.
¶ Understanding and Managing ZATCA response
When you initiate a GET request for a document, we return the ZATCA response alongside it. There are three status values you will need to track to effectively manage the response on your end. Refer to meta_info.zatca_response.status to identify the ZATCA response.
meta_info.zatca_response.statusThe possible status values are:
- PASS: ZATCA has approved the document, and no further action is required on your part.
- WARNING: ZATCA has approved the document with warnings. The document is valid and can be issued to the buyer. However, you must resolve these warnings in future submissions.
- ERROR: ZATCA has rejected the document. You need to correct the issue and resubmit the document. When resubmitting, you may retain the original document number.
From a document processing POV, PASS and WARNING statuses can be considered as approved from ZATCA, and the invoice can be issued to the buyer.