📦 Goods Receipt

The Goods Receipt page turns one of the most tedious warehouse processes – unpacking delivery notes and supplier invoices into your inventory – into a job that takes minutes. You can receive goods manually, but the headline of this module is document-driven receiving: upload a PDF or photo of a delivery note, the smart engine identifies the supplier, extracts the line items, maps them to your catalog – and all you have to do is review and approve.

🏁 How to Access

• On phone: ☰ at the top right → Goods Receipt.
• On computer: Hover over the sidebar → Goods Receipt.

💡 The "Goods Receipt" tab appears only if the goods-receiving feature is enabled for your company account. If you can't see it – ask your company admin to enable it under "Company Details".

👤 View by User Role

Role	What They See & Can Do
Manager / Sub-Manager	All goods receipts for every company branch, statistics, daily AI engine usage, manual creation, document upload, confirm / cancel / delete.
Employee with company-management permission	Same full access as a manager, but scoped to the branches assigned to them.
Regular employee	Read-only list of receipts, plus the ability to report actual received quantity against an expected line (verify-item). Cannot confirm or cancel.

🧠 What the Page Does

• Displays every goods receipt – drafts, confirmed, and cancelled.
• Lets you create a manual receipt from scratch (supplier, date, catalog items).
• Lets you upload a delivery note / invoice and have the engine build a draft for you automatically.
• Provides a review screen before saving: every uncertain line is highlighted, with alternative catalog matches suggested.
• On confirmation – automatically adds quantities to the branch's inventory (creates positive count records).
• Exports any receipt to Excel.
• Tracks document-processing cost (credits) and enforces a daily usage cap.

📊 Top Statistics

The top of the page (visible to managers) shows live metrics:

• Total Receipts – everything in the company.
• Open Drafts – not yet confirmed and editable.
• Confirmed – inventory has been updated.
• Cancelled – receipts that were voided.
• AI Usage Today – how many documents were uploaded, how many succeeded, how many failed, average processing time, and daily credit consumption.

🏷️ Receipt Statuses

Status	Meaning
🤖 AI Draft (ai_draft)	A receipt auto-built from a document, awaiting human review. Fully editable. Does not affect inventory.
📝 Draft (draft)	Either a manual receipt or an AI draft promoted by a human as "ready to confirm". Editable. Does not affect inventory.
✅ Confirmed (confirmed)	The receipt is closed and branch inventory has been updated. Cannot be edited.
❌ Cancelled (cancelled)	Receipt was voided. No inventory effect.

🔄 Document-Driven Path

Upload document → 🤖 AI Draft → Review & fix → 📝 Draft → ✅ Confirmed
                                                          ↓
                                            Branch inventory updated

🔄 Manual Path

Manual create → 📝 Draft → Add items → ✅ Confirmed

➕ Manual Receipt (No Document)

Manual entry is appropriate when items are counted live off the pallet, with no written document.

Step 1 – Receipt Details

Field	Required?	Notes
Branch	Yes	Pick from authorized branches. Single-branch accounts auto-select.
Supplier name	Yes (min 2 chars)	Smart search across the supplier registry. New names can be typed freely.
Document reference	Optional	Delivery note or invoice number.
Receipt date	Optional	Defaults to today. Past dates are allowed.
Allocation number	Optional	Mainly relevant for tax invoices above the regulatory threshold.
Free-form notes	Optional

Step 2 – Adding Items

• Catalog search – by item code / barcode / description. Click an item → it's added as a new line.
• Expected quantity – the quantity that should arrive (per the document).
• Smart merge – adding the same item twice automatically merges the quantities into one line.
• Non-catalog line – you can add a placeholder line with a free-text description and link it to a catalog item later.
• Actual received quantity – a separate field for verification during unpacking (e.g. "supplier shipped 24, only 23 arrived").
• Edit / delete line – available as long as the receipt is in Draft.

🤖 Document-Driven Receiving (AI)

This is the part that saves you hours of typing every week.

What You Can Upload

Type	Details
PDF	Supplier delivery notes / invoices (printed or scanned).
Images	JPG, PNG, WebP, HEIC – e.g. a phone snapshot of the printed slip.
Max size	Up to 20MB per file.
Page count	Capped (very long documents are rejected).

📸 Field tip: snap the slip with your phone while you're unpacking – the engine handles tilted and partially clipped images surprisingly well.

Processing Pipeline

After upload, the document moves through four stages – streamed live to the browser:

Stage	What Happens
⏳ Queued (queued)	File uploaded and assigned to a worker.
🔍 Classifying (classifying)	Detect document type (tax invoice, delivery note, receipt…) and page ranges.
📄 Extracting (extracting)	Read header, supplier details, document number, totals, and line structure.
🎯 Matching (matching)	Match every line to an existing catalog item.
✅ Ready (ready) or 👀 Review (review)	Done. If the engine isn't confident on a line, status will be "review" so you can take a look.
❌ Failed (failed)	If something went wrong – click "Retry" without re-uploading.

⚡ Average processing is anywhere from a few seconds to under a minute, depending on document length. The progress bar updates live and you don't have to stay on the page.

🧠 Smart Matching Engine

For every line on the document, the engine tries (in priority order) to find an exact match in your catalog:

Priority	Strategy	Confidence
1️⃣	Barcode (GTIN) exact match	0.98
2️⃣	Supplier alias / supplier SKU – from the alias library that builds up automatically from past receipts	varies (learned)
3️⃣	Item code exact	0.90
4️⃣	Fuzzy description – tolerant of typos, abbreviations, word order	0.70 – 0.75

• Lines the engine matched with high confidence are flagged green and pass through automatically.
• Lines the engine wasn't sure about are flagged amber and routed to the Review screen alongside alternative suggestions.
• Every manual selection in Review trains the engine – the next time the same supplier sends the same description, it will match automatically.

🧮 Automatic Sanity Checks

Before a document is marked "ready", the engine runs a few safety checks:

• Totals match – sum of line totals vs. document total (₪1 tolerance).
• Allocation number – for tax invoices above a regulated threshold (currently ₪10,000, dropping to ₪5,000 in June 2026), the system warns if no allocation number is present. It does not block – your call.
• File errors – if the document is unreadable or not a valid receipt, you'll see a clear reason (no_documents_detected, extraction_failed, rate_limited, etc.).

👀 The AI Review Screen

Once a document finishes processing it opens in a dedicated review screen (/goods-receiving/ai-review/:jobId):

• Header section – supplier, document number, date, totals. Everything is editable. Changes are saved automatically (debounced).
• Line table – one row per document line, with:
  • Confidence chip (green / amber / red).
  • Raw supplier description.
  • The matched catalog item – clickable to open a search and change.
  • Quantity, unit of measure, unit price, line total – editable inline.
  • "Why?" chip – click to see the reason the engine matched this item (barcode, item code, description fuzzy match, manual override).
  • Manually replace an incorrectly matched item – the choice is saved as a supplier alias for future receipts.
• Add manual line – for cases the engine missed.
• Delete line – if the supplier sent an irrelevant row (shipping, discount).
• The "Promote to Draft" button moves the receipt from ai_draft to draft and brings it back into the main list.

✅ Confirming a Receipt (Inventory Update)

The moment you click "Confirm Receipt" on a draft:

1. The system verifies that every line is linked to a catalog item (else unresolved_items).
2. The system verifies that a branch is selected (else store_required).
3. Status changes to confirmed.
4. For every line: a positive count record is created for the received quantity (or expected, if no actual was reported) at the receiving branch, in the confirming user's name.
5. Branch on-hand inventory rises immediately and the change is reflected in every report, in the count app, and in your ERP integrations.

⚠️ Confirmation is irreversible. If you made a mistake, create a reverse receipt (credit) or post a corrective manual count. Double-check before confirming.

📤 Excel Export

Every receipt (any status) has an Export to Excel button that produces an .xlsx file with:

• Receipt header (number, supplier, reference, date, status).
• Line table: item code, barcode, description, expected qty, received qty, notes.

Useful for offline filing, reconciliation against the supplier, and forwarding to your accountant.

🔎 Search & Filter

The receipts table supports compound filtering by:

• Branch – single branch or all authorized branches.
• Status – Draft / Confirmed / Cancelled / AI Draft.
• Date range – by receipt date (not creation date).
• Sort – by date, receipt number, status.
• Server-side pagination – the table doesn't load every receipt into memory; only the requested page (excellent performance even with thousands of receipts).

🔗 Connection to Other Pages

• 🗂️ Item Catalog – receiving is impossible unless the item exists in the catalog. The engine uses item code, barcode and description to search.
• 🏢 Branches – receipts are associated with a branch and update its on-hand inventory.
• 🧰 Inventory Counts – confirming a receipt creates positive count records that show up in count reports.
• 🔌 Integrations – if an ERP integration is active, the new counts will sync.
• 🧾 Company Details – allocation numbers for tax invoices are required per regulatory rules.

❓ FAQ

What happens if I upload the same document twice? The system detects it via fingerprint and routes you to the existing result – you won't be charged twice.

The supplier sent an invoice with 100 lines. How long will it take? Depends on length, but typically 10–60 seconds. You'll see live progress.

The engine matched the wrong item – how do I fix it? On the review screen, click the item name, open the search, and pick the right one. Your choice is saved as a supplier alias and the next time it will match automatically.

My supplier writes descriptions in shorthand Hebrew. Will the engine understand? Yes. Fuzzy search supports Hebrew, English, transliterations, abbreviations, typos and reordered words.

How likely is the engine to be wrong about a quantity or price? Numeric extraction is very accurate, but it's still wise to glance at amber-flagged lines. The automatic checks (line totals vs. document total) catch most errors.

Can I edit a receipt after confirming? No. Confirmation updates inventory and is therefore irreversible. If you erred, create a reverse receipt or correct via a manual count.

Is my document saved? Yes, the original file and the full extraction output are retained for audit and reprocessing. They are accessible only to your company users.

What if I don't have a tidy document – just a hand-written list? Use a manual receipt. Add lines from the catalog one by one, or build a simple Excel sheet and try the upload (if the structure resembles an invoice, the engine will give it a shot).

Who can see the receipts? Managers see the entire company. Employees with company-management permission see only their assigned branches. Regular employees can only report actual received quantities.

✅ Recommended Workflow

1. Pallet arrives at the warehouse – snap the delivery note or wait for the supplier file.
2. Open Goods Receipt and pick "Upload Document".
3. Wait ~30 seconds for the engine to finish. You can keep unpacking in parallel.
4. Open the review screen and only check amber rows – greens are likely correct.
5. Report "actual received quantity" for every item that differs from expected (shortages / damages).
6. Confirm – inventory is updated.
7. Export to Excel and forward to your accountant if needed.

⚠️ Mistakes to Avoid

• Confirming without reviewing – a row matched to the wrong item will inject the quantity into the wrong product. Always check amber chips.
• Forgetting to set branch – the system blocks confirmation, but it's better to set it upfront.
• "Non-catalog" rows left unresolved – they must be linked to a catalog item before confirmation.
• Uploading a blurry document – the engine will do its best, but confidence will drop. Prefer a clean scan.
• Burning credits on noisy uploads – don't upload one slip as several photos; use a single PDF.

Summary

Goods Receipt is one of the biggest time-savers in OpticCount. Instead of typing dozens of lines from every delivery note, upload the document, review only the flagged lines, and confirm. Inventory is updated in one click, history is retained, and supplier matches get smarter every time you correct them.