Serbia Invoices (SEF eFaktura national API)

Official3 toolsLive

by junter1989k-ai · JavaScript

Serbia SEF eFaktura invoices for AI agents: build UBL 2.1 SRB-CIUS, upload to SEF, query, cancel.

Topics

ai-agentclaudeefakturainvoicemcpmcp-serverserbiavatwishpool

Captured live from the server via tools/list.

create_invoice

Issue a Serbia B2B electronic invoice (elektronska faktura) into the national SEF eFaktura system (Ministry of Finance). Builds UBL 2.1 XML in the SRB-CIUS customization (Serbia's CIUS of EN 16931) and uploads it under your own SEF API key. Bring your own credential as a header: x-sef-api-key (the API key you self-generate in the SEF portal under Settings -> API management / Podesavanja -> Upravljanje API). Header x-sef-mode: prod switches to the live rail (default = demo, no fiscal effect). You must supply your own seller identity in the arguments (supplier_pib + supplier_name), because SEF validates that the seller in the XML matches your account. Returns sales_invoice_id (SEF's invoice id) — poll query_invoice with it to learn the status (New/Sent/Approved/Rejected/Cancelled...). Serbian VAT rates: 20 (standard), 10 (reduced), 0 (zero-rated). Amounts are in RSD (Serbian dinar). Set send_to_cir=true when the buyer is a budget / public-sector user (registration in the Central Invoice Register / CRF is then mandatory).

Parameters17

supplier_pib	string	required	Your (seller) PIB / tax number (poreski identifikacioni broj), exactly 9 digits. Required — SEF validates it against your API-key account.
supplier_name	string	required	Your (seller) legal name (BT-27). Required for a valid invoice.
supplier_registration_number	string	optional	Your (seller) company registration number (maticni broj), 8 digits (BT-30). Recommended.
supplier_address	string	optional	Your (seller) street address (BT-35). Recommended.
supplier_city	string	optional	Your (seller) city (BT-37). Default Beograd.
customer_name	string	required	Buyer legal name (naziv) as registered.
customer_pib	string	required	Buyer PIB / tax number, exactly 9 digits.
customer_registration_number	string	optional	Buyer company registration number (maticni broj), 8 digits (BT-47). Recommended.
customer_address	string	required	Buyer street address (BT-50 address line 1).
customer_city	string	optional	Buyer city (BT-52). Default Beograd.
customer_country	string	optional	Buyer country code (BT-55). Default RS.
invoice_number	string	optional	Your invoice number (BT-1). Auto-generated if omitted.
issue_date	string	optional	Invoice issue date (BT-2), YYYY-MM-DD. Default: today (UTC).
due_date	string	optional	Optional payment due date (BT-9), YYYY-MM-DD.
currency	string	optional	Document currency (BT-5). Default RSD.
send_to_cir	boolean	optional	Send to the Central Invoice Register (CRF). Set true when the buyer is a budget / public-sector user; default false for private B2B.
lines	array	required	Invoice lines. Each: name, unit_price (net, VAT-exclusive, RSD), vat_rate (20\|10\|0), optional quantity (default 1) and unit_code (UN/ECE Rec 20, default C62 = piece).

Raw schema

{
  "type": "object",
  "properties": {
    "supplier_pib": {
      "type": "string",
      "description": "Your (seller) PIB / tax number (poreski identifikacioni broj), exactly 9 digits. Required — SEF validates it against your API-key account."
    },
    "supplier_name": {
      "type": "string",
      "description": "Your (seller) legal name (BT-27). Required for a valid invoice."
    },
    "supplier_registration_number": {
      "type": "string",
      "description": "Your (seller) company registration number (maticni broj), 8 digits (BT-30). Recommended."
    },
    "supplier_address": {
      "type": "string",
      "description": "Your (seller) street address (BT-35). Recommended."
    },
    "supplier_city": {
      "type": "string",
      "description": "Your (seller) city (BT-37). Default Beograd."
    },
    "customer_name": {
      "type": "string",
      "description": "Buyer legal name (naziv) as registered."
    },
    "customer_pib": {
      "type": "string",
      "description": "Buyer PIB / tax number, exactly 9 digits."
    },
    "customer_registration_number": {
      "type": "string",
      "description": "Buyer company registration number (maticni broj), 8 digits (BT-47). Recommended."
    },
    "customer_address": {
      "type": "string",
      "description": "Buyer street address (BT-50 address line 1)."
    },
    "customer_city": {
      "type": "string",
      "description": "Buyer city (BT-52). Default Beograd."
    },
    "customer_country": {
      "type": "string",
      "description": "Buyer country code (BT-55). Default RS."
    },
    "invoice_number": {
      "type": "string",
      "description": "Your invoice number (BT-1). Auto-generated if omitted."
    },
    "issue_date": {
      "type": "string",
      "description": "Invoice issue date (BT-2), YYYY-MM-DD. Default: today (UTC)."
    },
    "due_date": {
      "type": "string",
      "description": "Optional payment due date (BT-9), YYYY-MM-DD."
    },
    "currency": {
      "type": "string",
      "description": "Document currency (BT-5). Default RSD."
    },
    "send_to_cir": {
      "type": "boolean",
      "description": "Send to the Central Invoice Register (CRF). Set true when the buyer is a budget / public-sector user; default false for private B2B."
    },
    "lines": {
      "type": "array",
      "minItems": 1,
      "description": "Invoice lines. Each: name, unit_price (net, VAT-exclusive, RSD), vat_rate (20|10|0), optional quantity (default 1) and unit_code (UN/ECE Rec 20, default C62 = piece).",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Item name/description (BT-153)."
          },
          "unit_price": {
            "type": "number",
            "description": "Net unit price in RSD, VAT-exclusive (BT-146)."
          },
          "vat_rate": {
            "type": "number",
            "description": "VAT rate percent: 20 standard, 10 reduced, 0 zero-rated (BT-152)."
          },
          "quantity": {
            "type": "number",
            "description": "Quantity (BT-129). Default 1."
          },
          "unit_code": {
            "type": "string",
            "description": "Unit of measure UN/ECE Rec 20 code (BT-130). Default C62 (piece)."
          }
        },
        "required": [
          "name",
          "unit_price",
          "vat_rate"
        ]
      }
    }
  },
  "required": [
    "supplier_pib",
    "supplier_name",
    "customer_name",
    "customer_pib",
    "customer_address",
    "lines"
  ]
}

query_invoice

Check the SEF status of a sales invoice created by create_invoice, using its sales_invoice_id. Status values (SEF SalesInvoiceStatus): NEW (Nova/New — draft not yet sent); SENDING (in transit); SENT (delivered to the buyer, awaiting their action); SEEN (buyer opened it); APPROVED (buyer accepted — Prihvacena); APPROVED_WITH_RESERVATION (accepted with reservation); REJECTED (buyer rejected — Odbijena); CANCELLED (seller cancelled — Otkazana); STORNO (reversed by a storno document); MISTAKE (marked as an error); OVERDUE (payment past due); REMINDED (a reminder was sent); DELETED. Safe to call anytime.

Parameters1

sales_invoice_id

string

required

The sales_invoice_id returned by create_invoice.

Raw schema

{
  "type": "object",
  "properties": {
    "sales_invoice_id": {
      "type": "string",
      "description": "The sales_invoice_id returned by create_invoice."
    }
  },
  "required": [
    "sales_invoice_id"
  ]
}

cancel_invoice

Cancel (Otkazivanje) a Serbia sales invoice you sent, using its sales_invoice_id and a mandatory reason (cancel_comment). This is the seller cancelling their own Sent invoice before the buyer accepts or rejects it; once the buyer has Approved it, cancellation is no longer possible and a storno (credit) document is required instead (storno is out of scope in v1 — honest limit). Returns the SEF response. Irreversible.

Parameters2

sales_invoice_id	string	required	The sales_invoice_id returned by create_invoice.
cancel_comment	string	required	Reason for cancellation (razlog otkazivanja). Required by SEF.

Raw schema

{
  "type": "object",
  "properties": {
    "sales_invoice_id": {
      "type": "string",
      "description": "The sales_invoice_id returned by create_invoice."
    },
    "cancel_comment": {
      "type": "string",
      "description": "Reason for cancellation (razlog otkazivanja). Required by SEF."
    }
  },
  "required": [
    "sales_invoice_id",
    "cancel_comment"
  ]
}

README.md3 KBView on GitHub

Serbia Invoice MCP 🇷🇸 — How can my AI agent issue a SEF eFaktura elektronska faktura in Serbia?

Remote MCP server that lets any AI agent issue Serbia SEF eFaktura electronic invoices (elektronska faktura) into the national Ministry of Finance system. It builds UBL 2.1 SRB-CIUS XML (Serbia's CIUS of EN 16931) and uploads it under the merchant's own SEF API key. Stateless, bring-your-own credential, never stores anything.

Live endpoint: https://inv-rs.wishpool.app/mcp · Registry: app.wishpool/serbia-invoice-mcp

Quick start

json

{
  "mcpServers": {
    "serbia-invoice": {
      "type": "http",
      "url": "https://inv-rs.wishpool.app/mcp",
      "headers": {
        "x-sef-api-key": "<your SEF API key>"
      }
    }
  }
}

You generate the SEF API key yourself in the SEF portal under Settings → API management (Podešavanja → Upravljanje API). Requests default to the SEF demo rail (no fiscal effect); add x-sef-mode: prod for the live rail. Your key never reaches storage — it is forwarded per-request to SEF as the official ApiKey header.

Tools

Tool	What it does
`create_invoice`	Build a UBL 2.1 SRB-CIUS invoice from seller PIB + name, buyer PIB + name + address + lines (name, qty, net unit price, VAT rate 20/10/0) and upload to SEF eFaktura. Returns `sales_invoice_id` + computed VAT totals. Optional `send_to_cir` for budget/public-sector buyers.
`query_invoice`	Check SEF status by `sales_invoice_id`: `NEW`, `SENDING`, `SENT`, `SEEN`, `APPROVED`, `APPROVED_WITH_RESERVATION`, `REJECTED`, `CANCELLED`, `STORNO`, `MISTAKE`, `OVERDUE`, `REMINDED`, `DELETED`.
`cancel_invoice`	Cancel (Otkazivanje) a sales invoice you sent, by `sales_invoice_id` + `cancel_comment`, before the buyer accepts it.

Amounts are in RSD. You supply your own seller identity (supplier_pib + supplier_name) — SEF validates it against your API-key account. After the buyer APPROVES, cancellation is closed — corrections require a storno (credit) document (out of scope in v1).

Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them.

Endpoints wrapped (SEF eFaktura publicApi REST)

Base: DEMO https://demoefaktura.mfin.gov.rs · PROD https://efaktura.mfin.gov.rs (prefix /api/publicApi)
Upload: POST /sales-invoice/ubl?requestId={unique}&sendToCir={true|false} (Content-Type application/xml, raw UBL body) → { InvoiceId, PurchaseInvoiceId }
Status: GET /sales-invoice?invoiceId={id} → invoice record incl. Status
Cancel: POST /sales-invoice/cancel?invoiceId={id}&cancelComment={text}
Auth: header ApiKey (forwarded from x-sef-api-key)

Develop

bash

node test/serve.js   # local server on :3238
node test/e2e.js     # protocol + validation + VAT math + UBL structure + fake-key live probes

Safety

Pure stateless translation layer over the national SEF eFaktura API. The API key stays with the merchant and travels per-request in a header; nothing is stored. Privacy policy.

Sister servers

Local invoices, one family: Romania e-Factura (inv-ro) · Mexico CFDI (inv-mx) · Brazil NF-e (inv-br) · Chile DTE (inv-cl) · Peru CPE (inv-pe) · India GST (inv-in). Local payments in 81 countries: mcp.wishpool.app.

MIT licensed.

Install

Tools (3)

create_invoicequery_invoicecancel_invoice

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://inv-rs.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "serbia-invoice-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://inv-rs.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.