- 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:
- Plan de la API: Developer (19 € al mes sin IVA). El plan Incluido solo lee.
- Permisos:
invoices:writepara facturar y anotar cobros;budgets:acceptsi también vas a aceptar o rechazar en nombre del cliente. Son permisos aparte a propósito: la clave de la gestoría que solo descarga facturas no los necesita. - Una clave por sistema, con nombre reconocible («Caja mostrador»), finalidad escrita y, si se puede, limitada a la IP del equipo que la usa. Cada cambio queda firmado en el historial como «API · Caja mostrador».
- Pruebas fuera de tu taller. Las claves
pt_test_de tu taller leen tus datos pero no pueden emitir nada (responden403 test_key_forbidden). Para probar aceptaciones, facturas y cobros está el entorno público de pruebas, con datos ficticios que se restauran cada 2 horas. - Quién revisa. Alguien del taller debería mirar las primeras facturas emitidas por API antes de darlo por bueno.
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.
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.
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:
| Respuesta | Qué significa | Qué hacer |
|---|---|---|
422 fiscal_data_incomplete | Faltan datos fiscales del cliente | Pedir los que indica missing y completar la ficha |
409 budget_not_invoiceable | El presupuesto no se puede facturar en su estado | Comprobar que está aceptado y tiene importe |
422 invoice_rejected | El programa no ha podido emitir la factura | Leer el mensaje y avisar al taller |
409 budget_locked | El presupuesto está cerrado (facturado, cancelado, rechazado…) | No reintentar; revisar en el programa |
403 insufficient_scope | La clave no tiene el permiso necesario | Revisar los permisos de la clave |
403 plan_scope_not_allowed | El plan de API no incluye ese permiso | Mejorar el plan |
409 idempotency_conflict | Esa Idempotency-Key ya se usó con otra petición | Usar 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
- Facturas rectificativas. Se hacen desde el programa. Si tu caja necesita anular una venta, el flujo es avisar al taller, no llamar a un endpoint.
- Facturas sin presupuesto. No existe «crear factura suelta». Si quieres facturar algo, primero tiene que existir como presupuesto con sus partidas.
- Enviar el enlace de aceptación al cliente. La API nunca devuelve ese enlace. El cliente sigue pudiendo aceptar desde el suyo; tu sistema solo registra lo que el cliente te dijo por otra vía.
- Decidir si una aceptación por teléfono es suficiente. La API lo registra con la evidencia que le das. Si un trabajo de cuatro cifras merece firma, esa decisión es tuya.
- Sustituir a tu gestoría. El programa emite y registra; qué serie usar, qué tipo de IVA aplica a cada caso o si te conviene factura simplificada son preguntas para ella.
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.