Fakturastatusar
Fakturor bär en gemenstatus:
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
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_bystödercreatedAt,invoiceTotalAfterTax,id,workOrderId,locationId,supplierFacilityIdochbuyerFacilityId. Utansort_bykommer resultaten nyast först. När du sättersort_byblirordersom standardasc, så skickaorder=descför fallande ordning. Andra fält, till exempelpublishedAt, går inte att sortera på; filtrera på ettpublishedAt-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_bymed 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,processingmatchar någon av statusarna.status=approved,processingletar 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 exempel08/01/2026 00:00:00. Värdet är en lokal klocktid som läses i den zon du anger itimezone, 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-urlencodegör det åt dig). Lägg inte till en offset som-05:00i värdet: OpenWrench ignorerar den. - Ett datum som inte kan tolkas returnerar
400medInvalid <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. timezonetar ett IANA-zonnamn, somAmerica/ChicagoellerUTC. Fasta offset (-05:00,GMT-5), förkortningar (CST) och okända namn returnerar400. Se Datumformat för sommartid.- Booleska värden är
trueellerfalse. Alla andra värden, eller ett icke-numeriskt id, kan få anropet att misslyckas med500istället för400. - Tenant-avgränsningen kan inte åsidosättas.
buyerCompanyIdsätts alltid från din API-nyckel, så att skicka det har ingen effekt.
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: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. Behandla400hä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: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
400fö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).
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:
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:- Polla
GET /invoices?status=pending(ellerpublishedAt-fönster) enligt schema. - 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. POST status/approved, exportera till ditt AP-system och sedanPOST status/processing.- Vid avräkning,
POST status/paidvia id, ellerstatus/paid/by_work_order_idmed den arbetsorderreferens som ditt AP-system bär. - Logga höljets
traceIdvid varje400/406så att supporten kan spåra den exakta förfrågan.