Invoices: issued in Billingo by the worker, downloadable on Számláim
CI / test (push) Successful in 1m29s
CI / build (push) Successful in 9m7s
CI / deploy (push) Skipped

A paid checkout queues an invoice row with every invoice detail (buyer,
tax type and number, item, net, VAT, gross). The worker's new 'invoices'
task creates the Billingo partner and the paid card invoice and e-mails
it (API v3), saving each step so a retry never issues a second invoice,
and keeps Billingo's whole answer; the PDF is fetched from Billingo when
the user downloads it from the new Számláim page (in the menu once there
is an invoice). Payments and invoices outlive a deleted account.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vLHzh5qUhFtmJhzkcTbXL
This commit is contained in:
feco
2026-11-20 07:52:34 +00:00
co-authored by Claude Opus 5.5
parent e530e78c54
commit 2a0830fda0
24 changed files with 1090 additions and 35 deletions
+489
View File
@@ -0,0 +1,489 @@
//! 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 and never issues a
//! second invoice. 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<Option<i64>>,
}
impl Billingo {
pub fn new(base: &str, key: &str, block: Option<i64>) -> 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<Value, String> {
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::<String>()));
}
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<i64, String> {
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<String>,
buyer_country: String,
buyer_post_code: String,
buyer_city: String,
buyer_address: String,
buyer_tax_type: String,
buyer_tax_number: Option<String>,
item_name: String,
gross_huf: i32,
vat_rate: String,
payment_method: String,
billingo_partner_id: Option<i64>,
billingo_document_id: Option<i64>,
sent_at: Option<OffsetDateTime>,
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<Date> {
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::<u8>().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<usize, sqlx::Error> {
let mut done = 0;
loop {
let due: Option<Due> = 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.gross_huf, \
i.vat_rate, i.payment_method, i.billingo_partner_id, i.billingo_document_id, 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 => {
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<sqlx::Error> for Failure {
fn from(e: sqlx::Error) -> Self {
Failure::Db(e)
}
}
impl From<String> 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<String, Failure> {
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::<Vec<_>>(),
"taxcode": 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": "db",
"vat": due.vat_rate,
}],
"comment": "Bankkártyával kifizetve (Stripe).",
});
let doc = 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<String>,) = 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())
}
pub async fn run(db: PgPool, billingo: Billingo, max_attempts: i32, interval: Duration, stop: watch::Receiver<bool>) {
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<Vec<(String, Value)>>,
documents: AtomicUsize,
/// Sending fails this many times first.
send_failures: AtomicUsize,
/// Partners are refused (a permanent error).
refuse_partners: std::sync::atomic::AtomicBool,
}
async fn fake_billingo(fake: Arc<Fake>) -> String {
async fn blocks(State(f): State<Arc<Fake>>) -> Json<Value> {
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<Arc<Fake>>, Json(body): Json<Value>) -> (StatusCode, Json<Value>) {
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<Arc<Fake>>, Json(body): Json<Value>) -> (StatusCode, Json<Value>) {
f.requests.lock().unwrap().push(("document".into(), body.clone()));
let n = f.documents.fetch_add(1, Ordering::SeqCst) + 1;
(
StatusCode::CREATED,
Json(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,
"items": [{"name": "x", "net_amount": 4724.41, "vat_amount": 1275.59, "gross_amount": 6000.0}]})),
)
}
async fn send(
State(f): State<Arc<Fake>>,
Path(id): Path<i64>,
Json(body): Json<Value>,
) -> (StatusCode, Json<Value>) {
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))
.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, \
'Sorsfonalak – Páros', 6000, 4724, 1276)",
)
.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<String>, Option<i64>, 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]["unit_price_type"], &doc["items"][0]["vat"]),
(&json!("gross"), &json!("27%"))
);
// 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"]), (4724, 1276, &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);
}
}