Die AttorneyOS-API

Verifikasie

Elke versoek dra 'n draertoken. 'n Firma-administrateur skep tokens onder Settings → API and webhooks, en kies read of read and write en 'n opsionele vervaldatum. 'n Token tree op as die persoon wat dit geskep het, slegs binne daardie firma, en kan te eniger tyd herroep word.

curl https://attorneyos.co.za/api/v1/me \
  -H "Authorization: Bearer aos_your_token_here" \
  -H "Accept: application/json"

Basis-URL https://attorneyos.co.za/api/v1. Antwoorde is JSON. Lyste word gepagineer met ?page en ?per_page (verstek 25, maksimum 100) en lewer data, meta en links. Datums is ISO 8601 in Suid-Afrikaanse tyd; geld is 'n desimale string in rand.

Tempolimiete en foute

120 versoeke per minuut per token. Daarbo ontvang u 429 met 'n Retry-After opskrif. Valideringsprobleme kom terug as 422 met 'n errors objek, volgens veld gesleutel; 'n ontbrekende of herroepte token is 401; 'n token sonder die nodige bevoegdheid, of 'n onaktiewe firma, is 403; 'n rekord buite u firma is eenvoudig 404.

Eindpunte

Metode en pad	Wat dit doen	Vereis
GET /me	Die firma, die gebruiker as wie die token optree, en die token se bevoegdhede.	read
GET /clients	Lys kliënte. Filters: search, updated_since.	read
POST /clients	Skep 'n kliënt. Velde: name (verpligtend), client_type, email, phone, id_number, company_number, address, popia_consent, fica_status, notes, assigned_user_id.	write
GET /clients/{id}	Een kliënt.	read
PATCH /clients/{id}	Werk enige van die velde hierbo by.	write
GET /matters	Lys sake. Filters: status, client_id, search, updated_since.	read
POST /matters	Open 'n saak. Velde: title (verpligtend), client_id, assigned_user_id, practice_area, matter_type, status, court, case_number, opposing_party, opposing_attorney, next_action, next_deadline, prescription_date, opened_at, notes. Die saaknommer word volgens die firma se nommering toegeken.	write
GET /matters/{id}	Een saak.	read
PATCH /matters/{id}	Werk 'n saak by, insluitend die status daarvan.	write
GET /time-entries	Lys tyd. Filters: matter_id, from, to, billed.	read
POST /time-entries	Teken tyd aan. Velde: matter_id, work_date, description, hours (verpligtend), rate (verstek is die saak- of gebruikerstarief), billable, user_id.	write
GET /invoices	Lys fakture. Filters: status, client_id, matter_id.	read
GET /invoices/{id}	Een faktuur met sy betalings.	read
GET /payments	Lys betalings. Filters: invoice_id, from.	read
GET /documents	Dokumentmetadata (nooit lêerinhoud nie). Filters: matter_id, client_id.	read
GET /enquiries	Navrae wat deur u gidsinskrywings ingekom het. Filter: status.	read
GET /events	Die webhook-gebeurtenisname en wat hulle beteken.	read
GET, POST /webhooks	Lys of registreer eindpunte. POST gee die ondertekeningsgeheim een keer terug.	read / write
PATCH, DELETE /webhooks/{id}	Verander gebeurtenisse, onderbreek of verwyder 'n eindpunt.	write
POST /webhooks/{id}/test	Plaas 'n ping aflewering in die tou.	write
GET /webhooks/{id}/deliveries	Die afleweringslogboek met statuskodes en pogings.	read

Voorbeeld: open 'n saak vir 'n nuwe kliënt

curl -X POST https://attorneyos.co.za/api/v1/clients \
  -H "Authorization: Bearer aos_..." -H "Content-Type: application/json" \
  -d '{"name":"Thandi Nkosi","client_type":"Individual","email":"thandi@example.co.za","phone":"082 123 4567"}'

curl -X POST https://attorneyos.co.za/api/v1/matters \
  -H "Authorization: Bearer aos_..." -H "Content-Type: application/json" \
  -d '{"title":"Transfer of Erf 5 Monavoni","client_id":123,"practice_area":"Conveyancing"}'

Webhooks

Registreer 'n https-URL en die gebeurtenisse wat u wil hê. Elke aflewering is 'n JSON POST met die opskrifte X-AttorneyOS-Event, X-AttorneyOS-Delivery en X-AttorneyOS-Signature. Antwoord binne tien sekondes met enige 2xx; enigiets anders word ná een minuut, vyf minute, dertig minute, twee uur en twaalf uur weer probeer, en dan as misluk gemerk. Aflewerings kan buite volgorde en, selde, twee keer aankom: gebruik die id om herhalings te ignoreer.

Gebeurtenis	Wanneer
client.created	A client was added
client.updated	A client was edited
matter.created	A matter was opened
matter.updated	A matter was edited or its status changed
time_entry.created	Time was recorded
invoice.created	An invoice was created
invoice.paid	An invoice was paid in full
payment.received	A payment was recorded
document.uploaded	A document was added
document.signed	A document was signed electronically
enquiry.received	A directory enquiry arrived for one of your listings
ping	A test delivery you trigger yourself

{
  "id": "evt_1042",
  "event": "matter.created",
  "created_at": "2026-09-04T09:12:33+02:00",
  "data": { "id": 87, "matter_number": "AOS-2026-00087", "title": "Transfer of Erf 5 Monavoni", "status": "Open", "client_id": 123, ... }
}

Verifieer 'n handtekening

Die opskrif is t=<unix time>,v1=<hex> waar die hex die HMAC-SHA256 is van "<t>.<raw body>" met u eindpunt se geheim. Verwerp enigiets ouer as vyf minute.

// PHP
[$t, $v1] = [null, null];
foreach (explode(',', $_SERVER['HTTP_X_ATTORNEYOS_SIGNATURE']) as $part) { [$k, $v] = explode('=', $part, 2); if ($k === 't') $t = $v; if ($k === 'v1') $v1 = $v; }
$body = file_get_contents('php://input');
$ok = abs(time() - (int) $t) < 300 && hash_equals(hash_hmac('sha256', $t.'.'.$body, $secret), (string) $v1);

// Node
const [t, v1] = sig.split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const ok = Math.abs(Date.now() / 1000 - Number(t)) < 300 && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

Goeie praktyk

• Skep een token per integrasie en noem dit na die stelsel wat dit gebruik, sodat die herroeping van een nooit 'n ander breek nie.
• Verkies leestokens. Gee skryfregte slegs aan die integrasie wat rekords skep.
• Peil met updated_since eerder as om alles te gaan haal; nog beter, teken in op webhooks en haal op aanvraag.
• Dokumente is slegs metadata; lêers bly binne die werkruimte waar POPIA-toegangsbeheer geld.
• Kort iets? Sê vir ondersteuning wat u bou. Die API groei met werklike integrasies.

Wysigingslog

2026-09-04 v1 vrygestel: kliënte, sake, tydinskrywings, fakture, betalings, dokumente, gidsnavrae, webhooks met ondertekende aflewerings en herprobering.