e-Faktura API

Quickstart

This walks through the shortest path from nothing to a delivered e-invoice: a sandbox key, one request, and a status you can poll.

1. Get a sandbox key

— sandbox keys are issued as we onboard accounts; self-serve signup is coming to this site. There are no free trials or free plans for production use, but sandbox access is part of every account, paid or not. Once you have one, a sandbox key looks like mfk_test_....

2. Issue an e-invoice

POST /v1/einvoices builds the document from your JSON, validates it, requests a signature from your signing agent, and submits it to UJP. In the sandbox, if the company’s backend is the Merot simulator, no real token or Bridge installation is required — see Sandbox.

Every write carries an Idempotency-Key, and clientReference is your own identifier for the document (safe to retry with the same body).

 curl -X POST "https://api.efaktura.merot.com/v1/einvoices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: a-unique-key-per-request" \
  -H "Content-Type: application/json" \
  -d '{
    "clientReference": "inv-2026-000481",
    "documentType": "100",
    "number": "000481",
    "issueDate": "2026-10-08",
    "turnoverDate": "2026-10-08",
    "deliveryDate": null,
    "periodStart": null,
    "periodEnd": null,
    "notes": null,
    "header": null,
    "footer": null,
    "buyer": {
      "country": "MK",
      "taxNumber": "4012009123456",
      "vatNumber": null,
      "name": "Купувач ДОО",
      "address": {
        "street": "Илинденска",
        "number": "1",
        "postalCode": "1000",
        "city": "Скопје"
      },
      "subsidiaryCode": null,
      "subsidiaryName": null,
      "contact": null,
      "email": "faktura@buyer.mk"
    },
    "receiver": null,
    "references": [],
    "payment": {
      "typeCode": "1",
      "currency": "MKD",
      "dueDate": "2026-11-07",
      "dueDays": 30,
      "terms": null,
      "note": null,
      "exchangeRate": null,
      "exchangeRateDate": null
    },
    "lines": [
      {
        "sku": null,
        "description": "Консултантски услуги — септември 2026",
        "unit": "услуга",
        "quantity": "1",
        "unitPrice": "10000.00",
        "unitDiscount": "0",
        "vatPercent": "18",
        "taxIndicator": "1",
        "domesticProduct": null
      }
    ],
    "advance": null,
    "expectedTotals": {
      "net": "10000.00",
      "vat": "1800.00",
      "gross": "11800.00",
      "currency": "MKD"
    }
  }' 
 const response = await fetch("https://api.efaktura.merot.com/v1/einvoices", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Idempotency-Key": "a-unique-key-per-request",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "clientReference": "inv-2026-000481",
    "documentType": "100",
    "number": "000481",
    "issueDate": "2026-10-08",
    "turnoverDate": "2026-10-08",
    "deliveryDate": null,
    "periodStart": null,
    "periodEnd": null,
    "notes": null,
    "header": null,
    "footer": null,
    "buyer": {
      "country": "MK",
      "taxNumber": "4012009123456",
      "vatNumber": null,
      "name": "Купувач ДОО",
      "address": {
        "street": "Илинденска",
        "number": "1",
        "postalCode": "1000",
        "city": "Скопје"
      },
      "subsidiaryCode": null,
      "subsidiaryName": null,
      "contact": null,
      "email": "faktura@buyer.mk"
    },
    "receiver": null,
    "references": [],
    "payment": {
      "typeCode": "1",
      "currency": "MKD",
      "dueDate": "2026-11-07",
      "dueDays": 30,
      "terms": null,
      "note": null,
      "exchangeRate": null,
      "exchangeRateDate": null
    },
    "lines": [
      {
        "sku": null,
        "description": "Консултантски услуги — септември 2026",
        "unit": "услуга",
        "quantity": "1",
        "unitPrice": "10000.00",
        "unitDiscount": "0",
        "vatPercent": "18",
        "taxIndicator": "1",
        "domesticProduct": null
      }
    ],
    "advance": null,
    "expectedTotals": {
      "net": "10000.00",
      "vat": "1800.00",
      "gross": "11800.00",
      "currency": "MKD"
    }
  }),
});

const data = await response.json();
console.log(data); 
 import requests

response = requests.post(
    "https://api.efaktura.merot.com/v1/einvoices",
    headers={
    "Authorization": "Bearer YOUR_API_KEY",
    "Idempotency-Key": "a-unique-key-per-request",
    "Content-Type": "application/json",
    },
    json={
    "clientReference": "inv-2026-000481",
    "documentType": "100",
    "number": "000481",
    "issueDate": "2026-10-08",
    "turnoverDate": "2026-10-08",
    "deliveryDate": None,
    "periodStart": None,
    "periodEnd": None,
    "notes": None,
    "header": None,
    "footer": None,
    "buyer": {
        "country": "MK",
        "taxNumber": "4012009123456",
        "vatNumber": None,
        "name": "Купувач ДОО",
        "address": {
            "street": "Илинденска",
            "number": "1",
            "postalCode": "1000",
            "city": "Скопје"
        },
        "subsidiaryCode": None,
        "subsidiaryName": None,
        "contact": None,
        "email": "faktura@buyer.mk"
    },
    "receiver": None,
    "references": [],
    "payment": {
        "typeCode": "1",
        "currency": "MKD",
        "dueDate": "2026-11-07",
        "dueDays": 30,
        "terms": None,
        "note": None,
        "exchangeRate": None,
        "exchangeRateDate": None
    },
    "lines": [
        {
            "sku": None,
            "description": "Консултантски услуги — септември 2026",
            "unit": "услуга",
            "quantity": "1",
            "unitPrice": "10000.00",
            "unitDiscount": "0",
            "vatPercent": "18",
            "taxIndicator": "1",
            "domesticProduct": None
        }
    ],
    "advance": None,
    "expectedTotals": {
        "net": "10000.00",
        "vat": "1800.00",
        "gross": "11800.00",
        "currency": "MKD"
    }
},
)

print(response.json()) 
 <?php
// composer require guzzlehttp/guzzle
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.efaktura.merot.com/v1/einvoices', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Idempotency-Key' => 'a-unique-key-per-request',
        'Content-Type' => 'application/json',
    ],
    'json' => [
    'clientReference' => 'inv-2026-000481',
    'documentType' => '100',
    'number' => '000481',
    'issueDate' => '2026-10-08',
    'turnoverDate' => '2026-10-08',
    'deliveryDate' => null,
    'periodStart' => null,
    'periodEnd' => null,
    'notes' => null,
    'header' => null,
    'footer' => null,
    'buyer' => [
        'country' => 'MK',
        'taxNumber' => '4012009123456',
        'vatNumber' => null,
        'name' => 'Купувач ДОО',
        'address' => [
            'street' => 'Илинденска',
            'number' => '1',
            'postalCode' => '1000',
            'city' => 'Скопје',
        ],
        'subsidiaryCode' => null,
        'subsidiaryName' => null,
        'contact' => null,
        'email' => 'faktura@buyer.mk',
    ],
    'receiver' => null,
    'references' => [],
    'payment' => [
        'typeCode' => '1',
        'currency' => 'MKD',
        'dueDate' => '2026-11-07',
        'dueDays' => 30,
        'terms' => null,
        'note' => null,
        'exchangeRate' => null,
        'exchangeRateDate' => null,
    ],
    'lines' => [
        [
            'sku' => null,
            'description' => 'Консултантски услуги — септември 2026',
            'unit' => 'услуга',
            'quantity' => '1',
            'unitPrice' => '10000.00',
            'unitDiscount' => '0',
            'vatPercent' => '18',
            'taxIndicator' => '1',
            'domesticProduct' => null,
        ],
    ],
    'advance' => null,
    'expectedTotals' => [
        'net' => '10000.00',
        'vat' => '1800.00',
        'gross' => '11800.00',
        'currency' => 'MKD',
    ],
],
]);

echo $response->getBody(); 
 using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.efaktura.merot.com/v1/einvoices");
request.Headers.Add("Authorization", "Bearer YOUR_API_KEY");
request.Headers.Add("Idempotency-Key", "a-unique-key-per-request");
var json = /* lang=json */ @"{
  ""clientReference"": ""inv-2026-000481"",
  ""documentType"": ""100"",
  ""number"": ""000481"",
  ""issueDate"": ""2026-10-08"",
  ""turnoverDate"": ""2026-10-08"",
  ""deliveryDate"": null,
  ""periodStart"": null,
  ""periodEnd"": null,
  ""notes"": null,
  ""header"": null,
  ""footer"": null,
  ""buyer"": {
    ""country"": ""MK"",
    ""taxNumber"": ""4012009123456"",
    ""vatNumber"": null,
    ""name"": ""Купувач ДОО"",
    ""address"": {
      ""street"": ""Илинденска"",
      ""number"": ""1"",
      ""postalCode"": ""1000"",
      ""city"": ""Скопје""
    },
    ""subsidiaryCode"": null,
    ""subsidiaryName"": null,
    ""contact"": null,
    ""email"": ""faktura@buyer.mk""
  },
  ""receiver"": null,
  ""references"": [],
  ""payment"": {
    ""typeCode"": ""1"",
    ""currency"": ""MKD"",
    ""dueDate"": ""2026-11-07"",
    ""dueDays"": 30,
    ""terms"": null,
    ""note"": null,
    ""exchangeRate"": null,
    ""exchangeRateDate"": null
  },
  ""lines"": [
    {
      ""sku"": null,
      ""description"": ""Консултантски услуги — септември 2026"",
      ""unit"": ""услуга"",
      ""quantity"": ""1"",
      ""unitPrice"": ""10000.00"",
      ""unitDiscount"": ""0"",
      ""vatPercent"": ""18"",
      ""taxIndicator"": ""1"",
      ""domesticProduct"": null
    }
  ],
  ""advance"": null,
  ""expectedTotals"": {
    ""net"": ""10000.00"",
    ""vat"": ""1800.00"",
    ""gross"": ""11800.00"",
    ""currency"": ""MKD""
  }
}";
request.Content = new StringContent(json, Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body); 
 import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.efaktura.merot.com/v1/einvoices"))
    .headers("Authorization", "Bearer YOUR_API_KEY", "Idempotency-Key", "a-unique-key-per-request", "Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(/* JSON */ "{   \"clientReference\": \"inv-2026-000481\",   \"documentType\": \"100\",   \"number\": \"000481\",   \"issueDate\": \"2026-10-08\",   \"turnoverDate\": \"2026-10-08\",   \"deliveryDate\": null,   \"periodStart\": null,   \"periodEnd\": null,   \"notes\": null,   \"header\": null,   \"footer\": null,   \"buyer\": {     \"country\": \"MK\",     \"taxNumber\": \"4012009123456\",     \"vatNumber\": null,     \"name\": \"Купувач ДОО\",     \"address\": {       \"street\": \"Илинденска\",       \"number\": \"1\",       \"postalCode\": \"1000\",       \"city\": \"Скопје\"     },     \"subsidiaryCode\": null,     \"subsidiaryName\": null,     \"contact\": null,     \"email\": \"faktura@buyer.mk\"   },   \"receiver\": null,   \"references\": [],   \"payment\": {     \"typeCode\": \"1\",     \"currency\": \"MKD\",     \"dueDate\": \"2026-11-07\",     \"dueDays\": 30,     \"terms\": null,     \"note\": null,     \"exchangeRate\": null,     \"exchangeRateDate\": null   },   \"lines\": [     {       \"sku\": null,       \"description\": \"Консултантски услуги — септември 2026\",       \"unit\": \"услуга\",       \"quantity\": \"1\",       \"unitPrice\": \"10000.00\",       \"unitDiscount\": \"0\",       \"vatPercent\": \"18\",       \"taxIndicator\": \"1\",       \"domesticProduct\": null     }   ],   \"advance\": null,   \"expectedTotals\": {     \"net\": \"10000.00\",     \"vat\": \"1800.00\",     \"gross\": \"11800.00\",     \"currency\": \"MKD\"   } }"))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body()); 

The response comes back 202 Accepted with the document in awaiting_signature or queued state — it hasn’t reached UJP yet.

3. Check its status

Poll GET /v1/einvoices/{id} (or, better, subscribe to webhooks so UJP tells you the moment the status changes).

 curl -X GET "https://api.efaktura.merot.com/v1/einvoices/einv_123" \
  -H "Authorization: Bearer YOUR_API_KEY" 
 const response = await fetch("https://api.efaktura.merot.com/v1/einvoices/einv_123", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});

const data = await response.json();
console.log(data); 
 import requests

response = requests.get(
    "https://api.efaktura.merot.com/v1/einvoices/einv_123",
    headers={
    "Authorization": "Bearer YOUR_API_KEY",
    },
)

print(response.json()) 
 <?php
// composer require guzzlehttp/guzzle
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.efaktura.merot.com/v1/einvoices/einv_123', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
    ],
]);

echo $response->getBody(); 
 using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.efaktura.merot.com/v1/einvoices/einv_123");
request.Headers.Add("Authorization", "Bearer YOUR_API_KEY");


using var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body); 
 import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.efaktura.merot.com/v1/einvoices/einv_123"))
    .headers("Authorization", "Bearer YOUR_API_KEY")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body()); 

Once status reaches delivered, accepted or auto_accepted, the document has a UJP euid and a qrLink. See Document lifecycle for the full status list.

Note

The example above uses the Merot simulator’s status values. Against real UJP test/production, the same fields are populated by UJP’s own responses — the shape doesn’t change.

Next steps

Authentication — API keys vs OAuth 2.0 client credentials for vendors.
Signing: Mode A vs Mode B — Merot Bridge or an SDK signing worker.
Webhooks — get notified instead of polling.
Full API reference — every endpoint, field and error.