Get StartedVeriFactuStripeAPI Reference

Auto-submit policy

The exact conditions under which BeeL sends an issued invoice to AEAT for you — and what happens when one of them isn't met.

BeeL never silently submits an invoice to AEAT. Auto-submit only happens when a small list of preconditions all hold — and when one of them fails, BeeL records why on the invoice so you can audit it later. This page documents the policy.

The three gates

All three must be open for BeeL to submit the invoice to AEAT. If any of them is closed, the invoice is issued locally with verifactu.enabled: false on the response.

Connection / serie auto-submit toggle

Per-serie or per-integration override. The Stripe integration carries its own VeriFactu submission toggle; manual issuance from the API uses the serie's default. You can flip it without disabling VeriFactu globally — handy when you want to issue a "draft-and-review" series.

A VeriFactu configuration exists

You must have set up VeriFactu on your account at least once. The configuration record carries:

  • The representation (PDF signed by you, delegating BeeL to submit on your behalf)
  • The environment target (Production or Sandbox)
  • The NIFs you have authorised for submission

Read it with GET /v1/configuration/verifactu and update it with PUT /v1/configuration/verifactu.

The configuration enabled flag is on

Your VeriFactu configuration has an enabled flag you can turn off without deleting the record. This is the kill switch for the entire account — useful for maintenance windows or before a wave of test issuance. When off, every issued invoice lands with verifactu.enabled: false until you flip it back on.

How a skipped submission looks on the invoice

When BeeL doesn't submit, the invoice resource exposes the state through the nested verifactu object:

{
  "id": "...",
  "status": "ISSUED",
  "verifactu": {
    "enabled": false
  }
}

When BeeL DOES submit (all three gates open), the invoice carries the full record:

{
  "id": "...",
  "status": "ISSUED",
  "verifactu": {
    "enabled": true,
    "submission_status": "PENDING",
    "registration_number": null,
    "registration_date": null,
    "invoice_hash": "F8B2A3...",
    "chaining_hash": "A1C4E7...",
    "qr_url": null,
    "qr_base64": null,
    "error_code": null,
    "error_message": null
  }
}

See Submission states for the full lifecycle of submission_status.

Defaults you should know

  • Stripe integrations ship with VeriFactu auto-submit on by default. Stripe Connect payments auto-submit unless you explicitly turn the toggle off.
  • Manual API issuance uses the serie's default. New series created via POST /v1/configuration/series inherit the global default.
  • Sandbox keys still submit to AEAT's sandbox environment — submissions are real but flagged as test in AEAT.

Production submissions are not undoable as a batch. Disable auto-submit before issuing a wave of invoices you don't want to send to AEAT.

There's no public "submit now" endpoint

The public API does not expose an endpoint to manually trigger a submission for an invoice that landed with verifactu.enabled: false. Your options:

This is by design — auto-submit is meant to be set once and trusted, not driven per-invoice from the API.

Submission states

Every state a VeriFactu submission can be in, what triggers transitions, and when you need to act.

Cancel vs amend

Decide between cancelling an invoice (void) and issuing a corrective (rectificativa). Each operation has different fiscal weight.

On this page

The three gatesConnection / serie auto-submit toggleA VeriFactu configuration existsThe configuration enabled flag is onHow a skipped submission looks on the invoiceDefaults you should knowThere's no public "submit now" endpointRelated