Endpoint reference

All paths are relative to the base URL and require a Bearer token. Amounts are in cents; field names are snake_case.

Entities (clients and suppliers)

An entity is a party you invoice or are invoiced by. Invoices reference an entity by recipient_id.

Method	Path	Description
GET	/v1/entities	List all entities for your company.
POST	/v1/entities	Create an entity.
GET	/v1/entities/{id}	Fetch a single entity.

Create an entity

curl -X POST https://api.uninvoice.app/v1/entities \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme S.L.",
    "type": "ES-company",
    "country": "ES",
    "fiscal_id": "B12345678",
    "address_lines": ["Calle Mayor 1"],
    "address_zipcode": "28013",
    "address_city": "Madrid",
    "currency_code": "EUR"
  }'

name, type, and country are required. type encodes both the country and legal form (e.g. ES-company, ES-individual) and determines how the entity is treated for tax and legal purposes. Optional fields include fiscal_id, vies_vat_id, the address_* fields, currency_code, and under_recargo_equivalencia (Spanish recargo de equivalencia).

Invoices

Invoices are created as drafts, then issued. A draft has no invoice number and is not final; issuing assigns the number, freezes a snapshot of the company and recipient data, generates the Veri*Factu record where applicable, and produces the final PDF.

Method	Path	Description
GET	/v1/invoices	List invoices (summary items).
POST	/v1/invoices	Create a draft invoice.
GET	/v1/invoices/{id}	Fetch a full invoice with its lines.
POST	/v1/invoices/{id}/issue	Issue a draft (assigns the number, finalizes it).
POST	/v1/invoices/{id}/correct	Create a corrective invoice for an issued one.
GET	/v1/invoices/{id}/pdf	Download the invoice PDF (binary).
POST	/v1/taxes/prefill	Compute the tax lines for a set of draft lines.

Create a draft invoice

curl -X POST https://api.uninvoice.app/v1/invoices \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_id": "ent_...",
    "supply_type": "services",
    "lines": [
      {
        "idx": 1,
        "concept": "Consulting — June 2026",
        "quantity": 10,
        "quantity_unit": "hours",
        "unit_price": 20000
      }
    ]
  }'

Fields:

• recipient_id (required) — the entity being invoiced.
• supply_type — services or goods (defaults to services).
• lines (required) — the line items. Each line has an idx (1-based order), a concept, and optional quantity, quantity_unit, unit_price (cents), unit_unit, date_start/date_end, and subtotal. A line with "is_tax": true and a tax_amount represents an explicit tax line.
• Correction fields (correction_reason, correction_type, corrected_invoice_id) apply only to corrective invoices — prefer the /correct endpoint.

Taxes are normally calculated for you from the company and recipient. To see the tax lines before creating the invoice, POST the same recipient_id and lines to /v1/taxes/prefill, which returns the lines with tax lines filled in.

Issue an invoice

curl -X POST https://api.uninvoice.app/v1/invoices/inv_.../issue \
  -H "Authorization: Bearer <token>"

Spanish issuers must authorize Veri*Factu first

For issuers established in Spain, issuing is blocked until you have granted the AEAT apoderamiento. Until then the invoice stays a draft and issue returns 403 with error: "verifactu_authorization_required". See Authorize uninvoice.app.

Proformas

Proformas are non-fiscal quotes. They can be edited and deleted, and promoted into a real invoice when accepted.

Method	Path	Description
GET	/v1/proformas	List proformas.
POST	/v1/proformas	Create a proforma.
GET	/v1/proformas/{id}	Fetch a proforma.
DELETE	/v1/proformas/{id}	Delete a proforma.
POST	/v1/proformas/{id}/promote	Promote a proforma into a draft invoice.
GET	/v1/proformas/{id}/pdf	Download the proforma PDF (binary).

Company

Method	Path	Description
GET	/v1/companies/current	Read your company configuration.
PUT	/v1/companies/current	Update your company configuration.
GET	/v1/companies/current/api-tokens	List API tokens.
POST	/v1/companies/current/api-tokens	Create an API token.
DELETE	/v1/companies/current/api-tokens/{token_id}	Revoke an API token.

Veri*Factu authorization

Read and confirm the Spanish Veri*Factu apoderamiento status for your company. See the Veri*Factu guide for the full flow.

Method	Path	Description
GET	/v1/verifactu/authorization	Current authorization status.
POST	/v1/verifactu/authorization/confirm	Record that you granted the AEAT power.

A typical integration flow

1. Create the recipient with POST /v1/entities (or reuse an existing one from GET /v1/entities).
2. (Optional) Preview taxes with POST /v1/taxes/prefill.
3. Create the draft with POST /v1/invoices.
4. Issue it with POST /v1/invoices/{id}/issue — this assigns the invoice number and, for Spanish issuers, reports it to the AEAT.
5. Download the PDF with GET /v1/invoices/{id}/pdf.