HTTP service that reads and decodes QR codes from Portuguese fiscal documents (PDFs), returning structured JSON with issuer tax IDs, buyer information, document types, VAT lines, and totals.
No PDF files are stored on the server — files are written to temporary OS storage, processed, and immediately deleted.
Live Prodution
Try it online — no account needed:
Features
- PDF upload via HTTP multipart
- QR code detection across all pages
- ATCUD validation per AT specification
- Raw scan endpoint (
/scan) and structured parse endpoint (/parse) - Embedded Portuguese web interface
- Interactive OpenAPI 3.1 / Swagger documentation
- Docker and Portainer ready
API Endpoints
| Endpoint | Description |
|---|---|
POST /api/v1/document/scan | Raw QR code content |
POST /api/v1/document/parse | Structured fiscal data |
GET /api/v1/version | Service metadata |
GET /health | Health check |
GET /docs | Swagger documentation |
Tech Stack
- Go
- Gin (HTTP framework)
- Huma v2 (OpenAPI/Swagger)
- gozxing (QR detection)
- poppler-utils / pdftoppm (PDF rendering)
- HTML + Tailwind CSS + Vanilla JS (frontend)
- Docker / Docker Compose
Architecture
Follows a simplified Domain-Driven Design with separate layers for configuration, domain entities, application services, infrastructure adapters, HTTP interfaces, and embedded UI.
Author
Ricardo Grangeia
Senior Software Engineer
Portugal
Website
https://ricardo.grangeia.pt
Project Github
https://github.com/ricgrangeia/atcud-pdf-qr-code-reader
License
MIT License