Hoppa till huvudinnehåll
Leverantörer fakturerar avslutade arbetsordrar via fakturor; Buyer API är där din AP-integration läser dem, för dem genom godkännande och markerar dem betalda. Fakturor kan även förankras till ett projekt i stället för en arbetsorder. Samma statusar och betalslutpunkter gäller, med skillnaderna beskrivna nedan. Alla exempel förutsätter:

Fakturastatusar

Fakturor bär en gemen status: Den köparkontrollerade vägen är pending → approved → processing → paid. Varje flytt har en dedikerad slutpunkt; det finns ingen generisk statussättare.

Läsa fakturor

En faktura länkar tillbaka till sitt supplierFacilityId plus exakt ett av workOrderId eller projectId (det andra är null, tillsammans med den hydrerade workOrder / project). Arbetsorderfakturor bär alltid locationId och buyerFacilityId; projektfakturor bär dem endast när klienten angav dem, så båda kan vara null. Fakturan bär pengauppdelningen i sektioner (arbete, material, resa, frakt, övrigt), var och en med rader, en taxRate och en totalBeforeTax, som rullar upp till invoiceTotalBeforeTax, invoiceTax och invoiceTotalAfterTax. Monetära värden serialiseras som strängar. En kort AI-härledd sammanfattning av omfattningen kan visas i title. Den renderade PDF:en finns i invoicePDFs; stödjande filer finns i attachments (se Filer och bilagor).

Lista, filtrera och räkna

GET /invoices, /invoices/count_by och /invoices/download tar samma filter från filterreferensen nedan. Filter kombineras med AND och kombineras alltid med tenant-avgränsningen som härleds från din nyckel. Leverantörsutkast och ogiltigförklarade fakturor returneras aldrig, oavsett vad du filtrerar på.
  • Sortering. sort_by stöder createdAt, invoiceTotalAfterTax, id, workOrderId, locationId, supplierFacilityId och buyerFacilityId. Utan sort_by kommer resultaten nyast först. När du sätter sort_by blir order som standard asc, så skicka order=desc för fallande ordning. Andra fält, till exempel publishedAt, går inte att sortera på; filtrera på ett publishedAt-fönster istället.
  • Okända filter ignoreras. Varje frågeparameter som inte finns i filterreferensen ignoreras istället för att avvisas, och anropet lyckas ändå. Innan du förlitar dig på ett nytt filter, jämför count_by med och utan det.

Filterreferens

Nycklarna är skiftlägeskänsliga. En nyckel i singular (status) tar ett värde; nyckeln i plural (statuses) tar en kommaseparerad lista och matchar något av värdena. Status Vad och var Vem och bokföring Datum

Regler för filtervärden

  • Använd pluralnyckeln för flera värden, utan mellanslag. statuses=approved,processing matchar någon av statusarna. status=approved,processing letar efter en enda status med just det namnet och returnerar ingenting. Ett mellanslag efter ett kommatecken i en id-lista kan få anropet att misslyckas.
  • Ett värde per nyckel. Om du upprepar en parameter används bara den första.
  • Datum använder MM/dd/yyyy HH:mm:ss, till exempel 08/01/2026 00:00:00. Värdet är en lokal klocktid som läses i den zon du anger i timezone, eller i UTC om den saknas. Tiden är obligatorisk. Startgränsen är inkluderande från den tid du skickar. Slutgränsen täcker hela slutdagen i den zonen: OpenWrench ersätter dess tid med 23:59:59. URL-koda värdet (curl -G --data-urlencode gör det åt dig). Lägg inte till en offset som -05:00 i värdet: OpenWrench ignorerar den.
  • Ett datum som inte kan tolkas returnerar 400 med Invalid <key>. Expected format MM/dd/yyyy HH:mm:ss. Det gäller även ISO 8601-värden (2026-10-09T00:00:00), datum utan tid (10/09/2026) och värden som bara består av mellanslag. OpenWrench läser fortfarande ett tomt värde som 1 januari 1970.
  • timezone tar ett IANA-zonnamn, som America/Chicago eller UTC. Fasta offset (-05:00, GMT-5), förkortningar (CST) och okända namn returnerar 400. Se Datumformat för sommartid.
  • Booleska värden är true eller false. Alla andra värden, eller ett icke-numeriskt id, kan få anropet att misslyckas med 500 istället för 400.
  • Tenant-avgränsningen kan inte åsidosättas. buyerCompanyId sätts alltid från din API-nyckel, så att skicka det har ingen effekt.
Om du vill matcha en lokal dag skickar du samma datum för båda gränserna tillsammans med din zon. Den här förfrågan returnerar fakturor som markerades som betalda den 9 oktober 2026, Central time:

Plattad export

GET /v1/buyer/invoice/invoices/download returnerar samma data som platta rader (en rad per faktura med totalsummorna denormaliserade), byggd för kalkylbladsexport och AP-systemimporter. Samma filter som list-slutpunkten. På projektfaktura-rader är workOrderId, workOrderTitle, problemTypeId, problemTypeName, locationId och locationName null; projectId är satt.

Flytta en faktura genom godkännande

Varje övergångsslutpunkt tar bara fakturans id:
De fyra slutpunkterna är status/pending, status/approved, status/processing och status/paid. Delat beteende:
  • Varje övergång rensar fakturans tvistflagga och sprider sedan en matchande statusändring till den associerade arbetsordern.
  • Om statusmappningen för arbetsordern misslyckas ogiltigförklaras fakturan och anropet returnerar 400. Behandla 400 här som “hämta om och inspektera”, inte “försök igen”.
  • Ett spar-nivåvalideringsfel returnerar 406.

Markera betald efter arbetsorder-id

När ditt AP-system känner till arbetsordern men inte OpenWrench-fakturans id, stäng loopen med:
Uppslagningen provar workOrderId först och faller tillbaka på externalWorkOrderId, alltid inom ditt företag. Redan paid fakturor returneras oförändrade (säkert att försöka igen); approved eller processing fakturor markeras som betalda; en faktura i någon annan status returnerar 400 med “Invoice not found”.

Projektfakturor

Projektfakturor är förankrade till ett projekt (projectId) i stället för en arbetsorder (workOrderId), och hoppar över arbetsordersidan av pipelinen. För en faktura utan workOrderId hoppar OpenWrench över:
  • NTE-kontrollen vid skapande och uppdatering.
  • Härledning av GL-kod från arbetsordern.
  • Speglingen av budgetutgifter och tillgångsutgifter.
  • Statussynken mot arbetsordern som normalt körs vid varje statusövergång (en statusövergång på en projektfaktura ogiltigförklarar aldrig och returnerar 400 för en trasig WO-mappning).
  • Tillägget av arbetsorderns detaljsida i faktura-PDF-verktyget.
  • WO-förankrade godkännandehierarkier och deras godkännande-, påminnelse- och eskaleringsnotifieringar.
  • Per-WO-dubblettkontrollen “en faktura per leverantör”.
  • Den valutabegränsade valideringen av taxLineItems (belopp valideras fortfarande som numeriska).
Analyser för kostnad-per-plats och kostnad-per-anläggning inkluderar endast fakturor som bär respektive fält. En projektfaktura skapad utan locationId eller buyerFacilityId visas inte i dessa rapporter. Genvägen POST status/paid/by_work_order_id matchar endast arbetsorderfakturor; för en projektfaktura, markera som betald via id med POST status/paid.

Verktyg

Lägg till arbetsorderdetaljsidan till PDF:en. PATCH /v1/buyer/invoice/file/invoice_pdf/add_work_order_detail_page/{invoiceId} genererar om fakturans PDF med arbetsorderdetaljsidan bifogad och returnerar den nya PDF-länken (höljestyp UpdatedInvoicePdf). Ingen förfrågan-kropp; inte hastighetsbegränsad. Massuppdatering med filter. PATCH /v1/buyer/invoice/bulk_update_with_filters tillämpar en kolumnuppdatering på varje faktura som matchar ett filter, alltid begränsat till ditt företag. Båda kartorna är fria kolumn→värde-mappningar:
Den returnerar antalet uppdaterade fakturor. Det här är ett kraftverktyg som förbigår sidoeffekterna från per-faktura-övergångar, så föredra statusslutpunkterna om du inte verkligen behöver en sweep. Inte hastighetsbegränsad. Publicera utkast för avslutade arbetsordrar. PATCH /v1/buyer/invoice/publish_draft_invoices_if_wo_complete_and_auto_publish_enabled publicerar leverantörsfakturautkast vars arbetsorder är klar, för leverantörer som aktiverade auto-publicering. Det kräver en super-admin köpar-API-nyckel och returnerar 403 för en vanlig nyckel. Avsett för schemalagda skötseljobb.

AP-synk-mönster

En robust leverantörsreskontrasynk:
  1. Polla GET /invoices?status=pending (eller publishedAt-fönster) enligt schema.
  2. Hämta varje faktura. För arbetsorderfakturor, matcha totalsummor mot det godkända förslaget och arbetsorderns nte. För projektfakturor, matcha mot din projektbudget i stället. NTE-kontrollen körs inte på serversidan för projektfakturor.
  3. POST status/approved, exportera till ditt AP-system och sedan POST status/processing.
  4. Vid avräkning, POST status/paid via id, eller status/paid/by_work_order_id med den arbetsorderreferens som ditt AP-system bär.
  5. Logga höljets traceId vid varje 400/406 så att supporten kan spåra den exakta förfrågan.