4invoices þróendaforritaskil

• Forritaskil 4invoices eru REST yfir HTTPS, með JSON inn og JSON út.
• Einn framleiðsluhýsill: https://api.4invoices.net/v1. Það er enginn sérstakur prófunarhýsill.
• OpenAPI 3.1-lýsingin er opinber og lykillaus — fluttu hana beint inn í Postman eða kóðaframleiðanda.
• Hvert svar ber X-Request-Id-haus; vísaðu í hann þegar þú biður um aðstoð.
• Sérhvert fjárhagslegt skrif er idempotent: endurtekning eftir tímamörk gefur aldrei út annað skjal.

• Öll ferðin um landskerfi rafrænna reikninga yfir API-ið (í Rúmeníu: ANAF e-Factura): forathugun, sending, rakning, undirritað svar og innhólfið fyrir innkomin skilaboð. Enginn rúmenskur keppinautur opnar þetta.
• SmartBill hefur engan endapunkt til að senda í landskerfi rafrænna reikninga (ANAF, í Rúmeníu) — sendingin er aðeins stillingarvalkostur í viðmótinu — og engan endapunkt til að lista reikninga.
• Oblio getur búið til viðskiptavini og vörur aðeins sem aukaverkun við útgáfu skjals, ekki sem fyrsta flokks auðlindir.
• UBL XML-myndun án sendingar (CIUS-RO fyrir Rúmeníu): þú færð lagalega skjalið sem skrá án þess að snerta landskerfið.
• Idempotency á fjárhagslegum skrifum: endurtekning eftir tímamörk býr hvorki til annan reikning né eyðir öðru númeri.
• Forritanlega lesanlegt innhólf reikninga birgja — grunnurinn að sjálfvirkri afstemmingu.

1. Búðu til skilríki í spjaldinu undir Reikningagerð → Stillingar → API aðgangur og afritaðu client_secret — það birtist einu sinni.
2. Ljúktu við fyrirtækjasniðið og virkjaðu að minnsta kosti eina númeröð af gerðinni fiscale, annars skilar útgáfan issuer_profile_incomplete eða no_series_configured.
3. Skiptu skilríkjunum fyrir token: POST /v1/auth/token með grant_type client_credentials. Tókenið gildir í eina klukkustund — geymdu það í skyndiminni, ekki sækja nýtt fyrir hverja beiðni.
4. Gefðu út reikninginn: POST /v1/invoices með Idempotency-Key-haus og vat_rate sem prósentu (21, ekki 0,21).
5. Keyrðu forathugunina (CIUS-RO fyrir Rúmeníu) með POST /v1/invoices/{id}/efactura/validate og sendu hann síðan í landskerfi rafrænna reikninga með POST /v1/invoices/{id}/efactura/submit.
6. Fylgstu með stöðunni með GET /v1/efactura/submissions/{id} þar til hún nær accepted eða rejected.

bash
# 1 — token (1 klst., geymdu í skyndiminni)
ACCESS_TOKEN=$(curl -sS -X POST https://api.4invoices.net/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"cli_XXX","client_secret":"sec_XXX"}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["access_token"])')

# 2 — gefðu út reikninginn (Idempotency-Key er KRAFIST)
curl -sS -X POST https://api.4invoices.net/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-10457-invoice' \
  -d '{"buyer":{"name":"Exemplu Comert SRL","tax_id":"RO12345678","county":"Cluj","city":"Cluj-Napoca","country":"RO"},
       "lines":[{"description":"Abonament SaaS","quantity":1,"unit_price":400,"vat_rate":21}]}'

# 3 — preflight CIUS-RO, then send to ANAF
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/efactura/validate \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/efactura/submit \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: efactura-inv_01J7ABC-1'

javascript
const BASE = "https://api.4invoices.net/v1";

const token = await fetch(`${BASE}/auth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "client_credentials",
    client_id: process.env.FOURINVOICES_CLIENT_ID,
    client_secret: process.env.FOURINVOICES_CLIENT_SECRET,
  }),
}).then((r) => r.json()).then((d) => d.access_token);

const invoice = await fetch(`${BASE}/invoices`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${orderId}-invoice`,
  },
  body: JSON.stringify({
    buyer: { name: "Exemplu Comert SRL", tax_id: "RO12345678", county: "Cluj", city: "Cluj-Napoca", country: "RO" },
    lines: [{ description: "Abonament SaaS", quantity: 1, unit_price: 400, vat_rate: 21 }],
    currency: "RON",
    metadata: { order_id: String(orderId) },
  }),
}).then((r) => r.json());

console.log(invoice.number, invoice.totals); // "FCT-000123" { net, vat, gross }

python
import os, uuid, requests

BASE = "https://api.4invoices.net/v1"

token = requests.post(f"{BASE}/auth/token", json={
    "grant_type": "client_credentials",
    "client_id": os.environ["FOURINVOICES_CLIENT_ID"],
    "client_secret": os.environ["FOURINVOICES_CLIENT_SECRET"],
}, timeout=30).json()["access_token"]

headers = {
    "Authorization": f"Bearer {token}",
    # Einn lykill fyrir hverja RÖKRÉTTA aðgerð — notaðu hann aftur við endurtekningu, býrðu aldrei til nýjan.
    "Idempotency-Key": f"order-{order_id}-invoice",
}

invoice = requests.post(f"{BASE}/invoices", headers=headers, json={
    "buyer": {"name": "Exemplu Comert SRL", "tax_id": "RO12345678",
              "county": "Cluj", "city": "Cluj-Napoca", "country": "RO"},
    "lines": [{"description": "Abonament SaaS", "quantity": 1,
               "unit_price": 400, "vat_rate": 21}],   # prósentu, ekki 0,21
    "currency": "RON",
}, timeout=60).json()

print(invoice["number"], invoice["totals"])

• Flæðið er client_credentials: þú skiptir client_id + client_secret fyrir Bearer access_token.
• Tókenið rennur út eftir 3600 sekúndur. Endurnýjaðu það fyrir gildislok, ekki í hverju kalli — POST /auth/token hefur sín eigin hraðamörk á hverja IP-tölu.
• client_secret er aðeins geymt sem hakk og er ekki hægt að endurheimta það. Týnirðu því býrðu til nýtt skilríki og afturkallar það gamla.
• Eingöngu netþjón-við-netþjón. Enginn uppruni í vafra fær að fara í gegnum CORS: úr JavaScript á síðu myndi leyndarmálið leka til gestsins.
• Heimildir (scopes) eru veittar á hvert skilríki. Gefðu út sérstakt skilríki fyrir hvert kerfi og gefðu hverju þeirra lágmarksheimildirnar sem það þarf.

Reikningagerð → Stillingar → API aðgangur

bash
curl -sS -X POST https://api.4invoices.net/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cli_XXXXXXXXXXXX",
    "client_secret": "sec_XXXXXXXXXXXXXXXXXXXX"
  }'

# → {"access_token":"eyJ...","token_type":"Bearer","expires_in":3600,
#    "scope":"invoices:read invoices:write efactura:submit"}

javascript
// Geymdu tókenið í skyndiminni; ekki búa til nýtt fyrir hverja beiðni.
let cached = { token: "", expiresAt: 0 };

async function getToken() {
  if (cached.token && Date.now() < cached.expiresAt - 60_000) return cached.token;

  const res = await fetch("https://api.4invoices.net/v1/auth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.FOURINVOICES_CLIENT_ID,
      client_secret: process.env.FOURINVOICES_CLIENT_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`token ${res.status}`);

  const data = await res.json();
  cached = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return cached.token;
}

• vat_rate er PRÓSENTA: 21 þýðir 21%.
• Gildi á bilinu (0, 1] eru hafnuð — 0,19 er brot, og 1 er óljóst á milli 1% og 100%.
• 0 er gilt og þýðir undanþegið eða snúið skattskil (reverse charge); settu lagatilvísunina í notes.
• unit_price er NETTÓ einingarverð þegar útgefandinn er VSK-greiðandi.
• Þarftu heildarfjárhæðirnar áður en þú skuldbindur þig? POST /v1/invoices/preview-totals keyrir sama reikning án þess að nota fjárhagslegt númer.

• Idempotency-Key-hausinn er KRAFIST á POST /invoices, POST /invoices/{id}/storno og POST /invoices/{id}/efactura/submit.
• Lyklar eru geymdir í 24 klukkustundir. Endurspilun sama lykils með sama efni skilar upprunalegu niðurstöðunni og setur Idempotency-Replayed: true.
• Sami lykill með öðru efni skilar 409 idempotency_key_reuse — reikningur sem þegar hefur verið gefinn út er aldrei skrifaður yfir.
• Einn lykill fyrir hverja RÖKRÉTTA aðgerð, ekki fyrir hverja HTTP-tilraun: order-10457-invoice, ekki nýtt UUID í hverri endurtekningu.
• Ástæðan er lagaleg, ekki tæknileg: notað fjárhagsnúmer og reikningur skráður í landskerfi rafrænna reikninga er ekki hægt að taka til baka.

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-10457-invoice' \
  -d '{
    "buyer": {
      "name": "Exemplu Comert SRL",
      "tax_id": "RO12345678",
      "address": "Str. Fabricii 12",
      "city": "Cluj-Napoca",
      "county": "Cluj",
      "country": "RO",
      "email": "[email protected]"
    },
    "lines": [
      { "description": "Abonament SaaS, iulie", "quantity": 1, "unit_price": 400, "vat_rate": 21, "unit": "buc" },
      { "description": "Implementare", "quantity": 6, "unit_price": 250, "vat_rate": 21, "unit": "ora" }
    ],
    "currency": "RON",
    "document_kind": "factura",
    "due_date": "2026-08-15",
    "metadata": { "order_id": "10457" }
  }'

25 endpoints · https://api.4invoices.net/v1/openapi.json

• invoices:read
• invoices:write
• clients:read
• clients:write
• efactura:read
• efactura:submit

• Stóri munurinn: öll ferðin um landskerfi rafrænna reikninga keyrir yfir API-ið, ekki bara myndun skjalsins.
• POST /invoices/{id}/efactura/validate keyrir forathugunina (CIUS-RO fyrir Rúmeníu) og skilar nákvæmlega þeim reitum sem landskerfi rafrænna reikninga myndi hafna, án þess að senda nokkuð.
• GET /invoices/{id}/xml myndar UBL XML (CIUS-RO fyrir Rúmeníu) án sendingar — gagnlegt fyrir þitt eigið safn eða innri endurskoðun.
• POST /invoices/{id}/efactura/submit skráir hann í landskerfi rafrænna reikninga. Þetta er óafturkræft: afrit af sama reikningi verður ekki tekið til baka úr kerfinu.
• Lífsferillinn er normaliseraður: not_sent → validating → queued → sent → processing → accepted | rejected | error. accepted þýðir að hann var löglega sendur; error er flutningsbilun hjá okkur og er óhætt að endurreyna.
• GET /efactura/submissions/{id}/download sækir skjalasafnið með undirrituðu svari landskerfis rafrænna reikninga.
• Innhólfið er líka til: POST /efactura/inbox/sync sækir ný skilaboð úr landskerfinu og GET /efactura/inbox listar reikningana sem birgjar þínir sendu þér.

bash
# CIUS-RO preflight. Sends NOTHING to ANAF.
curl -sS -X POST "https://api.4invoices.net/v1/invoices/inv_01J7ABC/efactura/validate?include_xml=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → {"invoice_id":"inv_01J7ABC","valid":false,
#    "errors":["buyer.county is required for RO buyers"],
#    "xml_base64":"PD94bWwg..."}

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/efactura/submit \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: efactura-inv_01J7ABC-1'

# → {"submission_id":"sub_01J7XYZ","status":"queued"}

python
import time, requests

BASE = "https://api.4invoices.net/v1"
TERMINAL = {"accepted", "rejected"}
H = {"Authorization": f"Bearer {token}"}

def wait_for_anaf(submission_id, timeout=900):
    deadline = time.time() + timeout
    delay = 15
    while time.time() < deadline:
        r = requests.get(f"{BASE}/efactura/submissions/{submission_id}", headers=H, timeout=30)
        r.raise_for_status()
        status = r.json()["status"]
        if status in TERMINAL:
            return r.json()
        # /refresh asks ANAF directly and shares the 10/min submit bucket.
        requests.post(f"{BASE}/efactura/submissions/{submission_id}/refresh", headers=H, timeout=30)
        time.sleep(delay)
        delay = min(delay * 2, 120)
    raise TimeoutError(submission_id)

• Sérhvert 4xx og 5xx notar sama umslag: { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
• type er grófi flokkurinn sem þú greinir eftir („get ég reynt aftur?“), og code er stöðuga ástæðan sem þú kortleggur inn í þitt eigið kerfi.
• param er punktaslóðin að reitnum sem olli vandanum, til dæmis lines.0.vat_rate.
• errors[] birtist þegar ein beiðni á í vandræðum á fleiri en einum reit.
• request_id er skráð hjá okkur. Vísaðu í það í hvaða aðstoðarbeiðni sem er — það festir nákvæmlega þá beiðni.
• 404 er einnig skilað fyrir auðkenni sem tilheyrir öðrum leigjanda: við staðfestum aldrei að gögn einhvers annars séu til.

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Datele trimise nu sunt valide.",
    "param": "lines.0.vat_rate",
    "doc_url": "https://4invoices.net/ro/api-dezvoltatori#errors",
    "request_id": "req_8a893f2f33d4472da8d6e144",
    "errors": [
      { "param": "lines.0.vat_rate", "message": "VAT rate must be a percent (21), not a fraction", "type": "value_error" }
    ]
  }
}

• Mörkin eru á hvert skilríki, á mínútu: 120 fyrir lestur, 30 fyrir skrif og 10 fyrir aðgerðir í landskerfinu (submit, refresh, inbox/sync).
• X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset birtast á HVERJU svari, þar með talið 429.
• 429 ber líka Retry-After í sekúndum. Virtu það; ekki reyna aftur í þéttri lúppu.
• 10/mínútu fatan er til því í Rúmeníu leyfir ANAF sjálft u.þ.b. eitt kall á skilaboðalista á mínútu á hvert CIF.
• Settu /efactura/inbox/sync á cron, ekki á ágengt kannanir.
• Þarftu hærri þök? Biddu um það í gegnum Hafa samband með væntanlegu daglegu magni.

X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset · Retry-After

http
HTTP/2 429
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1785312000
Retry-After: 17
Content-Type: application/json

{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded",
 "message":"...","doc_url":"https://4invoices.net/ro/api-dezvoltatori#errors",
 "request_id":"req_..."}}

javascript
// Virtu Retry-After; endurreyndu aldrei 4xx nema 429.
async function call(url, init, attempt = 0) {
  const res = await fetch(url, init);
  if (res.status === 429 || res.status >= 500) {
    if (attempt >= 5) return res;
    const retryAfter = Number(res.headers.get("Retry-After")) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return call(url, init, attempt + 1);
  }
  return res;
}

// Endurtekning skrifs VERÐUR að nota SAMA Idempotency-Key, annars gefurðu út
// annað fjárhagsskjal.

Hvert efni hefur sína eigin síðu með viðeigandi endapunktum, dæmum og villum.

• Auðkenning í 4invoices APISkiptu client_id og client_secret fyrir Bearer-token sem gildir í eina klukkustund, eingöngu netþjón-við-netþjón.
• Útgáfa reikninga í gegnum APIPOST /invoices með Idempotency-Key, VSK sem prósentur, auk lista, storno og merkingar greiddra reikninga.
• Viðskiptavinir og uppflettingar í opinberri fyrirtækjaskráInnsetning eða uppfærsla afritahreinsuð eftir tax_id, ásamt uppflettingu í opinberri skrá (í Rúmeníu: ANAF) svo rafrænum reikningi sé ekki hafnað.
• Landskerfi rafrænna reikninga í gegnum APIForathugun (CIUS-RO fyrir Rúmeníu), sending í landskerfið, normaliseruð staða, undirritað svar og innhólf innkominna reikninga frá birgjum.
• Númeraraðir í APIÁn virkrar númeraraðar af gerðinni fiscale skilar útgáfan 409 no_series_configured.
• Villukóðar og villuumslagiðEin lögun á hverri leið: type, code, message, param, doc_url, request_id og errors.
• Hraðamörk og endurtekningar120 lestrar, 30 skrif og 10 aðgerðir í landskerfinu á mínútu á hvert skilríki, með X-RateLimit-*-hausum.

• Að senda VSK sem brot (0.19) eða sem 1. Hvort tveggja er hafnað; sendu 19 eða 21.
• Að búa til token í hverri beiðni. Tókenið gildir í eina klukkustund; geymdu það í skyndiminni, annars rekst þú á hraðamörk tókenaendapunktsins á hverja IP-tölu.
• Að búa til nýjan idempotency-lykil í hverri endurtekningu — einmitt sú atburðarás sem framleiðir tvöföld reikningsskjöl.
• Að kalla úr JavaScript í vafra. CORS hafnar öllum uppruna, og leyndarmálið yrði hvort sem er afhjúpað.
• Að skrá í landskerfi rafrænna reikninga án forathugunar. Röng sending verður ekki tekin til baka.
• Að kanna /efactura/submissions/{id}/refresh oftar en 10 sinnum á mínútu — þessi fata deilist með submit.
• Að gefa út áður en fyrirtækjasniðið er fullgert og virk fjárhagsnúmerð er til staðar.