Billingo and Számlázz.hu integration

Billingo & Számlázz.hu Invoicing Integration

Hungarian invoicing regulations and NAV Online Számla real-time reporting mean that once a legal invoice (számla) is issued, it cannot be edited or deleted — any correction requires issuing an official storno / cancellation invoice (sztornó számla) or modification document (módosító számla). Treat invoicing as a decoupled, idempotent state machine separate from payment capture.

1. Core Hungarian Invoicing & NAV Online Számla Rules

• Document Types & Lifecycle:
  • Proforma (díjbekérő): a payment request, not a tax invoice (not reported to NAV). Used before wire transfer or pending checkout; once paid, issue a final invoice (számla) referencing the proforma.
  • Advance Invoice (előlegszámla) & Final Invoice (végszámla): required when payment precedes delivery in specific accounting flows.
  • Normal Invoice (számla): immutable tax document automatically reported to NAV Online Számla by Billingo / Számlázz.hu.
  • Storno / Cancellation (sztornó számla): reverses a mistakenly issued or fully refunded invoice by referencing the original invoice ID.
• VAT (ÁFA) & Buyer Tax Number Rules:
  • Never hardcode a single "27%" VAT rate without checking approved business rules: Hungarian VAT includes standard rates (27%, 18%, 5%, 0%) and special entitlement codes (AAM alanyi adómentes, TAM tárgyi adómentes, EU / EUK intra-community reverse charge, HO / KBAET third-country / outside territorial scope). Every non-standard VAT code requires its matching legal exemption text/reason!
  • Hungarian B2B buyers: if the buyer is a domestic Hungarian taxpayer providing a tax number (adószám), format and validate the 8-digit core tax number (or 12345678-1-23) so NAV Online Számla reporting does not fail with a validation error.

2. Billingo API v3 (https://api.billingo.hu/v3)

• Authentication: X-API-KEY header (never expose client-side).
• Partner + Document Creation Flow:
  1. Upsert or resolve the partner_id (POST /partners or PUT /partners/{id}) with buyer name, address (country_code, post_code, city, address), emails and taxcode.
  2. Create document (POST /documents) specifying partner_id, block_id (invoice pad), type ('invoice' | 'proforma' | 'draft' | 'advance'), fulfillment_date, due_date, payment_method, language, currency, conversion_rate (mandatory when currency !== 'HUF'! Fetch MNB / ECB exchange rate or Billingo currency rate), paid: true|false, and items.
• Idempotency & Retries: store the local invoice_attempt_id -> billingo_document_id mapping; if a network timeout occurs during POST /documents, check recent documents for the partner/order before retrying to avoid issuing two legal invoices.
• Cancellation: call POST /documents/{id}/cancel with cancellation_reason to issue a storno invoice.

3. Számlázz.hu (Számla Agent XML over HTTPS)

• Protocol: multipart/form-data POST to https://www.szamlazz.hu/szamla/ with an XML file payload (action-xmlagentxmlfile for invoice creation, action-szamla_agent_st for storno, action-szamla_agent_kifiz for recording payment).
• Authentication: always use <szamlaagentkulcs> (API key), never legacy username/password.
• Idempotency via <rendelesszam> & X-Command-Id:
  • Populate <rendelesszam> (order number) and trace identifiers consistently, and verify response headers (szlahu_szamlaszam, szlahu_error, szlahu_error_code).
  • Remember that szlahu_vevoifiokurl or szlahu_id headers may be URL-encoded.
• Decoupled Error Recovery: if Billingo or Számlázz.hu is temporarily unavailable or rejects a buyer's malformed postal code/tax number when a Stripe/Barion payment succeeds, still grant the paid product entitlement, mark invoice_status = 'failed_retryable' or 'requires_attention', and queue safe retry/admin correction.