144 lines
2.7 KiB
Markdown
144 lines
2.7 KiB
Markdown
|
# Prerequisites
|
||
|
|
|
||
|
|
## System Requirements
|
||
|
|
|
||
|
|
### Go
|
||
|
|
|
||
|
|
- **Version:** 1.26 or higher
|
||
|
|
- **Download:** https://go.dev/dl/
|
||
|
|
- **Verify installation:**
|
||
|
|
```bash
|
||
|
|
go version
|
||
|
|
```
|
||
|
|
|
||
|
|
No se requieren Python, OpenSSL ni scripts externos. Todo el procesamiento de certificados (.p12/.pfx) es nativo en Go.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Project Setup
|
||
|
|
|
||
|
|
### 1. Clone the repository
|
||
|
|
|
||
|
|
```bash
|
||
|
|
git clone <repository-url>
|
||
|
|
cd VerifactuMidAPI
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. Install Go dependencies
|
||
|
|
|
||
|
|
```bash
|
||
|
|
go mod download
|
||
|
|
```
|
||
|
|
|
||
|
|
### 3. Create required directories
|
||
|
|
|
||
|
|
```bash
|
||
|
|
mkdir -p data/certs data keys
|
||
|
|
```
|
||
|
|
|
||
|
|
| Directory | Purpose |
|
||
|
|
|---|---|
|
||
|
|
| `data/certs/` | Stored `.p12` certificates |
|
||
|
|
| `data/` | Hash chain records (JSON files per emitter) |
|
||
|
|
| `keys/` | Auto-generated RSA key pair for password encryption |
|
||
|
|
|
||
|
|
### 4. Configure the application
|
||
|
|
|
||
|
|
Copy or edit `config.yml`:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
server:
|
||
|
|
port: 6789
|
||
|
|
|
||
|
|
verifactu:
|
||
|
|
production: false
|
||
|
|
|
||
|
|
certificates:
|
||
|
|
storage_path: ./data/certs/
|
||
|
|
cert_file: ./data/certs/personal.p12
|
||
|
|
cert_password: YOUR_PASSWORD
|
||
|
|
|
||
|
|
crypto:
|
||
|
|
keys_path: ./keys/
|
||
|
|
name: "VeriFactu API"
|
||
|
|
email: "admin@example.com"
|
||
|
|
```
|
||
|
|
|
||
|
|
> **Important:** Change `cert_password` and `email` to your own values.
|
||
|
|
|
||
|
|
### 5. Obtain a digital certificate
|
||
|
|
|
||
|
|
VeriFactu requires a **qualified electronic certificate** (eIDAS compliant) in `.p12` or `.pfx` format.
|
||
|
|
|
||
|
|
- **FNMT Persona Fisica** (free): https://www.fnmt.es
|
||
|
|
- Must be valid and registered with AEAT for the testing environment
|
||
|
|
- Place it at `./data/certs/personal.p12` (or update `cert_file` in config)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Build & Run
|
||
|
|
|
||
|
|
### Development (auto-reload with source)
|
||
|
|
|
||
|
|
```bash
|
||
|
|
go run .
|
||
|
|
```
|
||
|
|
|
||
|
|
### Production build
|
||
|
|
|
||
|
|
```bash
|
||
|
|
go build -o verifactu-api .
|
||
|
|
./verifactu-api
|
||
|
|
```
|
||
|
|
|
||
|
|
The server starts on `http://localhost:6789` (or the port configured in `config.yml`).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Verify the installation
|
||
|
|
|
||
|
|
### 1. Health check
|
||
|
|
|
||
|
|
```bash
|
||
|
|
curl http://localhost:6789/api/v1/health
|
||
|
|
# Expected: {"status":"ok"}
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. Get public key
|
||
|
|
|
||
|
|
```bash
|
||
|
|
curl http://localhost:6789/api/v1/auth/public-key
|
||
|
|
# Expected: {"public_key":"<base64>"}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Troubleshooting
|
||
|
|
|
||
|
|
### `go: command not found`
|
||
|
|
|
||
|
|
Go is not installed or not in your `PATH`. Add it:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Linux/macOS
|
||
|
|
export PATH=$PATH:/usr/local/go/bin
|
||
|
|
|
||
|
|
# Windows: add C:\Program Files\Go\bin to system PATH
|
||
|
|
```
|
||
|
|
|
||
|
|
### `config.yml not found`
|
||
|
|
|
||
|
|
The API falls back to defaults but logs a warning. Create the file as described in step 4.
|
||
|
|
|
||
|
|
### `certificate expired` / `invalid_password_or_format`
|
||
|
|
|
||
|
|
- Verify the certificate dates with:
|
||
|
|
```bash
|
||
|
|
openssl pkcs12 -in ./data/certs/personal.p12 -info -nokeys
|
||
|
|
```
|
||
|
|
- Ensure the password in `config.yml` matches the certificate.
|
||
|
|
|
||
|
|
### `403 Forbidden` from AEAT
|
||
|
|
|
||
|
|
The certificate is not authorized in the AEAT testing environment. Contact AEAT or verify your FNMT certificate is enabled for VeriFactu.
|