Facturació des de terminals desatesos

3 d'octubre de 2026 — Un terminal d'autoservei o una màquina expenedora poden ja emetre una factura simplificada cobrada, amb el seu QR VERI*FACTU, en una sola crida idempotent. Al darrere hi ha una revisió de com arriben els registres a l'AEAT, una manera de remetre a través de Factuarea en lloc de fer-ho amb el teu propi certificat i una comprovació més estricta abans d'emetre una factura. Llegeix primer els tres canvis que trenquen; les operacions noves i les actualitzades es llisten al final.

Canvis que trenquen

A més, POST /v1/verifactu/records/{record}/retry ja no respon max_retries_exceeded per als registres de facturació: ja no hi ha límit d'intents. El codi continua aplicant al reintent d'un esdeveniment en mode no_verifactu.

Cobrament desatès a POST /v1/invoices

POST /v1/invoices i la tool MCP create_invoice guanyen, amb la mateixa semàntica:

• type: "F2": una factura simplificada, sense client (tiquet anònim) o amb un (factura simplificada qualificada, registrada com a F1 amb FacturaSimplificadaArt7273).
• prices_include_tax: el unit_price de cada línia és el preu final, i la base es calcula al cèntim perquè el total sigui igual a la suma que has enviat («qualsevol línia, i partir»; 422 amount_reconciliation_failed només quan una retenció o un recàrrec desplacen el total).
• payment (method, paid_at, reference): el pagament es registra després d'emetre.
• operation_on: el dia de l'operació quan difereix d'issued_on.
• options.register_verifactu: l'alta VeriFactu es genera abans de respondre. options.wait_for_pdf espera fins a uns 15 segons el PDF A4.

El 201 porta tres blocs addicionals, només en un cobrament desatès: verifactu (status, error_code, aeat_status, huella, qr_url, qr_png_base64, legend, csv), pdf (status, url, expires_at) i public_url. La guia és Facturació des de terminals desatesos, i el que ha de declarar el teu terminal és a Compliment del component de l'integrador.

El reenviament per external_id no caduca mai:

• El mateix external_id amb el mateix tipus i total respon 200 amb Idempotent-Replayed: true i la factura ja emesa, completant l'alta i el pagament si faltaven. Un email a la cua o lliurat no es torna a enviar.
• Un tipus o un total diferents respon 409 idempotency_key_reused, amb error.type: idempotency_error, subcode: unattended_replay_mismatch i param: external_id.
• Una altra petició amb el mateix external_id encara en curs fa que la segona esperi fins a 20 segons, i respongui després 409 resource_locked si la primera no ha acabat; la mateixa petició es pot enviar una altra vegada.

Un email demanat sense destinatari possible (options.send_automatically sense options.send_to i sense email de client) es rebutja abans de crear res: 422 missing_required_param amb error.param: options.send_to, sense esborrany i sense número. També regeix per a les altres peticions de POST /v1/invoices, que abans rebutjaven després de crear l'esborrany.

Emetre es rebutja quan el registre no hi cap

422 verifactu_not_eligible el retornen les operacions que emeten una factura: POST /v1/invoices amb options, POST /v1/invoices/{id}/issue, POST /v1/invoices/{id}/send i …/mark-sent quan emeten, POST /v1/invoices/{id}/corrective i POST /v1/invoices/substitute-simplified. La factura continua sent un esborrany i no consumeix número; corregeixes el camp i repeteixes. A bulk-create i bulk-status el rebuig apareix a failures[], per element.

Sense certificat de signatura utilitzable

Per a una empresa amb VeriFactu activat en mode NO VERI*FACTU, emetre i anul·lar es rebutgen abans d'executar-se quan l'empresa no pot signar el registre. Les operacions són POST /v1/invoices amb options, …/issue, …/send, …/mark-sent, …/corrective, substitute-simplified, …/annul i …/void. error.param diu què falta:

GET /v1/invoices/{invoice}/can-annul ho anticipa: can_annul és false i reasons porta el mateix missatge. A bulk-status el rebuig apareix a failures[], per element. Consulta Alta automàtica a VeriFactu.

Anul·lar una operació cobrada, tiquets i data de l'operació

• revert_collections — POST /v1/invoices/{invoice}/annul l'accepta (false per defecte). Amb true, tots els pagaments vigents es reverteixen amb el motiu reservat issued_in_error i la factura s'anul·la en una sola operació atòmica. GET …/can-annul afegeix requires_collection_reversal i active_collections_amount. POST /v1/invoices/{invoice}/payments/{payment}/reversal rebutja issued_in_error amb 422 reversal_reason_reserved. POST …/void no té aquesta opció.
• Format tiquet — GET /v1/invoices/{invoice}/pdf i …/pdf-link accepten format: a4 (per defecte), ticket_80 o ticket_58. Cada format es genera i es desa a la memòria cau per separat, i l'ETag canvia quan es crea l'alta VeriFactu i amb el format.
• operation_on — el recurs de factura el retorna, i POST /v1/invoices, PUT /v1/invoices/{invoice} i POST /v1/invoices/bulk-create l'accepten. No pot ser posterior a issued_on (422 operation_date_after_issue_date) tret que la primera línia que declara un regime_key faci servir 14 o 15, i una factura rectificativa l'hereta.
• Detall de pagaments — cada entrada de payments.detail al recurs de factura porta les cinc claus de reversió (is_reversed, reversed_at, reversal_reason, reversal_reason_text i reversal_note), també un pagament que continua en vigor (false i null).
• Enviament de la proforma — shipping_cost és un import amb IVA inclòs. En convertir la proforma en factura es desglossa en base i IVA i es conserva el total.
• Conversions — convertir un pressupost, una proforma o un albarà respon, només quan hi ha alguna cosa a advertir, warnings i warning_codes (zero_rate_line_without_exemption): una línia ha quedat al 0 % sense causa d'exempció. No bloqueja. El warnings de la factura rectificativa passa a ser opcional.

Errors que anomenen la línia

Un error de domini que neix d'una línia d'un document porta line_index, la posició de la línia començant per zero, al costat de param: error.line_index a l'API (i com a membre arrel d'application/problem+json) i error.data.line_index a MCP. És additiu; param continua anomenant el camp exactament com abans.

Rectificatives i edició

• Naturalesa per línia en una rectificativa — POST /v1/invoices/{invoice}/corrective i la tool create_corrective_invoice accepten unit, regime_key, exemption_reason i exemption_reason_text per línia. Una clau que omets hereta la línia original per índex; una clau que envies la substitueix; null significa cap.
• Les edicions no revaliden el que ja està desat. Editar un document de les cinc famílies de venda ja no exigeix que les referències que ja porta desades (variant o presentació del catàleg, configuració, opcions, despeses vinculades) continuïn actives o existents. Les referències noves o canviades es validen com sempre. update_delivery_note a MCP valida com l'API.
• original_pack_data es retorna i es conserva també a les línies de proformes i albarans, de manera que sobreviu a les edicions i a la conversió a factura.

VeriFactu: remissió, registres bloquejats i esmena

• Remissió per lots — els registres d'una empresa van a l'AEAT en lots ordenats de fins a 1.000, respectant el temps d'espera que indica l'AEAT, amb la resposta llegida registre a registre. Les fallades tècniques es reintenten almenys cada hora sense topall. Consulta Com arriben els registres a l'AEAT.
• POST /v1/verifactu/records/retry-blocked (nova, scope verifactu:write) — reactiva tots els registres bloquejats de l'empresa i respon 202 amb data.reactivated. La tool MCP és retry_blocked_verifactu_records.
• Estadístiques — GET /v1/verifactu/stats afegeix pending_incident_count, blocked_incident_count i oldest_pending_at.
• Registre — afegeix is_blocked, block_reason, aeat_error_code (inclou SCHEMA_INVALID, un registre que va incomplir l'esquema de l'AEAT i no es va enviar mai) i can_subsanar.
• POST /v1/verifactu/records/{record}/subsanar — ara admet també registres acceptats i genera sempre un registre nou: data.id és l'id del nou, no el del registre que vas enviar. Els errors de l'esmena són record_not_rejected, record_not_subsanable i requires_annulment. Consulta Esmena de registres VeriFactu.
• Remissió per un tercer — GET, POST i DELETE /v1/verifactu/representation (noves) registren, llegeixen i revoquen la representació, amb valid_until (com a màxim cinc anys), is_expired i un avís 30 i 7 dies abans que caduqui, i remission_mode a PUT /v1/verifactu/settings. El 201 del registre porta remission_mode; revocar admet reason de 3 a 500 caràcters. GET /v1/verifactu/config afegeix remission_mode, social_collaborator_available, has_active_representation, active_representation_valid_until, active_representation_is_expired i presenter_certificate_status. Les tools MCP són get_company_representation, register_company_representation i revoke_company_representation.
• Declaración responsable — GET /v1/verifactu/declaracion-responsable retorna el contingut de l'article 15: components, producer_address i signature_types, i system_name és ara el nom del sistema i no el seu codi.
• Factures simplificades — una factura simplificada amb el NIF del destinatari es registra com a F1 amb FacturaSimplificadaArt7273, i la seva rectificativa com a R1 a R4; la rectificativa d'una d'anònima continua sent R5.

Codis d'error: verifactu_not_eligible, signing_certificate_unavailable, resource_locked, idempotency_key_reused, unattended_replay_mismatch, amount_reconciliation_failed, reversal_reason_reserved, operation_date_after_issue_date, simplified_invoices_disabled, representation_required, invalid_representation i social_collaborator_unavailable.

Migració

1. Envia tax_rate a cada línia de venda, o configura l'IVA per defecte de l'empresa per a cada tipus de document, i tracta 422 missing_required_param amb lines.N.tax_rate.
2. Tracta 422 verifactu_not_eligible a cada operació que emet una factura: es recupera corregint el camp d'error.param.
3. Si una empresa funciona amb VeriFactu en mode NO VERI*FACTU, comprova que té un certificat utilitzable (o una representació activa) abans d'emetre o d'anul·lar.
4. Deixa de ramificar segons max_retries_exceeded als registres de facturació.
5. Si crides subsanar, llegeix data.id com el registre nou.
6. Un terminal envia un external_id estable per venda i reenvia la mateixa petició fins a rebre una resposta definitiva.