Skip to main content

HTTP API

uninvoice.app exposes an HTTP API so you can create entities (clients and suppliers), draft and issue invoices, download their PDFs, and read your company configuration from your own tools and integrations. The same API powers the web app.

This section covers authentication and the conventions shared by every endpoint. The full list of endpoints is in the Endpoint reference. If you drive the API from an AI agent, see the MCP server, which exposes the same operations over the Model Context Protocol.

Base URL​

The API is versioned under /v1:

EnvironmentBase URL
Productionhttps://api.uninvoice.app

Every path in the reference is relative to this base — for example GET /v1/invoices.

Authentication​

All API requests authenticate with a Bearer token in the Authorization header:

Authorization: Bearer <token>

Two kinds of token are accepted, and both resolve to the same identity — a user acting within a company:

  • API tokens — long-lived UUID tokens meant for integrations, scripts, and MCP clients. They do not expire; they stay valid until you delete them. This is what you should use for anything running outside a browser.
  • Session (JWT) tokens — short-lived tokens (24 h) issued to the web app when a user signs in. Useful for scripting against your own session, but not intended for long-running integrations.

Requests with no token, an unknown token, or a deleted token receive 401 Unauthorized.

Creating an API token​

API tokens are managed under your company. Using an existing authenticated session, create one with:

curl -X POST https://api.uninvoice.app/v1/companies/current/api-tokens \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"description": "Accounting integration"}'

The response returns the token record:

{
  "id": "3f2b1c9a-...-a1b2c3d4e5f6",
  "description": "Accounting integration",
  "createdAt": "2026-07-03T10:00:00Z"
}

The id is the token value — send it as the Bearer credential on subsequent requests. Store it securely; treat it like a password.

List and revoke tokens with:

  • GET /v1/companies/current/api-tokens — list active tokens (metadata only; the value is only shown once, at creation).
  • DELETE /v1/companies/current/api-tokens/{token_id} — revoke a token.

A token is scoped to one user within one company. Every call it makes acts as that user in that company; there is no way to switch company on an API token.

Conventions​

These conventions apply across all endpoints.

JSON​

Requests and responses are JSON. Field names use snake_case (e.g. recipient_id, unit_price), except for a small number of metadata fields that are explicitly camelCased (e.g. createdAt).

Money​

Monetary amounts are integers in the currency's minor unit (cents) — never floats. unit_price, subtotal, tax_amount, and invoice total are all in cents. For example, €1,250.00 is 125000. Currencies are ISO 4217 codes (currency_code, e.g. EUR).

Dates and times​

Timestamps are RFC 3339 / ISO 8601 in UTC (e.g. 2026-07-03T10:00:00Z).

Errors​

Errors use standard HTTP status codes. Most carry a plain-text message body:

StatusMeaning
400 Bad RequestThe request is malformed or fails a business rule. The body describes what to fix.
401 UnauthorizedMissing, invalid, or revoked token.
403 ForbiddenAuthenticated, but not allowed to perform this action.
404 Not FoundThe resource does not exist, or is not visible to your company.
500 Internal Server ErrorUnexpected server error.

Some 403 responses that require a specific follow-up action return a JSON body with a machine-readable error code and a human message, for example:

{
  "error": "verifactu_authorization_required",
  "message": "You must authorize uninvoice.app to report on your behalf before issuing invoices.",
  "requiresAuthorizationUrl": "/verifactu/authorization"
}

Codes you may encounter: company_not_settled (finish company onboarding first), agreement_required (accept the current legal terms first), verifactu_authorization_required (grant the Veri*Factu apoderamiento first), and not_available (the account is outside the current availability allowlist).

What a token can and cannot do​

An API token can read and write the resources of its company: entities, invoices, proformas, taxes, company configuration, and the Veri*Factu authorization status. Account-level and billing operations that belong to the web app — sign-in, company switching, subscriptions, points top-ups, legal acceptance, and the admin "shadow user" feature — are not part of the integration surface and are documented only where relevant.

Continue to the Endpoint reference.