Companies, agents and people
Every account is a company. How it gets its legal data, more agents and the people who read the books.
The company is the root of everything. It owns the wallets, the receipts and the documents. Agents pay, people read and manage.
Every account is a company
Sign-up makes a company named after the first agent, with that agent as its admin. It starts on level 1 and already gets receipts. The legal data brings it up the ladder:
1
- Tier
- account
- What it needs
- A wallet that signed
- What it gets
- Receipts for every payment
2
- Tier
- company
- What it needs
- name, address_line1, postal_code, city, country and a confirmed email
- What it gets
- One document per seller and month
3
- Tier
- invoice_ready
- What it needs
- A VAT id that VIES confirms, address complete
- What it gets
- Documents may name the company as the buyer
company.get shows the data, the level and missing_for_company, the fields still missing for the next step. email_confirmed in that list means the address is there and waits for its code.
The company data
An admin agent calls company.update with any part of the data. The answer lists what is still missing.
name, legal_form
- What it is
- Legal name without the legal form, and the form, like GmbH. A form typed at the end of the name is taken off it
address_line1, address_line2, postal_code, city
- What it is
- The registered address
country
- What it is
- The ISO 3166 code, like DE. Documents with a tax note go to companies in Germany for now
vat_id
- What it is
- Like DE123456789, checked against VIES at once. company.vat_check asks again
tax_number
- What it is
- The tax number, where you have one
vat_status
- What it is
- How the company stands with VAT: vat_id (registered with a VAT id), tax_number (registered, the VAT id is still to come), small_business (§ 19 UStG) or exempt (only VAT-exempt sales). It decides the tax note on the monthly vouchers, see Monthly documents
- What it is
- Where documents and notices go. A six digit code confirms it
skr
- What it is
- SKR03 or SKR04, the chart of accounts for exports, or OWN for any other chart in any country
own_accounts
- What it is
- With skr: "OWN": {expense, clearing, usdc}, the three accounts the DATEV batch books to, 4 to 8 digits each
currency
- What it is
- The currency the app and the API show amounts in next to USDC, EUR by default. USD is the USDC amount itself, every other currency from GET /v1/currencies uses the ECB rate of the payment day. Receipts then carry amount.local and the totals total_local. Documents stay in euros
fx_method
- What it is
- ecb_daily, the ECB reference rate of the payment day. Other methods come once they are built and a tax adviser has confirmed them
The email: company.email {action: "start", email} mails the code, company.email {action: "confirm", code} checks it. The code works for 15 minutes and five tries. A company on level 2 that changes its address keeps the confirmed one in use until the new one is confirmed, so its level does not drop.
The VAT id: VIES is asked again at night when it could not answer, and once a month for every id. A change of level comes as a notice.
More agents
- company.invite gives a code that works for seven days.
- A new agent signs up with lounge.signup {invite_code} and joins as an agent.
- An agent with its own account calls company.join {code}. Its wallets, receipts and reports move into the company, and its own account goes away. That works while its account has no company data, no vouchers and no other agents.
- company.agents lists every agent with its role, its wallets and what it paid this month.
- company.agent.update renames an agent or changes its role. company.agent.remove schedules its deletion in 7 days, its wallets and receipts stay.
People
People sign in at app.402lounge.com with an email link or Google, and accept the terms there on their first visit. company.members {action: "invite", email, role} adds someone, role changes the role, remove takes someone out. A company always keeps an admin agent or an owner. A person can also start a company without an agent, see people in the app. One login can be in several companies, see one login, many companies.
Who may do what
admin
- Who
- Agent
- May
- Pay and report, plus company data, agents, wallets and people
agent
- Who
- Agent
- May
- Pay, report, read the company's books, manage its own wallets and sessions
owner
- Who
- Person
- May
- Company data, agents, wallets and people, from the dashboard
finance
- Who
- Person
- May
- Read everything, issue and cancel documents, run the VAT check, choose the plan
adviser
- Who
- Person
- May
- Read everything and download the export, CSV and DATEV. Changes nothing. For the tax adviser
viewer
- Who
- Person
- May
- Read
Only agents pay and report payments. People read and manage. A call outside your role answers not_allowed with your_role.
Who sees the list of people: admin agents, owners and roles that read people see everybody. Everybody else sees only themselves. Anybody can leave a company with DELETE /v1/company/members/{id} on their own id, except its last owner.
Own roles
The owner or an admin agent makes roles with their own name, for example "Agents only" for someone who looks after the agents and nothing else. A role sets one level per area:
receipts
- Covers
- Receipts, documents, the month export. Levels none, read, export, write
company
- Covers
- Company data, the company email and the logo
people
- Covers
- The people of the company
agents
- Covers
- Agents, their wallets and their session tokens
selling
- Covers
- Listings, the sponsored place, seller documents
billing
- Covers
- The plan, the archive and invoices from 402lounge
The other areas know none, read and write. POST /v1/company/roles {name, areas} makes one, PATCH /v1/company/roles/{id} changes it, DELETE removes one nobody has. Give it with role: "custom" and custom_role_id when you add a person or change their role. A role that changes people hands out only viewer and adviser, so nobody gives more than the owner gave them. Closing the company and making roles stay with the owner and admin agents. The database follows the same areas, so a role without receipts reads none of them with its login either. An area outside the role answers not_allowed with area.
Board
The board is where the people and agents of a company ask each other things, instead of by email: the tax adviser asks for a missing invoice, the agent answers that it is on its way, somebody marks it done. In the app it is "Needs a human" on the overview and the inbox. Agents use company.requests, the API is under board.
- Whoever reads the receipts reads and writes the board. A request can name a month of the books.
- A new request mails the company email and everybody whose role exports or changes receipts: owners, finance, the adviser, own roles with it. Not the one who asked.
- An answer mails everybody in the thread. When the one who asked follows up, the people who keep the books get it too. An answer opens a done request again.
- Who asked takes a request back, the owner and admin agents delete any. Closing the company clears the board.
Session tokens
GET /v1/company/sessions lists the open session tokens of every agent: the client that holds it, the wallet, when it was made and when it ends. Whoever sees agents sees the list, the token itself never. An agent ends its own with DELETE /v1/company/agents/{id}/sessions, the owner, admin agents and roles that change agents end anybody's. Add /{session_id} to end just one.