ErpZeroZA documentation

01 · Installing

ErpZeroZA is a Frappe app. It needs ERPNext and csf_za on the same bench, and it never edits either of them, so both can be upgraded as normal.

On Frappe Cloud

1. Create a private bench group on Frappe v16 and add the apps: ERPNext (version-16), csf_za (Starktail/csf_za, version-16) and ErpZeroZA. Builder is optional but recommended for the website.
2. Deploy the bench group. Deploying only makes an app available; each site installs it separately.
3. Create the site from the bench group's Sites tab (a site created elsewhere can't use the group's apps), then install ERPNext, csf_za and ErpZeroZA on it.
4. Run the setup wizard with South Africa as the country, ZAR as the currency and a March–February financial year. When the company is saved, ErpZeroZA creates its VAT templates and VAT return settings (§02).
5. For updates: deploy the bench group, then press Update Available on each site. The update runs ErpZeroZA's patches, so sites installed earlier get the same set-up.

On your own server

On a bench running Frappe v16: bench get-app erpnext --branch version-16, bench get-app https://github.com/Starktail/csf_za --branch version-16, bench get-app https://github.com/erpafrica/erpzero-za --branch develop, then bench --site yoursite install-app erpnext csf_za erpzero_za. Issues and pull requests are welcome on GitHub.

02 · VAT and the VAT201

The company has one VAT control account (VAT), as in the standard South African chart and in Xero. What decides where a transaction lands on the VAT201 is the tax template chosen on the invoice. ErpZeroZA creates one template per VAT201 field for every company whose country is South Africa, and switches off the single "South Africa Tax" template that the setup wizard creates.

Sales (output tax)

Purchases (input tax)

Input tax may only be claimed with a valid tax invoice (s16(2)). Above R5,000 that must be a full tax invoice showing the recipient's name, address and VAT number (s20).

Preparing the return

1. Open Value-added Tax Return, choose the company and the first and last day of the tax period, and save. The return is named after the company and the period's last month, e.g. Karoo Kettle Co-202610 (the CCYYMM tax period SARS uses).
2. Click Get transactions for period. Every invoice and journal that touched VAT is listed with its classification. Zero-rated, export and exempt sales are listed too, at their net value, even though they post nothing to the VAT account.
3. Classify anything left over (usually journals), check the fields against the source documents, then submit. Field 20 is the VAT payable, or refundable when negative. File the figures on eFiling.

Barb can prepare the draft for you (§03); a person still checks and submits it.

03 · Barb the Bookkeeper

Barb is an AI bookkeeper inside ERPNext: a separate, licensed add-on app (barb) from 2nth.ai, installed alongside ErpZeroZA and switched on per site with a key. She is not open source and is not needed to run ErpZeroZA. Her VAT201 tool uses ErpZeroZA's VAT set-up.

Switching her on

1. Ask 2nth.ai for Barb for your site. You get access to the barb app and a Barb key.
2. Add the barb app to the bench (on Frappe Cloud, to the bench group), deploy, and install it on the site.
3. Put the key in the site config as barb_key (on Frappe Cloud: the site's Site Config tab, Add Config, key barb_key). There it stays out of database backups and out of sight in the desk. Barb Settings has a key field too, used only when the site config has none.
4. In ERPNext, open Barb Settings, tick Enabled and save. Leave the Barb URL as it is.
5. Reload the desk. Ask Barb appears at the bottom right of every page.

Using her

Ask in plain words. Good first questions: "Prepare my VAT201 for September and October", "Why is this period a refund?", "Who owes us money, and who should I chase first?", or, with an invoice open, "Is this a valid tax invoice?". She answers with the figures, links to the documents behind them, and what to do next.

Privacy and records

• Your books stay in your ERPNext. Barb's service decides what to look up; your system runs each lookup as you and sends back only the result. The service holds no password to your system and keeps nothing between questions.
• Each question is recorded in Barb Log: who asked, which lookups ran, the answer, the model used and the tokens it took. Users see their own entries; Accounts Managers see all.
• The model is Anthropic's Claude by default, called through Cloudflare AI Gateway on 2nth.ai's account.
• Barb is not a registered tax practitioner. On a judgement call she explains the rule, names the source and suggests you confirm with your accountant.

04 · Demo guests (showcase mode)

For consultants who want to let prospects try a demo company safely. Off by default; switch it on only on a demo site.

Before you switch it on

• An outgoing email account is set as the default (sign-in links are emailed).
• The demo company exists, with the data you want people to see.

Showcase Settings

What a demo guest can do

Guests get the standard Accounts User, Sales User and Purchase User roles, limited to the demo company, so every screen works as it would for a real bookkeeper: they can open anything and draft invoices, quotations and journals, and ask Barb. On top of that the Demo Guest role switches off submitting, cancelling, deleting anything but their own drafts, and sending email. A guest's sign-up never touches an existing user's account.

Every night the drafts and records guests made are cleared, and guests whose period is up are switched off. Each sign-up is kept as a Showcase Lead: name, email, company, consent, and how often they signed up. What they asked Barb is in Barb Log.

05 · The lean profile

On install, ErpZeroZA stops scheduled jobs for modules a set of books never uses, so a small plan isn't spent on work nobody asked for: CRM and marketing campaigns, Plaid bank feeds, manufacturing BOM costing, quality reviews, helpdesk auto-close and service levels, supplier scorecards, YouTube statistics and Google Calendar sync. It also switches on log clean-up.

Nothing a user sees is switched off: search, email, notifications, recurring documents, projects, assets, stock and the website all keep running. A System Manager can switch the stopped jobs back on in Scheduled Job Type, or all at once with erpzero_za.lean.restore.

06 · Official sources

ErpZeroZA's set-up, these docs and Barb's explanations follow these documents. Where we and a source disagree, the source wins: tell us and we'll fix it.

Check the SARS website for a newer issue before relying on a version number here.

07 · What changed