Yerinde hizmet API

Müşterinin adresinde hizmet — kim gidiyor, ne zaman varıyor, imza ve fotoğraf.

Modül kodu field_service · 5 işlem · 1 veri modeli · 7 olay. Bir anahtar ya da token, arkasındaki kişinin bu modülde yapabildiğinden fazlasını asla yapamaz; satır düzeyindeki güvenlik uygulamadakiyle birebir aynıdır. Yetki kapsamları: field_service (hepsi), field_service:read (yalnız okuma) ya da field_service:<yetenek>.

Kaynaklar

Listeler limit (en çok 200), cursor, order (ör. -created_at), fields ve q alır; diğer her sorgu parametresi bir sütun süzgecidir: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

İşlemler

field_service.advance

Ziyareti güncelle — Yolda, vardı, işe başladı — bu sırayla.

Gereken izin field_service:write · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/field_service.advance

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: field_service.en_route, field_service.arrived, field_service.started

Neye yazar: field_visit (update) — Moves the status and stamps the time

curl -X POST https://app.getera.io/api/v1/field_visits/FIELD_VISIT_ID/actions/advance \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to":"en_route"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "field_service.en_route",
    "field_service.arrived",
    "field_service.started"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.fieldVisits.advance("FIELD_VISIT_ID", {
  to: "en_route"
})

era field_visits advance FIELD_VISIT_ID \
  --to "en_route"

{
  "name": "era__field_service__advance",
  "arguments": {
    "visitId": "FIELD_VISIT_ID",
    "to": "en_route"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde field_service:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 visit_not_found, visit_closed, wrong_order · 429 çok sık istek

field_service.cancel_visit

Ziyareti iptal et — Ziyareti rotadan çıkarır. Randevunun kendisi iptal edilmez.

Gereken izin field_service:write · siler ya da geri alınamaz · Era çalıştırırken bir kişiye onaylatır

• Asıl adres: POST /api/v1/actions/field_service.cancel_visit

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: field_service.visit_cancelled

Neye yazar: field_visit (update) — Moves it to cancelled

curl -X POST https://app.getera.io/api/v1/field_visits/FIELD_VISIT_ID/actions/cancel_visit \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"note":"Why"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "field_service.visit_cancelled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.fieldVisits.cancelVisit("FIELD_VISIT_ID", {
  note: "Why"
})

era field_visits cancel_visit FIELD_VISIT_ID \
  --note "Why"

{
  "name": "era__field_service__cancel_visit",
  "arguments": {
    "visitId": "FIELD_VISIT_ID",
    "note": "Why"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde field_service:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 visit_not_found, visit_closed · 429 çok sık istek

field_service.complete

Ziyareti bitir — Ziyareti notlar, müşterinin imzası ve fotoğraflarla kapatır.

Gereken izin field_service:write · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/field_service.complete

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: field_service.completed

Neye yazar: field_visit (update) — Completes it with its proof of work

curl -X POST https://app.getera.io/api/v1/field_visits/FIELD_VISIT_ID/actions/complete \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"notes":"What was done"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "field_service.completed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.fieldVisits.complete("FIELD_VISIT_ID", {
  notes: "What was done"
})

era field_visits complete FIELD_VISIT_ID \
  --notes "What was done"

{
  "name": "era__field_service__complete",
  "arguments": {
    "visitId": "FIELD_VISIT_ID",
    "notes": "What was done"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde field_service:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 visit_not_found, visit_closed, not_started, signature_required, file_not_found · 429 çok sık istek

field_service.dispatch

Ziyareti görevlendir — Yerinde hizmet randevusunu, hizmet bölgesindeki bir adreste birinin rotasına koyar.

Gereken izin field_service:write · dışarıya ulaşır (gönderir, yayımlar ya da ücret alır)

• Asıl adres: POST /api/v1/actions/field_service.dispatch

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: field_service.dispatched

Neye yazar: field_visit (insert) — Opens the visit

curl -X POST https://app.getera.io/api/v1/field_visits/actions/dispatch \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"appointmentId":"APPOINTMENT_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "field_service.dispatched"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.fieldVisits.dispatch({
  appointmentId: "APPOINTMENT_ID"
})

era field_visits dispatch \
  --appointment-id "APPOINTMENT_ID"

{
  "name": "era__field_service__dispatch",
  "arguments": {
    "appointmentId": "APPOINTMENT_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde field_service:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 appointment_not_found, appointment_closed, already_dispatched, address_not_found, not_home_visit, outside_service_area, provider_cannot_perform · 429 çok sık istek

field_service.reassign

Başka birini gönder — Açık bir ziyareti hizmeti veren başka bir üyeye verir.

Gereken izin field_service:write · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/field_service.reassign

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: field_service.reassigned

Neye yazar: field_visit (update) — Changes who goes

curl -X POST https://app.getera.io/api/v1/field_visits/FIELD_VISIT_ID/actions/reassign \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"memberUserId":"MEMBER_USER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "field_service.reassigned"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.fieldVisits.reassign("FIELD_VISIT_ID", {
  memberUserId: "MEMBER_USER_ID"
})

era field_visits reassign FIELD_VISIT_ID \
  --member-user-id "MEMBER_USER_ID"

{
  "name": "era__field_service__reassign",
  "arguments": {
    "visitId": "FIELD_VISIT_ID",
    "memberUserId": "MEMBER_USER_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde field_service:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 visit_not_found, visit_closed, provider_cannot_perform · 429 çok sık istek

Veri modelleri

FieldVisit

Tablo field_visit · Kaynak field_visits

• GET /api/v1/field_visits
• GET /api/v1/field_visits/{id}

Birincil anahtar: id

Tekil: appointment_id

Denetimler:

• CHECK ((length(btrim(address)) > 0))
• CHECK (((status = 'cancelled'::text) = (cancelled_at IS NOT NULL)))
• CHECK (((status = 'completed'::text) = (completed_at IS NOT NULL)))

Olaylar

İş akışları ve webhook'lar bu olaylara tepki verir.