{
 "openapi": "3.1.0",
 "info": {
  "title": "pdfvera API",
  "version": "1.0.0",
  "description": "Convert PDF invoices to XRechnung (UBL, CII) and ZUGFeRD (EN 16931), checked against the KoSIT rules, and Brazilian bank statement PDFs to OFX, CSV and Excel with the balance reconciled. Included in every pdfvera subscription; each converted document counts once against the monthly quota (the same PDF again in the same month does not count). mode=preview never counts. Create API keys in your account: https://pdfvera.com/de/konto/ or https://pdfvera.com/pt-br/conta/. Docs: https://pdfvera.com/de/e-rechnung-api/ (German), https://pdfvera.com/pt-br/api-extrato-bancario/ (Portuguese).",
  "contact": {
   "email": "kontakt@pdfvera.com",
   "url": "https://pdfvera.com/"
  }
 },
 "servers": [
  {
   "url": "https://pdfvera.com"
  }
 ],
 "security": [
  {
   "bearer": []
  }
 ],
 "paths": {
  "/api/v1/de/convert": {
   "post": {
    "operationId": "convertInvoice",
    "summary": "PDF invoice to XRechnung and ZUGFeRD",
    "description": "Reads the invoice, recalculates the totals and builds XRechnung 3.0 (UBL and CII), a ZUGFeRD PDF/A-3 (EN 16931) and a check report. XRechnung files are only delivered when they pass the KoSIT rules; the ZUGFeRD PDF is added only when it also passes the Mustang validator. If mandatory data is missing, deliverable is false and questions lists the fields this invoice needs (missing: true = still open); send the same PDF again with the values in form. Correct a value read from the PDF with the key from found[].edit[].key (e.g. fix:number). The PDF is processed in the EU and not stored. A rejected correction is reported in fix_errors. If the invoice cannot be converted with more data (e.g. totals do not match), questions is empty and reasons explains why.",
    "requestBody": {
     "required": true,
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "required": [
         "pdf"
        ],
        "properties": {
         "pdf": {
          "type": "string",
          "format": "binary",
          "description": "PDF invoice, max 20 MB, 30 pages, 10 scanned pages"
         },
         "form": {
          "type": "string",
          "description": "JSON object: answers to questions (key = questions[].field) and corrections (key = fix:<field>). Example: {\"buyer_reference\":\"04011000-12345-06\",\"buyer.email\":\"rechnung@kunde.de\"}"
         },
         "mode": {
          "type": "string",
          "enum": [
           "full",
           "preview"
          ],
          "default": "full",
          "description": "preview: check only, no files, not counted"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Result; with mode=preview no files are built. Check deliverable.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "deliverable": {
           "type": "boolean"
          },
          "outputs": {
           "type": "object",
           "additionalProperties": {
            "type": "string",
            "format": "byte"
           },
           "description": "File name -> Base64 content. Only when the document was converted and mode is not preview."
          },
          "questions": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "field": {
              "type": "string"
             },
             "type": {
              "type": "string"
             },
             "bt": {
              "type": "string"
             },
             "label": {
              "type": "object"
             },
             "help": {
              "type": "object"
             },
             "why": {
              "type": "string"
             },
             "example": {
              "type": "string"
             },
             "value": {
              "type": "string"
             },
             "missing": {
              "type": "boolean"
             },
             "error": {
              "type": "string"
             },
             "escape": {
              "type": "object",
              "properties": {
               "label": {
                "type": "string"
               },
               "value": {
                "type": "string"
               }
              }
             }
            }
           }
          },
          "found": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "field": {
              "type": "string"
             },
             "label": {
              "type": "string"
             },
             "value": {
              "type": "string"
             },
             "corrected": {
              "type": "boolean"
             },
             "edit": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "key": {
                 "type": "string"
                },
                "label": {
                 "type": "string"
                },
                "type": {
                 "type": "string"
                },
                "value": {
                 "type": "string"
                }
               }
              }
             }
            }
           }
          },
          "invoice": {
           "type": "object",
           "properties": {
            "number": {
             "type": "string"
            },
            "issue_date": {
             "type": "string"
            },
            "seller": {
             "type": "string"
            },
            "buyer": {
             "type": "string"
            },
            "net": {
             "type": "string"
            },
            "tax": {
             "type": "string"
            },
            "gross": {
             "type": "string"
            },
            "payable": {
             "type": "string"
            },
            "currency": {
             "type": "string"
            }
           }
          },
          "reasons": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Rule codes not yet met, e.g. kosit:BR-DE-15"
          },
          "report_html": {
           "type": "string"
          },
          "pages": {
           "type": "integer"
          },
          "ocr_pages": {
           "type": "integer"
          },
          "sha256": {
           "type": "string"
          },
          "used": {
           "type": "integer"
          },
          "quota": {
           "type": "integer"
          },
          "fix_errors": {
           "type": "object",
           "description": "Correction key -> reason it was rejected"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "API key missing, wrong or revoked (error: key)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "402": {
      "description": "No active subscription (error: subscription) or monthly quota used up (error: quota)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "413": {
      "description": "PDF larger than 20 MB (error: size)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "415": {
      "description": "Not a PDF (error: type)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "Too many pages or scanned pages (error: pages, scanned, pagesize)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit: 20/minute, 120/hour, 1000/day per account (error: rate, scope)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "Converter busy (error: busy) or temporarily unavailable (error: unavailable); retry later",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "400": {
      "description": "form is not a JSON object or longer than 4096 characters (error: form)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "5XX": {
      "description": "Conversion failed (error: failed); retry later",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/br/convert": {
   "post": {
    "operationId": "convertStatement",
    "summary": "Bank statement PDF to OFX, CSV and Excel",
    "description": "Reads a Brazilian bank statement, sums the entries and checks them against the printed balances. Files are only delivered when the balance reconciles. One set of files per account for multi-account PDFs; with profile dominio the OFX is split into files of at most 12 months. The PDF is not stored by pdfvera, also when the conversion fails. Statements the rules cannot read are sent to the Anthropic API to read the entries (deleted by Anthropic within 30 days, not used for training).",
    "requestBody": {
     "required": true,
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "required": [
         "pdf"
        ],
        "properties": {
         "pdf": {
          "type": "string",
          "format": "binary",
          "description": "Statement PDF, max 20 MB, 300 pages, 40 scanned pages"
         },
         "profile": {
          "type": "string",
          "enum": [
           "dominio",
           "alterdata",
           "contaazul",
           "omie"
          ],
          "default": "dominio",
          "description": "Accounting system the OFX is made for"
         },
         "password": {
          "type": "string",
          "description": "PDF password"
         },
         "cpf": {
          "type": "string",
          "description": "Account holder CPF, to try the banks' usual passwords"
         },
         "mode": {
          "type": "string",
          "enum": [
           "full",
           "preview"
          ],
          "default": "full"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Result; with mode=preview no files are built. Check ok.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "bank": {
           "type": "string"
          },
          "cause": {
           "type": [
            "string",
            "null"
           ],
           "description": "Why ok is false, e.g. password"
          },
          "error": {
           "type": [
            "string",
            "null"
           ]
          },
          "reconciliation": {
           "type": [
            "object",
            "null"
           ],
           "properties": {
            "ok": {
             "type": "boolean"
            },
            "opening": {
             "type": "string"
            },
            "closing": {
             "type": "string"
            },
            "computed_closing": {
             "type": "string"
            },
            "lines_checked": {
             "type": "integer"
            },
            "errors": {
             "type": "array"
            }
           }
          },
          "transactions": {
           "type": "integer"
          },
          "accounts": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "account": {
              "type": "string"
             },
             "ok": {
              "type": "boolean"
             },
             "cause": {
              "type": [
               "string",
               "null"
              ]
             },
             "pages": {
              "type": "array"
             },
             "transactions": {
              "type": "integer"
             },
             "opening": {
              "type": "string"
             },
             "closing": {
              "type": "string"
             }
            }
           }
          },
          "sample": {
           "type": "array",
           "description": "First five entries"
          },
          "outputs": {
           "type": "object",
           "additionalProperties": {
            "type": "string",
            "format": "byte"
           },
           "description": "File name -> Base64 content. Only when the document was converted and mode is not preview."
          },
          "pages": {
           "type": "integer"
          },
          "ocr_pages": {
           "type": "integer"
          },
          "sha256": {
           "type": "string"
          },
          "used": {
           "type": "integer"
          },
          "quota": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "API key missing, wrong or revoked (error: key)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "402": {
      "description": "No active subscription (error: subscription) or monthly quota used up (error: quota)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "413": {
      "description": "PDF larger than 20 MB (error: size)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "415": {
      "description": "Not a PDF (error: type)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "Too many pages or scanned pages (error: pages, scanned, pagesize)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit: 20/minute, 120/hour, 1000/day per account (error: rate, scope)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "Converter busy (error: busy) or temporarily unavailable (error: unavailable); retry later",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "400": {
      "description": "Unknown profile (error: profile)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "5XX": {
      "description": "Conversion failed (error: failed); retry later",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/usage": {
   "get": {
    "operationId": "usage",
    "summary": "Plan and monthly quota",
    "responses": {
     "200": {
      "description": "plan is null without an active subscription",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "plan": {
           "type": [
            "string",
            "null"
           ]
          },
          "used": {
           "type": "integer"
          },
          "quota": {
           "type": "integer"
          },
          "period_start": {
           "type": "integer"
          },
          "resets": {
           "type": "integer",
           "description": "Unix time the quota renews"
          },
          "cancel_at_period_end": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "API key missing, wrong or revoked (error: key)",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "description": "API key pv_… from your pdfvera account"
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "string",
      "description": "key, subscription, quota, size, type, pages, scanned, pagesize, rate, busy, unavailable, failed, form, profile"
     },
     "used": {
      "type": "integer"
     },
     "quota": {
      "type": "integer"
     },
     "scope": {
      "type": "string",
      "enum": [
       "minute",
       "hour",
       "day"
      ]
     }
    }
   }
  }
 }
}