Tally Extractor Skill#

Extract invoice/bill data from PDFs and images received via Telegram or WhatsApp, convert to a canonical JSON payload, and POST to the bridge service on Instance B for Tally entry.

• No direct Tally access: This skill does NOT connect to TallyPrime. Voucher posting is handled by tally-skill on Instance B.
• Telegram/WhatsApp interface: User sends PDF/image → this skill extracts → bridge → Tally.
• Structured output: Always emit the canonical JSON schema (see reference/extraction-schema.md).

Hero Use Case: Telegram invoice → Tally entry#

Goal: zero manual entry for CAs handling many clients.

1. User sends invoice PDF/image via Telegram.
2. This skill extracts: company, party, GSTIN, date, invoice no, items (description, HSN, qty, rate, tax), total.
3. Validate extraction: tax math check, GSTIN format, required fields present.
4. POST canonical JSON to bridge ( /v1/post-voucher).
5. Receive result from bridge and reply to user in accountant-friendly language.

When to use this skill#

Scope note: This skill is for Instance A (Extractor). It does not post to Tally — that responsibility belongs to tally-skill on Instance B.

Use when:

• User sends a PDF or image of an invoice/bill via Telegram/WhatsApp
• User requests to extract data from a document
• User asks to "add this invoice to Tally" (extract + forward to bridge)
• User provides invoice details as text message (parse and forward)

Do NOT use this skill for:

• Direct Tally operations (reports, ledger queries) — those go to Instance B
• PDF generation ( tallyca runs on Instance B)
• Master management (ledgers, groups) — that's on Instance B

Critical rules (must follow)#

1. Never hallucinate data: If a field is unclear or missing from the document, mark it as low-confidence or ask the user. Do not invent GSTINs, HSN codes, or amounts.
2. Validate GSTIN format: 15 characters, pattern ^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[1-9A-Z]{1}Z[0-9A-Z]{1}$. If invalid, flag it.
3. Validate HSN format: 4-8 digits. If invalid, flag it.
4. Tax math check: taxable_amount × tax_rate / 100 ≈ tax_amount (within ±0.01). If mismatch, flag it.
5. Total check: Sum of item amounts + taxes = total (within ±1 for rounding). If mismatch, flag it.
6. Place of Supply: Derive from first 2 digits of party GSTIN (state code). Map to state name using reference/extraction-schema.md state code table.
7. Inter-state vs Intra-state: If company GSTIN state ≠ party GSTIN state → IGST. If same state → CGST + SGST.
8. Dates: Extract as YYYY-MM-DD. Common formats on invoices: DD/MM/YYYY, DD-MM-YYYY, DD.MM.YYYY, MMM DD, YYYY.
9. Idempotency key: Generate deterministic GUID using pattern {companyShort}-{voucherType}-{invoiceNumber}-{date}.
10. Confidence scores: Assign confidence (0.0-1.0) to each extracted field. Flag fields with confidence < 0.7 for user confirmation.

Extraction workflow#

Step 1: Receive document#

User sends PDF or image via Telegram. The document is available for OCR/vision processing.

Step 2: Check bridge health#

Before extraction, verify Instance B is reachable:

bash

curl -s -X GET \
  -H "Authorization: Bearer $BRIDGE_BEARER" \
  "$BRIDGE_URL/v1/health"

Expected response:

json

{
  "tally": "ok",
  "company_default": "ABC Company",
  "version": "1.0.0"
}

If tally: "down", inform user: "Tally is not running on the client machine. Please ask them to open TallyPrime."

Step 3: Extract data#

Parse the document and extract:

FieldSourceValidationParty nameInvoice headerRequiredParty GSTINNear party name or GST section15-char formatCompany GSTINNear company name or letterhead15-char formatInvoice numberInvoice headerRequiredInvoice dateInvoice headerParse to YYYY-MM-DDItemsLine items tableAt least oneItem descriptionLine itemRequired per itemHSN/SACLine item4-8 digitsQuantityLine itemNumericUnitLine itemOptionalRateLine itemNumericTax rateLine item or GST sectionPercentageCGST/SGST/IGST amountsGST sectionNumericTotalInvoice footerRequired, must balanceNarrationNotes sectionOptional

Step 4: Determine voucher type#

Document typeVoucher typePurchase invoice (we are buyer)PurchaseSales invoice (we are seller)SalesPayment receiptReceiptPayment voucherPaymentCredit noteCreditNoteDebit noteDebitNote

Clues:

• "Tax Invoice" with company as seller → Sales
• "Tax Invoice" with company as buyer → Purchase
• "Receipt" or "Payment Received" → Receipt
• "Credit Note" in header → CreditNote

If ambiguous, ask user: "Is this a purchase (you bought) or sales (you sold)?"

Step 5: Validate extraction#

Run these checks before sending to bridge:

CheckRuleAction if failsRequired fieldsAll required fields presentList missing fields, ask userGSTIN format15-char regex matchFlag invalid, ask userHSN format4-8 digitsFlag invalid, ask userTax mathtaxable × rate / 100 ≈ taxFlag mismatch, ask userTotal balanceitems + taxes = total (±1)Flag mismatch, ask userDate parseableValid dateAsk user for correct date

Step 6: Build canonical JSON#

Construct the JSON payload per reference/extraction-schema.md:

json

{
  "schema_version": "1.0",
  "request_id": "uuid-v4",
  "idempotency_key": "abc-purchase-xyz-186-20260518",
  "company": "ABC Company",
  "voucher": {
    "type": "Purchase",
    "date": "2026-05-18",
    "number": "186",
    "is_invoice_mode": true,
    "voucher_class": null,
    "narration": "Against Invoice 186",
    "party": {
      "name": "XYZ Party",
      "gstin": "27AABCU9603R1ZM",
      "place_of_supply": "Maharashtra",
      "registration_type": "Regular"
    },
    "company_gstin": "27AABCU9603R1ZN",
    "items": [...],
    "taxes": {...},
    "total": 46199.83,
    "bill_allocations": [...]
  },
  "source": {
    "kind": "pdf",
    "filename": "invoice_186.pdf",
    "extracted_at": "2026-05-18T10:30:00Z"
  },
  "confidence": {
    "overall": 0.93,
    "fields": {...}
  }
}

Step 7: POST to bridge#

Send the JSON to Instance B:

bash

# Compute HMAC
BODY='{"schema_version":"1.0",...}'
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$BRIDGE_HMAC_SECRET" | cut -d' ' -f2)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BRIDGE_BEARER" \
  -H "X-Signature: hmac-sha256=$SIGNATURE" \
  -H "Idempotency-Key: abc-purchase-xyz-186-20260518" \
  -d "$BODY" \
  "$BRIDGE_URL/v1/post-voucher"

Full HTTP contract in reference/bridge.md.

Step 8: Handle response#

Success

json

{
  "status": "posted",
  "guid": "abc-purchase-xyz-186-20260518",
  "voucher_number": "186",
  "company": "ABC Company",
  "summary": "Purchase voucher posted: XYZ Party, ₹46,199.83",
  "masters_created": ["XYZ Party"]
}

Reply to user (see reference/prompts.md):

Entry posted to Tally.

Company: ABC Company

Type: Purchase

Party: XYZ Party

Invoice No: 186

Date: 18 May 2026

Amount: ₹46,199.83 (Taxable: ₹39,152.40 + IGST: ₹7,047.43)

New ledger created: XYZ Party

Needs Clarification

json

{
  "status": "needs_clarification",
  "missing_fields": ["voucher.voucher_class"],
  "message": "Please confirm the voucher class name (e.g., 'Purchase @ 18 %')."
}

Forward the question to the user.

Error

json

{
  "status": "error",
  "error_code": "TALLY_UNREACHABLE",
  "message": "Could not connect to Tally."
}

Reply to user: "Tally is not responding. Please check that TallyPrime is open and try again."

Company name handling#

The company name must match exactly in TallyPrime. Strategies:

1. Explicit in document: Extract from invoice letterhead
2. User specified: User may say "Add to ABC Company"
3. Default from bridge: /v1/health returns company_default
4. Ask user: If unclear, ask "Which Tally company should this entry go to?"

Voucher class handling#

Some Tally companies use voucher classes for automatic GST splitting. This skill does NOT know which class to use — that's Instance B's job.

• If user specifies class in message (e.g., "use Sales @ 18 %"), include in JSON
• If not specified, leave voucher_class: null and let Instance B handle it
• If Instance B returns needs_clarification for class, forward to user

Confidence scoring#

Assign confidence scores based on:

Extraction qualityConfidenceClear text, high contrast, exact match0.95 - 1.0Readable but some ambiguity0.7 - 0.94Blurry, low contrast, guessed0.4 - 0.69Highly uncertain0.0 - 0.39

Fields with confidence < 0.7 should be flagged for user confirmation before posting.

State code to state name mapping#

First 2 digits of GSTIN → Place of Supply:

CodeState01Jammu and Kashmir02Himachal Pradesh03Punjab04Chandigarh05Uttarakhand06Haryana07Delhi08Rajasthan09Uttar Pradesh10Bihar11Sikkim12Arunachal Pradesh13Nagaland14Manipur15Mizoram16Tripura17Meghalaya18Assam19West Bengal20Jharkhand21Odisha22Chhattisgarh23Madhya Pradesh24Gujarat25Daman and Diu26Dadra and Nagar Haveli27Maharashtra28Andhra Pradesh (Old)29Karnataka30Goa31Lakshadweep32Kerala33Tamil Nadu34Puducherry35Andaman and Nicobar Islands36Telangana37Andhra Pradesh38Ladakh

Deployment topology#

There is exactly one chat interface (Telegram on Instance A). Instance B has no Telegram/WhatsApp — only the bridge HTTP endpoint.

Rendering diagram...

EnvironmentInstance AInstance BTally accessProductionYour EC2 (Telegram, Codex Plus)Client mini-PC beside TallyB → http://localhost:9000 (no ngrok for Tally)Dev / testingSame Ubuntu EC2Second OpenClaw on same EC2B uses ngrok URL to remote Tally

Instance A reaches B via an inbound tunnel on the client box ( ngrok http 8787 or Cloudflare Tunnel). Share BRIDGE_URL, BRIDGE_BEARER, and BRIDGE_HMAC_SECRET with the team running A.

Instance A configuration checklist#

StepSettingValue1HostUbuntu EC2 (or dev server)2InstallNode.js, OpenClaw3LLMOpenAI ChatGPT Codex Plus session (subscription)4Skill loadedtally-extractor-skill/ only — do not load tally-skill/5ChannelTelegram bot token on A only6BRIDGE_URL``https://<client-tunnel>.ngrok.app (no trailing slash)7BRIDGE_BEARERShared secret from client team8BRIDGE_HMAC_SECRETShared HMAC secret from client team9Do not setTALLY_URL on Instance A10Preflightcurl -H "Authorization: Bearer $BRIDGE_BEARER" $BRIDGE_URL/v1/health → tally: ok

Reference files#

• Extraction schema: reference/extraction-schema.md — Full JSON schema, examples
• Bridge HTTP contract: reference/bridge.md — Endpoints, auth, errors
• Reply templates: reference/prompts.md — User-facing messages