е-Фактура API

Брз старт

Ова е најкраткиот пат од нула до испорачана е-фактура: sandbox клуч, едно барање и статус што можете да го следите.

1. Добијте sandbox клуч

— клучевите за sandbox (тест околина) се издаваат при отворање на сметка; самостојна регистрација наскоро стигнува на овој сајт. Нема бесплатни пробни периоди ниту бесплатни планови за продукциска употреба, но пристапот до sandbox е дел од секоја сметка, платена или не. Кога ќе добиете клуч, sandbox клучот изгледа вака: mfk_test_....

2. Издадете е-фактура

POST /v1/einvoices го гради документот од вашиот JSON, го валидира, бара потпис од вашиот агент за потпишување и го поднесува до УЈП. Во sandbox околината, ако backend-от на компанијата е Merot-симулаторот, не ви треба вистински токен или инсталиран Bridge — видете Sandbox.

Секое пишување носи Idempotency-Key, а clientReference е ваш сопствен идентификатор за документот (безбедно за повторување со истото тело).

 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()); 

Одговорот пристигнува со 202 Accepted, со документот во состојба awaiting_signature или queued — сè уште не стигнал до УЈП.

3. Проверете го статусот

Проверувајте со GET /v1/einvoices/{id} (или, подобро, претплатете се на webhooks за УЈП сам да ве извести штом статусот се промени).

 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()); 

Штом статусот стигне до delivered, accepted или auto_accepted, документот има euid од УЈП и qrLink. Видете Животен циклус на документ за целосната листа на статуси.

Забелешка

Примерот погоре ги користи статусите на Merot-симулаторот. Кај вистински тест систем/продукција на УЈП, истите полиња се пополнуваат со вистинските одговори на УЈП — обликот не се менува.

Следни чекори

Автентикација — API клучеви наспроти OAuth 2.0 client credentials за софтверски куќи.
Потпишување: Режим А наспроти Режим Б — Merot Bridge или SDK-агент за потпишување.
Webhooks — добивајте известувања наместо постојано да проверувате.
Целосна API референца — секој endpoint, поле и грешка.