Direct invoices

An API connection can issue invoices directly after its owner completes the Enable VeriFactu invoicing consent wizard in Factulit. Creating the technical connection or synchronizing orders does not enable this endpoint.

POST /api/v1/invoice is an issuance operation, not a draft operation. A successful request atomically assigns the connection's current API-* series and number, creates the VeriFactu ALTA record, and leaves it pending for AEAT submission. Issued invoices cannot be updated with PUT.

Idempotency

Choose a stable external_id in your system:

• The first request returns HTTP 201.
• The same external_id and the same normalized payload returns the existing result with HTTP 200 and replayed: true.
• The same external_id with a different payload returns HTTP 409 and error_code: idempotency_conflict.

Example

curl -X POST https://api.factulit.es/api/v1/invoice \
  -H "X-API-KEY: factulit_example_key" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 019ffae4-example" \
  -d '{
    "external_id": "invoice-2026-0001",
    "invoice_type": "F1",
    "description": "Online sale",
    "currency": "EUR",
    "recipient": {
      "company": "Example SL",
      "vat_number": "B00000000",
      "country": "ES",
      "address1": "Main Street 1",
      "postcode": "28001",
      "city": "Madrid"
    },
    "lines": [{
      "description": "Product",
      "quantity": 1,
      "price_unit": 100,
      "tax_rate": 21,
      "regime": "01",
      "qualification": "S1",
      "type_tax": "01"
    }]
  }'

Use GET /api/v1/invoice/{external_id} to retrieve the result. A non-EUR request must include exchange_rate and exchange_rate_date.

The documentary regime (art6_full or art7_simplified) is independent from the AEAT code. Exceptional crossings require their structured flag: qualified_simplified_art_7_2_3 for a qualified simplified F1, or no_recipient_article_6_1_d for a complete F2 without recipient identification. The general automatic simplified-invoice threshold is EUR 400. Requests for art7_simplified above EUR 400 must include a structured simplified_attestation covering the legal basis, buyer role and the exact line_id set. The article_4_2 basis retains the EUR 3,000 ceiling; aeat_authorisation must match the active audited authorisation configured in Factulit. Missing or ambiguous evidence is rejected with an actionable fiscal error.

Before consent, customer, status and order synchronization remains available; fiscal effects are deferred and direct invoice requests return 409 invoicing_not_enabled.