Programa Taller
API

Facturar por API un presupuesto aprobado y anotar el cobro, paso a paso

La caja, el ERP o la plataforma de una flota quieren cerrar la venta, pero la factura tiene que salir de un solo sitio. Así se pide al programa del taller que facture un presupuesto aprobado y anote el cobro, sin romper la numeración ni el Verifactu.

Por el equipo de Programa Taller · 19 nov 2026 · Lectura: 8 min
Ilustración de una factura con un código QR y una marca verde, una tarjeta de pago y un terminal de cobro, sobre fondo azul oscuro e índigo
En pocas palabras
  • La API factura un presupuesto aprobado con la serie, la numeración correlativa, el hash encadenado y el QR de Verifactu del propio programa.
  • Antes de facturar, tu sistema puede aceptar en nombre del cliente indicando quién acepta y por qué canal; queda en el historial con el nombre de la clave.
  • Nunca hay dos facturas del mismo presupuesto: si ya existe, la API devuelve la que hay.
  • Los cobros se anotan contra la factura y la marca de pagada se recalcula sola.
  • No hay facturas sueltas ni rectificativas por API; las rectificativas se hacen desde el programa.

Sí se puede facturar por API un presupuesto aprobado sin duplicar la facturación: tu otro sistema (una caja, un CRM, el ERP de un grupo, la plataforma de una flota) le pide al programa del taller que emita la factura, y la factura sale con la serie, la numeración correlativa, el hash encadenado y el QR de Verifactu del propio programa. Después, el mismo sistema puede anotar el cobro. En Programa Taller son dos llamadas: POST /budgets/{id}/invoice y POST /invoices/{id}/payments, con el permiso invoices:write del plan Developer.

Y si el cliente aceptó el presupuesto por teléfono o en el mostrador, tu sistema puede registrar esa aceptación en su nombre, dejando escrito quién aceptó y por qué canal. Aquí tienes el recorrido completo, paso a paso, con lo que responde la API cuando algo no cuadra.

¿Por qué no emitir la factura directamente en el otro sistema?

Porque una factura no es un PDF. Desde el reglamento de sistemas informáticos de facturación (el Real Decreto 1007/2023, lo que todo el mundo llama Verifactu), cada factura que emite un programa genera un registro con una huella que se encadena con la anterior. Si el taller factura en su programa y la caja factura por su cuenta, tienes dos sistemas emitiendo, dos cadenas y, con mala suerte, dos numeraciones que se pisan dentro de la misma serie.

La solución sensata es que solo un sistema emita y los demás se lo pidan. Si la reparación nace, se presupuesta y se aprueba en el programa del taller, lo natural es que también se facture allí. La API no crea facturas sueltas: solo factura presupuestos, y nunca dos veces el mismo. Para lo que dice la norma en tu caso concreto, la referencia es la sección de preguntas frecuentes de la Agencia Tributaria y, para cualquier duda, tu gestoría. Si quieres el contexto sin tecnicismos, lo tienes en Verifactu para talleres.

Antes de empezar: plan, permisos y una clave de prueba

Lo que tiene que decidir la gerencia, en cinco líneas:

Paso 1: que el presupuesto esté aceptado

Solo se factura lo aprobado. Lo normal es que el cliente acepte y firme desde el enlace de seguimiento que le envía el taller. Pero en el mostrador pasa otra cosa. Escena inventada: Eduardo Prieto llama a las 10:12 y dice que adelante con el cambio de distribución de su Golf, matrícula 7314 LHP. Amparo, la gerente, tiene una caja propia que su programador, Raúl, ha conectado con el taller. Desde ella registra la aceptación:

curl -X POST https://tu-taller.example/api/v1/budgets/6120/accept \
 -H "Authorization: Bearer pt_live_4b7e…" \
 -H "Idempotency-Key: 5e0c9a71-2b3d-4f66" \
 -H "Content-Type: application/json" \
 -d '{"accepted_by": "Eduardo Prieto", "channel": "phone",
      "note": "Confirmado por teléfono a las 10:12"}'

La evidencia es obligatoria: quién acepta (accepted_by) y por qué canal (phone, in_person, email, whatsapp u other). La aceptación pasa por la misma regla que la del cliente: el presupuesto queda Aprobado, se avisa al equipo, se confirma al cliente según los avisos configurados y se emiten los webhooks lead.accepted y budget.accepted. En el historial queda «Aceptado por API en nombre del cliente», con el nombre de la clave, quién y por qué canal.

Si tu taller exige firma del cliente al aceptar, la API acepta igualmente y lo deja escrito como «sin firma, aceptado por integración». Decide antes si eso te vale para trabajos grandes o si prefieres que el cliente firme siempre desde su enlace.

Dos detalles que ahorran disgustos. Solo se acepta desde «Enviado»; si ya estaba aceptado, la respuesta lo indica (already=true) y no pasa nada más. Y si faltan datos fiscales mínimos del cliente, la API responde 422 fiscal_data_incomplete con la lista de lo que falta: mejor pedírselo en ese momento que descubrirlo al facturar.

¿Y si el cliente dice que no?

El rechazo en su nombre usa el mismo permiso y exige motivo: POST /budgets/{id}/reject con reason, quién lo rechaza y el canal. Se puede rechazar desde Pendiente, En cotización, Enviado o Aprobado si el vehículo aún no ha entrado. El motivo queda en el historial y viaja en los avisos lead.rejected y budget.rejected, que es lo que luego permite saber por qué se pierden presupuestos.

Paso 2: facturar el presupuesto

El jueves por la tarde Eduardo pasa a recoger el coche. Raúl ha preparado un botón «Facturar» en la caja que hace esto:

curl -X POST https://tu-taller.example/api/v1/budgets/6120/invoice \
 -H "Authorization: Bearer pt_live_4b7e…" \
 -H "Idempotency-Key: c41d8e27-90aa-4b13" \
 -H "Content-Type: application/json" \
 -d '{"issue": true, "pay_method": "TARJETA"}'

El programa copia las partidas y el impuesto del presupuesto, crea el asiento contable y emite la factura con la serie que toque, su número y su registro Verifactu. El presupuesto pasa a Facturado. Se puede facturar uno que esté Aprobado, En curso, En espera o Finalizado, siempre que tenga importe. Si ese presupuesto ya tenía factura, la API devuelve la existente (created=false) en lugar de hacer otra: si Raúl pulsa dos veces, no hay dos facturas.

La respuesta trae lo que la caja necesita para imprimir o enviar: número completo, total, estado de cobro y el hash Verifactu. El PDF original, con su QR, se descarga de GET /invoices/{id}/pdf.

Paso 3: anotar el cobro

Eduardo paga con tarjeta en el datáfono. La caja lo anota contra la factura:

curl -X POST https://tu-taller.example/api/v1/invoices/918/payments \
 -H "Authorization: Bearer pt_live_4b7e…" \
 -H "Idempotency-Key: 0f7a2c55-6e19-4d02" \
 -H "Content-Type: application/json" \
 -d '{"amount": 612.40, "date": "2026-10-15",
      "pay_method": "TARJETA", "notes": "Cobrado en mostrador"}'

Es el mismo registro de cobros que la ficha de la factura en el programa. La marca de «pagada» no se fuerza: se recalcula con todos los cobros anotados. Si Eduardo paga la mitad hoy y la otra mitad el viernes, son dos cobros y la factura queda pagada con el segundo. Solo se anotan cobros sobre facturas emitidas.

Paso 4: que los demás se enteren solos

Facturar y cobrar disparan avisos: invoice.created, invoice.issued y payment.received. Si tu contabilidad, tu gestoría o el ERP de tu grupo están suscritos, reciben la factura y el cobro sin que nadie reenvíe un email. Es el mismo circuito que contamos en la gestoría que recibe las facturas automáticamente.

Mirado desde el mostrador, el resultado es menos teclado: Amparo no factura dos veces ni copia importes de una pantalla a otra. Mirado desde la gerencia, es poder abrir una segunda caja, o vender por otro canal, sin que la facturación se complique.

Prueba el ciclo entero sin riesgo

Acepta, factura y cobra en el entorno de pruebas con datos ficticios antes de tocar tu serie real.

Empieza: 3 meses por 1 €

¿Qué responde la API cuando algo no cuadra?

Una integración de facturación se mide por cómo se comporta en los casos raros. Estos son los errores que más verás, y qué hacer con cada uno:

RespuestaQué significaQué hacer
422 fiscal_data_incompleteFaltan datos fiscales del clientePedir los que indica missing y completar la ficha
409 budget_not_invoiceableEl presupuesto no se puede facturar en su estadoComprobar que está aceptado y tiene importe
422 invoice_rejectedEl programa no ha podido emitir la facturaLeer el mensaje y avisar al taller
409 budget_lockedEl presupuesto está cerrado (facturado, cancelado, rechazado…)No reintentar; revisar en el programa
403 insufficient_scopeLa clave no tiene el permiso necesarioRevisar los permisos de la clave
403 plan_scope_not_allowedEl plan de API no incluye ese permisoMejorar el plan
409 idempotency_conflictEsa Idempotency-Key ya se usó con otra peticiónUsar una clave nueva para cada operación distinta

La regla de oro para tu programador: una Idempotency-Key nueva por operación, y la misma si reintenta esa operación. Repetir la misma clave con el mismo cuerpo en 24 horas devuelve la respuesta guardada; así un corte de red no genera un segundo cobro.

Lo que no se puede hacer por API

Con esos límites claros, facturar por API sirve para lo que tiene que servir: que la factura salga una vez, bien numerada, desde el sistema que sabe lo que se ha hecho en el coche, aunque el botón esté en otra pantalla. Todos los parámetros están en la referencia de la API.

Preguntas frecuentes

¿Se puede emitir una factura por API sin presupuesto?

No. La API solo factura presupuestos que estén Aprobados, En curso, En espera o Finalizados con importe. Si algo hay que facturar, primero tiene que existir como presupuesto con sus partidas.

¿La factura emitida por API cumple con Verifactu?

Usa la misma facturación del programa: serie, número correlativo, hash encadenado y QR Verifactu, y crea el asiento contable. Es exactamente la misma factura que si se emitiera desde la pantalla del taller.

¿Qué pasa si mi sistema pide facturar dos veces el mismo presupuesto?

Si el presupuesto ya tiene factura, la API devuelve esa misma factura en lugar de crear otra. Con la cabecera Idempotency-Key, los reintentos por cortes de red tampoco generan duplicados.

¿Cómo se registra que el cliente aceptó por teléfono?

Con el permiso budgets:accept se acepta en su nombre indicando quién acepta y el canal (teléfono, en persona, email, WhatsApp u otro). Pasa por la misma regla que la aceptación del cliente y queda en el historial como aceptado por API en nombre del cliente.

¿Se pueden anotar pagos parciales?

Sí. Cada cobro se anota por separado contra la factura emitida y el programa recalcula si está pagada con la suma de todos. Nunca se marca como pagada a la fuerza.

¿Qué plan de la API necesito para facturar?

El plan Developer, de 19 € al mes sin IVA, que incluye los permisos de escritura, facturación y aceptación. El plan Incluido solo permite leer.

¿Puedo hacer una factura rectificativa desde mi sistema?

No por API. Las rectificativas se hacen desde el propio programa del taller, para que la corrección quede bien encadenada con la factura original.

Sigue leyendo

API

Enviar las facturas a la gestoría automáticamente: cómo hacerlo con la API

23 oct 2026 · 10 min
Normativa

Verifactu para talleres: guía completa tras el aplazamiento a 2027

19 ago 2026 · 13 min
API

Entorno de pruebas de la API (sandbox): probar una integración sin riesgo

16 nov 2026 · 9 min
3 meses por 1 €