Help

2. Goal

• Put a SIM in the hands of a customer.
• The customer must complete RICA.
• The customer must use the SIM.
• The network pays commission after RICA and after spend of about R25.
• The company then pays this commission to agents and drivers.

RICA is not activation. Activation is RICA plus spend of about R25. The network sends a monthly file. The system pays commission from that file.

3. Who does what

The system does not send money. It shows the amount. Admin pays outside the system.

4. Files for this test

Supplier files (new stock). Use these on Stock → Receive.

• Cell C: the order file from Cell C.
• MTN: the kit file from MTN.
• Smartcall: one Vodacom CSV or one Telkom CSV. Put one network in one file.

Use a .csv, .txt, or .dat file. Do not use an Excel file. Select the supplier and the network before you put the file in. One file has one network.

These names show the file shape only. Do not put a file in again when those serials are already in the warehouse.

Monthly activation files (commission). Folder activation_reports_examples/. Use on Stock → Activate. Set year 2026 and month 7 for the July samples.

One number on each line. No header. The July files may not match SIMs from the September purchasing files. See step 9 for a clean commission test.

5. Flow for one month

6. Step 1 — Login

1. Open login.html.
2. Select ? and read the guide.
3. Enter username and password.
4. If the system asks for a new password, set a new password.

Demo field users: D1 (driver), D1-001 (agent), D2 (driver). Temporary password: ChangeMe123!

Admin is ADMIN_USER in .env. Admin login opens admin-app.html.

7. Step 2 — Add people and set commission (Admin)

Page: People and stores

1. Add a Driver first.
2. Add an Agent or a Store under that Driver.
3. Tick “This person receives commission” only if you pay this person.
4. Set pay per activated SIM for each network. Use rands. The monthly activation file uses this rate.
5. Set the low-stock warning as a SIM count per network. Home warns if on-hand stock drops below that number. This is not pay.
6. Select Edit on a driver or agent to change name, ID, region, pay, or low-stock warning. The code, the role, and Reports to stay the same.
7. A change to pay per activated SIM applies to the next monthly file. Closed months stay as they are.
8. A store that a driver submitted sits in Directory. Select Stores or Needs approval.
9. Select Activate. Review the documents. Leave Give this store a login off unless the store will use the field app.

Demo people may already exist. Confirm a commission amount is set. If there is no rule, the payout amount is R0.

8. Step 3 — Receive supplier SIMs (Admin)

Page: Admin → Stock → Receive

Only an admin can use this page.

1. Select supplier CellC, MTN, or Smartcall.
2. Select the network. Smartcall is Vodacom or Telkom.
3. Enter unit cost excl. VAT per SIM. This value is required.
4. Received at is today. Change the date if the stock arrived on another day. Delivery ref is optional.
5. Put one supplier file in the drop area. Use a .csv, .txt, or .dat file. One file has one network.
6. Split a mixed Vodacom and Telkom workbook into two files before you receive it.
7. The system checks each serial start against the selected network. One serial that does not match stops the file.
8. If the message names a new prefix, add that prefix on Settings, Networks. Then receive the file again.
9. Read the exception list. The system stores new serials only. A duplicate is already in the warehouse or already with a holder. Bad serials are not stored.
10. Select Receive N new serials. The button is under the file name and above the preview.
11. If the count is 0, the button stays off. Read the exception list.
12. Wait for the result line. The file, the preview, and the button go away. Supplier, network, unit cost, delivery ref, and the date stay. Check them. Then put the next file in.

Result: new SIMs sit in the warehouse. Do not put an activation file on this page. Do not use Scan for a supplier file. A serial start that does not match the selected network stops the file.

9. Step 3b — Pack SIMs (Admin)

Page: Admin → Stock → Pack

1. Set the pack size. The default is 10.
2. Scan that many SIMs. A handheld scanner can send Enter. A valid serial also adds itself.
3. You can scan a brick or a box to fill the pack from warehouse stock.
4. When the pack is full, stick a printed QR sticker on the pack. Scan the sticker to seal.

Result: the pack has a QR code. Agents and drivers receive packs. They do not receive boxes or bricks. Boxes and bricks stay whole for large customers.

10. Step 4 — Move packs to the Driver (Admin)

Page: Stock → Move

1. Select the Driver or the Agent first.
2. Scan pack stickers into the list. You can mix networks. Select Remove if a row is wrong.
3. For a large customer (store), select that store, then scan a box or a brick.
4. When the list is complete, select Move.

Result: SIMs are in transit. The Driver sees a red mark on Field Home.

11. Step 5 — Driver confirms, then moves to the Agent

Page: Field Scan. Login as the Driver.

1. Scan the inbound pack or SIM.
2. Select Confirm receive.
3. Scan again.
4. Select the Agent.
5. Select Allocate to Agent / Store.

Result: SIMs are in transit to the Agent. An Agent can also send a stock request from Field Home. The driver can split a pack. The driver cannot split a box or a brick.

12. Step 6 — Agent confirms stock

Page: Field Scan. Login as the Agent.

1. Scan the inbound SIM, box, or brick.
2. Select Confirm receive.

Do not skip confirm. Stock that you do not confirm is not yours.

13. Step 7 — RICA for the customer

Page: Field RICA or Admin RICA.

1. Scan the SIM that the customer will use.
2. Scan the customer ID, or type the ID number. ID or passport only.
3. Enter the address and the contact number.
4. Complete all steps. Wait for a successful result.
5. Tell the customer to spend about R25 on the SIM.

Result: the SIM is with the end customer. Status is RICA registered. The SIM is not activated yet.

14. Step 8 — Customer uses the SIM

The customer spends about R25 with the network. This system does not record the spend. The network includes the SIM in the next monthly activation file if RICA and spend are complete.

15. Step 9 — End of month: Activate (Admin)

Page: Admin → Stock → Activate.

1. Set the year and the month of the file.
2. Put one activation file in the drop area. One number on each line. No header.
3. Select Preview. Read the commission total. Preview does not save the file and does not change stock.
4. Select Preview Download. Open the CSV. Check each person and each rand amount. This does not save the file and does not change stock.
5. Select Commit only when the preview is right. Commit saves the file and marks the matched SIMs as activated. You cannot undo Commit.
6. Repeat for MTN, Vodacom, Cell C, and Telkom.

Hold the pointer on each button to read what that button does.

Commit marks matched SIMs as activated. Commission is the stored amount from Preview. A person gets rand only when that person is set to receive commission and has a rate. You cannot put the same network and month in the system twice.

When all files are in, select Close this month. That stores the payout history. A second close returns an error. You cannot delete a closed month. Targets stay. Home year-to-date activated is the sum of every month that has a file. Home starts at zero in the next calendar month.

Clean commission test. Copy 3 to 10 ICCIDs that you imported. Put one ICCID on each line. No header. On Activate, set year and month (example: 2026 and 9). Commit that small file. Then the Agent Home details show those SIMs and the commission.

To test the real July files, set year 2026 and month 7. The system matches numbers that already exist in stock.

16. Step 10 — See the SIMs and pay

Agent or Driver: Field Home → Show details. After the file is in the system, this list is activated SIMs and commission for that month.

Admin: Stock → Activate → Payout. Pay that amount outside the system. The system does not mark “paid” yet.

17. Step 11 — Start a new month

Close the previous month on Activate first. That stores the payout. You do not reset the target numbers or the commission rates. Those stay as setup.

1. Field Home counts the new calendar month from zero.
2. Closed months stay in the Closed months list.
3. Continue daily work: Receive, Move, Confirm, RICA, spend of about R25.
4. At the end of the new month, put the new activation files in Activate, then Close this month.
5. Pay commission from that closed payout list.

Do not import last month’s activation file again. A closed month is blocked. You cannot delete a closed month.

18. Daily vs monthly

19. What good looks like for one SIM

1. Receive: SIM is in the warehouse.
2. Pack: SIM is in a sealed pack with a printed sticker.
3. Move to Driver: SIM is in transit.
4. Driver confirms: SIM is with the Driver.
5. Move to Agent: SIM is in transit.
6. Agent confirms: SIM is with the Agent.
7. RICA success: SIM is with the end customer. Status is RICA registered.
8. Customer spends about R25.
9. Activation file matches the SIM: status is activated. Commission sits on the Agent for that month.

Use Admin → Insight → Find a SIM to search one serial and read the timeline.

20. Short test path

1. Login as Admin. Open admin-app.html. Select ? on each hub.
2. People and stores: confirm D1 and D1-001 exist. Set commission for one network (example: R12.50).
3. Receive: put one new supplier file in. Do not use a file whose serials are already in the warehouse.
4. Stock → Pack: put 10 SIMs in a pack. Scan a sticker code to seal.
5. Stock → Move: scan the pack sticker and send it to D1.
6. Login as D1. Confirm on Scan. Allocate to D1-001.
7. Login as D1-001. Confirm on Scan.
8. RICA one SIM. Tell the customer to spend about R25.
9. Copy that ICCID into a one-line text file.
10. Admin → Stock → Activate. Set year and month. Commit the one-line file.
11. Login as D1-001. Home → Show details. Confirm the SIM and the commission.
12. Admin Activate → Payout. Pay from that list. That ends the month for those SIMs.

Then start the next month with new Receive / Move / RICA work. Do not reuse the same network and month on Activate.