Durable invoice delivery
Why processing is durable
An idle Cloud Run container can stop receiving CPU, and an instance can be replaced. Work therefore must not depend on an in-memory list, a file cache in a temporary container, or a thread continuing after its HTTP response.
Spring persists delivery handoffs in its business database. Laravel persists accepted batches, invoice checkpoints, email work, and template snapshots in its configured delivery database.
Handoff sequence
Spring outbox
Records move through PENDING, SENDING, FAILED, and SUBMITTED. Dispatch claims a database lease and uses the outbox UUID as the idempotency key.
SUBMITTED means accepted by Laravel. It is not a receipt from Telegram or SMTP. Retry unsubmitted handoffs with:
POST /invoice/batch/retry-deliveries?limit=25
The accepted limit is 1–100. This can hand off real delivery work; use it as an operator action.
Shared authentication
Configure the same PRINT_WORKER_TOKEN in Spring and Laravel. Spring sends X-Print-Worker-Token, leaving Authorization available for Cloud Run IAM where required.
A token header authenticates these worker calls. It does not secure every browser/template/generation route by itself; retain the appropriate upstream access controls.
Laravel processing
An asynchronous batch submission is:
POST /generate/batch-invoice?async=1
Idempotency-Key: a-stable-uuid-for-this-payload
X-Print-Worker-Token: <configured shared token>
Content-Type: application/json
[ { "INVOICE_NO": "SAMPLE-INVOICE", "invoiceItems": [] } ]
Replaying the same key/payload returns the same logical batch. A different payload with the same key conflicts.
A processing request handles up to five units with a 45-second budget checked between units. An in-flight network operation may exceed that budget up to its configured timeout. Batch leases prevent concurrent workers from claiming the same live work.
Use POST /generate/batches/process-pending or the scheduled print:process-pending --limit=3 command. On Cloud Run, use persistent external database storage and an HTTP scheduler. On cPanel, the shared SQLite file can be persistent and cron can invoke Laravel's scheduler.
Retry versus review
- Rendering/configuration failures can be retried through the batch retry endpoint.
- Confirmed sends are not automatically repeated.
- Unknown irreversible-send outcomes become
needs_review.
Inspect the batch's review entries, then explicitly resolve one:
POST /generate/batches/BATCH-ID/resolve-delivery
X-Print-Worker-Token: <configured shared token>
Content-Type: application/json
{ "kind": "email", "recordId": "RECORD-ID", "action": "sent" }
Use action: "retry" only when another send is intended. kind can be email or telegram.