NewProvince is only required for addresses in Spain
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog

Simplified invoice exchanges are recorded with VeriFactu

With VeriFactu, exchanging simplified invoices now issues the full invoice and records it as F3. SIMPLIFIED_EXCHANGE_NOT_RECORDABLE now only means a simplified invoice issued without VeriFactu.

ChangelogBreaking

Until now, an exchange of simplified invoices for a full invoice answered 422 SIMPLIFIED_EXCHANGE_NOT_RECORDABLE when the company had VeriFactu enabled, and nothing was issued. Now the full invoice is issued and recorded as F3, identifying each simplified invoice it replaces by number and issue date. The simplified invoices become VOIDED with void_cause EXCHANGED, as before, and keep their registration: no cancellation record is sent for them.

An F3 only replaces simplified invoices the AEAT already accepted, so each one in simplified_invoice_ids is checked before anything is issued. The exchange stays all or nothing, and without VeriFactu nothing changes.

What breaks

  • SIMPLIFIED_EXCHANGE_NOT_RECORDABLE changes meaning. It no longer says that exchanges are unavailable with VeriFactu: it now names one simplified invoice that was issued without VeriFactu, which an F3 cannot replace, and the message carries its number. An integration that read it as "not available yet" gets 201 for the same request now.
  • Two new rejections on the exchange: 422 EXCHANGE_SIMPLIFIED_NOT_YET_ACCEPTED when a simplified invoice's registration is still pending (wait until it is accepted and retry), and 422 EXCHANGE_SIMPLIFIED_RECORD_REJECTED when it was rejected (fix or resubmit it first).
  • A simplified invoice listed twice is rejected: simplified_invoice_ids used to drop a repeated id silently; now the request fails with 422 EXCHANGE_DUPLICATED_SIMPLIFIED, naming the repeated invoice, and nothing is issued. A null in the list fails with 422 MISSING_REQUIRED_FIELD. The contract no longer declares uniqueItems on the list.
  • An exchange invoice recorded as F3 cannot be corrected yet: a corrective on it answers 422 EXCHANGE_INVOICE_NOT_CORRECTABLE. It still cannot be voided either (EXCHANGE_INVOICE_NOT_VOIDABLE).

Does this affect you?

  • If you branch on SIMPLIFIED_EXCHANGE_NOT_RECORDABLE to hide or postpone exchanges under VeriFactu, remove that branch: the exchange works now.
  • If you exchange simplified invoices right after issuing them, handle EXCHANGE_SIMPLIFIED_NOT_YET_ACCEPTED by retrying once verifactu.status.updated reports them accepted.
  • If you correct exchange invoices, handle EXCHANGE_INVOICE_NOT_CORRECTABLE.

What else changed

  • Same company and environment. Every simplified invoice must belong to the company in the path and to the environment of the API key; otherwise 422 SIMPLIFIED_NOT_EXCHANGEABLE.
  • Webhook examples: the verifactu.status.updated examples in the reference now show operation, including an accepted cancellation.

Endpoints

  • POST/v1/companies/{company_id}/invoices/simplified-exchangesRecorded as F3 with VeriFactu; EXCHANGE_SIMPLIFIED_NOT_YET_ACCEPTED, EXCHANGE_SIMPLIFIED_RECORD_REJECTED, EXCHANGE_DUPLICATED_SIMPLIFIED
  • POST/v1/companies/{company_id}/invoices/{invoice_id}/correctiveEXCHANGE_INVOICE_NOT_CORRECTABLE on an F3 exchange invoice

Where to go next

Exchanging simplified invoices with VeriFactuExchange simplified invoices

Province is only required for addresses in Spain

`province` is no longer required on an `Address` outside Spain: a foreign customer or inline recipient without one is accepted. A Spanish address without it still answers `422 PROVINCE_EMPTY`.

The VeriFactu status webhook says whether it reports the registration or the cancellation

`verifactu.status.updated` now carries `operation`: `REGISTRATION` or `VOID`. AEAT's answer to a cancellation reaches you by webhook without a lookup.