Vantane Sandbox API

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 · Sandbox key vantane_sandbox_public · llms.txt · llms-full.txt · AGENTS.md · openapi.json

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/invoicesGET /v1/invoices/{id}GET /v1/invoices/{id}/document.xmlGET /v1/invoices/{id}/preview.pngGET /v1/capabilitiesGET /v1/billingPOST /v1/billing/topupPOST /v1/webhooks/stripePOST /v1/webhooks/delivery/{provider}POST /v1/validate

POST/v1/invoices

Create (and optionally simulate delivery of) a compliant invoice.

Auth: Bearer API key required · Request: CreateInvoiceRequest

Parameter	In	Required	Description
`Idempotency-Key`	header	no	Replays return the original invoice instead of creating a new one.

Status	Meaning	Schema
`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}

Fetch a previously created invoice and its status history.

Auth: Bearer API key required

Parameter	In	Required	Description
`id`	path	yes

Status	Meaning	Schema
`200`	The invoice envelope.	`InvoiceEnvelope`
`401`	Missing or invalid API key.	`ErrorResponse`
`404`	No such invoice.	`ErrorResponse`

GET/v1/invoices/{id}/document.xml

Fetch the generated UBL XML document.

Auth: Bearer API key required

Parameter	In	Required	Description
`id`	path	yes

Status	Meaning	Schema
`200`	The UBL XML.	—
`401`	Missing or invalid API key.	`ErrorResponse`
`404`	No document for this invoice.	`ErrorResponse`

GET/v1/invoices/{id}/preview.png

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

Parameter	In	Required	Description
`id`	path	yes
`page`	query	no	The 1-based page to render for multi-page invoices.

Status	Meaning	Schema
`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

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

Parameter	In	Required	Description
`asOf`	query	no	ISO date (YYYY-MM-DD) to evaluate the matrix as-of. Defaults to today.

Status	Meaning	Schema
`200`	The routing capabilities matrix.	`Capabilities`
`400`	Malformed asOf date.	`ErrorResponse`

GET/v1/billing

Account balance and this month usage.

Auth: Bearer API key required

Status	Meaning	Schema
`200`	Billing summary.	`BillingSummary`
`401`	Missing or invalid API key.	`ErrorResponse`

POST/v1/billing/topup

Start a Stripe Checkout for prepaid credit (€10/25/50/100). Credit never expires.

Auth: Bearer API key required

Status	Meaning	Schema
`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

Ingest Stripe events (signature-verified). Checkout completion credits the ledger. — Unauthenticated; verified via the Stripe-Signature header against STRIPE_WEBHOOK_SECRET.

Auth: none

Status	Meaning	Schema
`200`	Event processed.	`WebhookResult`
`400`	Missing/invalid signature or body.	`ErrorResponse`
`503`	Stripe is not configured.	`ErrorResponse`

POST/v1/webhooks/delivery/{provider}

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

Parameter	In	Required	Description
`provider`	path	yes	The registered provider name whose payload shape to parse.

Status	Meaning	Schema
`200`	The webhook batch was ingested.	`WebhookResult`
`404`	No delivery provider by that name is registered.	`ErrorResponse`

POST/v1/validate

Validate canonical invoice JSON. Free, stateless, no auth.

Auth: none · Request: Invoice

Status	Meaning	Schema
`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"
      ]
    }
  }
}