Vista previa de facturas, registro de pagos y abonos mediante la API

Retrospectiva histórica: mayo–agosto de 2026
Este artículo se escribió posteriormente y describe las acciones independientes sobre facturas que se habilitaron mediante la API.

Una integración debe distinguir entre consultar una factura, registrar una acción y mover dinero. Empieza con una vista previa para comprobar las líneas y los importes; después, crea o consulta la factura definida en el contrato actual.

Flujo de ejemplo

1. Usa el endpoint de vista previa de facturas del cliente para comprobar los periodos, las líneas y el total.
2. Si lo necesitas, descarga el PDF de la vista previa para su aprobación interna.
3. Crea o consulta la factura y usa su UUID en las llamadas posteriores.
4. Usa mark-as-sent cuando el flujo de trabajo haya entregado o registrado el documento. La llamada nunca envía un correo electrónico: registra que se entregó por un canal externo y suprime cualquier correo automático de factura que esté pendiente.
5. Usa mark-as-paid cuando debas registrar manualmente un pago. No inicia un nuevo cobro con tarjeta.
6. Usa el endpoint de abono cuando deban abonarse líneas concretas de una factura. Un abono es una acción independiente y no equivale a eliminar la factura.

Un reembolso puede seguir pendiente incluso después de que se acepte la solicitud. Lee la respuesta y consulta el estado posterior antes de mostrar el dinero como devuelto.

Errores y expectativas

La vista previa, el PDF, el envío, el pago y el abono tienen respuestas y estados distintos. Usa la referencia actual de OpenAPI para consultar los esquemas y los campos permitidos. No incluyas tokens reales ni información de clientes en el código de prueba; utiliza UUID sintéticos en los ejemplos.

Consulta la guía de API pública y webhooks (Markdown-fil, AI-agentvenlig) para ver el contrato actual.

¿mark-as-sent envía un correo? Nunca. Registra que un canal externo entregó la factura y suprime cualquier correo automático de factura pendiente. Usa la acción de envío independiente si quieres que Alunta mande el correo.

¿mark-as-paid mueve dinero? No. Registra un pago manual; no inicia un nuevo cobro con tarjeta.

¿Se puede hacer un abono parcial? Sí. Usa la acción documentada para abonar líneas y vuelve a consultar el estado antes de mostrarla como completada.

Mantén separados los estados en tu integración

Una vista previa permite mostrar al usuario lo que se facturará antes de que exista el documento definitivo. El PDF presenta la misma información en un formato que se puede aprobar o archivar. Cuando ya existe la factura, mark-as-sent registra el flujo de trabajo. Si la integración también debe enviar el documento, debe usar la acción de envío documentada y gestionar su respuesta por separado.

Del mismo modo, mark-as-paid es un registro manual. Úsalo únicamente cuando el usuario o una fuente externa conciliada haya confirmado el pago. No deduzcas que se ha realizado un pago a partir de una vista previa correcta o de un estado de envío. Abonar líneas seleccionadas modifica el importe pendiente de cobro mediante una acción de abono: no elimina la factura original ni supone automáticamente un reembolso en efectivo. mark-as-sent nunca envía correos, tampoco si se llama después de finalizar la factura; bloquea el envío automático que esté pendiente.

Usa el UUID de la factura para las llamadas de seguimiento y consulta el estado actual después de cada acción. Si la respuesta está pendiente, muestra «pendiente» en lugar de «completado». Así el usuario puede consultar el siguiente resultado de la integración sin repetir una acción que ya se ha registrado.