After submission: the different cases and the supplier's tasks
This page describes what happens with the submitted action-agent_ceg_mb request, and what is needed for the connection to go live:
- what happens after the connection request is submitted - the possible cases depending on whether an account with the given tax number already exists,
- the supplier's tasks: activation and approval - what the supplier has to do, and what happens until then,
- and the response and error handling - how the response arrives, and the most common errors of the call.
For assembling the request, see Building the request and the XML; for the overview of the flow, see Establish the connection via API.
What happens after the connection request is submitted?
The same XML request is processed differently depending on whether an account with the given tax number (<cegtaxnumber>) already exists:
| Case | Behaviour | Response (XML_AGENT_RESPONSE) |
|---|---|---|
| No account with this tax number | New supplier account is created, and an account-owner invitation email is sent to <cegemail>. | DONE |
| Account exists, but has no account owner yet | No new account; the account-owner invitation email is re-sent. | "Már létező fiók, nincs fiókgazdája. Fiókgazdai meghívó (megbízott számlakibocsátás) email újraküldve." (existing account without owner, invitation re-sent) |
Account exists with account owner, and a join request for the same <usremail> is already pending | The existing join request email is re-sent to the account owner. | "Már létező fiók fiókgazdával. A csatlakozási kérelem emailt újraküldtük a fiókgazdának." (existing account with owner, join request re-sent) |
| Account exists with account owner, no pending request for this user | A new join request is created (with the prefix from <cegszamlaszamelotag>) and the account owner is notified by email. | "Már létező fiók fiókgazdával. Csatlakozási kérelmet küldtünk a fiókgazdának." (existing account with owner, join request sent) |
The existing-account cases, with the related error codes, are described in detail on the error handling page: Existing account with the given tax number.
In that case the system only uses the tax number (to identify the account) and the invoice prefix (stored as part of the join request) from the <cegMb> block; the company name, address, bank account, email addresses and the other fields remain unchanged in the existing account. As for the <usrMb> block: if a user with the given <usremail> already exists in the system, the join request is created for that existing user (the submitted password and name do not modify it); if it does not exist yet, the system creates it.
The test/live combinations of the delegate and supplier accounts (when test documents are created, and when a fee is charged) are summarised in the table of the Who bears the costs section of the general overview.
The supplier's tasks: activation and approval
After the request is submitted, the process continues on the supplier's side:
- For a new account, the account is not ready to invoice immediately: Számlázz.hu sends an activation email to
<cegemail>, and the supplier must take ownership of the account, activate it, and allow invoicing for the delegate. - For an existing account, the supplier's account owner receives an email notification about the request and approves (or rejects) it in the control panel. The link in the email is not required for the approval: if the account owner logs into their invoicing account, the pending request is also visible in the control panel and can be accepted there. If the account owner rejects the request, the delegate is notified by email; the request is closed, but a new request can be sent later - for example by re-submitting the same XML request.
- If the request contained an agreed invoice prefix (
<cegszamlaszamelotag>), an invoice book is created with that prefix on acceptance, tied to the delegate. If the prefix would conflict with one already used with the supplier's tax number, the acceptance fails and the delegate is notified by email; see Invoice prefix handling. - Once done, the delegate receives a confirmation email that the account is ready.
After the approval, the <usrMb> dedicated user gets the "delegated invoice issuer" role in the supplier's account (with invoicing permissions): this is the user to send the invoicing Agent calls with, and the same user can also log in on the web UI (where it only sees the documents it issued itself).
The connection becomes live only after the supplier's approval. Until then, login and invoicing attempts with <usrMb> fail as follows:
- For a new account not yet taken over, the call fails with error 250: "Ez a fiók nem használható, mert a fiókgazda még nem regisztrált. Üzenetet küldtünk a fiókgazdának, hogy vegye birtokba a fiókját (email address)." (the account cannot be used because the account owner has not registered yet) - in this case the system also automatically re-sends the account-owner invitation.
- For an existing account, until the account owner accepts the request, the user has no access to the supplier's account, so the call fails with error 3 (login failed).
There is no dedicated status-query API for the state of the connection. The delegate receives an email confirmation about the approval; programmatically, you can track the state from the call results: as long as a call made with the <usrMb> user returns error 250 or 3 above, the connection is not live yet - the first successful call indicates that the supplier has approved the connection.
If the activation / notification email got lost, you have two options: re-submit the same XML request (the system then re-sends the account-owner invitation or the pending join request - see the table above), or log in once with <usrMb> - the attempt fails with the error 250 above, but it triggers the account-owner invitation email again.
Response and error handling
A successful call returns the outcome in the XML_AGENT_RESPONSE HTTP response header (for example XML_AGENT_RESPONSE=DONE). On failure, the error is returned in the szlahu_error and szlahu_error_code headers, like other Agent calls; see Error handling.
The most common errors of this call:
| Code | When it occurs |
|---|---|
| 3 | Login failed; the login user must belong to exactly one account |
| 7 | Missing required data, for example missing <cegszamlaszamelotag> (invoice prefix) or missing login credentials |
| 68 | An account with this tax number and invoice prefix already exists |
| 101 | Only when a new supplier account is created: the <usremail> login name is already taken. When joining an existing account this is not an error - the join request is created for the existing user (see the info block above). |
| 137 | Your account has no licence for this interface. The exact (Hungarian) message: "Jelenleg nincs jogosultsága ahhoz, hogy ilyen módon hozzon létre számlázási fiókot. Ha mégis szeretne, vegye fel a kapcsolatot ügyfélszolgálatunkkal (szamlazz.hu/kapcsolat)" - you can request the licence from customer support |
| 309 | Invalid data, for example malformed tax number. You can validate the tax number automatically before submission with the Számla Agent taxpayer query interface: query the tax number first, and start the connection request only after the validation succeeded. |
| 337 | Malformed invoice prefix. The exact (Hungarian) message: "Az előtag csak nagybetűket és számokat tartalmazhat, és hossza legfeljebb 5 karakter lehet." |
The full list, with exact messages and what to do, is on the Error handling page.
Next steps
Once the supplier has approved the connection, invoicing can start in the supplier's account: Issue invoices as delegate.