Saltar al contenido principal
Cuando el trabajo requiere un precio antes de continuar, los proveedores envían propuestas (cotizaciones) contra la orden de trabajo. A través de la Buyer API, las propuestas son de solo lectura: las listas, inspeccionas las líneas y las concilias con las facturas. La aprobación o rechazo de una propuesta ocurre en la app de OpenWrench. Todos los ejemplos asumen:

Estados de propuesta

Los estados se guardan en minúsculas.

Leer propuestas

Reglas de alcance que conviene conocer:
  • Los borradores no enviados de los proveedores siempre se excluyen de los listados.
  • Si el contacto de tu clave de API tiene restricción por ubicación, solo ves propuestas de las ubicaciones accesibles. Un contacto con un conjunto accesible vacío obtiene una página vacía, no un error.
  • La lectura individual devuelve 404 para propuestas eliminadas de forma lógica, borradores y propuestas fuera de tu alcance de ubicación. Trata 404 como “no visible para ti”, no necesariamente como “no existe”.

Referencia de filtros

El listado acepta 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 y por ubicación de tu clave. No hay endpoint de conteo: el count de la respuesta del listado es el número total de coincidencias, así que pide limit=1 cuando solo necesites el número.
Reglas de valores:
  • Ordenamiento. sort_by admite createdAt, updatedAt, totalAfterTax, id, workOrderId, locationId, supplierFacilityId y buyerFacilityId. Sin sort_by, o con cualquier otro valor, los resultados se ordenan por id ascendente (más antiguas primero). Una vez que estableces sort_by, order toma por defecto asc, así que envía order=desc para ver las más recientes primero.
  • Las listas llevan comas sin espacios. Una clave en singular (status) toma un valor; la clave en plural toma una lista separada por comas. Un espacio después de una coma puede hacer fallar la solicitud.
  • 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 el alcance por inquilino no se puede anular: buyerCompanyId siempre se establece a partir de tu clave de API, y los borradores se excluyen aunque pidas status=draft.
Para obtener un único día local, envía la misma fecha en ambos extremos junto con tu zona. Esta solicitud devuelve las propuestas adjudicadas el 9 de octubre de 2026, en hora central:

Dentro de una propuesta

El dinero se descompone en las mismas secciones que las facturas: laborLineItems, materialLineItems, travelLineItems, freightLineItems y miscLineItems, cada sección con su propia tasa de impuestos y ...TotalBeforeTax, que se suman a totalBeforeTax, tax y totalAfterTax. Los valores monetarios se serializan como cadenas; parséalos como decimales, no como floats, si vas a hacer aritmética. Otros campos útiles: workOrderId, supplierFacilityId, workOrderNTEBeforeApproval (el not-to-exceed de la orden de trabajo al momento del envío), proposalPdfLink, attachments, submittedAt y approvedAt.

Dónde encajan las propuestas en el flujo

  1. El proveedor envía una propuesta; la orden de trabajo suele pausarse a la espera de aprobación.
  2. Tus aprobadores la otorgan o la rechazan en la app. Otorgarla eleva el techo de gasto efectivo para el trabajo.
  3. Cuando llega la factura final, compara invoiceTotalAfterTax con el totalAfterTax de la propuesta otorgada antes de aprobar el pago. Marca las variaciones por encima de tu tolerancia para revisión humana.
Un ciclo práctico de sondeo para un tablero de compras: filtra status=pending, ordena con sort_by=createdAt&order=desc y pagina con limit=25, respetando el límite de tasa de 10 solicitudes por ventana de 20 segundos.