{
  "info": {
    "name": "VeriFactu SaaS API v1",
    "description": "API REST para la plataforma VeriFactu SaaS de ALMC.es.\n\nPermite integrar facturacion electronica conforme al sistema VeriFactu de la AEAT.\n\nAutenticacion: Cabecera X-Api-Key con formato key.secret",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "_exporter_id": "verifactu-almc"
  },
  "variable": [
    {
      "key": "api_url",
      "value": "https://almc.es/api/verifactu/v1",
      "type": "string"
    },
    {
      "key": "api_key",
      "value": "vf_sb_xxxxxx.sk_yyyyyyyyyyyyyyyy",
      "type": "string"
    }
  ],
  "auth": {
    "type": "apikey",
    "apikey": [
      {
        "key": "key",
        "value": "X-Api-Key",
        "type": "string"
      },
      {
        "key": "value",
        "value": "{{api_key}}",
        "type": "string"
      },
      {
        "key": "in",
        "value": "header",
        "type": "string"
      }
    ]
  },
  "item": [
    {
      "name": "Health",
      "item": [
        {
          "name": "Health Check",
          "request": {
            "auth": { "type": "noauth" },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/health",
              "host": ["{{api_url}}"],
              "path": ["health"]
            },
            "description": "Verificar estado del servicio. No requiere autenticacion."
          },
          "response": [
            {
              "name": "Healthy",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"status\": \"healthy\",\n  \"checks\": {\n    \"database\": \"ok\",\n    \"redis\": \"ok\",\n    \"queue\": \"ok\",\n    \"aeat_sandbox\": \"ok\",\n    \"aeat_production\": \"ok\"\n  },\n  \"timestamp\": \"2026-04-06T10:30:00+02:00\"\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "Auth",
      "item": [
        {
          "name": "Register",
          "request": {
            "auth": { "type": "noauth" },
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"company_name\": \"Mi Empresa S.L.\",\n  \"nif\": \"B12345678\",\n  \"email\": \"admin@miempresa.es\",\n  \"password\": \"MiPassword123!\",\n  \"phone\": \"+34 612 345 678\",\n  \"address\": \"Calle Gran Via 1, 28001 Madrid\"\n}"
            },
            "url": {
              "raw": "{{api_url}}/auth/register",
              "host": ["{{api_url}}"],
              "path": ["auth", "register"]
            },
            "description": "Registrar nuevo tenant. Devuelve datos del tenant y primera clave API."
          },
          "response": [
            {
              "name": "Created",
              "status": "Created",
              "code": 201,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"success\": true,\n  \"data\": {\n    \"tenant\": {\n      \"uuid\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n      \"company_name\": \"Mi Empresa S.L.\",\n      \"email\": \"admin@miempresa.es\",\n      \"status\": \"trial\",\n      \"trial_ends_at\": \"2026-04-20T00:00:00+02:00\",\n      \"plan\": \"free\"\n    },\n    \"api_key\": {\n      \"key\": \"vf_sb_a1b2c3d4e5f6\",\n      \"secret\": \"sk_1234567890abcdef1234567890abcdef\",\n      \"name\": \"Default Sandbox Key\",\n      \"prefix\": \"vf_sb_a1b2\",\n      \"environment\": \"sandbox\",\n      \"note\": \"Store these credentials securely. The secret will not be shown again.\"\n    }\n  },\n  \"meta\": {\n    \"request_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"timestamp\": \"2026-04-06T10:30:00+02:00\",\n    \"version\": \"1.0\"\n  }\n}"
            }
          ]
        },
        {
          "name": "Login",
          "request": {
            "auth": { "type": "noauth" },
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"admin@miempresa.es\",\n  \"password\": \"MiPassword123!\"\n}"
            },
            "url": {
              "raw": "{{api_url}}/auth/login",
              "host": ["{{api_url}}"],
              "path": ["auth", "login"]
            },
            "description": "Autenticar tenant con email y contrasena."
          },
          "response": [
            {
              "name": "Success",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"success\": true,\n  \"data\": {\n    \"tenant\": {\n      \"uuid\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n      \"company_name\": \"Mi Empresa S.L.\",\n      \"email\": \"admin@miempresa.es\",\n      \"status\": \"active\",\n      \"plan\": \"professional\"\n    }\n  },\n  \"meta\": {\n    \"request_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"timestamp\": \"2026-04-06T10:30:00+02:00\",\n    \"version\": \"1.0\"\n  }\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "API Keys",
      "item": [
        {
          "name": "List API Keys",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/auth/api-keys",
              "host": ["{{api_url}}"],
              "path": ["auth", "api-keys"]
            },
            "description": "Listar todas las claves API activas del tenant."
          },
          "response": []
        },
        {
          "name": "Create API Key",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Backend Production\",\n  \"environment\": \"production\",\n  \"scopes\": [\"invoices:write\", \"invoices:read\"],\n  \"ip_whitelist\": [\"203.0.113.10\"]\n}"
            },
            "url": {
              "raw": "{{api_url}}/auth/api-keys",
              "host": ["{{api_url}}"],
              "path": ["auth", "api-keys"]
            },
            "description": "Crear nueva clave API. El secreto solo se muestra una vez."
          },
          "response": []
        },
        {
          "name": "Revoke API Key",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{api_url}}/auth/api-keys/1",
              "host": ["{{api_url}}"],
              "path": ["auth", "api-keys", "1"]
            },
            "description": "Revocar una clave API. Deja de funcionar inmediatamente."
          },
          "response": []
        },
        {
          "name": "Rotate API Key",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{api_url}}/auth/api-keys/1/rotate",
              "host": ["{{api_url}}"],
              "path": ["auth", "api-keys", "1", "rotate"]
            },
            "description": "Rotar clave API. Revoca la actual y genera una nueva con los mismos permisos."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Settings",
      "item": [
        {
          "name": "Get Settings",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/settings",
              "host": ["{{api_url}}"],
              "path": ["settings"]
            },
            "description": "Obtener configuracion actual del tenant."
          },
          "response": []
        },
        {
          "name": "Update Settings",
          "request": {
            "method": "PUT",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"environment\": \"production\",\n  \"certificate_id\": 1,\n  \"auto_submit\": true,\n  \"webhook_url\": \"https://miapp.com/webhooks/verifactu\",\n  \"webhook_events\": [\"invoice.accepted\", \"invoice.rejected\"]\n}"
            },
            "url": {
              "raw": "{{api_url}}/settings",
              "host": ["{{api_url}}"],
              "path": ["settings"]
            },
            "description": "Actualizar configuracion. Solo se modifican los campos enviados."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Certificates",
      "item": [
        {
          "name": "List Certificates",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/certificates",
              "host": ["{{api_url}}"],
              "path": ["certificates"]
            },
            "description": "Listar todos los certificados digitales del tenant."
          },
          "response": []
        },
        {
          "name": "Upload Certificate",
          "request": {
            "method": "POST",
            "header": [],
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "name",
                  "value": "Certificado FNMT 2026",
                  "type": "text"
                },
                {
                  "key": "file",
                  "type": "file",
                  "src": "",
                  "description": "Archivo .pfx o .p12 (max 10 MB)"
                },
                {
                  "key": "password",
                  "value": "",
                  "type": "text",
                  "description": "Contrasena del certificado"
                }
              ]
            },
            "url": {
              "raw": "{{api_url}}/certificates",
              "host": ["{{api_url}}"],
              "path": ["certificates"]
            },
            "description": "Subir certificado digital (.pfx/.p12). Se cifra en reposo."
          },
          "response": []
        },
        {
          "name": "Get Certificate",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/certificates/1",
              "host": ["{{api_url}}"],
              "path": ["certificates", "1"]
            },
            "description": "Obtener detalles de un certificado."
          },
          "response": []
        },
        {
          "name": "Delete Certificate",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{api_url}}/certificates/1",
              "host": ["{{api_url}}"],
              "path": ["certificates", "1"]
            },
            "description": "Eliminar certificado y archivo cifrado."
          },
          "response": []
        },
        {
          "name": "Validate Certificate",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{api_url}}/certificates/1/validate",
              "host": ["{{api_url}}"],
              "path": ["certificates", "1", "validate"]
            },
            "description": "Validar que el certificado es legible y no esta corrupto."
          },
          "response": []
        },
        {
          "name": "Certificate Expiry",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/certificates/1/expiry",
              "host": ["{{api_url}}"],
              "path": ["certificates", "1", "expiry"]
            },
            "description": "Consultar fechas de validez y expiracion del certificado."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Series",
      "item": [
        {
          "name": "List Series",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/series",
              "host": ["{{api_url}}"],
              "path": ["series"]
            },
            "description": "Listar todas las series de facturacion."
          },
          "response": []
        },
        {
          "name": "Create Series",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"code\": \"F-2026\",\n  \"description\": \"Facturas ordinarias 2026\"\n}"
            },
            "url": {
              "raw": "{{api_url}}/series",
              "host": ["{{api_url}}"],
              "path": ["series"]
            },
            "description": "Crear nueva serie de facturacion."
          },
          "response": []
        },
        {
          "name": "Update Series",
          "request": {
            "method": "PUT",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"description\": \"Facturas ordinarias 2026 (actualizada)\",\n  \"is_active\": true\n}"
            },
            "url": {
              "raw": "{{api_url}}/series/1",
              "host": ["{{api_url}}"],
              "path": ["series", "1"]
            },
            "description": "Actualizar descripcion o estado de una serie."
          },
          "response": []
        },
        {
          "name": "Delete Series",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{api_url}}/series/1",
              "host": ["{{api_url}}"],
              "path": ["series", "1"]
            },
            "description": "Eliminar serie (solo si no tiene facturas)."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Invoices",
      "item": [
        {
          "name": "List Invoices",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/invoices?status=&from=&to=&external_id=&per_page=25",
              "host": ["{{api_url}}"],
              "path": ["invoices"],
              "query": [
                { "key": "status", "value": "", "description": "Filtrar por estado: draft, queued, submitted, accepted, rejected, cancelled, error" },
                { "key": "from", "value": "", "description": "Fecha desde (YYYY-MM-DD)" },
                { "key": "to", "value": "", "description": "Fecha hasta (YYYY-MM-DD)" },
                { "key": "external_id", "value": "", "description": "ID externo" },
                { "key": "per_page", "value": "25", "description": "Resultados por pagina (1-100)" }
              ]
            },
            "description": "Listar facturas con filtros y paginacion."
          },
          "response": []
        },
        {
          "name": "Create Invoice",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"series_code\": \"F-2026\",\n  \"issue_date\": \"2026-04-06\",\n  \"invoice_type\": \"F1\",\n  \"description\": \"Servicios de consultoria marzo 2026\",\n  \"recipient_name\": \"Cliente Ejemplo S.L.\",\n  \"recipient_nif\": \"B98765432\",\n  \"recipient_country\": \"ES\",\n  \"external_id\": \"ERP-2026-001\",\n  \"items\": [\n    {\n      \"description\": \"Consultoria estrategica\",\n      \"quantity\": 10,\n      \"unit_price\": 80.00,\n      \"tax_rate\": 21.0\n    },\n    {\n      \"description\": \"Desarrollo web\",\n      \"quantity\": 20,\n      \"unit_price\": 65.00,\n      \"tax_rate\": 21.0\n    }\n  ],\n  \"auto_submit\": false,\n  \"metadata\": {\n    \"erp_id\": \"INV-2026-001\"\n  }\n}"
            },
            "url": {
              "raw": "{{api_url}}/invoices",
              "host": ["{{api_url}}"],
              "path": ["invoices"]
            },
            "description": "Crear nueva factura. Se asigna numero automaticamente de la serie."
          },
          "response": []
        },
        {
          "name": "Get Invoice",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
              "host": ["{{api_url}}"],
              "path": ["invoices", "a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
            },
            "description": "Obtener detalle completo de una factura."
          },
          "response": []
        },
        {
          "name": "Update Invoice",
          "request": {
            "method": "PUT",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"description\": \"Servicios actualizados\",\n  \"items\": [\n    {\n      \"description\": \"Consultoria estrategica (revisada)\",\n      \"quantity\": 12,\n      \"unit_price\": 85.00,\n      \"tax_rate\": 21.0\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{api_url}}/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
              "host": ["{{api_url}}"],
              "path": ["invoices", "a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
            },
            "description": "Actualizar factura en estado draft. Los items se reemplazan completamente."
          },
          "response": []
        },
        {
          "name": "Delete Invoice",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{api_url}}/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
              "host": ["{{api_url}}"],
              "path": ["invoices", "a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
            },
            "description": "Eliminar factura (solo en estado draft)."
          },
          "response": []
        },
        {
          "name": "Submit Invoice to AEAT",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{api_url}}/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/submit",
              "host": ["{{api_url}}"],
              "path": ["invoices", "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "submit"]
            },
            "description": "Enviar factura a la AEAT. Operacion asincrona, devuelve job_id."
          },
          "response": []
        },
        {
          "name": "Cancel Invoice",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{api_url}}/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel",
              "host": ["{{api_url}}"],
              "path": ["invoices", "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "cancel"]
            },
            "description": "Anular factura (solo accepted/submitted)."
          },
          "response": []
        },
        {
          "name": "Query Invoice in AEAT",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{api_url}}/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/query",
              "host": ["{{api_url}}"],
              "path": ["invoices", "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "query"]
            },
            "description": "Consultar estado de factura en la AEAT."
          },
          "response": []
        },
        {
          "name": "Rectify Rejected Invoice",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{api_url}}/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/rectify",
              "host": ["{{api_url}}"],
              "path": ["invoices", "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "rectify"]
            },
            "description": "Rectificar factura rechazada (solo status rejected)."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Jobs",
      "item": [
        {
          "name": "Get Job Status",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/jobs/b2c3d4e5-f6a7-8901-bcde-f12345678901",
              "host": ["{{api_url}}"],
              "path": ["jobs", "b2c3d4e5-f6a7-8901-bcde-f12345678901"]
            },
            "description": "Consultar estado de un trabajo asincrono (submit, cancel, query, rectify)."
          },
          "response": [
            {
              "name": "Completed",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"success\": true,\n  \"data\": {\n    \"job_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"type\": \"submit\",\n    \"status\": \"completed\",\n    \"attempts\": 1,\n    \"result\": {\n      \"csv\": \"1234\",\n      \"estado\": \"Correcto\"\n    },\n    \"invoice_uuid\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"started_at\": \"2026-04-06T10:30:01+02:00\",\n    \"completed_at\": \"2026-04-06T10:30:03+02:00\",\n    \"created_at\": \"2026-04-06T10:30:00+02:00\"\n  },\n  \"meta\": {\n    \"request_id\": \"c3d4e5f6-a7b8-9012-cdef-123456789012\",\n    \"timestamp\": \"2026-04-06T10:30:05+02:00\",\n    \"version\": \"1.0\"\n  }\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "Usage",
      "item": [
        {
          "name": "Current Usage",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/usage",
              "host": ["{{api_url}}"],
              "path": ["usage"]
            },
            "description": "Consumo del periodo actual y limites del plan."
          },
          "response": []
        },
        {
          "name": "Usage History",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/usage/history?months=12",
              "host": ["{{api_url}}"],
              "path": ["usage", "history"],
              "query": [
                { "key": "months", "value": "12", "description": "Meses a consultar (1-24, default 12)" }
              ]
            },
            "description": "Historial de consumo mensual."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Events",
      "item": [
        {
          "name": "List Events",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/events?type=&severity=&invoice_uuid=&per_page=50",
              "host": ["{{api_url}}"],
              "path": ["events"],
              "query": [
                { "key": "type", "value": "", "description": "Tipo de evento (ej: invoice.submitted)" },
                { "key": "severity", "value": "", "description": "Severidad: info, warning, error, critical" },
                { "key": "invoice_uuid", "value": "", "description": "UUID de factura" },
                { "key": "per_page", "value": "50", "description": "Resultados por pagina (1-100)" }
              ]
            },
            "description": "Listar eventos con filtros y paginacion."
          },
          "response": []
        },
        {
          "name": "Get Event Detail",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{api_url}}/events/1",
              "host": ["{{api_url}}"],
              "path": ["events", "1"]
            },
            "description": "Obtener detalle completo de un evento, incluyendo payload."
          },
          "response": []
        }
      ]
    }
  ]
}