{"openapi":"3.1.1","info":{"title":"FretGuard invoice reading API","version":"1.0.1","description":"Documented read-only subset of the production FretGuard gateway API. Requires an authorized user access token (Bearer JWT), an organization and invoices:read permission. No public API-key provisioning is advertised.","contact":{"name":"FretGuard","email":"contact@fretguard.com"}},"servers":[{"url":"https://fretguard.com","description":"Production gateway"}],"externalDocs":{"description":"FretGuard developer documentation (French)","url":"https://fretguard.com/fr/developers"},"paths":{"/api/v1/invoices":{"get":{"operationId":"listInvoices","summary":"Read transport invoices","description":"Read invoices in the authenticated user organization. Requires a valid Bearer access token and invoices:read permission. The fg.session frontend cookie alone does not authenticate this gateway route.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–200, default 50).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"description":"Number of records to skip (default 0).","schema":{"type":"integer","minimum":0,"maximum":9007199254740991,"default":0}},{"name":"q","in":"query","required":false,"description":"Search text (trimmed).","schema":{"type":"string","maxLength":200}},{"name":"invoice_number","in":"query","required":false,"description":"Invoice number filter.","schema":{"type":"string"}},{"name":"supplier","in":"query","required":false,"description":"Supplier filter.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Start invoice date.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End invoice date.","schema":{"type":"string","format":"date"}},{"name":"status","in":"query","required":false,"description":"Document status.","schema":{"type":"string","enum":["UPLOADING","STORED","DUPLICATE","FAILED"]}},{"name":"invoice_status","in":"query","required":false,"description":"Analysis status.","schema":{"type":"string","enum":["unanalyzed","analyzed"]}},{"name":"analyzed","in":"query","required":false,"description":"Whether the invoice has been analyzed.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Paginated invoices for the authenticated organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoices"}}}},"401":{"description":"Missing, invalid or expired Bearer token, or missing organization.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/DetailError"}]}}}},"403":{"description":"Missing invoices:read permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid query parameter.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/DetailError"}]}}}},"503":{"description":"Authentication service unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Other gateway or Cloudflare failure. Content type and body may vary; inspect the HTTP status before parsing. Retry-After, when present, takes precedence for retries."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Authorized user access token. The HttpOnly fg.session cookie belongs to the frontend and is not a gateway credential. Contact FretGuard to arrange machine access; never share tokens in prompts."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}},"Invoice":{"type":"object","properties":{"original_filename":{"type":["string","null"]},"invoice_number":{"type":["string","null"]},"supplier":{"type":["string","null"]},"carrier_name":{"type":["string","null"]},"currency":{"type":["string","null"]},"amount_ht":{"type":["string","null"]},"amount_ttc":{"type":["string","null"]},"invoice_date":{"type":["string","null"]},"due_date":{"type":["string","null"]},"document_id":{"type":"string"},"status":{"type":"string"},"r2_key":{"type":"string"},"created_at":{"type":"string"},"analysis":{"type":["object","null"],"properties":{"anomalies":{"type":"number","description":"Sum of upstream error and warning counts."},"validation_event_id":{"type":"string"},"is_compliant":{"type":"boolean"},"savings_ht":{"type":["string","null"]},"analyzed_at":{"type":"string"}}},"invoice_status":{"type":"string","enum":["unanalyzed","analyzed"]}},"required":["original_filename","invoice_number","supplier","carrier_name","currency","amount_ht","amount_ttc","invoice_date","due_date","document_id","status","r2_key","created_at","analysis","invoice_status"]},"Invoices":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"total_count":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":200},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}},"required":["items","total_count","limit","offset","has_more"]},"DetailError":{"type":"object","required":["detail"],"properties":{"detail":{"description":"Legacy validation details or missing-organization information.","oneOf":[{"type":"string"},{"type":"object","additionalProperties":true},{"type":"array","items":{"type":"object","additionalProperties":true}}]}}}}}}