ה-API של Doxbox

מה אפשר לעשות

שבע נקודות קצה. הכל לקריאה בלבד, אלא אם המפתח שלכם נוצר עם הרשאת כתיבה.

הרשאות: קריאה כברירת מחדל. העלאת מסמכים דורשת מפתח עם הרשאת כתיבה.

התחלה מהירה

1. צרו מפתח. כמנהלי חשבון, גשו אל הגדרות חשבון ← חיבורים ← מפתחות API ← יצירת מפתח. העתיקו אותו, הוא מוצג פעם אחת בלבד.
2. הגדירו אותו במשתני הסביבה:

export DOXBOX_API_KEY="dbx_..."

ועכשיו הקריאה הראשונה:

curl https://app.doxbox.io/api/v1/documents \
  -H "Authorization: Bearer $DOXBOX_API_KEY"

const res = await fetch("https://app.doxbox.io/api/v1/documents", {
  headers: { Authorization: `Bearer ${process.env.DOXBOX_API_KEY}` }
});
if (!res.ok) throw new Error(`${res.status} ${(await res.json()).code}`);
const { data, nextCursor } = await res.json();

import os, requests

r = requests.get(
    "https://app.doxbox.io/api/v1/documents",
    headers={"Authorization": f"Bearer {os.environ['DOXBOX_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
payload = r.json()

אימות

כל בקשה, למעט /health requires an API key sent as a טוקן Bearer:

Authorization: Bearer dbx_<prefix>_<secret>

כל מפתח שייך לחשבון אחד ויכול לגעת אך ורק בנתונים של אותו חשבון. ביטול מפתח נכנס לתוקף מיידית.

הרשאות

לכל מפתח יש אחת משתי רמות הרשאה, שנקבעת ביצירה. מפתחות הם לקריאה בלבד אלא אם ביקשתם במפורש הרשאת כתיבה. קריאה לנקודת קצה של כתיבה עם מפתח קריאה מחזירה 403 API_KEY_FORBIDDEN.

מוסכמות

חלוקה לעמודים

נקודות הקצה של רשימות משתמשות בחלוקה מבוססת סמן: ?limit= (1 עד 100, ברירת מחדל 25) ו- ?cursor= (ה- id של הפריט האחרון בעמוד הקודם). התשובות מחזירות nextCursor, שהוא מזהה, או null בעמוד האחרון.

הגבלת קצב

הבקשות מוגבלות לכל מפתח (ברירת מחדל 120 לדקה). Every response carries rate-limit headers; exceeding the limit מחזירה 429 עם כותרת Retry-After header.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1785690000

מכסות

העלאות נספרות מול מכסת המסמכים החודשית של התוכנית שלכם. כשהמכסה נגמרת, POST /documents מחזירה 403 PLAN_LIMIT_EXCEEDED and no documents in the batch are ingested, all-or-nothing, so you're never left עם כותרת partial upload.

טיפול בכפילויות

העלאות עוברות זיהוי כפילויות לפי תוכן הקובץ. העלאה חוזרת של קובץ שכבר קיים ב-Doxbox לא יוצרת מסמך שני, והתשובה מסמנת אותו כ- "duplicate" and מחזירה the existing id. Uploads are safe to retry.

מתכונים

שלושה דברים שבאמת עושים עם ה-API הזה, מקצה לקצה.

מעבר על כל המסמכים

המשיכו להעביר את nextCursor בחזרה כ- cursor עד שיחזור null. שום דבר אחר לא עוצר את הלולאה.

const base = "https://app.doxbox.io/api/v1";
const auth = { Authorization: `Bearer ${process.env.DOXBOX_API_KEY}` };

let cursor = null, all = [];
do {
  const url = new URL(base + "/documents");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, { headers: auth });
  if (res.status === 429) {                // respect the limiter
    await new Promise(r => setTimeout(r, (+res.headers.get("Retry-After") || 5) * 1000));
    continue;
  }
  const page = await res.json();
  all.push(...page.data);
  cursor = page.nextCursor;
} while (cursor);

הורדת הקבצים של כל חשבונית שלא שולמה

The file endpoint answers עם כותרת 302 to a short-lived signed URL, so follow redirects and stream the body straight to disk.

import os, requests

base = "https://app.doxbox.io/api/v1"
auth = {"Authorization": f"Bearer {os.environ['DOXBOX_API_KEY']}"}

docs, cursor = [], None
while True:
    params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
    page = requests.get(f"{base}/documents", headers=auth, params=params, timeout=30).json()
    docs += page["data"]
    cursor = page["nextCursor"]
    if not cursor: break

for d in docs:
    if d["documentType"] != "Invoice" or d["paymentStatus"] != "Unpaid":
        continue
    r = requests.get(f"{base}/documents/{d['id']}/file", headers=auth,
                     allow_redirects=True, timeout=60)
    r.raise_for_status()
    with open(f"{d['documentNumber'] or d['id']}.pdf", "wb") as f:
        f.write(r.content)

בניית הקובץ החודשי לרואה החשבון

קריאה אחת. התשובה מחזירה כתובת הורדה חתומה שתקפה לכ-12 שעות.

curl -X POST https://app.doxbox.io/api/v1/exports \
  -H "Authorization: Bearer $DOXBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exportType":"excel_monthly","filters":{"year":2026,"month":7}}'

Swap exportType for csv, pdf_merged or zip. כדי לייצא אוסף נבחר במקום חודש שלם, שלחו "scope":"selected" with selectedDocumentIds.

שגיאות

Errors return a JSON body עם כותרת message ובמקומות רלוונטיים גם code:

{ "message": "API key has expired", "code": "API_KEY_EXPIRED" }

מילון שדות

ערכים אפשריים שתראו בתשובות:

שדות סכום הם מספרים במטבע של המסמך, currency. Dates are ISO 8601 strings and may be null כאשר Doxbox לא הצליחה לקרוא אותם מהמסמך.

זמינות השירות והגרסה. ללא אימות.

{ "status": "ok", "api": "v1" }

רשימת המסמכים בחשבון, מהחדש לישן. מחולק בסמן (limit, cursor).

curl "https://app.doxbox.io/api/v1/documents?limit=2" \
  -H "Authorization: Bearer $DOXBOX_API_KEY"

{
  "data": [
    {
      "id": 1042,
      "documentNumber": "INV-2026-118",
      "totalAmount": 1170.0,
      "currency": "ILS",
      "documentType": "Invoice",
      "paymentStatus": "Unpaid",
      "supplierName": "Acme Ltd"
    }
  ],
  "nextCursor": 1041
}

A single document with full metadata and the ids of its image pages. A document that isn't in your account מחזירה 404, בלי לחשוף אם הוא קיים בחשבון אחר.

{
  "id": 1042,
  "documentNumber": "INV-2026-118",
  "documentType": "Invoice",
  "netAmount": 1000.0,
  "vat": 170.0,
  "totalAmount": 1170.0,
  "currency": "ILS",
  "paymentStatus": "Unpaid",
  "supplier": { "id": 9, "name": "Acme Ltd", "crn": "514123456" },
  "images": [{ "id": 5001 }, { "id": 5002 }]
}

Returns a הפניה 302 לכתובת חתומה חדשה וקצרת מועד לקובץ של המסמך. אחסון הקבצים נשאר פרטי. הפרמטר האופציונלי ?image=<id> selects a specific page (ברירת מחדלs to the first).

curl -L https://app.doxbox.io/api/v1/documents/1042/file \
  -H "Authorization: Bearer $DOXBOX_API_KEY" \
  -o invoice.pdf

העלאת מסמך אחד או יותר. הם עוברים את אותו תהליך כמו מסמכים שנוספו באפליקציה, כולל OCR, התאמת ספק וזיהוי כפילויות, ומופיעים בחשבון עם סימון שהועלו דרך ה-API. שלחו גוף multipart/form-data body with one or more files in the files field. Counts against your monthly quota; the batch is all-or-nothing.

curl -X POST https://app.doxbox.io/api/v1/documents \
  -H "Authorization: Bearer $DOXBOX_API_KEY" \
  -F "files=@invoice-july.pdf" \
  -F "files=@receipt-123.pdf"

{
  "results": [
    { "filename": "invoice-july.pdf", "documentId": 1055, "status": "created" },
    { "filename": "receipt-123.pdf",  "documentId": 980,  "status": "duplicate" }
  ],
  "summary": { "total": 2, "created": 1, "duplicate": 1, "failed": 0 }
}

Per-file status is created, duplicate, או failed (קובץ שנכשל כולל reason and doesn't stop the rest of the batch).

The account's suppliers (those with documents in the account), with per-supplier aggregates, sorted by total amount.

{
  "data": [
    { "id": 8, "name": "Globex", "crn": "514000222", "documentCount": 12, "totalAmount": 18400.0 },
    { "id": 9, "name": "Acme Ltd", "crn": "514123456", "documentCount": 5, "totalAmount": 5850.0 }
  ]
}

יצירת ייצוא file for a month's documents. Returns a signed download URL valid for about 12 hours. Exporting via the API never changes your documents.

curl -X POST https://app.doxbox.io/api/v1/exports \
  -H "Authorization: Bearer $DOXBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "exportType": "excel_monthly", "filters": { "year": 2026, "month": 7 } }'

{
  "fileName": "Acme_2026-07.xlsx",
  "fileUrl": "https://storage.googleapis.com/.../signed...",
  "totalDocuments": 17,
  "skippedFiles": 0,
  "provider": "server"
}

fileUrl היא כתובת חתומה זמנית, כ-12 שעות.

גרסאות ותמיכה

גרסאות

כל נתיב נושא את הגרסה בתחילתו, /api/v1. שינויים מוסיפים, כמו שדה חדש בתשובה או פרמטר אופציונלי חדש, יכולים להופיע ב- v1 at any time, so parse responses leniently and ignore fields you do not recognise. Breaking changes ship under a new version and are announced in advance; v1 לא נעלמת מתחת לרגליים שלכם.

קבלת עזרה

Questions about the API, a response you cannot explain, או an endpoint you need that is not here: inbox@doxbox.io.

זה חוסך סבב אם תצרפו את הבקשה ששלחתם עם המפתח מוסתר, את גוף התשובה המלא כולל code, ואת השעה שבה זה קרה.

דואר אלקטרוני

inbox@doxbox.io

ניסיון חי

Swagger UI

מפרט OpenAPI

openapi.json

זמינות

GET /api/v1/health