Wersja API 1.2.1

API EV+MAP Flota

Planuj trasy z ładowaniem, wysyłaj listy punktów i odczytuj plany z własnych systemów kluczem API, a o zmianach dowiaduj się z podpisanych webhooków. Dokumentacja poniżej powstaje z tych samych tabel, którymi API sprawdza żądania.

Dokumentacja techniczna jest po angielsku: nazwy pól, kody i komunikaty są takie same w każdym języku.

Pobierz OpenAPI 3.1 (YAML) Serwer: https://evmap.pl/api/v1

Klucze, limity i zasady

Organization API of the EVMap fleet module: routes up to 30 stops planned with charging stops, point lists, places, vehicles and exports.

Authentication: Authorization: Bearer evf_<prefix>_<secret> (created in the panel, Integrations > Fleet API keys; shown once). Test keys create, read, cancel and plan again test routes only (isTest: planned normally, outside the monthly route limit, at most 25 per UTC day, never approved, shared or assigned) and read places and vehicles; live keys never see test routes.

Creating requests (POST that creates a resource) require Idempotency-Key (16-200 visible ASCII characters): a repeat with the same key and body returns the first answer with Idempotent-Replayed: true; the same key with another body is refused (422 idempotency_key_reused). Keys are kept 24 hours; 429 and 5xx answers are not stored, so retry them with the same key after Retry-After.

Limits: the organization's planning queue holds max(10, 2 x the plan's vehicle limit) pending and running jobs (429 fleet_queue_full, Retry-After); when the plan usage cannot be read, operations counted against the plan answer 503 fleet_usage_unavailable (Retry-After) instead of assuming zero.

Every answer uses the envelope {status, messages, data, meta}; errors carry meta.code and meta.details. Times are ISO 8601 in UTC; a departureAt without an offset is the organization's local time.

Webhooks (section webhooks): signed HTTPS POST with X-EVMap-Event, X-EVMap-Delivery, X-EVMap-Timestamp and X-EVMap-Signature: sha256=HMAC_SHA256(secret, timestamp + "." + body); events fleet.route.ready, fleet.route.needs_attention, fleet.route.failed, fleet.route.replanned, fleet.route.approved, fleet.import.ready, fleet.import.failed, fleet.report.ready, fleet.assignment.created, fleet.execution.updated, fleet.stop.updated, fleet.readiness.risk, fleet.readiness.resolved, fleet.alert.raised, fleet.alert.resolved. Payloads carry identifiers, statuses, totals and codes only.

Operacje

Account

Key, plan and limits.

GET `/fleet/openapi`

This OpenAPI 3.1 document (YAML, no key needed)

Odpowiedź: 200 application/yaml
Odpowiedzi z błędem: 404

GET `/fleet/capabilities`

Limits, features and scopes of the calling key

Odpowiedź: 200 CapabilitiesResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503

Routes

Routes with up to 30 stops, planned asynchronously (webhooks fleet.route.*).

POST `/fleet/routes`

Create a route and queue it for planning. Scope: fleet.routes:write. Test keys: yes (test routes only).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`Idempotency-Key`	header	string	tak	16-200 visible ASCII characters, unique per creating request.

Treść żądania: RouteCreate application/json
Odpowiedź: 202 RouteResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422, 409

GET `/fleet/routes`

List routes of a service date or status. Scope: fleet.routes:read. Test keys: yes (test routes only).

Parametry
Nazwa	Miejsce	Typ	Opis
`date`	query	string (date)	Service date (organization time zone).
`status`	query	string: draft \| queued \| planning \| planned \| needs_attention \| failed \| approved \| cancelled \| completed
`vehicle`	query	string (uuid)	Vehicle identifier.
`limit`	query	integer	Page size, default 50.

Odpowiedź: 200 RouteListResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422

POST `/fleet/routes/batch`

Create up to 50 routes at once (all or nothing). Scope: fleet.routes:write. Test keys: yes (test routes only).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`Idempotency-Key`	header	string	tak	16-200 visible ASCII characters, unique per creating request.

Treść żądania: RouteBatchCreate application/json
Odpowiedź: 202 RouteListResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422, 409

GET `/fleet/routes/{routeId}`

Route with its points and the current plan. Scope: fleet.routes:read. Test keys: yes (test routes only).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`routeId`	path	string (uuid)	tak	Route identifier.

Odpowiedź: 200 RouteResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503

POST `/fleet/routes/{routeId}/cancel`

Cancel a route. Scope: fleet.routes:write. Test keys: yes (test routes only).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`routeId`	path	string (uuid)	tak	Route identifier.

Odpowiedź: 200 RouteResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503

POST `/fleet/routes/{routeId}/replan`

Plan a route again (new revision). Scope: fleet.routes:write. Test keys: yes (test routes only).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`routeId`	path	string (uuid)	tak	Route identifier.

Odpowiedź: 202 RouteResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503

POST `/fleet/routes/{routeId}/approve`

Approve a planned route. Scope: fleet.routes:write. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`routeId`	path	string (uuid)	tak	Route identifier.

Odpowiedź: 200 RouteResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503

POST `/fleet/routes/{routeId}/customer-links`

Customer link of one stop: that stop, its arrival window and the route status only (URL returned once; the stop's older link stops working). Scope: fleet.routes:write. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`routeId`	path	string (uuid)	tak	Route identifier.

Treść żądania: CustomerLinkCreate application/json
Odpowiedź: 201 CustomerLinkResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422

Point lists

Lists geocoded and checked asynchronously (webhooks fleet.import.*).

POST `/fleet/point-lists`

Send a point list as JSON rows (geocoded and checked asynchronously). Scope: fleet.lists:write. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`Idempotency-Key`	header	string	tak	16-200 visible ASCII characters, unique per creating request.

Treść żądania: PointListCreate application/json
Odpowiedź: 202 PointListResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422, 409

POST `/fleet/point-lists/imports`

Upload a CSV or XLSX point list. Scope: fleet.lists:write. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`Idempotency-Key`	header	string	tak	16-200 visible ASCII characters, unique per creating request.

Treść żądania: PointListUpload multipart/form-data
Odpowiedź: 202 PointListResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422, 409

GET `/fleet/point-lists/{listId}`

State and rows of a point list. Scope: fleet.lists:write. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`listId`	path	string (uuid)	tak	Point list identifier.

Odpowiedź: 200 PointListResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503

Places

Depots, customers and warehouses.

GET `/fleet/places`

List places. Scope: fleet.places:read. Test keys: yes (test routes only).

Parametry
Nazwa	Miejsce	Typ	Opis
`kind`	query	string: depot \| customer \| warehouse \| other
`externalRef`	query	string
`status`	query	string: active \| archived
`limit`	query	integer	Page size, default 100.

Odpowiedź: 200 PlaceListResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422

POST `/fleet/places`

Create a place. Scope: fleet.places:write. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`Idempotency-Key`	header	string	tak	16-200 visible ASCII characters, unique per creating request.

Treść żądania: PlaceCreate application/json
Odpowiedź: 201 PlaceResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422, 409

PATCH `/fleet/places/{placeId}`

Change a place (only the fields sent). Scope: fleet.places:write. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`placeId`	path	string (uuid)	tak	Place identifier.

Treść żądania: PlacePatch application/json
Odpowiedź: 200 PlaceResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422

Vehicles

Fleet vehicles with battery data.

GET `/fleet/vehicles`

List vehicles. Scope: fleet.vehicles:read. Test keys: yes (test routes only).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`status`	query	string: active \| archived

Odpowiedź: 200 VehicleListResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422

POST `/fleet/vehicles`

Create a vehicle. Scope: fleet.vehicles:write. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`Idempotency-Key`	header	string	tak	16-200 visible ASCII characters, unique per creating request.

Treść żądania: VehicleCreate application/json
Odpowiedź: 201 VehicleResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422, 409

PATCH `/fleet/vehicles/{vehicleId}`

Change a vehicle (only the fields sent). Scope: fleet.vehicles:write. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`vehicleId`	path	string (uuid)	tak	Vehicle identifier.

Treść żądania: VehiclePatch application/json
Odpowiedź: 200 VehicleResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422

Exports

Schedules, GPX and monthly reports (webhook fleet.report.ready).

POST `/fleet/exports`

Request a schedule, GPX or monthly report file (prepared asynchronously, kept 7 days). Scope: fleet.reports:read. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`Idempotency-Key`	header	string	tak	16-200 visible ASCII characters, unique per creating request.

Treść żądania: ExportCreate application/json
Odpowiedź: 202 ExportResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422, 409

GET `/fleet/exports/{exportId}`

State of an export. Scope: fleet.reports:read. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`exportId`	path	string (uuid)	tak	Export identifier.

Odpowiedź: 200 ExportResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503

GET `/fleet/exports/{exportId}/file`

Download a ready export file. Scope: fleet.reports:read. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`exportId`	path	string (uuid)	tak	Export identifier.

Odpowiedź: 200 application/octet-stream
Odpowiedzi z błędem: 404, 401, 403, 429, 503

Charging sessions

Charging sessions of card providers for the settlement: matched to vehicles, routes and planned stops; the results are in the panel (Card settlement).

POST `/fleet/charging-sessions/imports`

Send up to 1000 charging sessions of a card provider (stored at once, matched to vehicles, routes and planned stops asynchronously). Scope: fleet.sessions:write. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`Idempotency-Key`	header	string	tak	16-200 visible ASCII characters, unique per creating request.

Treść żądania: ChargingSessionImportCreate application/json
Odpowiedź: 202 ChargingSessionImportResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503, 422, 409

GET `/fleet/charging-sessions/imports/{importId}`

State of a charging session import with its session and match counts. Scope: fleet.sessions:write. Test keys: no (403 test_key_not_allowed).

Parametry
Nazwa	Miejsce	Typ	Wymagane	Opis
`importId`	path	string (uuid)	tak	Charging session import identifier.

Odpowiedź: 200 ChargingSessionImportResponse
Odpowiedzi z błędem: 404, 401, 403, 429, 503

Webhooki

Events sent to your HTTPS endpoint (panel: Integrations > Webhooks, up to 5 per organization, chosen events, secret shown once).

Nagłówki każdej dostawy
Nazwa	Typ	Opis
`X-EVMap-Event`	string: fleet.route.ready \| fleet.route.needs_attention \| fleet.route.failed \| fleet.route.replanned \| fleet.route.approved \| fleet.import.ready \| fleet.import.failed \| fleet.report.ready \| fleet.assignment.created \| fleet.execution.updated \| fleet.stop.updated \| fleet.readiness.risk \| fleet.readiness.resolved \| fleet.alert.raised \| fleet.alert.resolved	Event type, the same as type in the body.
`X-EVMap-Delivery`	string (uuid)	Delivery to this endpoint (the same for its retries).
`X-EVMap-Timestamp`	string	UNIX seconds of the attempt; refuse values more than 5 minutes away from your clock.
`X-EVMap-Signature`	string	`sha256=` + hex HMAC-SHA256 of `timestamp + "." + raw body`, key = the endpoint secret (`whsec_…`, shown once in the panel). Compare in constant time.

Received: any 2xx answer within 5 s acknowledges the delivery (the body is ignored).

Any other answer, a redirect, a timeout or a connection error: retried after 1, 5 and 25 minutes and about 2 hours (5 attempts); 20 failed attempts in a row switch the endpoint off.

Sprawdzenie podpisu (PHP)

$body = file_get_contents('php://input');
$timestamp = (int)($_SERVER['HTTP_X_EVMAP_TIMESTAMP'] ?? 0);
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, getenv('EVMAP_WEBHOOK_SECRET'));
if (abs(time() - $timestamp) > 300 || !hash_equals($expected, (string)($_SERVER['HTTP_X_EVMAP_SIGNATURE'] ?? ''))) {
    http_response_code(401);
    exit;
}
http_response_code(204); // acknowledge within 5 s, then process the event (deduplicate by its id)

POST `fleet.route.ready`

The first revision of a route is planned without problems.

Treść zdarzenia: WebhookRouteEvent

POST `fleet.route.needs_attention`

The first revision of a route is planned with something to look at (e.g. a missed time window); the plan is complete.

Treść zdarzenia: WebhookRouteEvent

POST `fleet.route.failed`

Planning of a route failed (errorCode).

Treść zdarzenia: WebhookRouteEvent

POST `fleet.route.replanned`

A later revision of a route is planned (status planned or needs_attention).

Treść zdarzenia: WebhookRouteEvent

POST `fleet.route.approved`

A route was approved.

Treść zdarzenia: WebhookRouteEvent

POST `fleet.import.ready`

A point list is geocoded and checked (rows ready, to review and rejected).

Treść zdarzenia: WebhookPointListEvent

POST `fleet.import.failed`

A point list could not be processed (errorCode).

Treść zdarzenia: WebhookPointListEvent

POST `fleet.report.ready`

An export file is ready (kept 7 days). Files of the panel only (route card, delivery proofs) are announced without links and file name.

Treść zdarzenia: WebhookExportEvent

POST `fleet.assignment.created`

A driver was assigned to a route (previousDriverId when another driver was replaced).

Treść zdarzenia: WebhookAssignmentEvent

POST `fleet.execution.updated`

The driver changed the state of the route execution; replanRequired after a check-in that needs a new plan.

Treść zdarzenia: WebhookExecutionEvent

POST `fleet.stop.updated`

The driver reported a stop (arrived, completed, skipped or failed, with the reason).

Treść zdarzenia: WebhookExecutionEvent

POST `fleet.readiness.risk`

A vehicle will not be charged at its base in time for its first route tomorrow (once per new risk or a shortfall change of 1 kWh or more).

Treść zdarzenia: WebhookReadinessEvent

POST `fleet.readiness.resolved`

An announced readiness risk is gone after a recalculation: status ok, unknown or none (no route that day any more); once per announced risk.

Treść zdarzenia: WebhookReadinessEvent

POST `fleet.alert.raised`

A dispatcher alert was raised (one active alert per route and type, per stop for stations).

Treść zdarzenia: WebhookAlertEvent

POST `fleet.alert.resolved`

A dispatcher alert was closed (resolution).

Treść zdarzenia: WebhookAlertEvent

Schematy

RoutePointInput

RoutePointInput
Pole	Typ	Opis
`label`	string
`placeId`	string (uuid)	Saved place; its coordinates, name and default stop time are used.
`latitude`	number
`longitude`	number
`dwellMinutes`	integer	Stop time at the customer (stops only).
`timeWindowFrom`	string	Soft time window, HH:MM local time of the stop on the day of departure: the time zone of the stop's country inside the cross-border coverage (for example Europe/Vilnius in Lithuania), the organization time zone elsewhere; the route's points report it as timezone. An earlier arrival waits for it, a later one is reported as window_missed. A stop at a place without its own window takes the place's default window.
`timeWindowTo`	string
`externalRef`	string
`notes`	string	Instructions for the driver (never sent in webhooks).
`locked`	boolean	Keeps the stop's position when optimizeOrder is on.

RouteCreate

RouteCreate
Pole	Typ	Wymagane	Opis
`name`	string		Shown in the panel, on the route card, in e-mails and exports: no personal data of customers (names, addresses, phone numbers). Default: "<vehicle> · <date> · stops: <count>".
`vehicleId`	string (uuid)	tak
`driverId`	string (uuid)
`departureAt`	string (date-time)	tak	ISO 8601 with an offset or Z; without an offset the organization time zone applies.
`departureSocPercent`	number		Battery at departure; default: the vehicle's expected morning level.
`costCenter`	string
`optimizeOrder`	boolean
`winterMode`	boolean
`maxVariants`	integer
`notes`	string
`points`	array of RoutePointInput	tak	Start, stops in the visiting order, end.

RouteBatchCreate

RouteBatchCreate
Pole	Typ	Wymagane	Opis
`routes`	array of RouteCreate	tak

PointListRow

PointListRow
Pole	Typ	Opis
`kind`	string: start \| stop \| end
`label`	string
`address`	string
`houseNumber`	string
`postalCode`	string
`city`	string
`latitude`	number
`longitude`	number
`placeRef`	string	externalRef of a saved place.
`externalRef`	string
`dwellMinutes`	integer
`timeWindowFrom`	string
`timeWindowTo`	string
`notes`	string
`vehicle`	string	Registration number or name; splits the list into routes per vehicle.
`driver`	string
`date`	string (date)
`departureTime`	string
`departureSocPercent`	number	Battery at departure of the route of this vehicle and day (the first value given in its rows applies); default: the vehicle's expected morning level.

PointListCreate

PointListCreate
Pole	Typ	Wymagane	Opis
`sourceRef`	string		Your list identifier; a new list with the same value synchronizes rows by externalRef.
`serviceDate`	string (date)
`departureTime`	string
`vehicleId`	string (uuid)
`dwellMinutes`	integer
`returnToDepot`	boolean
`optimizeOrder`	boolean
`winterMode`	boolean
`costCenter`	string
`rows`	array of PointListRow	tak

PointListUpload

PointListUpload
Pole	Typ	Wymagane	Opis
`file`	string	tak	CSV (UTF-8, ; or , separated) or XLSX, at most 2 MB and 1000 rows.
`sourceRef`	string		Your list identifier; a new list with the same value synchronizes rows by externalRef.
`serviceDate`	string (date)
`departureTime`	string
`vehicleId`	string (uuid)
`dwellMinutes`	integer
`returnToDepot`	boolean
`optimizeOrder`	boolean
`winterMode`	boolean
`costCenter`	string

PlaceCreate

PlaceCreate
Pole	Typ	Wymagane	Opis
`name`	string	tak
`kind`	string: depot \| customer \| warehouse \| other
`addressLine`	string
`postCode`	string
`city`	string
`latitude`	number \| null
`longitude`	number \| null
`externalRef`	string
`defaultDwellMinutes`	integer
`defaultWindowFrom`	string \| null		Default delivery window of the stops at this place (HH:MM local time of the place, as RoutePointInput.timeWindowFrom); null = open.
`defaultWindowTo`	string \| null
`openingHours`	string
`notes`	string
`chargerCount`	integer
`chargerPowerKw`	number
`chargerCurrent`	string: ac \| dc		Current of the charging points (readiness for tomorrow: the vehicle's AC or DC limit applies).
`siteLimitKw`	number
`chargingWindowFrom`	string \| null		Overnight charging window of the depot (HH:MM, organization time zone, both ends or none; may run past midnight); null = from the return to the departure.
`chargingWindowTo`	string \| null
`status`	string: active \| archived

PlacePatch

PlacePatch
Pole	Typ	Opis
`name`	string
`kind`	string: depot \| customer \| warehouse \| other
`addressLine`	string
`postCode`	string
`city`	string
`latitude`	number \| null
`longitude`	number \| null
`externalRef`	string
`defaultDwellMinutes`	integer
`defaultWindowFrom`	string \| null	Default delivery window of the stops at this place (HH:MM local time of the place, as RoutePointInput.timeWindowFrom); null = open.
`defaultWindowTo`	string \| null
`openingHours`	string
`notes`	string
`chargerCount`	integer
`chargerPowerKw`	number
`chargerCurrent`	string: ac \| dc	Current of the charging points (readiness for tomorrow: the vehicle's AC or DC limit applies).
`siteLimitKw`	number
`chargingWindowFrom`	string \| null	Overnight charging window of the depot (HH:MM, organization time zone, both ends or none; may run past midnight); null = from the return to the departure.
`chargingWindowTo`	string \| null
`status`	string: active \| archived

VehicleCreate

VehicleCreate
Pole	Typ	Wymagane	Opis
`name`	string	tak
`registrationNumber`	string		Spaces are removed; up to 32 letters, digits and dashes remain.
`vehicleClass`	string: m1 \| n1
`batteryUsableKwh`	number	tak	Usable battery, 5-250 kWh.
`batterySohPercent`	number
`consumptionWhKm`	integer		0 = the catalog or planner estimate; otherwise 80-1000.
`maxAcKw`	number
`maxDcKw`	number
`connectorTypes`	array of string
`defaultReserveSocPercent`	number
`defaultTargetSocPercent`	number
`expectedMorningSocPercent`	number
`leaseKmLimitPerYear`	integer
`leaseEndDate`	string (date) \| null
`homePlaceId`	string (uuid) \| null
`status`	string: active \| archived

VehiclePatch

VehiclePatch
Pole	Typ	Opis
`name`	string
`registrationNumber`	string	Spaces are removed; up to 32 letters, digits and dashes remain.
`vehicleClass`	string: m1 \| n1
`batteryUsableKwh`	number	Usable battery, 5-250 kWh.
`batterySohPercent`	number
`consumptionWhKm`	integer	0 = the catalog or planner estimate; otherwise 80-1000.
`maxAcKw`	number
`maxDcKw`	number
`connectorTypes`	array of string
`defaultReserveSocPercent`	number
`defaultTargetSocPercent`	number
`expectedMorningSocPercent`	number
`leaseKmLimitPerYear`	integer
`leaseEndDate`	string (date) \| null
`homePlaceId`	string (uuid) \| null
`status`	string: active \| archived

ExportCreate

ExportCreate
Pole	Typ	Wymagane	Opis
`kind`	string: route_schedule \| day_schedule \| route_gpx \| monthly	tak
`format`	string: csv \| xlsx \| gpx	tak
`routeId`	string (uuid)		route_schedule and route_gpx.
`serviceDate`	string (date)		day_schedule.
`month`	string (month)		monthly (YYYY-MM).
`groupBy`	string: vehicle \| driver \| costCenter		monthly CSV grouping.
`locale`	string: pl \| en		Language, CSV separator and decimal mark of the file; default pl.

CustomerLinkCreate

CustomerLinkCreate
Pole	Typ	Wymagane	Opis
`stop`	integer	tak	Number of the stop on the route (sequence of a point of kind "stop"; the start is 0).

CustomerLink

CustomerLink
Pole	Typ	Opis
`id`	string (uuid)
`url`	string	Public page of the stop (no key or PIN needed); shown once.
`stop`	integer
`expiresAt`	string (date-time)	24 h after the end of the service day.

Route

Route
Pole	Typ	Opis
`id`	string (uuid)
`name`	string
`status`	string: draft \| queued \| planning \| planned \| needs_attention \| failed \| approved \| cancelled \| completed
`revision`	integer
`isTest`	boolean	Created with a test key: outside plan limits and monthly reports.
`serviceDate`	string (date)
`departureAt`	string (date-time)
`timezone`	string
`vehicleId`	string (uuid) \| null
`driverId`	string (uuid) \| null
`costCenter`	string \| null
`options`	object
`options.optimizeOrder`	boolean
`options.winterMode`	boolean
`options.maxVariants`	integer
`errorCode`	string \| null
`plan`	object \| null	Present once the route is planned.
`plan.plannedAt`	string (date-time) \| null
`plan.distanceMeters`	integer
`plan.drivingSeconds`	integer
`plan.chargingSeconds`	integer
`plan.dwellSeconds`	integer
`plan.windowWaitSeconds`	integer	Waiting for time windows to open (part of totalSeconds).
`plan.lateStopCount`	integer	Stops reached after their time window (the route then needs attention).
`plan.windowLateSeconds`	integer
`plan.totalSeconds`	integer
`plan.arrivalAt`	string (date-time) \| null
`plan.arrivalSocPercent`	number \| null
`plan.gridEnergyWh`	integer
`plan.chargingStopCount`	integer
`plan.chargingCost`	array of object
`plan.chargingCost[].currency`	string
`plan.chargingCost[].amount`	string
`plan.dwellChargingStopCount`	integer	Stops where the vehicle charges during the visit (no extra time).
`plan.dwellChargingEnergyWh`	integer	Energy charged during visits (battery side); the grid side is in gridEnergyWh.
`plan.warningCodes`	array of string
`plan.chargingStops`	array of object
`plan.chargingStops[].stationId`	string \| null
`plan.chargingStops[].locationId`	string \| null
`plan.chargingStops[].stationName`	string \| null
`plan.chargingStops[].operatorName`	string \| null
`plan.chargingStops[].address`	string \| null
`plan.chargingStops[].city`	string \| null
`plan.chargingStops[].latitude`	number
`plan.chargingStops[].longitude`	number
`plan.chargingStops[].powerKw`	number
`plan.chargingStops[].arrivalAt`	string (date-time) \| null
`plan.chargingStops[].departureAt`	string (date-time) \| null
`plan.chargingStops[].unplugBy`	string (date-time) \| null
`plan.chargingStops[].arrivalSocPercent`	number
`plan.chargingStops[].departureSocPercent`	number
`plan.chargingStops[].gridEnergyWh`	integer
`plan.chargingStops[].authorization`	object \| null
`plan.chargingStops[].reliability`	string \| null
`plan.chargingStops[].warningCodes`	array of string
`points`	array of object
`points[].sequence`	integer	Position in the list that was sent.
`points[].plannedIndex`	integer	Position in the planned visiting order.
`points[].kind`	string: start \| stop \| end
`points[].label`	string
`points[].placeId`	string (uuid) \| null
`points[].latitude`	number
`points[].longitude`	number
`points[].timezone`	string	IANA time zone of the point's local times (its time window as HH:MM): the zone of its country inside the cross-border coverage, the route's timezone elsewhere and wherever both keep the same offsets.
`points[].dwellMinutes`	integer
`points[].externalRef`	string
`points[].notes`	string
`points[].locked`	boolean
`points[].timeWindowFrom`	string (date-time) \| null
`points[].timeWindowTo`	string (date-time) \| null
`points[].plannedArrivalAt`	string (date-time) \| null
`points[].plannedDepartureAt`	string (date-time) \| null
`points[].arrivalSocPercent`	number \| null
`points[].departureSocPercent`	number \| null
`points[].windowWaitSeconds`	integer	Planned wait for the time window to open.
`points[].windowLateSeconds`	integer	Planned arrival after the window closes; 0 = on time.
`points[].dwellCharging`	object \| null	Charging during the visit at a station nearby or at the place's own chargers; null = none.
`points[].dwellCharging.source`	string: station \| depot
`points[].dwellCharging.current`	string: ac \| dc
`points[].dwellCharging.locationId`	string \| null
`points[].dwellCharging.stationName`	string
`points[].dwellCharging.operatorName`	string \| null
`points[].dwellCharging.latitude`	number
`points[].dwellCharging.longitude`	number
`points[].dwellCharging.distanceMeters`	integer
`points[].dwellCharging.powerKw`	number
`points[].dwellCharging.startAt`	string (date-time) \| null
`points[].dwellCharging.endAt`	string (date-time) \| null
`points[].dwellCharging.energyWh`	integer
`points[].dwellCharging.gridEnergyWh`	integer
`points[].dwellCharging.departureSocPercent`	number
`points[].dwellCharging.cost`	object \| null	From the fleet card tariffs or the depot energy price; null = unpriced.
`points[].dwellCharging.cost.currency`	string
`points[].dwellCharging.cost.amount`	string
`scenario`	object \| null	Condition scenario (winter or summer) planned next to the route; null = none. Differences are scenario minus plan in the unit of the row.
`scenario.code`	string
`scenario.status`	string
`scenario.stale`	boolean	Computed for an earlier revision of the route.
`scenario.plannedAt`	string (date-time) \| null
`scenario.rows`	object \| null	energyExpectedWh, gridWh, chargingStopCount, chargingSeconds, totalSeconds, arrivalSocBp; null until the scenario is planned.
`scenario.headline`	object \| null
`scenario.headline.energyWhDelta`	integer
`scenario.headline.energyPercentDelta`	number \| null
`scenario.headline.totalSecondsDelta`	integer
`scenario.headline.chargingStopDelta`	integer
`scenario.headline.arrivalSocBpDelta`	integer
`createdAt`	string (date-time)
`plannedAt`	string (date-time) \| null
`approvedAt`	string (date-time) \| null
`links`	object
`links.self`	string

PointList

PointList
Pole	Typ	Opis
`id`	string (uuid)
`status`	string
`sourceKind`	string
`sourceRef`	string \| null
`rows`	object
`rows.total`	integer
`rows.ready`	integer
`rows.review`	integer
`rows.rejected`	integer
`routeCount`	integer
`errorCode`	string \| null
`createdAt`	string (date-time)
`completedAt`	string (date-time) \| null
`items`	array of object	Rows (first 1000) with their check result.

Place

Place
Pole	Typ	Opis
`id`	string (uuid)
`name`	string
`kind`	string: depot \| customer \| warehouse \| other
`addressLine`	string
`postCode`	string
`city`	string
`latitude`	number \| null
`longitude`	number \| null
`externalRef`	string
`defaultDwellMinutes`	integer
`defaultWindowFrom`	string \| null	Default delivery window of the stops at this place (HH:MM local time of the place, as RoutePointInput.timeWindowFrom); null = open.
`defaultWindowTo`	string \| null
`openingHours`	string
`notes`	string
`chargerCount`	integer
`chargerPowerKw`	number
`chargerCurrent`	string: ac \| dc	Current of the charging points (readiness for tomorrow: the vehicle's AC or DC limit applies).
`siteLimitKw`	number
`chargingWindowFrom`	string \| null	Overnight charging window of the depot (HH:MM, organization time zone, both ends or none; may run past midnight); null = from the return to the departure.
`chargingWindowTo`	string \| null
`status`	string: active \| archived

Vehicle

Vehicle
Pole	Typ	Opis
`id`	string (uuid)
`name`	string
`registrationNumber`	string	Spaces are removed; up to 32 letters, digits and dashes remain.
`vehicleClass`	string: m1 \| n1
`batteryUsableKwh`	number	Usable battery, 5-250 kWh.
`batterySohPercent`	number
`consumptionWhKm`	integer	0 = the catalog or planner estimate; otherwise 80-1000.
`maxAcKw`	number
`maxDcKw`	number
`connectorTypes`	array of string
`defaultReserveSocPercent`	number
`defaultTargetSocPercent`	number
`expectedMorningSocPercent`	number
`leaseKmLimitPerYear`	integer
`leaseEndDate`	string (date) \| null
`homePlaceId`	string (uuid) \| null
`status`	string: active \| archived

Export

Export
Pole	Typ	Wymagane	Opis
`id`	string (uuid)
`kind`	string
`format`	string
`status`	string: pending \| processing \| ready \| failed \| expired
`errorCode`	string \| null
`fileName`	string \| null
`byteSize`	integer
`createdAt`	string (date-time)
`expiresAt`	string (date-time) \| null
`links`	object
`links.self`	string
`links.file`	string \| null

Capabilities

Capabilities
Pole	Typ	Wymagane	Opis
`organization`	object
`key`	object
`plan`	object
`limits`	object
`webhookEvents`	array of string

Error

Error
Pole	Typ	Opis
`status`	string = error
`messages`	array of object
`messages[].type`	string
`messages[].text`	string
`meta`	object
`meta.code`	string	Stable error code, e.g. invalid_api_key, insufficient_scope, test_key_not_allowed, validation_failed, idempotency_key_reused, rate_limited, fleet_plan_limit, fleet_queue_full, fleet_usage_unavailable.
`meta.statusCode`	integer
`meta.errors`	array of object
`meta.errors[].field`	string
`meta.errors[].code`	string
`meta.errors[].message`	string

RouteResponse

RouteResponse
Pole	Typ	Wymagane	Opis
`status`	string = ok
`data`	object
`data.route`	Route

RouteListResponse

RouteListResponse
Pole	Typ	Wymagane	Opis
`status`	string = ok
`data`	object
`data.routes`	array of Route

PointListResponse

PointListResponse
Pole	Typ	Wymagane	Opis
`status`	string = ok
`data`	object
`data.pointList`	PointList

PlaceResponse

PlaceResponse
Pole	Typ	Wymagane	Opis
`status`	string = ok
`data`	object
`data.place`	Place

PlaceListResponse

PlaceListResponse
Pole	Typ	Wymagane	Opis
`status`	string = ok
`data`	object
`data.places`	array of Place

VehicleResponse

VehicleResponse
Pole	Typ	Wymagane	Opis
`status`	string = ok
`data`	object
`data.vehicle`	Vehicle

VehicleListResponse

VehicleListResponse
Pole	Typ	Wymagane	Opis
`status`	string = ok
`data`	object
`data.vehicles`	array of Vehicle

ExportResponse

ExportResponse
Pole	Typ	Wymagane	Opis
`status`	string = ok
`data`	object
`data.export`	Export

CustomerLinkResponse

CustomerLinkResponse
Pole	Typ	Wymagane	Opis
`status`	string = ok
`data`	object
`data.customerLink`	CustomerLink

CapabilitiesResponse

CapabilitiesResponse
Pole	Typ	Wymagane	Opis
`status`	string = ok
`data`	object
`data.capabilities`	Capabilities

ChargingSessionInput

ChargingSessionInput
Pole	Typ	Wymagane	Opis
`sessionId`	string	tak	Transaction number of the provider; a session sent again with the same number updates it (corrected invoice lines).
`cardNumber`	string		Charging card number; only its last four characters are stored (the card is found by them).
`vehicleRegistration`	string		Registration number when the provider knows it; it wins over the card.
`startedAt`	string (date-time)	tak	ISO 8601 with Z or an offset; without an offset the time zone of the request (or of the organization) applies.
`endedAt`	string (date-time)
`energyKwh`	number	tak
`costNet`	number		Net amount in the currency (major units, e.g. 68.70).
`costGross`	number		Gross amount; a missing one is derived from the VAT rate of the charging policy in the reports.
`currency`	string
`operatorName`	string
`stationName`	string
`address`	string
`city`	string
`evseId`	string
`latitude`	number		Station position for the match with the planned stops (never returned).
`longitude`	number

ChargingSessionImportCreate

ChargingSessionImportCreate
Pole	Typ	Wymagane	Opis
`programId`	string (uuid)		Card program of the sessions; narrows the card search.
`timezone`	string		IANA time zone of the times without an offset; default: the organization's.
`currency`	string		Currency of the sessions without one; default: the organization's.
`sessions`	array of ChargingSessionInput	tak

ChargingSessionImport

ChargingSessionImport
Pole	Typ	Opis
`id`	string (uuid)
`source`	string: file \| api \| rematch	api, or file / rematch for the imports of the panel.
`status`	string: pending \| processing \| processed \| failed \| cancelled
`errorCode`	string \| null
`sessions`	object
`sessions.total`	integer
`sessions.imported`	integer
`sessions.updated`	integer
`sessions.unchanged`	integer
`sessions.rejected`	integer
`match`	object \| null	Present once the import is processed.
`match.matched`	integer
`match.unmatched`	integer
`match.suspicious`	integer
`rejected`	array of object	Sessions that were not stored: position in the request (from 0) and the reason, e.g. invalid_start, end_before_start, missing_energy, invalid_currency, duplicate_in_file.
`rejected[].index`	integer
`rejected[].code`	string
`createdAt`	string (date-time)
`processedAt`	string (date-time) \| null
`links`	object
`links.self`	string

ChargingSessionImportResponse

ChargingSessionImportResponse
Pole	Typ	Wymagane	Opis
`status`	string = ok
`data`	object
`data.import`	ChargingSessionImport

WebhookRouteEvent

WebhookRouteEvent
Pole	Typ	Wymagane	Opis
`id`	string	tak	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.route.ready \| fleet.route.needs_attention \| fleet.route.failed \| fleet.route.replanned \| fleet.route.approved	tak
`apiVersion`	string = v1	tak
`createdAt`	string (date-time)	tak
`test`	boolean	tak	A test route, or a test event sent from the panel.
`data`	object	tak
`data.route`	WebhookRoute

WebhookPointListEvent

WebhookPointListEvent
Pole	Typ	Wymagane	Opis
`id`	string	tak	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.import.ready \| fleet.import.failed	tak
`apiVersion`	string = v1	tak
`createdAt`	string (date-time)	tak
`test`	boolean	tak	A test route, or a test event sent from the panel.
`data`	object	tak
`data.pointList`	WebhookPointList

WebhookExportEvent

WebhookExportEvent
Pole	Typ	Wymagane	Opis
`id`	string	tak	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.report.ready	tak
`apiVersion`	string = v1	tak
`createdAt`	string (date-time)	tak
`test`	boolean	tak	A test route, or a test event sent from the panel.
`data`	object	tak
`data.export`	WebhookExport

WebhookAssignmentEvent

WebhookAssignmentEvent
Pole	Typ	Wymagane	Opis
`id`	string	tak	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.assignment.created	tak
`apiVersion`	string = v1	tak
`createdAt`	string (date-time)	tak
`test`	boolean	tak	A test route, or a test event sent from the panel.
`data`	object	tak
`data.assignment`	WebhookAssignment

WebhookExecutionEvent

WebhookExecutionEvent
Pole	Typ	Wymagane	Opis
`id`	string	tak	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.execution.updated \| fleet.stop.updated	tak
`apiVersion`	string = v1	tak
`createdAt`	string (date-time)	tak
`test`	boolean	tak	A test route, or a test event sent from the panel.
`data`	WebhookExecution	tak

WebhookReadinessEvent

WebhookReadinessEvent
Pole	Typ	Wymagane	Opis
`id`	string	tak	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.readiness.risk \| fleet.readiness.resolved	tak
`apiVersion`	string = v1	tak
`createdAt`	string (date-time)	tak
`test`	boolean	tak	A test route, or a test event sent from the panel.
`data`	object	tak
`data.readiness`	WebhookReadiness

WebhookAlertEvent

WebhookAlertEvent
Pole	Typ	Wymagane	Opis
`id`	string	tak	Event identifier, the same for every endpoint and attempt: deduplicate by it (an event can arrive more than once).
`type`	string: fleet.alert.raised \| fleet.alert.resolved	tak
`apiVersion`	string = v1	tak
`createdAt`	string (date-time)	tak
`test`	boolean	tak	A test route, or a test event sent from the panel.
`data`	object	tak
`data.alert`	WebhookAlert

WebhookRoute

WebhookRoute
Pole	Typ	Opis
`id`	string (uuid)
`name`	string
`status`	string: draft \| queued \| planning \| planned \| needs_attention \| failed \| approved \| cancelled \| completed
`revision`	integer
`isTest`	boolean
`serviceDate`	string (date)
`departureAt`	string (date-time) \| null
`vehicleId`	string (uuid) \| null
`costCenter`	string \| null
`pointCount`	integer
`errorCode`	string \| null
`plan`	object \| null	Plan totals; null before planning and after a failure.
`plan.distanceMeters`	integer
`plan.drivingSeconds`	integer
`plan.totalSeconds`	integer
`plan.chargingStopCount`	integer
`plan.gridEnergyWh`	integer
`plan.arrivalAt`	string (date-time) \| null
`plan.arrivalSocPercent`	number \| null
`plan.warningCodes`	array of string
`links`	object	API address of the route (GET for the points and the full plan).
`links.self`	string

WebhookPointList

WebhookPointList
Pole	Typ	Opis
`id`	string (uuid)
`status`	string: pending \| processing \| awaiting_mapping \| ready \| needs_review \| committed \| superseded \| failed \| cancelled
`sourceRef`	string \| null
`rows`	object
`rows.total`	integer
`rows.ready`	integer
`rows.review`	integer
`rows.rejected`	integer
`errorCode`	string \| null
`links`	object	API address of the point list.
`links.self`	string

WebhookExport

WebhookExport
Pole	Typ	Opis
`id`	string (uuid)
`kind`	string: route_schedule \| day_schedule \| route_gpx \| monthly \| route_card \| delivery_proofs
`format`	string
`fileName`	string	Empty for the files of the panel only.
`byteSize`	integer
`expiresAt`	string (date-time) \| null
`links`	object	API addresses of the export and its file; empty for the files of the panel only.
`links.self`	string
`links.file`	string

WebhookAssignment

WebhookAssignment
Pole	Typ	Opis
`id`	string (uuid)
`status`	string
`assignedAt`	string (date-time) \| null
`routeId`	string (uuid)
`routeRevision`	integer
`serviceDate`	string (date)
`driverId`	string (uuid)
`previousDriverId`	string (uuid) \| null
`links`	object	API address of the route.
`links.route`	string

WebhookExecution

WebhookExecution
Pole	Typ	Opis
`executionId`	string (uuid)
`assignmentId`	string (uuid)
`routeId`	string (uuid)
`status`	string	State of the execution, e.g. accepted, checked_in, started, completed, declined, abandoned.
`stateVersion`	integer	Grows with every change of the execution: ignore an event older than the one you have.
`replanRequired`	boolean	Check-in only: the vehicle or the battery level differs from the plan, so the route is planned again.
`stop`	object	fleet.stop.updated only.
`stop.id`	string (uuid)
`stop.status`	string: arrived \| completed \| skipped \| failed
`stop.reason`	string: other \| customer_unavailable \| recipient_refused \| access_closed \| vehicle_fault \| charger_fault \| safety \| dispatch_cancelled \| null

WebhookReadiness

WebhookReadiness
Pole	Typ	Opis
`serviceDate`	string (date)
`status`	string: risk \| ok \| unknown \| none	risk for fleet.readiness.risk; ok, unknown or none (no route that day any more) for fleet.readiness.resolved.
`reasonCode`	string \| null
`vehicleId`	string (uuid) \| null
`routeId`	string (uuid) \| null
`placeId`	string (uuid) \| null
`departureAt`	string (date-time) \| null
`predictedSocPercent`	number \| null
`requiredSocPercent`	number
`energyNeededKwh`	number
`shortfallKwh`	number
`chargingStartAt`	string (date-time) \| null
`socSource`	string: driver_report \| plan \| vehicle_profile \| none
`socObservedAt`	string (date-time) \| null
`returnToBaseConfirmed`	boolean \| null
`chargingAssumption`	string \| null
`previousExecutionStatus`	string \| null
`previousReasonCode`	string	fleet.readiness.resolved only: the announced reason.
`previousShortfallKwh`	number	fleet.readiness.resolved only: the announced shortfall.
`links`	object	API address of the route (empty without a route).
`links.route`	string

WebhookAlert

WebhookAlert
Pole	Typ	Opis
`id`	string (uuid)
`type`	string: driver_check_in \| driver_pin_locked \| window_missed \| plan_partial \| plan_missing \| replan_failed \| charging_warning \| no_driver \| driver_unavailable \| vehicle_unavailable \| readiness_risk \| station_unavailable
`severity`	string: critical \| warning
`status`	string: open \| acknowledged \| resolved
`serviceDate`	string (date) \| null
`routeId`	string (uuid) \| null
`vehicleId`	string (uuid) \| null
`raisedAt`	string (date-time) \| null
`resolvedAt`	string (date-time) \| null
`resolution`	string: manual \| condition_cleared \| route_closed \| expired \| swapped \| null
`details`	object	Codes and counts only; a key is present when it applies to the alert type.
`details.errorCode`	string
`details.revision`	integer
`details.unplannedPointCount`	integer
`details.lateStopCount`	integer
`details.maxLateSeconds`	integer
`details.sequences`	array of integer
`details.stopCount`	integer
`details.codes`	array of string
`details.stops`	array of object
`details.stops[].index`	integer
`details.stops[].codes`	array of string
`details.reason`	string
`details.untilAt`	string (date-time)
`details.reasonCode`	string
`details.shortfallWh`	integer
`details.stopIndex`	integer
`details.locationPublicId`	string (uuid)
`details.hasBackup`	boolean
`links`	object	API address of the route (empty without a route).
`links.route`	string

API EV+MAP Flota

Klucze, limity i zasady

Operacje

Account

GET /fleet/openapi

GET /fleet/capabilities

Routes

POST /fleet/routes

GET /fleet/routes

POST /fleet/routes/batch

GET /fleet/routes/{routeId}

POST /fleet/routes/{routeId}/cancel

POST /fleet/routes/{routeId}/replan

POST /fleet/routes/{routeId}/approve

POST /fleet/routes/{routeId}/customer-links