Tezora

Lotes

Lotes de ventas

POST /sales/batches recibe hasta 1.000 ventas y las crea y emite en cola, en el orden enviado, con las mismas reglas de POST /sales. Cada venta exige una reference única dentro del lote, que es la clave para cruzar resultados. La respuesta es 202 inmediata y el lote cuenta como una petición.

flowchart TD
  A[POST /sales/batches] -->|202| B[queued]
  B --> C[processing en tramos de 100]
  C --> D{Resultado de cada venta}
  D --> E[issued, contingency, rejected, failed, already_invoiced o invalidated_before]
  E --> F[completed y webhook sale.batch.completed]
  F --> G[sin ventas pendientes ni en contingencia: webhook sale.batch.settled]
transmission Comportamiento
auto (por omisión) Los documentos de cada tramo de 100 se transmiten de inmediato: en un lote de Hacienda dentro de su ventana, uno por uno fuera de ella.
next_window Para facturación cíclica. Las ventas se crean al instante y sus documentos se emiten y firman al abrir la siguiente ventana; entretanto cada venta está scheduled.

La ventana de lotes de Hacienda va de 08:00 a 17:00 en pruebas y de 22:00 a 05:00 en producción, hora de El Salvador. Tezora deja de enviar lotes 15 minutos antes del cierre.

status de una venta Significado
pending En espera de su turno o de la respuesta del lote de Hacienda.
scheduled Creada; su documento sale en la próxima ventana.
issued Sellada por Hacienda.
contingency Emitida en contingencia; sale.document.processed llega al sellarse.
rejected Documento rechazado; la venta existe. rejection trae el codigoMsg de Hacienda en message_code y su respuesta en message. También cuando la reference ya tenía una venta cuyo documento está rechazado: no se crea otra, y esa venta se corrige con POST /sales/{uuid}/document. Un documento rechazado no es una factura, así que el lote no la cuenta como facturada.
failed Venta no creada o documento no emitido. error_code es el de POST /sales, document_not_issued (se reintenta con POST /sales/{uuid}/document) o sale_not_created. Si la reference ya es de una venta de otra sucursal que la de la llave, error_code es sale_reference_exists, errors.reference nombra esa sucursal y sale es nulo: no hay que enviarla de nuevo.
already_invoiced Ya existía una venta con esa reference, enlazada en sale con su total: la vigente, o la que corrige el documento invalidado de la venta original (tipo 1 o 3). No es una falla. differs es true cuando lo reenviado no es esa venta, que no se modifica: los payments suman otra cifra que el total menos vat_withheld, o las lines nombran otros productos, cantidades o unit_price, en cualquier orden. Una línea sin unit_price se compara por producto y cantidad.
invalidated El documento se invalidó después.
invalidated_before La reference es de una venta retirada sin nada en su lugar (rescisión, tipo 2), enlazada en sale con su invalidation. El lote no la factura de nuevo; solo POST /sales lo hace.

Un archivo de cierre reenviado después de una devolución no factura dos veces el ticket devuelto: el ticket queda invalidated_before. Tras una corrección con reemplazo (tipo 1 o 3), el ticket original queda already_invoiced sobre la venta de reemplazo, y la reference del reemplazo, si viene en el archivo, también. Un ticket reenviado mientras su documento está rechazado queda rejected, y pasa a issued cuando el documento se corrige y se sella.

GET /sales/batches/{uuid} trae las ventas del lote paginadas en items, de 25 en 25 por omisión: per_page admite hasta 100 y page elige la página; meta y links.next dicen si quedan más. status y error_code filtran las ventas. Un lote de 1.000 ventas son 10 páginas de 100.

Una venta fallida no detiene a las demás. El lote pasa a completed cuando todas sus ventas tienen resultado y envía una sola vez sale.batch.completed con sus conteos. Después, cada venta sigue el estado de su documento y los conteos se recalculan: contingency y rejected pasan a issued al sellarse, issued pasa a invalidated, y una failed cuya reference se factura después toma esa venta con resolved_outside_batch: true. Cuando a un lote completed ya no le queda ninguna venta pendiente ni en contingencia, envía una sola vez sale.batch.settled con los conteos finales y fija settled_at. Cuenta la venta a la que apunta cada ítem, también la de un already_invoiced: un lote reenviado mientras las ventas originales siguen en contingencia no queda settled hasta que Hacienda las sella. Un lote que terminó con 40 ventas en contingencia envía settled cuando Hacienda sella la última. Un lote que termina sin nada en contingencia envía los dos, y a cada destino le llega settled solo después de que completed se entregó (o se dio por fallido tras sus reintentos). settled no espera a las ventas rejected ni failed, porque ninguna se resuelve sola: dice que el lote ya no cambia sin una acción del integrador, no que todo quedó sellado. Con sale.batch.settled basta para saber que el lote terminó; si counts.rejected o counts.failed no son 0, esas ventas se revisan con GET /sales/batches/{uuid}?status=rejected (o failed) y se corrigen. counts.differs dice cuántas de las already_invoiced llegaron con otro contenido, las mismas que traen differs: true. Las ventas de una empresa se procesan en tramos de 100, un tramo a la vez, y dos lotes de la misma empresa se turnan por tramo. Dentro de la ventana un tramo sale en un lote de Hacienda y el siguiente toma su turno sin esperar la respuesta; fuera de ella cada documento se envía solo y espera la suya, así que los lotes de una empresa terminan uno después de otro y tardan más.

Lotes de clientes y productos

POST /customers/batch y POST /products/batch crean o actualizan hasta 100 registros, enviados en la lista items: { "items": [ … ] }, con el mismo nombre en los dos. Cada elemento es el cuerpo del PUT correspondiente más su code. El lote cuenta como una sola petición para el límite.

status Significado
created Registro creado.
updated Registro actualizado.
unchanged Coincidía con lo guardado.
failed No se guardó; errors por campo y, si el caso tiene nombre, error_code.
error_code Cuándo
customer_already_exists, product_already_exists El documento o el código pertenecen a otro registro.
duplicate_in_batch El código se repite en el lote; solo se guarda el primero.