Saltar al contenido principal
El dinero fluye por dos objetos: propuestas (cotizaciones que el comprador aprueba antes de que proceda el trabajo) y facturas (la cuenta por el trabajo completado). Los proveedores crean ambos a través de esta API.
Ninguno de los endpoints está disponible para claves de equipo interno de servicio; la cotización y facturación son para proveedores terceros que facturan a un comprador.
Todos los ejemplos asumen:

El dinero son cadenas, en secciones

Las propuestas y facturas comparten una estructura de líneas. Los montos son cadenas que deben parsearse como números (“450.00”, no 450.00 como float; deberías formatear con dos decimales y parsear como decimales). Las secciones son labor, material, viaje, flete y misc (las propuestas añaden costo incurrido). Cada una tiene sus líneas, tasa de impuestos y ...TotalBeforeTax, que se suman a los totales antes de impuestos, impuestos y después de impuestos. Las líneas de viaje, flete y misc son objetos simples { "description", "amount" }.

Propuestas (cotizaciones)

POST /v1/supplier/quote/proposals crea la propuesta directamente en estado pending bajo tu instalación; no hay un paso separado de envío. Requerido: workOrderId y totalAfterTax.
Comportamiento a conocer:
  • locationId, buyerFacilityId y buyerCompanyId se derivan de la orden de trabajo; no puedes establecerlos.
  • Los campos de impuestos y totales de sección no establecidos toman por defecto "0".
  • requestForProposalId toma por defecto el RFP de la orden de trabajo cuando se omite.
  • proposalPdfLink, si se envía, debe ser una URL válida. attachments toma FileDetails del endpoint de subida de archivos.
  • Pasar un id actualiza una propuesta existente.
Rastrea el resultado volviendo a consultar: status se mueve de pending a awarded o declined (los motivos del rechazo aparecen en declineNotes). Lista con GET /v1/supplier/quote/proposals (ver filtrar listados), lee una con GET /v1/supplier/quote/proposals/{id}.

Facturas

El ciclo de vida

Las facturas empiezan como draft (invisibles para el comprador), se publican a pending, y luego el comprador las mueve por approved y processing hasta paid (o las disputa). Tu integración crea el borrador y lo publica; a partir de pending, mayormente estás leyendo estado.

Crear el borrador

POST /v1/supplier/invoice/invoices requiere workOrderId; locationId, buyerFacilityId, buyerCompanyId, spendCategoryId y problemTypeId se derivan de él.
Comportamiento a tener en cuenta:
  • poNumber toma por defecto el PO number de la orden de trabajo.
  • serviceCallIds toma por defecto todas las llamadas de servicio de la orden de trabajo cuando se omite o está vacío; establécelo explícitamente cuando factures un subconjunto de visitas.
  • OpenWrench valida taxLineItems contra los tipos de impuestos permitidos por la moneda de la factura y rechaza cualquier otro. Actualmente solo CAD los soporta (GST/HST/PST).
  • invoicePDFLink (una URL válida) se convierte en la única entrada de PDF de la factura si alojas tú mismo el PDF; la mayoría de integraciones usa en su lugar el endpoint de subida más abajo.
  • autoPublishOnApproval inscribe esta factura en la auto-publicación cuando la orden de trabajo se completa.
  • Guardar una factura puede transicionar el estado de la orden de trabajo asociada según el mapeo de estado factura-a-orden. Un fallo de validación a nivel de guardado devuelve 406.
  • Pasar un id actualiza una factura existente (solo borradores, en la práctica; los estados del lado del comprador no son tuyos para editar).

Subir el PDF y publicar

POST /v1/supplier/invoice/file/upload_and_publish/{invoiceId} hace ambos pasos a la vez: el PDF subido (parte multipart file, máx. 512 MB) se convierte en el único PDF de la factura, y el estado pasa a pending.
El endpoint devuelve 400 si falla alguna precondición: tu instalación debe ser dueña de la factura, la orden de trabajo asociada debe estar en display status Completed, y la configuración del comprador debe permitir la edición de facturas por proveedor.

Leer y conciliar

GET /v1/supplier/invoice/invoices (filtrable, ver filtrar listados) y GET /v1/supplier/invoice/invoices/{id}. Los proveedores terceros ven registros enmascarados con los campos privados del comprador en blanco. Consulta el estado por sondeo para alimentar tu libro AR: approvedAt, processedAt y markedPaidAt marcan la progresión del comprador.

Filtrar listados

GET /v1/supplier/quote/proposals y GET /v1/supplier/invoice/invoices aceptan offset, limit (por defecto 10, máx. 25), sort_by y order, además de los filtros de abajo. Los filtros se combinan con AND, y siempre se combinan con el alcance por inquilino de tu clave, así que solo ves las propuestas y facturas de tu instalación. Ninguno de los dos listados tiene endpoint de conteo; el count de la respuesta es el número total de coincidencias.
Ambos listados Solo propuestas Solo facturas Reglas de valores:
  • Ordenamiento. Ambos listados se ordenan por createdAt, id, workOrderId, locationId, supplierFacilityId o buyerFacilityId; las facturas también por invoiceTotalAfterTax, y las propuestas por updatedAt y totalAfterTax. Una vez que estableces sort_by, order toma por defecto asc, así que envía order=desc para ver los más recientes primero. Sin sort_by, las facturas llegan de más reciente a más antigua y las propuestas en orden de id (más antiguas primero). Un sort_by no admitido en propuestas también recae en el orden por id.
  • Las listas llevan comas sin espacios. Una clave en singular (status) toma un valor; la clave en plural toma una lista separada por comas. status=pending,approved busca un único estado con ese nombre literal y no devuelve nada. Un espacio después de una coma 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. 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 valores deben estar bien formados. Un id no numérico, o un booleano distinto de true o false, puede hacer fallar la solicitud con un 500 en lugar de un 400.
  • Los filtros no reconocidos se ignoran, y tu alcance por inquilino no se puede anular: supplierFacilityId siempre se establece a partir de tu clave de API.
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:

Flujo de facturación de extremo a extremo

  1. La orden de trabajo llega a cotización: envía una propuesta y espera awarded.
  2. Completa el trabajo mediante el check-out de la llamada de servicio.
  3. Crea la factura en borrador; genera tu PDF.
  4. Una vez que la orden de trabajo aparezca como Completed, upload_and_publish.
  5. Consulta el estado de la factura por sondeo hasta paid, y concilia contra markedPaidAt.