Saltar al contenido principal
Los proveedores facturan las órdenes de trabajo completadas mediante facturas; la Buyer API es donde tu integración con AP las lee, las mueve por la aprobación y las marca como pagadas. Las facturas también pueden anclarse a un proyecto en lugar de una orden de trabajo. Aplican los mismos estados y endpoints de pago, con las diferencias señaladas a continuación. Todos los ejemplos asumen:

Estados de factura

Las facturas llevan un status en minúsculas: La ruta controlada por el comprador es pending → approved → processing → paid. Cada movimiento tiene un endpoint dedicado; no hay un setter de estado genérico.

Leer facturas

Una factura enlaza de vuelta a su supplierFacilityId más exactamente uno de workOrderId o projectId (el otro es null, junto con el workOrder / project hidratado). Las facturas de orden de trabajo siempre llevan locationId y buyerFacilityId; las facturas de proyecto los llevan solo cuando el cliente los proporcionó, por lo que ambos pueden ser null. La factura lleva el desglose monetario en secciones (labor, material, viaje, flete, misc), cada una con líneas, una taxRate y un totalBeforeTax, que se suman a invoiceTotalBeforeTax, invoiceTax e invoiceTotalAfterTax. Los valores monetarios se serializan como cadenas. Un breve resumen del alcance derivado por IA puede aparecer en title. El PDF renderizado está en invoicePDFs; los archivos de soporte están en attachments (ver Archivos y adjuntos).

Listar, filtrar y contar

GET /invoices, /invoices/count_by y /invoices/download aceptan los mismos filtros de la referencia de filtros que aparece más abajo. Los filtros se combinan con AND, y siempre se combinan con el alcance por inquilino derivado de tu clave. Los borradores del proveedor y las facturas anuladas nunca se devuelven, sea cual sea el filtro.
  • Ordenamiento. sort_by admite createdAt, invoiceTotalAfterTax, id, workOrderId, locationId, supplierFacilityId y buyerFacilityId. Sin sort_by, los resultados llegan de más reciente a más antiguo. Una vez que estableces sort_by, order toma por defecto asc, así que envía order=desc para orden descendente. Otros campos, como publishedAt, no se pueden ordenar; filtra por una ventana de publishedAt en su lugar.
  • Los filtros no reconocidos se ignoran. Cualquier parámetro de consulta que no esté en la referencia de filtros se ignora en lugar de rechazarse, y la solicitud igualmente tiene éxito. Antes de depender de un filtro nuevo, compara count_by con y sin él.

Referencia de filtros

Las claves distinguen entre mayúsculas y minúsculas. Una clave en singular (status) toma un valor; la clave en plural (statuses) toma una lista separada por comas y coincide con cualquiera de los valores. Estado Qué y dónde Quién y contabilidad Fechas

Reglas de valores de filtro

  • Usa la clave en plural para varios valores, sin espacios. statuses=approved,processing coincide con cualquiera de los dos estados. status=approved,processing busca un único estado con ese nombre literal y no devuelve nada. Un espacio después de una coma en una lista de ids puede hacer fallar la solicitud.
  • Un valor por clave. Si repites un parámetro, solo se usa el primero.
  • Las fechas usan MM/dd/yyyy HH:mm:ss, por ejemplo 08/01/2026 00:00:00. El valor es una hora local de reloj, interpretada en la zona que pases en timezone, o en UTC si no lo pasas. La hora es obligatoria. El extremo inicial es inclusivo a partir de la hora que envías. El extremo final cubre todo el día final en esa zona: OpenWrench reemplaza su hora por 23:59:59. Codifica el valor para URL (curl -G --data-urlencode lo hace por ti). No añadas un offset como -05:00 al valor: OpenWrench lo ignora.
  • Una fecha que no se puede interpretar devuelve 400 con Invalid <key>. Expected format MM/dd/yyyy HH:mm:ss. Eso incluye valores ISO 8601 (2026-10-09T00:00:00), fechas sin hora (10/09/2026) y valores formados solo por espacios. OpenWrench sigue leyendo un valor vacío como 1 de enero de 1970.
  • timezone acepta un nombre de zona IANA, como America/Chicago o UTC. Los offsets fijos (-05:00, GMT-5), las abreviaturas (CST) y los nombres desconocidos devuelven 400. Consulta Formatos de fecha para el horario de verano.
  • Los booleanos son true o false. Cualquier otro valor, o un id no numérico, puede hacer fallar la solicitud con un 500 en lugar de un 400.
  • El alcance por inquilino no se puede anular. buyerCompanyId siempre se establece a partir de tu clave de API, así que pasarlo no tiene efecto.
Para obtener un único día local, envía la misma fecha en ambos extremos junto con tu zona. Esta solicitud devuelve las facturas marcadas como pagadas el 9 de octubre de 2026, en hora central:

Exportación aplanada

GET /v1/buyer/invoice/invoices/download devuelve los mismos datos como filas planas (una fila por factura con los totales desnormalizados), pensado para exportación a hoja de cálculo e importaciones en sistemas AP. Mismos filtros que el endpoint de listado. En las filas de facturas de proyecto, workOrderId, workOrderTitle, problemTypeId, problemTypeName, locationId y locationName son null; projectId está definido.

Mover una factura por la aprobación

Cada endpoint de transición toma solo el id de la factura:
Los cuatro endpoints son status/pending, status/approved, status/processing y status/paid. Comportamiento compartido:
  • Cada transición borra la marca de disputa de la factura y luego propaga un cambio de estado equivalente a la orden de trabajo asociada.
  • Si el mapeo del estado de la orden de trabajo falla, la factura se anula y la llamada devuelve 400. Trata un 400 aquí como “vuelve a consultar e inspecciona”, no como “reintentar”.
  • Un fallo de validación a nivel de guardado devuelve 406.

Marcar como pagada por id de orden de trabajo

Cuando tu sistema AP conoce la orden de trabajo pero no el id de factura de OpenWrench, cierra el ciclo con:
La búsqueda prueba primero con workOrderId y recae en externalWorkOrderId, siempre dentro de tu empresa. Las facturas ya paid se devuelven sin cambios (seguro reintentar); las facturas approved o processing se marcan como pagadas; una factura en cualquier otro estado devuelve 400 con “Invoice not found”.

Facturas de proyecto

Las facturas de proyecto se anclan a un proyecto (projectId) en lugar de a una orden de trabajo (workOrderId), y omiten el lado de orden de trabajo del pipeline. Para una factura sin workOrderId, OpenWrench omite:
  • La verificación de NTE al crear y actualizar.
  • La derivación de código GL a partir de la orden de trabajo.
  • El reflejo del gasto de presupuesto y del gasto de activos.
  • La sincronización de estado de orden de trabajo que normalmente se ejecuta en cada transición de estado (una transición de estado en una factura de proyecto nunca se anula ni devuelve 400 por un mapeo roto de la orden de trabajo).
  • La adición de la página de detalle de la orden de trabajo en la utilidad del PDF de la factura.
  • Las jerarquías de aprobación ancladas a orden de trabajo y sus notificaciones de aprobación / recordatorio / escalación.
  • La verificación por orden de trabajo de “una factura por proveedor” para duplicados.
  • La validación con alcance de moneda sobre taxLineItems (los montos aún se validan como numéricos).
Las analíticas de costo por ubicación y costo por instalación solo incluyen facturas que llevan el campo respectivo. Una factura de proyecto creada sin locationId o buyerFacilityId no aparece en esos reportes. El atajo POST status/paid/by_work_order_id solo coincide con facturas de orden de trabajo; para una factura de proyecto, márcala como pagada por id mediante POST status/paid.

Utilidades

Añadir la página de detalle de la orden de trabajo al PDF. PATCH /v1/buyer/invoice/file/invoice_pdf/add_work_order_detail_page/{invoiceId} regenera el PDF de la factura con la página de detalle de la orden de trabajo añadida y devuelve el nuevo enlace del PDF (envoltura tipo UpdatedInvoicePdf). Sin cuerpo de solicitud; sin límite de tasa. Actualización masiva con filtros. PATCH /v1/buyer/invoice/bulk_update_with_filters aplica una actualización de columna a cada factura que coincide con un filtro, siempre limitado a tu empresa. Ambos mapas son de formato libre columna→valor:
Devuelve el número de facturas actualizadas. Es una herramienta potente que salta los efectos secundarios de la transición por factura, así que prefiere los endpoints de estado a menos que realmente necesites un barrido. Sin límite de tasa. Publicar borradores de órdenes de trabajo completadas. PATCH /v1/buyer/invoice/publish_draft_invoices_if_wo_complete_and_auto_publish_enabled publica facturas en borrador del proveedor cuya orden de trabajo esté completa, para proveedores que habilitaron la auto-publicación. Requiere una clave de API de super-admin de comprador y devuelve 403 para una clave normal. Está pensado para trabajos programados de mantenimiento.

Patrón de sincronización con AP

Una sincronización robusta de cuentas por pagar:
  1. Consulta GET /invoices?status=pending (o ventanas de publishedAt) según programación.
  2. Descarga cada factura. Para facturas de orden de trabajo, contrasta los totales con la propuesta aprobada y el nte de la orden de trabajo. Para facturas de proyecto, contrasta con tu presupuesto de proyecto en su lugar. La verificación de NTE no se ejecuta del lado del servidor para facturas de proyecto.
  3. POST status/approved, exporta a tu sistema AP y luego POST status/processing.
  4. En la liquidación, POST status/paid por id, o status/paid/by_work_order_id con la referencia de la orden de trabajo que lleva tu sistema AP.
  5. Registra el traceId de la envoltura en cualquier 400/406 para que soporte pueda rastrear la solicitud exacta.