API Guide

skeemrr exposes a REST API for programmatic e-invoice validation.

Base URL: https://api.skeemrr.skeeterlab.com
During development, the API endpoint may differ. Check your deployment for the current URL.

Download OpenAPI Spec — Import into Postman, Swagger UI, or use for SDK generation.

Authentication

The /validate and /validate-batch endpoints accept two authentication methods:

Option 1: API Key (recommended for scripts and integrations)

Generate an API key from the API Keys page, then include it in the X-API-Key header:

X-API-Key: skmr_your_key_here

Option 2: JWT Bearer Token

Authenticate via Cognito and include the JWT in the Authorization header:

Authorization: Bearer <your-jwt-token>

The /health and /analytics endpoints are public and do not require authentication.

POST /validate

Validates an e-invoice XML payload against Schematron business rules. Supports FatturaPA, UBL, CII, and SBDH-wrapped invoices.

Request

curl -X POST https://api.skeemrr.skeeterlab.com/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: skmr_your_key_here" \
  -d '{"payload": "<p:FatturaElettronica ...>...</p:FatturaElettronica>"}'

Response (valid)

{
  "validationId": "a1b2c3d4-...",
  "valid": true,
  "format": "peppol-bis3-ubl-invoice",
  "formatDisplayName": "PEPPOL BIS 3.0 (UBL Invoice)",
  "invoiceType": "380",
  "rulesetVersion": "v3.0",
  "errors": 0,
  "warnings": 0,
  "successes": 160,
  "results": [
    { "severity": "success", "ruleId": "BR-01", "location": "/...", "message": "..." },
    ...
  ]
}

Response (invalid)

{
  "validationId": "a1b2c3d4-...",
  "valid": false,
  "format": "fatturapa-fpr12",
  "formatDisplayName": "FatturaPA (FPR12)",
  "invoiceType": "FPR12",
  "rulesetVersion": "v1.9",
  "errors": 2,
  "warnings": 0,
  "successes": 25,
  "results": [
    { "severity": "error", "ruleId": "SDI-00400", "location": "/...", "message": "[00400] Natura is required when AliquotaIVA is 0.00" },
    { "severity": "success", "ruleId": "SDI-00311", "location": "/...", "message": "..." },
    ...
  ]
}

TypeScript Interface

interface ValidationResult {
  validationId: string;
  valid: boolean;
  format: string;
  formatDisplayName: string;
  invoiceType: string;
  rulesetVersion: string;
  errors: number;
  warnings: number;
  successes: number;
  skipped: SkippedRule[];
  results: ValidationError[];
}

interface ValidationError {
  severity: 'error' | 'warning' | 'success';
  ruleId: string;
  location: string;
  message: string;
}

POST /validate-batch

Validates up to 20 invoices in a single request.

Request

curl -X POST https://api.skeemrr.skeeterlab.com/validate-batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: skmr_your_key_here" \
  -d '{"payloads": ["<Invoice>...</Invoice>", "<Invoice>...</Invoice>"]}'

Response

{
  "results": [
    { "validationId": "...", "valid": true, ... },
    { "validationId": "...", "valid": false, ... }
  ]
}

GET /analytics

Returns anonymized aggregate validation statistics for the last 90 days. Public — no authentication required.

curl https://api.skeemrr.skeeterlab.com/analytics

{
  "period": "90d",
  "totalValidations": 1234,
  "formatBreakdown": { "fatturapa-fpr12": 500, "peppol-bis3-ubl-invoice": 300, ... },
  "passRate": { "total": 1234, "passed": 800, "failed": 434, "rate": 65 },
  "topErrors": [
    { "ruleId": "SDI-00400", "count": 120 },
    { "ruleId": "BR-DE-1", "count": 85 },
    ...
  ]
}

API Key Management

Manage API keys via the Settings page in the UI, or programmatically:

POST /api-keys

Create a new API key (requires JWT auth). Max 3 keys per user.

curl -X POST https://api.skeemrr.skeeterlab.com/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -d '{"label": "CI/CD pipeline"}'

{
  "keyId": "a1b2c3d4-...",
  "key": "skmr_abc123...",
  "label": "CI/CD pipeline",
  "prefix": "skmr_abc1",
  "createdAt": "2026-04-06T12:00:00Z",
  "message": "Save this key — it will not be shown again."
}

GET /api-keys

List your API keys (requires JWT auth). Keys are shown as prefixes only.

DELETE /api-keys/:id

Revoke an API key (requires JWT auth).

GET /health

Public endpoint. Returns service status and supported formats.

curl https://api.skeemrr.skeeterlab.com/health

Error Codes

Authentication errors return HTTP 401 with the message: "Authentication required. Use Authorization: Bearer <jwt> or X-API-Key: <key>"