POST/api/mod/contabilidad/{espacio}/push/invoice

Encola una factura

Deja una factura de venta en la cola para tu software contable. Responde al momento con el id de la entrada; la factura la emite tu software cuando se procesa la cola.

PERMISOescribe
CRÉDITOSno gasta
AUTENTICACIÓNBearer bth_…

PARÁMETROS

CAMPO	TIPO	REQUERIDO	QUÉ ES
espacio	string	SÍ	El id del espacio (sale en GET /api/companies). Tiene que tener el módulo Contabilidad.

CUERPO · JSON

CAMPO	TIPO	REQUERIDO	QUÉ ES
referencia_interna	string	SÍ	Tu id de la venta (el de tu pedido). Es la clave que impide facturar dos veces lo mismo.
cliente	object	SÍ	A quién se factura: ver cliente.
lineas	array	SÍ	Una por producto: ver lineas[].
subtotal · total	cifra	SÍ	Ya calculados: el módulo no los recalcula ni los comprueba.
descuento_total	cifra	no	Por defecto 0.
moneda	string	no	Por defecto COP.
fecha	string	SÍ	La fecha de la venta, en ISO 8601 (2026-10-02T15:04:05).
metadata	object	no	La observación de la factura: `anotation` en Alegra, `observations` en Siigo. Sin ella, «Ref interna <referencia_interna>».

RESPUESTA 202

La entrada en la cola. Guarda su outbox_id.

CAMPO	TIPO	QUÉ ES
outbox_id	string	El id de la entrada.
estado	string	pending si es nueva; si ya existía, el suyo de ahora.
idempotent_replay	boolean	true si esa referencia_interna ya estaba encolada: no se creó otra.

CLIENTE

CAMPO	TIPO	QUÉ ES
tipo_id	"NIT" \| "CC" \| "CE" \| "PASAPORTE"	El tipo de documento. Por defecto CC.
identificacion	string	El número.
nombre	string	Nombre o razón social.
email · telefono	string	Opcionales.
raw	object	Campos extra, con los nombres de tu software, que se mandan tal cual al crear el cliente. Al facturar no se usan.

LINEAS[]

CAMPO	TIPO	QUÉ ES
sku	string	La referencia del producto.
descripcion	string	El texto de la línea.
cantidad · precio_unitario	cifra	Unidades y precio de cada una.
descuento · impuesto_pct	cifra	El descuento de la línea y el porcentaje de impuesto (19 = 19 %). Por defecto 0.

ERRORES DE ESTA RUTA · SIEMPRE {"detail": …}

STATUS	CUÁNDO	DETAIL LITERAL
403	El espacio no tiene el módulo Contabilidad	módulo no habilitado para este espacio.
403	La clave es de solo lectura	Tu cuenta es de solo lectura en este espacio.
502	El módulo no está disponible en este momento: reintenta en unos minutos	—
422	Falta un campo obligatorio o uno no tiene su tipo (detail es una lista)	—

Y los de cualquier ruta —clave inválida, cuenta no al día, IP, límites—, en Errores, límites y créditos.

CONVIENE SABER

Encolar no manda nada todavía: el envío ocurre al procesar la cola. Síguelo con GET push/{entrada}.
Encolar dos veces la misma referencia_interna no duplica nada: devuelve la entrada que ya existía, con idempotent_replay: true y su estado de ahora.
Las cifras se guardan exactas: mándalas como texto ("38000.50"). También aceptan números, pero un número con decimales puede perder precisión antes de llegar.
La factura legal la emite tu software con su numeración: Bentho le pasa los datos. El número y, si lo da, el CUFE vuelven en resultado_json.