//! Issuing the invoices of the Stripe payments in Billingo (API v3). //! //! The backend queues one `invoices` row per paid checkout, with the buyer and //! the item as they go on the invoice. This job takes the due rows and, step //! by step, creates the Billingo partner, the invoice (paid by card, //! electronic) and e-mails it to the buyer. Each step's result is saved before //! the next one, so a retry continues where it stopped. The invoice request is //! marked before it is sent: when Billingo's answer was lost, the retry finds //! the invoice under the invoice's own partner instead of issuing a second //! one. An invoice that was issued but could not be e-mailed still counts as //! issued (it can be downloaded). Billingo's whole answer is kept; the PDF is //! not (the backend fetches it when the user downloads it). use std::time::Duration; use serde_json::{Value, json}; use sqlx::PgPool; use time::{Date, Month, OffsetDateTime, UtcOffset, Weekday}; use tokio::sync::{Mutex, watch}; use uuid::Uuid; use crate::email::backoff; pub const DEFAULT_BASE_URL: &str = "https://api.billingo.hu/v3"; /// How long a claimed invoice is left alone (a crashed worker's row comes back). const LEASE: &str = "10 minutes"; pub struct Billingo { http: reqwest::Client, base: String, key: String, /// The invoice pad (`BILLINGO_BLOCK_ID`, or the account's first invoice pad). block: Mutex>, } impl Billingo { pub fn new(base: &str, key: &str, block: Option) -> Self { let http = reqwest::Client::builder().timeout(Duration::from_secs(30)).build().expect("static configuration"); Self { http, base: base.trim_end_matches('/').to_owned(), key: key.to_owned(), block: Mutex::new(block) } } async fn call(&self, method: reqwest::Method, path: &str, body: Option<&Value>) -> Result { let mut req = self .http .request(method.clone(), format!("{}{path}", self.base)) .header("X-API-KEY", &self.key) .header("Accept", "application/json"); if let Some(body) = body { req = req.json(body); } let res = req.send().await.map_err(|e| format!("{method} {path}: {e}"))?; let status = res.status(); let text = res.text().await.unwrap_or_default(); if !status.is_success() { return Err(format!("{method} {path}: HTTP {status}: {}", text.chars().take(500).collect::())); } if text.trim().is_empty() { return Ok(Value::Null); } serde_json::from_str(&text).map_err(|e| format!("{method} {path}: not JSON: {e}")) } async fn block(&self) -> Result { let mut block = self.block.lock().await; if let Some(id) = *block { return Ok(id); } let list = self.call(reqwest::Method::GET, "/document-blocks?type=invoice&per_page=100", None).await?; let id = list["data"] .as_array() .and_then(|pads| pads.iter().find(|p| p["type"] == "invoice" || p["type"].is_null())) .and_then(|p| p["id"].as_i64()) .ok_or("Billingo has no invoice pad (document block); set BILLINGO_BLOCK_ID")?; *block = Some(id); Ok(id) } } #[derive(sqlx::FromRow)] struct Due { id: Uuid, attempts: i32, buyer_name: String, buyer_email: Option, buyer_country: String, buyer_post_code: String, buyer_city: String, buyer_address: String, buyer_tax_type: String, buyer_tax_number: Option, item_name: String, item_comment: Option, item_unit: String, gross_huf: i32, vat_rate: String, payment_method: String, billingo_partner_id: Option, billingo_document_id: Option, document_requested_at: Option, sent_at: Option, paid_at: OffsetDateTime, } /// The date in Hungary (CET, CEST from the last Sunday of March to the last /// Sunday of October, 01:00 UTC): the invoice's fulfilment date. pub fn hungarian_date(t: OffsetDateTime) -> Date { let last_sunday = |month| { let mut d = Date::from_calendar_date(t.year(), month, 31).expect("March and October have 31 days"); while d.weekday() != Weekday::Sunday { d = d.previous_day().expect("not the first day"); } d.with_hms(1, 0, 0).expect("valid time").assume_utc() }; let summer = t >= last_sunday(Month::March) && t < last_sunday(Month::October); t.to_offset(UtcOffset::from_hms(if summer { 2 } else { 1 }, 0, 0).expect("valid offset")).date() } /// A `YYYY-MM-DD…` value of Billingo's answer. fn date(v: &Value) -> Option { let s = v.as_str()?.get(..10)?; let mut parts = s.split('-'); let year = parts.next()?.parse().ok()?; let month = Month::try_from(parts.next()?.parse::().ok()?).ok()?; Date::from_calendar_date(year, month, parts.next()?.parse().ok()?).ok() } /// Issues the due invoices; returns how many were finished. pub async fn run_once(db: &PgPool, billingo: &Billingo, max_attempts: i32) -> Result { let mut done = 0; loop { let due: Option = sqlx::query_as(&format!( "UPDATE invoices i SET attempts = i.attempts + 1, next_attempt_at = now() + interval '{LEASE}' \ FROM stripe_checkouts c \ WHERE c.id = i.checkout_id AND i.id = (SELECT id FROM invoices WHERE status = 'pending' \ AND next_attempt_at <= now() ORDER BY next_attempt_at FOR UPDATE SKIP LOCKED LIMIT 1) \ RETURNING i.id, i.attempts, i.buyer_name, i.buyer_email, i.buyer_country, i.buyer_post_code, \ i.buyer_city, i.buyer_address, i.buyer_tax_type, i.buyer_tax_number, i.item_name, i.item_comment, i.item_unit, i.gross_huf, \ i.vat_rate, i.payment_method, i.billingo_partner_id, i.billingo_document_id, \ i.document_requested_at, i.sent_at, \ coalesce(c.completed_at, i.created_at) AS paid_at" )) .fetch_optional(db) .await?; let Some(due) = due else { return Ok(done) }; match issue(db, billingo, &due).await { Ok(number) => { tracing::info!(invoice = %due.id, number = %number, "invoice issued"); done += 1; } Err(Failure::Db(e)) => return Err(e), Err(Failure::Billingo(error)) if due.attempts >= max_attempts => { // Issued but never e-mailed: it is still an invoice (the user downloads it). let issued: Option<(Option,)> = sqlx::query_as( "UPDATE invoices SET status = 'issued', issued_at = now(), last_error = $2 \ WHERE id = $1 AND billingo_document_id IS NOT NULL RETURNING invoice_number", ) .bind(due.id) .bind(format!("issued, not e-mailed: {error}")) .fetch_optional(db) .await?; match issued { Some((number,)) => { tracing::warn!(invoice = %due.id, number = ?number, %error, "invoice issued but not e-mailed") } None => { tracing::error!(invoice = %due.id, %error, "invoice failed; an admin has to look at it"); sqlx::query("UPDATE invoices SET status = 'failed', last_error = $2 WHERE id = $1") .bind(due.id) .bind(&error) .execute(db) .await?; } } done += 1; } Err(Failure::Billingo(error)) => { let wait = backoff(due.attempts); tracing::warn!(invoice = %due.id, %error, retry_in = ?wait, "invoice not issued yet"); sqlx::query( "UPDATE invoices SET last_error = $2, next_attempt_at = now() + make_interval(secs => $3) \ WHERE id = $1", ) .bind(due.id) .bind(&error) .bind(wait.as_secs_f64()) .execute(db) .await?; } } } } enum Failure { Billingo(String), Db(sqlx::Error), } impl From for Failure { fn from(e: sqlx::Error) -> Self { Failure::Db(e) } } impl From for Failure { fn from(e: String) -> Self { Failure::Billingo(e) } } impl From<&str> for Failure { fn from(e: &str) -> Self { Failure::Billingo(e.to_owned()) } } /// Partner, invoice, e-mail: whatever is still missing. Returns the number. async fn issue(db: &PgPool, billingo: &Billingo, due: &Due) -> Result { use reqwest::Method; let partner = match due.billingo_partner_id { Some(id) => id, None => { let body = json!({ "name": due.buyer_name, "address": { "country_code": due.buyer_country, "post_code": due.buyer_post_code, "city": due.buyer_city, "address": due.buyer_address, }, "emails": due.buyer_email.iter().collect::>(), // Without a tax type number (a Hungarian company with only an // EU VAT number) the number goes into the invoice's comment. "taxcode": if due.buyer_tax_type == "NO_TAX_NUMBER" { String::new() } else { due.buyer_tax_number.clone().unwrap_or_default() }, "tax_type": due.buyer_tax_type, }); let partner = billingo.call(Method::POST, "/partners", Some(&body)).await?; let id = partner["id"].as_i64().ok_or("Billingo partner without id")?; sqlx::query("UPDATE invoices SET billingo_partner_id = $2 WHERE id = $1") .bind(due.id) .bind(id) .execute(db) .await?; id } }; let document = match due.billingo_document_id { Some(id) => id, None => { let day = hungarian_date(due.paid_at).to_string(); let body = json!({ "partner_id": partner, "block_id": billingo.block().await?, "type": "invoice", "fulfillment_date": day, "due_date": day, "payment_method": due.payment_method, "language": "hu", "currency": "HUF", "electronic": true, "paid": true, "items": [{ "name": due.item_name, "unit_price": due.gross_huf, "unit_price_type": "gross", "quantity": 1, "unit": due.item_unit, "vat": due.vat_rate, "comment": due.item_comment.clone().unwrap_or_default(), }], "comment": document_comment(due), }); // An earlier attempt asked already: its invoice may exist although // the answer never came. The partner is this invoice's own, so any // invoice of it is ours. let earlier = match due.document_requested_at { Some(_) => find_document(billingo, partner).await?, None => None, }; let doc = match earlier { Some(doc) => { tracing::warn!(invoice = %due.id, number = ?doc["invoice_number"], "found the invoice of an earlier attempt"); doc } None => { sqlx::query("UPDATE invoices SET document_requested_at = now() WHERE id = $1") .bind(due.id) .execute(db) .await?; billingo.call(Method::POST, "/documents", Some(&body)).await? } }; let id = doc["id"].as_i64().ok_or("Billingo invoice without id")?; let item = &doc["items"][0]; sqlx::query( "UPDATE invoices SET billingo_document_id = $2, invoice_number = $3, invoice_date = $4, \ fulfillment_date = $5, due_date = $6, document = $7, \ net_huf = coalesce($8, net_huf), vat_huf = coalesce($9, vat_huf) WHERE id = $1", ) .bind(due.id) .bind(id) .bind(doc["invoice_number"].as_str()) .bind(date(&doc["invoice_date"])) .bind(date(&doc["fulfillment_date"])) .bind(date(&doc["due_date"])) .bind(&doc) .bind(item["net_amount"].as_f64().map(|n| n.round() as i32)) .bind(item["vat_amount"].as_f64().map(|n| n.round() as i32)) .execute(db) .await?; id } }; if due.sent_at.is_none() && let Some(email) = &due.buyer_email { let body = json!({ "emails": [email] }); billingo.call(Method::POST, &format!("/documents/{document}/send"), Some(&body)).await?; sqlx::query("UPDATE invoices SET sent_at = now() WHERE id = $1").bind(due.id).execute(db).await?; } let (number,): (Option,) = sqlx::query_as( "UPDATE invoices SET status = 'issued', issued_at = now(), last_error = NULL WHERE id = $1 \ RETURNING invoice_number", ) .bind(due.id) .fetch_one(db) .await?; Ok(number.unwrap_or_default()) } /// The invoice's comment: how it was paid, the VAT exemption, and a /// Hungarian company's EU VAT number when it gave no domestic one. fn document_comment(due: &Due) -> String { let mut comment = String::from("Bankkártyával kifizetve (Stripe)."); if due.vat_rate == "AAM" { comment.push_str(" Alanyi adómentes."); } if due.buyer_tax_type == "NO_TAX_NUMBER" && let Some(eu) = &due.buyer_tax_number { comment.push_str(&format!(" A vevő közösségi adószáma: {eu}.")); } comment } /// The invoice already issued to `partner`, if any (an error is a failed /// attempt: an invoice is never made without knowing there is none). async fn find_document(billingo: &Billingo, partner: i64) -> Result, Failure> { let list = billingo .call(reqwest::Method::GET, &format!("/documents?partner_id={partner}&type=invoice&per_page=10"), None) .await?; let items = list["data"].as_array().or_else(|| list.as_array()).ok_or("Billingo document list without data")?; Ok(items .iter() .find(|d| d["id"].as_i64().is_some() && d["partner"]["id"].as_i64().is_none_or(|p| p == partner)) .cloned()) } pub async fn run(db: PgPool, billingo: Billingo, max_attempts: i32, interval: Duration, stop: watch::Receiver) { loop { if let Err(e) = run_once(&db, &billingo, max_attempts).await { tracing::error!(error = %e, "invoices"); } tokio::select! { () = tokio::time::sleep(interval) => {} () = crate::stopped(stop.clone()) => break, } } } #[cfg(test)] mod tests { use std::sync::Arc; use std::sync::atomic::{AtomicUsize, Ordering}; use super::*; use axum::extract::{Path, State}; use axum::http::StatusCode; use axum::routing::{get, post}; use axum::{Json, Router}; fn at(s: &str) -> OffsetDateTime { OffsetDateTime::parse(s, &time::format_description::well_known::Rfc3339).unwrap() } #[test] fn fulfilment_dates_are_hungarian() { // 23:30 UTC is already the next day in Budapest, in winter and summer. assert_eq!(hungarian_date(at("2026-11-20T23:30:00Z")).to_string(), "2026-11-21"); assert_eq!(hungarian_date(at("2026-11-20T22:59:00Z")).to_string(), "2026-11-20"); assert_eq!(hungarian_date(at("2026-07-01T22:30:00Z")).to_string(), "2026-07-02"); assert_eq!(hungarian_date(at("2026-07-01T21:59:00Z")).to_string(), "2026-07-01"); assert_eq!(date(&json!("2026-11-21T00:00:00+01:00")).unwrap().to_string(), "2026-11-21"); } #[derive(Default)] struct Fake { requests: std::sync::Mutex>, documents: AtomicUsize, /// Sending fails this many times first. send_failures: AtomicUsize, /// Partners are refused (a permanent error). refuse_partners: std::sync::atomic::AtomicBool, /// The next invoice is made, but its answer is lost (an error instead). lose_document_answer: std::sync::atomic::AtomicBool, /// The invoices made so far, for the list. made: std::sync::Mutex>, } async fn fake_billingo(fake: Arc) -> String { async fn blocks(State(f): State>) -> Json { f.requests.lock().unwrap().push(("blocks".into(), Value::Null)); Json(json!({"data": [{"id": 5, "name": "Számlák", "type": "invoice"}], "total": 1})) } async fn partner(State(f): State>, Json(body): Json) -> (StatusCode, Json) { f.requests.lock().unwrap().push(("partner".into(), body.clone())); if f.refuse_partners.load(Ordering::SeqCst) { return (StatusCode::UNPROCESSABLE_ENTITY, Json(json!({"message": "invalid tax code"}))); } (StatusCode::CREATED, Json(json!({"id": 42, "name": body["name"]}))) } async fn document(State(f): State>, Json(body): Json) -> (StatusCode, Json) { f.requests.lock().unwrap().push(("document".into(), body.clone())); let n = f.documents.fetch_add(1, Ordering::SeqCst) + 1; let doc = json!({"id": 900 + n, "invoice_number": format!("SF-2026-{n}"), "invoice_date": "2026-11-20", "fulfillment_date": body["fulfillment_date"], "due_date": body["due_date"], "gross_total": 6000.0, "partner": {"id": body["partner_id"]}, "items": [{"name": "x", "net_amount": 6000.0, "vat_amount": 0.0, "gross_amount": 6000.0}]}); f.made.lock().unwrap().push(doc.clone()); if f.lose_document_answer.swap(false, Ordering::SeqCst) { return (StatusCode::GATEWAY_TIMEOUT, Json(json!({"error": "timeout"}))); } (StatusCode::CREATED, Json(doc)) } async fn documents( State(f): State>, axum::extract::Query(q): axum::extract::Query>, ) -> Json { f.requests.lock().unwrap().push(("list".into(), json!(q))); let partner: i64 = q.get("partner_id").and_then(|p| p.parse().ok()).unwrap_or(-1); let data: Vec = f.made.lock().unwrap().iter().filter(|d| d["partner"]["id"] == partner).cloned().collect(); Json(json!({"data": data, "total": data.len()})) } async fn send( State(f): State>, Path(id): Path, Json(body): Json, ) -> (StatusCode, Json) { f.requests.lock().unwrap().push((format!("send {id}"), body.clone())); if f.send_failures.load(Ordering::SeqCst) > 0 { f.send_failures.fetch_sub(1, Ordering::SeqCst); return (StatusCode::INTERNAL_SERVER_ERROR, Json(json!({"error": "mail down"}))); } (StatusCode::OK, Json(body)) } let app = Router::new() .route("/document-blocks", get(blocks)) .route("/partners", post(partner)) .route("/documents", post(document).get(documents)) .route("/documents/{id}/send", post(send)) .with_state(fake); let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); let addr = listener.local_addr().unwrap(); tokio::spawn(async move { axum::serve(listener, app).await.unwrap() }); format!("http://{addr}") } async fn paid(db: &PgPool, tax: Option<&str>) -> Uuid { let checkout = format!("cs_{}", Uuid::now_v7()); sqlx::query( "INSERT INTO stripe_checkouts (id, package, price_huf, live, completed_at) \ VALUES ($1, 'couple', 6000, false, '2026-11-20T23:30:00Z')", ) .bind(&checkout) .execute(db) .await .unwrap(); let id = Uuid::now_v7(); sqlx::query( "INSERT INTO invoices (id, checkout_id, buyer_name, buyer_email, buyer_country, buyer_post_code, \ buyer_city, buyer_address, buyer_tax_type, buyer_tax_number, item_name, gross_huf, net_huf, vat_huf) \ VALUES ($1, $2, 'Csillag Kft.', 'anna@example.com', 'HU', '6720', 'Szeged', 'Fő utca 1.', $3, $4, \ 'Online tartalomszolgáltatás – Páros csomag', 6000, 6000, 0)", ) .bind(id) .bind(&checkout) .bind(if tax.is_some() { "HAS_TAX_NUMBER" } else { "NO_TAX_NUMBER" }) .bind(tax) .execute(db) .await .unwrap(); id } async fn state(db: &PgPool, id: Uuid) -> (String, Option, Option, bool, i32) { sqlx::query_as( "SELECT status, invoice_number, billingo_document_id, sent_at IS NOT NULL, attempts FROM invoices \ WHERE id = $1", ) .bind(id) .fetch_one(db) .await .unwrap() } #[sqlx::test(migrator = "db::MIGRATOR")] async fn invoices_are_issued_and_sent_once(db: PgPool) { let fake = Arc::new(Fake::default()); let billingo = Billingo::new(&fake_billingo(fake.clone()).await, "key", None); let id = paid(&db, Some("12345678-1-23")).await; fake.send_failures.store(1, Ordering::SeqCst); // The invoice is made, but the e-mail fails: it is retried later. assert_eq!(run_once(&db, &billingo, 5).await.unwrap(), 0); let (status, number, document, sent, attempts) = state(&db, id).await; assert_eq!( (status.as_str(), number.as_deref(), document, sent, attempts), ("pending", Some("SF-2026-1"), Some(901), false, 1) ); { let requests = fake.requests.lock().unwrap(); let partner = &requests.iter().find(|(k, _)| k == "partner").unwrap().1; assert_eq!(partner["taxcode"], "12345678-1-23"); assert_eq!(partner["tax_type"], "HAS_TAX_NUMBER"); assert_eq!(partner["address"]["post_code"], "6720"); let doc = &requests.iter().find(|(k, _)| k == "document").unwrap().1; assert_eq!((&doc["partner_id"], &doc["block_id"]), (&json!(42), &json!(5))); assert_eq!( (&doc["paid"], &doc["payment_method"], &doc["currency"]), (&json!(true), &json!("online_bankcard"), &json!("HUF")) ); assert_eq!(doc["items"][0]["unit_price"], 6000); assert_eq!( (&doc["items"][0]["name"], &doc["items"][0]["unit"]), (&json!("Online tartalomszolgáltatás – Páros csomag"), &json!("csomag")) ); assert_eq!( (&doc["items"][0]["unit_price_type"], &doc["items"][0]["vat"]), (&json!("gross"), &json!("AAM")) ); // Paid at 00:30 in Budapest. assert_eq!(doc["fulfillment_date"], "2026-11-21"); } // Not before its time. assert_eq!(run_once(&db, &billingo, 5).await.unwrap(), 0); sqlx::query("UPDATE invoices SET next_attempt_at = now()").execute(&db).await.unwrap(); assert_eq!(run_once(&db, &billingo, 5).await.unwrap(), 1); let (status, _, _, sent, _) = state(&db, id).await; assert_eq!((status.as_str(), sent), ("issued", true)); // One partner and one invoice, even with the retry. assert_eq!(fake.documents.load(Ordering::SeqCst), 1); let (net, vat, kept): (i32, i32, Value) = sqlx::query_as("SELECT net_huf, vat_huf, document FROM invoices WHERE id = $1") .bind(id) .fetch_one(&db) .await .unwrap(); assert_eq!((net, vat, &kept["invoice_number"]), (6000, 0, &json!("SF-2026-1"))); assert_eq!(run_once(&db, &billingo, 5).await.unwrap(), 0); } #[sqlx::test(migrator = "db::MIGRATOR")] async fn invoices_fail_after_the_last_attempt(db: PgPool) { let fake = Arc::new(Fake::default()); fake.refuse_partners.store(true, Ordering::SeqCst); let billingo = Billingo::new(&fake_billingo(fake.clone()).await, "key", Some(7)); let id = paid(&db, None).await; run_once(&db, &billingo, 2).await.unwrap(); sqlx::query("UPDATE invoices SET next_attempt_at = now()").execute(&db).await.unwrap(); assert_eq!(run_once(&db, &billingo, 2).await.unwrap(), 1); let (status, ..) = state(&db, id).await; assert_eq!(status, "failed"); let (error,): (String,) = sqlx::query_as("SELECT last_error FROM invoices WHERE id = $1").bind(id).fetch_one(&db).await.unwrap(); assert!(error.contains("422") && error.contains("invalid tax code"), "{error}"); assert_eq!(fake.documents.load(Ordering::SeqCst), 0); } #[sqlx::test(migrator = "db::MIGRATOR")] async fn a_lost_answer_does_not_make_a_second_invoice(db: PgPool) { let fake = Arc::new(Fake::default()); fake.lose_document_answer.store(true, Ordering::SeqCst); let billingo = Billingo::new(&fake_billingo(fake.clone()).await, "key", Some(7)); let id = paid(&db, None).await; // Billingo makes the invoice, but its answer is lost. assert_eq!(run_once(&db, &billingo, 5).await.unwrap(), 0); assert_eq!(state(&db, id).await.2, None); // The retry finds it instead of making another. sqlx::query("UPDATE invoices SET next_attempt_at = now()").execute(&db).await.unwrap(); assert_eq!(run_once(&db, &billingo, 5).await.unwrap(), 1); let (status, number, document, sent, _) = state(&db, id).await; assert_eq!( (status.as_str(), number.as_deref(), document, sent), ("issued", Some("SF-2026-1"), Some(901), true) ); assert_eq!(fake.documents.load(Ordering::SeqCst), 1); } #[sqlx::test(migrator = "db::MIGRATOR")] async fn an_invoice_that_cannot_be_emailed_still_counts_as_issued(db: PgPool) { let fake = Arc::new(Fake::default()); fake.send_failures.store(100, Ordering::SeqCst); let billingo = Billingo::new(&fake_billingo(fake.clone()).await, "key", Some(7)); let id = paid(&db, None).await; run_once(&db, &billingo, 2).await.unwrap(); sqlx::query("UPDATE invoices SET next_attempt_at = now()").execute(&db).await.unwrap(); assert_eq!(run_once(&db, &billingo, 2).await.unwrap(), 1); let (status, number, _, sent, _) = state(&db, id).await; assert_eq!((status.as_str(), number.as_deref(), sent), ("issued", Some("SF-2026-1"), false)); let (error,): (String,) = sqlx::query_as("SELECT last_error FROM invoices WHERE id = $1").bind(id).fetch_one(&db).await.unwrap(); assert!(error.starts_with("issued, not e-mailed"), "{error}"); } }