E8-F5: E-Racuni Integration¶

Epic: E8: Payment Processing

Size: M (Medium)

Problem / Outcome¶

Integrate with Croatian e-invoicing system (e-racuni).

Scope¶

In-Scope:

API integration for payment offers
API integration for invoices
API integration for credit notes
Fiscalization support
Status polling
Configuration via environment variables

Out-of-Scope:

Bank reconciliation automation

Configuration¶

E-Racuni credentials provided via environment variables: - ERACUNI_USERNAME - ERACUNI_PW - ERACUNI_TOKEN

Test credentials available for development/staging environments.

Acceptance Criteria¶

AC1: Payment offer creation via API returns e-racuni reference
AC2: Invoice issuance via API after payment received
AC3: Credit note creation via API for refunds

Data Model Impact¶

ERacuniDocument table:
- id (UUID, PK)
- document_type (ENUM: payment_offer, invoice, credit_note)
- local_reference_id (UUID) - Order/Refund ID
- e_racuni_id (VARCHAR)
- e_racuni_number (VARCHAR)
- fiscalization_id (VARCHAR, nullable)
- status (ENUM: draft, sent, fiscalized, cancelled)
- created_at (TIMESTAMP)
- fiscalized_at (TIMESTAMP)

ERacuniApiLog table:
- id (UUID, PK)
- document_id (UUID, FK)
- request_type (VARCHAR)
- request_json (JSONB)
- response_json (JSONB)
- http_status (INTEGER)
- created_at (TIMESTAMP)

Permissions/Roles¶

System (API calls)

How to Verify¶

npm test -- --grep "e-racuni"

Expected: API calls succeed, documents created in e-racuni.

Dependencies¶

None (external service)

Implementation Tasks¶

See E8: Payment Processing Tasks

Doc References¶

Last Updated: January 2026