Skip to main content

Establish the connection via API

Delegated invoicing means that one company (the delegate) issues invoices in the name of another company (the supplier), in the supplier's Számlázz.hu account. Before that can happen, a connection must be established between the two companies. There are two ways to do this: on the web interface (Establish the connection on the UI) or programmatically, via API (action-agent_ceg_mb) - the latter is described in this section, on three pages:

  1. Overview and prerequisites (this page): what the call does, what you need, and how the flow is structured.
  2. Building the request and the XML: the technical parameters of the request, the XML blocks and fields, example XML and XSD.
  3. After submission: the different cases and the supplier's tasks: what happens with the submitted request, what the supplier has to do, response and error handling.

For the roles (supplier, delegate) and the business overview, see Third-party invoicing.

What does the action-agent_ceg_mb call do?​

The API route covers two situations with the same XML request:

  • if the supplier does not have a Számlázz.hu account yet, the call creates the supplier account;
  • if the supplier already has an account (identified by the given tax number), the call sends a join request to the account owner - no duplicate account is created.
The accuracy of the tax number is critical

The system recognizes the supplier's existing account solely based on an exact match of the tax number sent in the request. If the tax number contains a typo or differs from the one stored in the account, the call creates a new account instead of sending a join request. Before submitting, always double-check the supplier's details, especially the tax number.

In both cases the call also creates the dedicated user (<usrMb>) that the delegate will later use to invoice in the supplier's account. With multiple suppliers, specify a separate dedicated user (a separate <usremail>) per supplier: the user used for Agent calls may only have access to exactly one account, otherwise the calls fail with error 164.

Prerequisites​

Before assembling the request, you will need:

  • A registered delegate account on Számlázz.hu with Számla Agent access; for identification you use an Agent key, but you can also use a username + password pair, see Authentication.
  • A licence for this interface: the action-agent_ceg_mb call requires a licence. You can request access from customer support; without the licence the call fails with error code 137.
  • The supplier's details. Required: company name, tax number, registered address, and a valid email address - important: when a new account is created, the supplier receives the activation (account-owner invitation) email at this address given in the request. The tags for the bank name, the bank account number and the reply-to address of the invoice notifications must be present in the XML, but their values may be left empty. Optional: a different postal address, and the periods of cash accounting and of the small taxpayer (KATA) status. Field-by-field details: Building the request and the XML.
  • An agreed invoice number prefix (max. 5 characters, uppercase letters and digits only): the delegate's invoices will be issued in this ledger; see Prefix handling.
info

If the calling (delegate) account is in test mode, the supplier account created by the call is automatically a test account too, and its company name gets an " (agentceg teszt)" suffix. This lets you try the whole flow safely, without live data; see Testing the flow. The licence for the interface is required for the test account too - it is not part of the #profi feature set of test mode either, so request it from customer support for your test account as well.

Overview of the flow​

In chronological order, this is how the connection is established via API:

  1. Assemble the XML of the action-agent_ceg_mb request with the supplier company's data; see Building the request and the XML.
  2. Submit the request via HTTP POST to the Számla Agent endpoint.
  3. Based on the tax number, the system creates the supplier account or sends a join request to the existing account; see What happens after the connection request is submitted?
  4. The supplier receives an email: for a new account, the activation (account-owner invitation) email goes to the <cegemail> address given in the request; for an existing account, the approval notification goes to the company email stored in the account and to the account owner's email address, and the account owner accepts the request in the control panel.
  5. When the supplier takes ownership of the account / approves the request, the delegate receives a confirmation email.
  6. Before live invoicing, the NAV Online Számla connection must be completed in the supplier account.
  7. Then invoicing can start in the supplier's account; see Issue invoices as delegate.

Next step​

Assemble the request: Building the request and the XML.