End-to-end process

Read this document before you test. Select the ? button on each screen for the short guide.

1. Screens to use

Start at login.html.

Admin Receive is Stock → Receive on admin-app.html.

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). Folder sample_network_purchasing_files/. Use on Receive.

These files have headers and box data. The system detects the network from the contents.

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

1. Select supplier CellC, MTN, or Smartcall (Vodacom and Telkom).
2. Enter unit cost excl. VAT per SIM. Received at defaults to today.
3. Put one file from sample_network_purchasing_files/ in the drop area.
4. The system detects the network.
5. Look at new SIMs and exceptions.
6. Select Receive. The button is at the top. After Receive, the button is not active.

Result: SIMs sit in the warehouse. Do not put activation files on this page. The MTN purchasing file has many rows. Start with Cell C, Vodacom, or Telkom for a short test.

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.
3. Select Preview. Confirm the network and the matched count.
4. Select Commit.
5. Repeat for MTN, Vodacom, Cell C, and Telkom.

Matched SIMs become activated. Commission is matched count × the commission rule, only if that person is set to receive commission. 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 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: import Telkom_Sep_2026_Serials.csv or ORDER_17180677-1.txt.
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.