# Vantane — Full API Reference

Agent-native e-invoicing. Create a compliant Peppol BIS 3.0 UBL invoice from canonical JSON, or validate one for free. This is the public sandbox: delivery is always simulated and anonymous invoices are purged after 24h.

Base URL: https://vantane.com
OpenAPI: https://vantane.com/v1/openapi.json  (version 0.1.0)
Auth: Bearer API key. Public sandbox key: vantane_sandbox_public (IP rate-limited 60/min).
pricing: sandbox=free; validate=free; production=EUR/delivered-invoice, first 25/calendar-month free, then 0.10 (26-1000), 0.06 (1001-10000), 0.03 (10001+); settle=card-threshold(EUR10 or month-end) OR prepaid-credits(non-expiring)

## Endpoints

### POST /v1/invoices  (createInvoice)
Create (and optionally simulate delivery of) a compliant invoice.
Auth: Bearer API key required
Parameters:
  - Idempotency-Key (header): Replays return the original invoice instead of creating a new one.
Request body (application/json): CreateInvoiceRequest
Responses:
  - 200: Idempotent replay of a prior create. -> InvoiceEnvelope
  - 201: Invoice created. -> InvoiceEnvelope
  - 400: Malformed request. -> ErrorResponse
  - 401: Missing or invalid API key. -> ErrorResponse
  - 402: Prepaid balance exhausted; the error llmFix carries the top-up action. -> ErrorResponse
  - 429: Public sandbox rate limit exceeded. -> ErrorResponse

### GET /v1/invoices/{id}  (getInvoice)
Fetch a previously created invoice and its status history.
Auth: Bearer API key required
Parameters:
  - id (path, required): 
Responses:
  - 200: The invoice envelope. -> InvoiceEnvelope
  - 401: Missing or invalid API key. -> ErrorResponse
  - 404: No such invoice. -> ErrorResponse

### GET /v1/invoices/{id}/document.xml  (getInvoiceDocument)
Fetch the generated UBL XML document.
Auth: Bearer API key required
Parameters:
  - id (path, required): 
Responses:
  - 200: The UBL XML.
  - 401: Missing or invalid API key. -> ErrorResponse
  - 404: No document for this invoice. -> ErrorResponse

### GET /v1/invoices/{id}/preview.png  (getInvoicePreview)
Render a PNG preview of the invoice so an agent can visually inspect it.
Rendered by a headless-Chromium sidecar and cached per page. Use ?page=N for multi-page invoices.
Auth: Bearer API key required
Parameters:
  - id (path, required): 
  - page (query): The 1-based page to render for multi-page invoices.
Responses:
  - 200: The rendered PNG.
  - 400: Page out of range. -> ErrorResponse
  - 401: Missing or invalid API key. -> ErrorResponse
  - 404: No such invoice, or no document to preview. -> ErrorResponse
  - 502: The rendering sidecar failed. -> ErrorResponse
  - 503: Preview rendering is not configured. -> ErrorResponse

### GET /v1/capabilities  (getCapabilities)
The current country/format/channel routing matrix. Free, no auth.
Declarative, versioned routing rules with effective dates so agents can discover what Vantane supports (and which mandates are upcoming). Pass ?asOf=YYYY-MM-DD to preview a future date.
Auth: none
Parameters:
  - asOf (query): ISO date (YYYY-MM-DD) to evaluate the matrix as-of. Defaults to today.
Responses:
  - 200: The routing capabilities matrix. -> Capabilities
  - 400: Malformed asOf date. -> ErrorResponse

### GET /v1/billing  (getBilling)
Account balance and this month usage.
Auth: Bearer API key required
Responses:
  - 200: Billing summary. -> BillingSummary
  - 401: Missing or invalid API key. -> ErrorResponse

### POST /v1/billing/topup  (startTopup)
Start a Stripe Checkout for prepaid credit (€10/25/50/100). Credit never expires.
Auth: Bearer API key required
Responses:
  - 200: Checkout session created. -> TopupResult
  - 400: Invalid top-up amount. -> ErrorResponse
  - 401: Missing or invalid API key. -> ErrorResponse
  - 503: Stripe is not configured on this deployment. -> ErrorResponse

### POST /v1/webhooks/stripe  (ingestStripeWebhook)
Ingest Stripe events (signature-verified). Checkout completion credits the ledger.
Unauthenticated; verified via the Stripe-Signature header against STRIPE_WEBHOOK_SECRET.
Auth: none
Responses:
  - 200: Event processed. -> WebhookResult
  - 400: Missing/invalid signature or body. -> ErrorResponse
  - 503: Stripe is not configured. -> ErrorResponse

### POST /v1/webhooks/delivery/{provider}  (ingestDeliveryWebhook)
Ingest a delivery-status webhook from a delivery provider.
Unauthenticated by design: providers cannot carry Vantane API keys. The {provider} path segment selects the parser that maps the native payload into our canonical status model. Unknown providers 404; unparseable or unmatched payloads are accepted as a no-op so providers do not hammer retries.
Auth: none
Parameters:
  - provider (path, required): The registered provider name whose payload shape to parse.
Responses:
  - 200: The webhook batch was ingested. -> WebhookResult
  - 404: No delivery provider by that name is registered. -> ErrorResponse

### POST /v1/validate  (validateInvoice)
Validate canonical invoice JSON. Free, stateless, no auth.
Auth: none
Request body (application/json): Invoice
Responses:
  - 200: Validation report.

## Schemas

### Invoice
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "invoiceTypeCode": {
      "type": "string",
      "pattern": "^\\d{3}$",
      "default": "380"
    },
    "issueDate": {
      "type": "string"
    },
    "dueDate": {
      "type": "string"
    },
    "currencyCode": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "buyerReference": {
      "type": "string",
      "minLength": 1
    },
    "seller": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "legalForm": {
          "type": "string",
          "minLength": 1
        },
        "vatId": {
          "type": "string",
          "pattern": "^[A-Z]{2}[A-Z0-9]{2,20}$"
        },
        "registrationNumber": {
          "type": "string",
          "minLength": 1
        },
        "address": {
          "type": "object",
          "properties": {
            "line1": {
              "type": "string",
              "minLength": 1
            },
            "line2": {
              "type": "string",
              "minLength": 1
            },
            "city": {
              "type": "string",
              "minLength": 1
            },
            "postalCode": {
              "type": "string",
              "minLength": 1
            },
            "countrySubdivision": {
              "type": "string",
              "minLength": 1
            },
            "countryCode": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          "required": [
            "countryCode"
          ],
          "additionalProperties": false
        },
        "electronicAddress": {
          "type": "object",
          "properties": {
            "scheme": {
              "type": "string"
            },
            "value": {
              "type": "string",
              "minLength": 1
            }
          },
          "required": [
            "scheme",
            "value"
          ],
          "additionalProperties": false
        },
        "contact": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1
            },
            "phone": {
              "type": "string",
              "minLength": 1
            },
            "email": {
              "type": "string",
              "format": "email"
            }
          },
          "additionalProperties": false
        }
      },
      "required": [
        "name",
        "address"
      ],
      "additionalProperties": false
    },
    "buyer": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "legalForm": {
          "type": "string",
          "minLength": 1
        },
        "vatId": {
          "type": "string",
          "pattern": "^[A-Z]{2}[A-Z0-9]{2,20}$"
        },
        "registrationNumber": {
          "type": "string",
          "minLength": 1
        },
        "address": {
          "type": "object",
          "properties": {
            "line1": {
              "type": "string",
              "minLength": 1
            },
            "line2": {
              "type": "string",
              "minLength": 1
            },
            "city": {
              "type": "string",
              "minLength": 1
            },
            "postalCode": {
              "type": "string",
              "minLength": 1
            },
            "countrySubdivision": {
              "type": "string",
              "minLength": 1
            },
            "countryCode": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          "required": [
            "countryCode"
          ],
          "additionalProperties": false
        },
        "electronicAddress": {
          "type": "object",
          "properties": {
            "scheme": {
              "type": "string"
            },
            "value": {
              "type": "string",
              "minLength": 1
            }
          },
          "required": [
            "scheme",
            "value"
          ],
          "additionalProperties": false
        },
        "contact": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1
            },
            "phone": {
              "type": "string",
              "minLength": 1
            },
            "email": {
              "type": "string",
              "format": "email"
            }
          },
          "additionalProperties": false
        }
      },
      "required": [
        "name",
        "address"
      ],
      "additionalProperties": false
    },
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "description": {
            "type": "string",
            "minLength": 1
          },
          "quantity": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0
          },
          "unitCode": {
            "type": "string",
            "pattern": "^[A-Z0-9]{1,4}$"
          },
          "unitPrice": {
            "type": "number",
            "minimum": 0
          },
          "vat": {
            "type": "object",
            "properties": {
              "categoryCode": {
                "type": "string",
                "enum": [
                  "S",
                  "Z",
                  "E",
                  "AE",
                  "K",
                  "G",
                  "O"
                ]
              },
              "rate": {
                "type": "number",
                "minimum": 0,
                "maximum": 100
              },
              "exemptionReason": {
                "type": "string",
                "minLength": 1
              },
              "exemptionReasonCode": {
                "type": "string",
                "minLength": 1
              }
            },
            "required": [
              "categoryCode",
              "rate"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "id",
          "description",
          "quantity",
          "unitCode",
          "unitPrice",
          "vat"
        ],
        "additionalProperties": false
      },
      "minItems": 1
    },
    "documentAllowances": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "minLength": 1
          },
          "amount": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0
          },
          "vat": {
            "type": "object",
            "properties": {
              "categoryCode": {
                "type": "string",
                "enum": [
                  "S",
                  "Z",
                  "E",
                  "AE",
                  "K",
                  "G",
                  "O"
                ]
              },
              "rate": {
                "type": "number",
                "minimum": 0,
                "maximum": 100
              },
              "exemptionReason": {
                "type": "string",
                "minLength": 1
              },
              "exemptionReasonCode": {
                "type": "string",
                "minLength": 1
              }
            },
            "required": [
              "categoryCode",
              "rate"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "amount",
          "vat"
        ],
        "additionalProperties": false
      },
      "default": []
    },
    "documentCharges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "minLength": 1
          },
          "amount": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0
          },
          "vat": {
            "type": "object",
            "properties": {
              "categoryCode": {
                "type": "string",
                "enum": [
                  "S",
                  "Z",
                  "E",
                  "AE",
                  "K",
                  "G",
                  "O"
                ]
              },
              "rate": {
                "type": "number",
                "minimum": 0,
                "maximum": 100
              },
              "exemptionReason": {
                "type": "string",
                "minLength": 1
              },
              "exemptionReasonCode": {
                "type": "string",
                "minLength": 1
              }
            },
            "required": [
              "categoryCode",
              "rate"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "amount",
          "vat"
        ],
        "additionalProperties": false
      },
      "default": []
    },
    "paymentTerms": {
      "type": "string",
      "minLength": 1
    },
    "paymentMeans": {
      "type": "object",
      "properties": {
        "typeCode": {
          "type": "string",
          "minLength": 1,
          "default": "30"
        },
        "iban": {
          "type": "string",
          "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$"
        },
        "bic": {
          "type": "string",
          "pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$"
        },
        "accountName": {
          "type": "string",
          "minLength": 1
        }
      },
      "additionalProperties": false
    },
    "attachments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "description": {
            "type": "string",
            "minLength": 1
          },
          "filename": {
            "type": "string",
            "minLength": 1
          },
          "mimeCode": {
            "type": "string",
            "minLength": 1
          },
          "content": {
            "type": "string",
            "minLength": 1
          },
          "externalUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "additionalProperties": false
      },
      "default": []
    },
    "declaredTotals": {
      "type": "object",
      "properties": {
        "lineExtensionAmount": {
          "type": "number",
          "minimum": 0
        },
        "allowanceTotalAmount": {
          "type": "number",
          "minimum": 0
        },
        "chargeTotalAmount": {
          "type": "number",
          "minimum": 0
        },
        "taxExclusiveAmount": {
          "type": "number",
          "minimum": 0
        },
        "totalVatAmount": {
          "type": "number",
          "minimum": 0
        },
        "taxInclusiveAmount": {
          "type": "number",
          "minimum": 0
        },
        "payableAmount": {
          "type": "number",
          "minimum": 0
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "issueDate",
    "currencyCode",
    "seller",
    "buyer",
    "lines"
  ],
  "additionalProperties": false
}

### AgentError
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "example": "PEPPOL-EN16931-R003"
    },
    "humanSummary": {
      "type": "string"
    },
    "llmFix": {
      "type": "string"
    },
    "docsUrl": {
      "type": "string"
    },
    "offendingValue": {
      "type": [
        "string",
        "null"
      ]
    },
    "field": {
      "type": [
        "string",
        "null"
      ]
    },
    "ruleId": {
      "type": "string"
    },
    "severity": {
      "type": "string",
      "enum": [
        "fatal",
        "warning"
      ]
    },
    "stage": {
      "type": "string",
      "enum": [
        "xsd",
        "en16931",
        "peppol"
      ]
    },
    "rawMessage": {
      "type": "string"
    },
    "location": {
      "type": "string"
    }
  },
  "required": [
    "code",
    "humanSummary",
    "llmFix",
    "severity",
    "stage"
  ]
}

### ValidationReport
{
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AgentError"
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AgentError"
      }
    }
  },
  "required": [
    "errors",
    "warnings"
  ]
}

### InvoiceEnvelope
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "validated",
        "invalid",
        "delivered_simulated",
        "submitted"
      ]
    },
    "document_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "validation": {
      "$ref": "#/components/schemas/ValidationReport"
    },
    "preview_url": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "id",
    "status",
    "validation"
  ]
}

### CreateInvoiceRequest
{
  "type": "object",
  "properties": {
    "invoice": {
      "$ref": "#/components/schemas/Invoice"
    },
    "options": {
      "type": "object",
      "properties": {
        "deliver": {
          "type": "boolean",
          "default": false,
          "description": "Sandbox delivery is always simulated."
        },
        "format": {
          "type": "string",
          "enum": [
            "auto",
            "ubl"
          ],
          "default": "auto"
        }
      }
    }
  },
  "required": [
    "invoice"
  ]
}

### Capabilities
{
  "type": "object",
  "description": "The current country/format/channel routing matrix. Declarative and versioned; mandates carry effective dates.",
  "properties": {
    "version": {
      "type": "string"
    },
    "updated": {
      "type": "string"
    },
    "asOf": {
      "type": "string",
      "description": "The date the matrix was evaluated for (YYYY-MM-DD)."
    },
    "formats": {
      "type": "object",
      "additionalProperties": true
    },
    "channels": {
      "type": "object",
      "additionalProperties": true
    },
    "rules": {
      "type": "array",
      "description": "The full declarative rule table, including not-yet-active mandates; each flagged with its as-of active state.",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "countries": {
      "type": "array",
      "description": "Per-country outcome for a domestic buyer not reachable on Peppol, evaluated as-of the queried date.",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    }
  },
  "required": [
    "version",
    "asOf",
    "formats",
    "channels",
    "rules",
    "countries"
  ]
}

### WebhookResult
{
  "type": "object",
  "description": "Ingestion outcome for a delivery-status webhook batch.",
  "properties": {
    "received": {
      "type": "integer",
      "description": "Number of status events parsed from the payload."
    },
    "applied": {
      "type": "integer",
      "description": "Events matched to a known delivery and persisted."
    },
    "unmatched": {
      "type": "integer",
      "description": "Events for an unknown providerRef, skipped (not an error)."
    }
  },
  "required": [
    "received",
    "applied",
    "unmatched"
  ]
}

### BillingSummary
{
  "type": "object",
  "description": "Account balance and this calendar month usage. Money is integer euro cents.",
  "properties": {
    "balance_cents": {
      "type": "integer",
      "description": "Running ledger sum. Positive = prepaid credit; negative = owed."
    },
    "balance": {
      "type": "string",
      "example": "€12.40"
    },
    "owed_cents": {
      "type": "integer",
      "description": "Amount owed (0 unless a card account has accrued debt)."
    },
    "payment_mode": {
      "type": "string",
      "enum": [
        "prepaid",
        "card_threshold"
      ]
    },
    "delivered_this_month": {
      "type": "integer"
    },
    "currency": {
      "type": "string",
      "example": "eur"
    }
  },
  "required": [
    "balance_cents",
    "balance",
    "owed_cents",
    "payment_mode",
    "delivered_this_month",
    "currency"
  ]
}

### TopupResult
{
  "type": "object",
  "properties": {
    "checkout_url": {
      "type": "string",
      "description": "Stripe Checkout URL to complete the top-up."
    },
    "session_id": {
      "type": "string"
    },
    "amount_cents": {
      "type": "integer",
      "enum": [
        1000,
        2500,
        5000,
        10000
      ]
    }
  },
  "required": [
    "checkout_url",
    "session_id",
    "amount_cents"
  ]
}

### ErrorResponse
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "llmFix": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  }
}