From f509c21d9f9b50568c72480d7de1581910f2f588 Mon Sep 17 00:00:00 2001
From: admin <admin@byolivia.work>
Date: Wed, 8 Apr 2026 14:30:54 +0200
Subject: [PATCH] docs: add README with API usage and structure

---
 README.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 167 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b11f69c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,167 @@
+# VeriFactu Middle API
+
+API intermediaria para el protocolo VeriFactu de la AEAT.
+
+---
+
+## Instalación
+
+```bash
+go build .
+```
+
+---
+
+## Configuración
+
+Editar `config.yml` para configurar el servidor y VeriFactu.
+
+---
+
+## Autenticación
+
+### 1. Obtener clave pública
+
+**GET /api/v1/auth/public-key**
+
+Devuelve la clave pública RSA para cifrar la contraseña del certificado.
+
+### 2. Registrar certificado
+
+**POST /api/v1/auth/register**
+
+```json
+{
+  "cert_name": "mi-certificado",
+  "cert_path": "archivo.p12",
+  "password_encrypted": "BASE64_RSA_ENCRYPTED_PASSWORD"
+}
+```
+
+Respuesta:
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+}
+```
+
+### 3. Usar token
+
+En todas las peticiones siguientes:
+```
+Authorization: Bearer <token>
+```
+
+---
+
+## Estructura de datos
+
+### Enviar factura (POST /api/v1/facturas)
+
+```json
+{
+  "tipo": "alta",
+  "factura": {
+    "emisor_nif": "A12345678",
+    "num_serie": "2024-001",
+    "fecha_expedicion": "13-09-2024",
+    "tipo_factura": "F1",
+    "descripcion": "Descripción",
+    "destinatario": {
+      "nombre": "CLIENTE SL",
+      "nif": "B98765432"
+    },
+    "iva": [
+      {"base": 100.00, "cuota": 21.00, "tipo": 21.00}
+    ],
+    "importe_total": 121.00
+  },
+  "sistema": {
+    "nombre": "Software",
+    "nif_proveedor": "A12345678",
+    "version": "1.0.0"
+  }
+}
+```
+
+### Anular factura (POST /api/v1/facturas/anular)
+
+```json
+{
+  "factura": {
+    "emisor_nif": "A12345678",
+    "num_serie": "2024-001",
+    "fecha_expedicion": "13-09-2024"
+  },
+  "sistema": {
+    "nombre": "Software",
+    "nif_proveedor": "A12345678",
+    "version": "1.0.0"
+  }
+}
+```
+
+---
+
+## Campos obligatorios
+
+| Campo | Tipo | Descripción |
+|-------|------|-------------|
+| `tipo` | string | `alta` o `anulacion` |
+| `emisor_nif` | string | NIF emisor (9 caracteres) |
+| `num_serie` | string | Número de serie |
+| `fecha_expedicion` | string | Fecha (`dd-mm-yyyy`) |
+| `tipo_factura` | string | `F1`, `F2`, `R1`-`R5` |
+| `iva[]` | array | Al menos un registro |
+| `importe_total` | number | > 0 |
+| `sistema.*` | object | Datos del software |
+
+---
+
+## Respuestas
+
+### Éxito
+
+```json
+{
+  "success": true,
+  "csv": "ABC123...",
+  "estado": "Correcto"
+}
+```
+
+### Error de validación
+
+```json
+{
+  "success": false,
+  "error": "validation_failed",
+  "details": [{"field": "emisor_nif", "message": "invalid NIF format"}]
+}
+```
+
+### Error AEAT
+
+```json
+{
+  "success": false,
+  "error": "aeat_error",
+  "codigo": "1000",
+  "mensaje": "Descripción"
+}
+```
+
+Ver `ERRORES.md` para códigos de error completos.
+
+---
+
+## Límites
+
+-Máximo 1.000 registros por solicitud (actualmente 1)
+- Entorno actual: pruebas (sandbox)
+
+---
+
+## Documentación
+
+Ver `Documentacion de Verifactu/` para el protocolo completo.