{"openapi":"3.1.0","info":{"title":"Remittax API","version":"1","description":"Create and track Form 146 and Form 145 certificates, vendors and invoices from your own systems. JSON keys are snake_case, money is a decimal string and dates are ISO 8601."},"servers":[{"url":"https://apps.remittax.com"}],"tags":[{"name":"Certificates","description":"Requests and certificates: create, move through the stages, record acknowledgements, download the forms, and match payments to invoices."},{"name":"Vendors","description":"The foreign parties paid, with their TRC, Form 10F and no-PE declarations."},{"name":"Invoices","description":"Vendor invoices and what is still open on each."},{"name":"Companies","description":"The remitting companies and their bank accounts."},{"name":"Documents","description":"Files attached to a certificate. Files never travel in the JSON body: ask for an upload URL, PUT the file there, then record it."}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key from Settings → API keys: rmx_live_… or rmx_test_…"}},"schemas":{"Problem":{"type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/api/v1/certificates":{"get":{"operationId":"get_certificates","summary":"List certificates","description":"Newest first. Filter by client group, company or stage, or changes since a time.","tags":["Certificates"],"security":[{"apiKey":["certificates:read"]}],"x-scope":"certificates:read","parameters":[{"name":"client_group_id","in":"query","required":false,"schema":{"description":"Only this client group.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Only this client group."},{"name":"limit","in":"query","required":false,"schema":{"description":"How many to return, 1 to 100. Default 50.","type":"string"},"description":"How many to return, 1 to 100. Default 50."},{"name":"cursor","in":"query","required":false,"schema":{"description":"The next_cursor from the previous page.","type":"string"},"description":"The next_cursor from the previous page."},{"name":"company_id","in":"query","required":false,"schema":{"description":"Only this company.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Only this company."},{"name":"stage","in":"query","required":false,"schema":{"type":"string","enum":["draft","in_progress","on_hold","ready_to_file","form_145_pending","filed","rejected"]}},{"name":"updated_since","in":"query","required":false,"schema":{"description":"Only certificates changed at or after this time.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"description":"Only certificates changed at or after this time."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"post_certificates","summary":"Raise a request","description":"Creates a draft certificate for a company. A firm key may leave out ca_firm_id.","tags":["Certificates"],"security":[{"apiKey":["certificates:write"]}],"x-scope":"certificates:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Any unique string, such as a UUID. A retry with the same key and body returns the first response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ca_firm_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"vendor_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"bank_account_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"signatory_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"nature_code":{"type":["string","null"]},"country_code":{"description":"ISO 3166 alpha-2 such as DE, or the income-tax portal's code such as 49. Kept and returned as the portal code.","anyOf":[{"type":"string","maxLength":4},{"type":"null"}]},"currency":{"type":"string","minLength":3,"maxLength":3},"amount":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,6})?$"},"fx_rate":{"anyOf":[{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,6})?$"},{"type":"null"}]},"proposed_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"accrual_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"deduction_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"recorded_in_books":{"type":"boolean"},"grossed_up":{"type":"boolean"},"client_notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"details":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"tags":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":40}},"allocations":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"invoice_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"amount":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,6})?$"}},"required":["invoice_id","amount"]}}},"required":["company_id","currency","amount"]},"example":{"company_id":"3f6c2a9e-1b7d-4c55-9a43-2f8e0d6b1c7a","ca_firm_id":"3f6c2a9e-1b7d-4c55-9a43-2f8e0d6b1c7a","vendor_id":"3f6c2a9e-1b7d-4c55-9a43-2f8e0d6b1c7a","bank_account_id":"3f6c2a9e-1b7d-4c55-9a43-2f8e0d6b1c7a","signatory_id":"3f6c2a9e-1b7d-4c55-9a43-2f8e0d6b1c7a","nature_code":"16.21","country_code":"DE","currency":"EUR","amount":"24500.00","fx_rate":"24500.00","proposed_date":"2026-10-20","accrual_date":"2026-10-20","deduction_date":"2026-10-20","recorded_in_books":false,"grossed_up":false,"client_notes":"Second instalment of the annual licence fee","details":"x","tags":["x"],"allocations":[{"invoice_id":"3f6c2a9e-1b7d-4c55-9a43-2f8e0d6b1c7a","amount":"24500.00"}]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/certificates/{id}":{"get":{"operationId":"get_certificates_by_id","summary":"Get a certificate","tags":["Certificates"],"security":[{"apiKey":["certificates:read"]}],"x-scope":"certificates:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/certificates/{id}/stage":{"post":{"operationId":"post_certificates_by_id_stage","summary":"Move a certificate","description":"Accept (in_progress), hold (on_hold, with a note), reject (rejected, with a note), mark ready_to_file or reopen (draft). Send the version you read; a newer version gets 409 version_conflict.","tags":["Certificates"],"security":[{"apiKey":["certificates:write"]}],"x-scope":"certificates:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Any unique string, such as a UUID. A retry with the same key and body returns the first response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","enum":["draft","in_progress","on_hold","ready_to_file","form_145_pending","filed","rejected"]},"note":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"expected_version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["to","expected_version"]},"example":{"to":"draft","note":"Filed on the portal","expected_version":1}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/certificates/{id}/acknowledgements":{"post":{"operationId":"post_certificates_by_id_acknowledgements","summary":"Record a Form 146 or Form 145 acknowledgement","tags":["Certificates"],"security":[{"apiKey":["certificates:write"]}],"x-scope":"certificates:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Any unique string, such as a UUID. A retry with the same key and body returns the first response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"form":{"type":"string","const":"form146"},"ack_no":{"type":"string"},"filed_on":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"udin":{"type":"string"},"has_ao_order":{"type":"boolean"},"expected_version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["form","ack_no","filed_on","udin","expected_version"]},{"type":"object","properties":{"form":{"type":"string","const":"form145"},"ack_no":{"type":"string"},"filed_on":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"expected_version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["form","ack_no","filed_on","expected_version"]}]},"example":{"form":"form146","ack_no":"x","filed_on":"2026-10-20","udin":"x","has_ao_order":false,"expected_version":1}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/certificates/{id}/files/{kind}":{"get":{"operationId":"get_certificates_by_id_files_by_kind","summary":"Download a certificate's file","description":"Form 146 JSON, Form 145 data, the PDF certificate, or (certificates made before Form 146) 15CB/15CA XML.","tags":["Certificates"],"security":[{"apiKey":["certificates:read"]}],"x-scope":"certificates:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["form146","form145","pdf","15cb-xml","15ca-xml"]}}],"responses":{"200":{"description":"The file","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/certificates/{id}/allocations":{"post":{"operationId":"post_certificates_by_id_allocations","summary":"Pay an invoice from a certificate","tags":["Certificates"],"security":[{"apiKey":["certificates:write"]}],"x-scope":"certificates:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Any unique string, such as a UUID. A retry with the same key and body returns the first response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"amount":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,6})?$"}},"required":["invoice_id","amount"]},"example":{"invoice_id":"3f6c2a9e-1b7d-4c55-9a43-2f8e0d6b1c7a","amount":"24500.00"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/allocations/{id}":{"patch":{"operationId":"patch_allocations_by_id","summary":"Change an allocation's amount","tags":["Certificates"],"security":[{"apiKey":["certificates:write"]}],"x-scope":"certificates:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,6})?$"}},"required":["amount"]},"example":{"amount":"24500.00"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"delete_allocations_by_id","summary":"Remove an allocation","tags":["Certificates"],"security":[{"apiKey":["certificates:write"]}],"x-scope":"certificates:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"204":{"description":"Done, nothing to return"},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/vendors":{"get":{"operationId":"get_vendors","summary":"List vendors","tags":["Vendors"],"security":[{"apiKey":["vendors:read"]}],"x-scope":"vendors:read","parameters":[{"name":"client_group_id","in":"query","required":false,"schema":{"description":"Only this client group.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Only this client group."},{"name":"limit","in":"query","required":false,"schema":{"description":"How many to return, 1 to 100. Default 50.","type":"string"},"description":"How many to return, 1 to 100. Default 50."},{"name":"cursor","in":"query","required":false,"schema":{"description":"The next_cursor from the previous page.","type":"string"},"description":"The next_cursor from the previous page."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"post_vendors","summary":"Add a vendor","tags":["Vendors"],"security":[{"apiKey":["vendors:write"]}],"x-scope":"vendors:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Any unique string, such as a UUID. A retry with the same key and body returns the first response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_group_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","maxLength":200},"entity_type":{"anyOf":[{"type":"string","enum":["company","individual"]},{"type":"null"}]},"salutation":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"pan":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"tax_id":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"default_currency":{"anyOf":[{"type":"string","minLength":3,"maxLength":3},{"type":"null"}]},"flat_door_block":{"type":["string","null"]},"premises":{"type":["string","null"]},"road":{"type":["string","null"]},"area":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country_code":{"description":"ISO 3166 alpha-2 such as DE, or the income-tax portal's code such as 49. Kept and returned as the portal code.","anyOf":[{"type":"string","maxLength":4},{"type":"null"}]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"external_ref":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]}},"required":["name"]},"example":{"client_group_id":"3f6c2a9e-1b7d-4c55-9a43-2f8e0d6b1c7a","name":"Nordlicht GmbH","entity_type":"company","salutation":"x","pan":"AAACN1234Q","tax_id":"x","default_currency":"EUR","flat_door_block":"x","premises":"x","road":"x","area":"x","city":"x","region":"x","postal_code":"x","country_code":"DE","email":"accounts@example.com","phone":"x","external_ref":"x"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/vendors/{id}":{"get":{"operationId":"get_vendors_by_id","summary":"Get a vendor with its tax documents","tags":["Vendors"],"security":[{"apiKey":["vendors:read"]}],"x-scope":"vendors:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"patch_vendors_by_id","summary":"Change a vendor","description":"Send only the fields to change; null clears a field.","tags":["Vendors"],"security":[{"apiKey":["vendors:write"]}],"x-scope":"vendors:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"entity_type":{"anyOf":[{"type":"string","enum":["company","individual"]},{"type":"null"}]},"salutation":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"pan":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"tax_id":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"default_currency":{"anyOf":[{"type":"string","minLength":3,"maxLength":3},{"type":"null"}]},"flat_door_block":{"type":["string","null"]},"premises":{"type":["string","null"]},"road":{"type":["string","null"]},"area":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country_code":{"description":"ISO 3166 alpha-2 such as DE, or the income-tax portal's code such as 49. Kept and returned as the portal code.","anyOf":[{"type":"string","maxLength":4},{"type":"null"}]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"external_ref":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]}}},"example":{"name":"Nordlicht GmbH","entity_type":"company","salutation":"x","pan":"AAACN1234Q","tax_id":"x","default_currency":"EUR","flat_door_block":"x","premises":"x","road":"x","area":"x","city":"x","region":"x","postal_code":"x","country_code":"DE","email":"accounts@example.com","phone":"x","external_ref":"x"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/vendors/{id}/documents/uploads":{"post":{"operationId":"post_vendors_by_id_documents_uploads","summary":"Get an upload URL for a tax document","description":"PUT the file to upload_url with the content type, then record it.","tags":["Vendors"],"security":[{"apiKey":["vendors:write"]}],"x-scope":"vendors:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Any unique string, such as a UUID. A retry with the same key and body returns the first response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file_name":{"type":"string","minLength":1,"maxLength":255},"size":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["file_name","size"]},"example":{"file_name":"trc-2026.pdf","size":182044}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/vendors/{id}/documents":{"post":{"operationId":"post_vendors_by_id_documents","summary":"Record a vendor's TRC, Form 10F or no-PE declaration","tags":["Vendors"],"security":[{"apiKey":["vendors:write"]}],"x-scope":"vendors:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Any unique string, such as a UUID. A retry with the same key and body returns the first response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"financial_year":{"type":"string"},"kind":{"type":"string","enum":["trc","form_10f","no_pe"]},"status":{"type":"string","enum":["provided","not_applicable"]},"valid_until":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"signed_on":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"path":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"file_name":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["financial_year","kind","status"]},"example":{"financial_year":"2026-27","kind":"trc","status":"provided","valid_until":"2026-10-20","signed_on":"2026-10-20","path":"x","file_name":"trc-2026.pdf"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/invoices":{"get":{"operationId":"get_invoices","summary":"List invoices","tags":["Invoices"],"security":[{"apiKey":["invoices:read"]}],"x-scope":"invoices:read","parameters":[{"name":"client_group_id","in":"query","required":false,"schema":{"description":"Only this client group.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Only this client group."},{"name":"limit","in":"query","required":false,"schema":{"description":"How many to return, 1 to 100. Default 50.","type":"string"},"description":"How many to return, 1 to 100. Default 50."},{"name":"cursor","in":"query","required":false,"schema":{"description":"The next_cursor from the previous page.","type":"string"},"description":"The next_cursor from the previous page."},{"name":"vendor_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["unpaid","part_paid","paid"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"post_invoices","summary":"Add an invoice","tags":["Invoices"],"security":[{"apiKey":["invoices:write"]}],"x-scope":"invoices:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Any unique string, such as a UUID. A retry with the same key and body returns the first response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"vendor_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"number":{"type":"string","maxLength":80},"invoice_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"currency":{"type":"string","minLength":3,"maxLength":3},"total_amount":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,6})?$"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]}},"required":["company_id","vendor_id","number","currency","total_amount"]},"example":{"company_id":"3f6c2a9e-1b7d-4c55-9a43-2f8e0d6b1c7a","vendor_id":"3f6c2a9e-1b7d-4c55-9a43-2f8e0d6b1c7a","number":"INV-2026-0142","invoice_date":"2026-10-20","currency":"EUR","total_amount":"24500.00","description":"Engineering services, September 2026"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/invoices/{id}":{"get":{"operationId":"get_invoices_by_id","summary":"Get an invoice with its balance","tags":["Invoices"],"security":[{"apiKey":["invoices:read"]}],"x-scope":"invoices:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"patch_invoices_by_id","summary":"Change an invoice, with a reason","description":"Every change is kept in the invoice's history with the reason. Send the version you read.","tags":["Invoices"],"security":[{"apiKey":["invoices:write"]}],"x-scope":"invoices:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","maxLength":80},"invoice_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"currency":{"type":"string","minLength":3,"maxLength":3},"total_amount":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,6})?$"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"reason":{"type":"string","minLength":1,"maxLength":500},"expected_version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["reason","expected_version"]},"example":{"number":"INV-2026-0142","invoice_date":"2026-10-20","currency":"EUR","total_amount":"24500.00","description":"Engineering services, September 2026","reason":"Corrected the total","expected_version":1}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/companies":{"get":{"operationId":"get_companies","summary":"List companies","tags":["Companies"],"security":[{"apiKey":["companies:read"]}],"x-scope":"companies:read","parameters":[{"name":"client_group_id","in":"query","required":false,"schema":{"description":"Only this client group.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":"Only this client group."},{"name":"limit","in":"query","required":false,"schema":{"description":"How many to return, 1 to 100. Default 50.","type":"string"},"description":"How many to return, 1 to 100. Default 50."},{"name":"cursor","in":"query","required":false,"schema":{"description":"The next_cursor from the previous page.","type":"string"},"description":"The next_cursor from the previous page."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/companies/{id}/bank_accounts":{"get":{"operationId":"get_companies_by_id_bank_accounts","summary":"List a company's bank accounts","tags":["Companies"],"security":[{"apiKey":["companies:read"]}],"x-scope":"companies:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/certificates/{id}/documents/uploads":{"post":{"operationId":"post_certificates_by_id_documents_uploads","summary":"Get an upload URL for a certificate document","tags":["Documents"],"security":[{"apiKey":["documents:write"]}],"x-scope":"documents:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Any unique string, such as a UUID. A retry with the same key and body returns the first response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file_name":{"type":"string","minLength":1,"maxLength":255},"size":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["file_name","size"]},"example":{"file_name":"trc-2026.pdf","size":182044}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/certificates/{id}/documents":{"post":{"operationId":"post_certificates_by_id_documents","summary":"Record an uploaded certificate document","tags":["Documents"],"security":[{"apiKey":["documents:write"]}],"x-scope":"documents:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255},"description":"Any unique string, such as a UUID. A retry with the same key and body returns the first response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["invoice","agreement","tax_opinion","form146_ack","form145_ack","other"]},"file_name":{"type":"string","minLength":1,"maxLength":255},"path":{"type":"string","minLength":1,"maxLength":600},"size_bytes":{"type":"integer","minimum":0,"maximum":9007199254740991},"mime_type":{"type":"string","maxLength":100}},"required":["kind","file_name","path","size_bytes","mime_type"]},"example":{"kind":"invoice","file_name":"trc-2026.pdf","path":"x","size_bytes":182044,"mime_type":"application/pdf"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Someone changed it first; read it again","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The change breaks a rule","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/documents/{id}/download":{"get":{"operationId":"get_documents_by_id_download","summary":"Get a download link","description":"A signed link that works for 60 seconds.","tags":["Documents"],"security":[{"apiKey":["documents:read"]}],"x-scope":"documents:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The input isn't valid; errors lists each problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"The key is missing, invalid, revoked or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The key lacks the scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Nothing with this id, or the key can't see it","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}