{
 "openapi": "3.1.0",
 "info": {
  "title": "einvoicewiz e-invoice API",
  "version": "1.0.0",
  "description": "Generate and validate EN 16931 e-invoices (Factur-X / ZUGFeRD 2.x PDF/A-3, XRechnung 3.0) for the German and French mandates. Deterministic pipeline (no AI), Mustang rule engine, failed validations are never charged. Every passing file gets a permanent verification certificate. 20 free credits on signup, then €9 / 500 credits.",
  "contact": {
   "email": "support@einvoicewiz.com"
  },
  "termsOfService": "https://einvoicewiz.com/terms"
 },
 "servers": [
  {
   "url": "https://einvoicewiz.com"
  }
 ],
 "components": {
  "securitySchemes": {
   "ApiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   }
  },
  "schemas": {
   "Invoice": {
    "type": "object",
    "required": [
     "invoice_number",
     "issue_date",
     "currency",
     "seller",
     "buyer",
     "lines"
    ],
    "properties": {
     "doc_type": {
      "type": "integer",
      "enum": [
       380,
       381,
       384
      ],
      "default": 380,
      "description": "380 invoice, 381 credit note, 384 correction"
     },
     "invoice_number": {
      "type": "string"
     },
     "issue_date": {
      "type": "string",
      "format": "date"
     },
     "due_date": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "delivery_date": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "currency": {
      "type": "string",
      "example": "EUR"
     },
     "buyer_reference": {
      "type": [
       "string",
       "null"
      ],
      "description": "Leitweg-ID (BT-10). Required for XRechnung."
     },
     "order_reference": {
      "type": [
       "string",
       "null"
      ]
     },
     "seller": {
      "type": "object",
      "required": [
       "name",
       "country"
      ],
      "properties": {
       "name": {
        "type": "string"
       },
       "line_one": {
        "type": "string"
       },
       "postcode": {
        "type": "string"
       },
       "city": {
        "type": "string"
       },
       "country": {
        "type": "string"
       },
       "vat_id": {
        "type": "string"
       },
       "tax_number": {
        "type": "string"
       },
       "contact_email": {
        "type": "string"
       },
       "contact_phone": {
        "type": "string"
       },
       "email": {
        "type": "string"
       }
      }
     },
     "buyer": {
      "type": "object",
      "required": [
       "name",
       "country"
      ],
      "properties": {
       "name": {
        "type": "string"
       },
       "line_one": {
        "type": "string"
       },
       "postcode": {
        "type": "string"
       },
       "city": {
        "type": "string"
       },
       "country": {
        "type": "string"
       },
       "vat_id": {
        "type": "string"
       },
       "email": {
        "type": "string"
       }
      }
     },
     "payment": {
      "type": "object",
      "properties": {
       "iban": {
        "type": "string"
       },
       "bic": {
        "type": "string"
       },
       "terms": {
        "type": "string"
       }
      }
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "prepaid": {
      "type": "number",
      "default": 0
     },
     "exemption_reason": {
      "type": [
       "string",
       "null"
      ]
     },
     "lines": {
      "type": "array",
      "minItems": 1,
      "items": {
       "type": "object",
       "required": [
        "name",
        "qty",
        "unit_price",
        "vat_rate"
       ],
       "properties": {
        "name": {
         "type": "string"
        },
        "description": {
         "type": "string"
        },
        "qty": {
         "type": "number"
        },
        "unit": {
         "type": "string",
         "enum": [
          "piece",
          "hour",
          "day",
          "kg",
          "litre",
          "month",
          "km",
          "lump",
          "m2",
          "m"
         ],
         "default": "piece"
        },
        "unit_price": {
         "type": "number"
        },
        "vat_rate": {
         "type": "number"
        },
        "vat_category": {
         "type": "string",
         "enum": [
          "S",
          "Z",
          "E",
          "AE",
          "K",
          "G",
          "O"
         ]
        }
       }
      }
     }
    }
   },
   "Verify": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string",
      "example": "EIW-3F9A1C2B7D0E"
     },
     "url": {
      "type": "string",
      "format": "uri"
     }
    }
   },
   "Certificate": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "url": {
      "type": "string"
     },
     "issued": {
      "type": "string"
     },
     "kind": {
      "type": "string",
      "enum": [
       "generated",
       "validated"
      ]
     },
     "profile": {
      "type": "string"
     },
     "status": {
      "type": "string"
     },
     "errors": {
      "type": "integer"
     },
     "warnings": {
      "type": "integer"
     },
     "warning_messages": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "files": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "description": "filename → SHA-256"
     },
     "engine": {
      "type": "string"
     },
     "statement": {
      "type": "string"
     }
    }
   }
  }
 },
 "paths": {
  "/v1/signup": {
   "post": {
    "summary": "Create an API key with 20 free credits",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "email"
        ],
        "properties": {
         "email": {
          "type": "string",
          "format": "email"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "API key (shown once)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "api_key": {
           "type": "string"
          },
          "credits": {
           "type": "integer"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/v1/me": {
   "get": {
    "summary": "Credits remaining and calls used",
    "security": [
     {
      "ApiKey": []
     }
    ],
    "responses": {
     "200": {
      "description": "OK"
     }
    }
   }
  },
  "/v1/generate": {
   "post": {
    "summary": "Invoice JSON → validated EN 16931 CII XML (1 credit)",
    "security": [
     {
      "ApiKey": []
     }
    ],
    "parameters": [
     {
      "name": "profile",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "en16931",
        "xrechnung"
       ],
       "default": "en16931"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/Invoice"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Validated XML + certificate",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "xml": {
           "type": "string"
          },
          "profile": {
           "type": "string"
          },
          "validation": {
           "type": "object"
          },
          "verify": {
           "$ref": "#/components/schemas/Verify"
          },
          "credits_left": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "422": {
      "description": "Generated XML failed validation — not charged; body lists violated rules"
     },
     "402": {
      "description": "Out of credits"
     }
    }
   }
  },
  "/v1/facturx": {
   "post": {
    "summary": "Your PDF + invoice JSON → Factur-X / ZUGFeRD PDF/A-3 (1 credit)",
    "security": [
     {
      "ApiKey": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "required": [
         "pdf",
         "invoice"
        ],
        "properties": {
         "pdf": {
          "type": "string",
          "format": "binary"
         },
         "invoice": {
          "type": "string",
          "description": "Invoice JSON as a string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "PDF/A-3 binary. Headers X-Cert-Id and X-Verify-URL carry the certificate.",
      "content": {
       "application/pdf": {}
      }
     },
     "422": {
      "description": "Validation or embedding failed — not charged"
     }
    }
   }
  },
  "/v1/validate": {
   "post": {
    "summary": "Raw PDF or XML body → EN 16931 + KOSIT + PDF/A rule-level report (1 credit)",
    "security": [
     {
      "ApiKey": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/pdf": {},
      "application/xml": {}
     }
    },
    "responses": {
     "200": {
      "description": "Report; verify is set when the file passed",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "result": {
           "type": "object"
          },
          "verify": {
           "$ref": "#/components/schemas/Verify"
          },
          "credits_left": {
           "type": "integer"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/verify/{id}": {
   "get": {
    "summary": "Look up a verification certificate (free)",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Certificate",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "cert": {
           "$ref": "#/components/schemas/Certificate"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Unknown ID"
     }
    }
   }
  },
  "/api/verify": {
   "post": {
    "summary": "Upload a file → certificates whose recorded SHA-256 matches it (free)",
    "requestBody": {
     "required": true,
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "properties": {
         "file": {
          "type": "string",
          "format": "binary"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Match result",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "sha256": {
           "type": "string"
          },
          "matched": {
           "type": "boolean"
          },
          "certificates": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Certificate"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  }
 }
}