> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.useopenwrench.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fakturans livscykel och betalflöden i Buyer API

> Läs, godkänn och betala leverantörsfakturor med OpenWrench Buyer API, inklusive statusövergångar, AP-systemsynk, plattade exporter och massuppdateringar.

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:

```bash theme={null}
export BASE="https://api.useopenwrench.com/api/external"
export KEY="<your-api-key>"
export SECRET="<shared-secret>"
```

## Fakturastatusar

Fakturor bär en gemen `status`:

| Status                           | Betydelse                                                               |
| -------------------------------- | ----------------------------------------------------------------------- |
| `draft`                          | Leverantören redigerar fortfarande. **Aldrig synlig i köparläsningar.** |
| `pending`                        | Publicerad till dig, väntar på granskning.                              |
| `approved`                       | Godkänd för betalning.                                                  |
| `processing`                     | I din betalningskörning.                                                |
| `paid`                           | Avräknad.                                                               |
| `disputed`                       | Du har bestridit den (upprättad i appen).                               |
| `pastdue`, `transferred`, `void` | Åldrande, överlämnad och ogiltigförklarad.                              |

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

```bash theme={null}
# Väntande fakturor, nyast först
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/invoice/invoices?status=pending&sort_by=publishedAt&order=desc&limit=25"

# Endast antal
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/invoice/invoices/count_by?status=pending"

# En faktura
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/buyer/invoice/invoices/7710"
```

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](/buyer-api/files-and-attachments)).

### Filtrera efter entitetstyp

Lägg till `invoiceEntityType=work_order` eller `invoiceEntityType=project` till `GET /invoices`, `/invoices/count_by` och `/invoices/download` för att avgränsa till en flik; utelämna det för att få båda. `projectId` och `projectIdSeq` filtrerar till specifika projekt på samma sätt som `workOrderId` / `workOrderIdSeq` filtrerar till specifika arbetsordrar.

```bash theme={null}
# Endast projektfakturor för det här projektet
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/invoice/invoices?invoiceEntityType=project&projectId=482"
```

### 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:

```bash theme={null}
curl -X POST "$BASE/v1/buyer/invoice/status/approved" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "id": 7710 }'
```

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:

```bash theme={null}
curl -X POST "$BASE/v1/buyer/invoice/status/paid/by_work_order_id" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "workOrderId": "9001" }'
```

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, så en projektfaktura skapad utan `locationId` eller `buyerFacilityId` utesluts från 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:

```bash theme={null}
curl -X PATCH "$BASE/v1/buyer/invoice/bulk_update_with_filters" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "filters": { "status": "approved" }, "updates": { "status": "processing" } }'
```

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](/buyer-api/quotes-and-proposals) 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.