{ "openapi": "3.0.3", "info": { "title": "Vehicle", "version": "1.0.0", "description": "Portão 3 vehicle API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Fleet vehicles, each with a dedicated wallet. Confidence tiers: generated:typed=9 copied:manual=0 unknown=0." }, "servers": [ { "url": "https://api.vehicle.v2.portao3.com.br/", "description": "production" }, { "url": "https://api.vehicle.dev.3pers.com.br/", "description": "development" } ], "x-p3-surface": "public", "tags": [ { "name": "Vehicles" } ], "components": {}, "paths": { "/realms/{realmId}/organizations/{organizationId}/vehicles": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdVehicles", "summary": "List vehicles", "tags": [ "Vehicles" ], "x-p3-sidebar-order": 1, "description": "Lists the organization's vehicles, newest first.", "x-mint": { "content": "Each vehicle comes with its dedicated `wallet` — its balance and the users who can use it. A vehicle whose wallet can't be read at that moment is returned without one; send `includeWallet=false` to leave the wallets out altogether, which is faster.\n\nFilter by `name` and `licensePlate` (both match part of the text, ignoring case), `status` or `walletId`, and page with `limit` + `next`. `status` takes its values comma-separated (`?status=ACTIVE,ARCHIVED`); repeating the parameter (`?status=ACTIVE&status=ARCHIVED`) works too. A blank parameter counts as not sent." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization whose vehicles you want to list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "name", "in": "query", "required": false, "description": "Only vehicles whose name contains this text (case-insensitive).", "schema": { "type": "string", "maxLength": 256 }, "example": "van" }, { "name": "licensePlate", "in": "query", "required": false, "description": "Only vehicles whose license plate contains this text. Case, hyphens and spaces are ignored.", "schema": { "type": "string", "maxLength": 16 }, "example": "BRA2" }, { "name": "status", "in": "query", "required": false, "description": "Only vehicles in these statuses. Omit to list both.\n\n---\n\nExample (comma-separated list): `?status=ACTIVE,ARCHIVED`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] } }, "style": "form", "explode": false }, { "name": "walletId", "in": "query", "required": false, "description": "Only the vehicle whose dedicated wallet has this ID (its `external.walletId`).", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "example": "6710b8e4c9e77b0012a4d6f3" }, { "name": "includeWallet", "in": "query", "required": false, "description": "`false` returns the vehicles without their `wallet`, which is faster.", "schema": { "default": "true", "type": "string", "enum": [ "true", "false" ] }, "example": "false" }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page.", "schema": { "type": "string" }, "example": "MjAyNi0xMC0xN1QxMzo0NToxMi4wMDBa" }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "default": 15, "type": "integer", "minimum": 1, "maximum": 100 }, "example": 15 }, { "name": "order", "in": "query", "required": false, "description": "Sort direction of `orderBy`. Case-insensitive.", "schema": { "default": "DESC", "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "DESC" }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort by. Only `createdAt` is supported.", "schema": { "default": "createdAt", "type": "string", "enum": [ "createdAt" ] }, "example": "createdAt" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the vehicle.", "example": "6710b8e4c9e77b0012a4d6f1" }, "realmId": { "type": "string", "description": "ID of the realm the vehicle belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the vehicle belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Display name of the vehicle.", "example": "Delivery van 07" }, "licensePlate": { "type": "string", "description": "License plate, upper-cased with no hyphen or space: the old Brazilian format (`ABC1234`) or the Mercosul one (`ABC1D23`).", "example": "BRA2E19" }, "make": { "type": "string", "description": "Manufacturer.", "example": "Fiat" }, "model": { "type": "string", "description": "Model.", "example": "Fiorino" }, "year": { "type": "number", "description": "Model year.", "example": 2023 }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ], "description": "`ACTIVE`, or `ARCHIVED` once the vehicle was archived. An archived vehicle's wallet is blocked.", "example": "ACTIVE" }, "external": { "type": "object", "properties": { "walletId": { "type": "string", "description": "ID of the vehicle's dedicated wallet. Use it with the wallet, card and transaction endpoints of the Banking API.", "example": "6710b8e4c9e77b0012a4d6f3" }, "accountId": { "type": "string", "description": "ID of the organization's account the wallet belongs to.", "example": "66f2a1c7b4d3e80012c9a0b4" } }, "required": [ "walletId", "accountId" ], "description": "The vehicle's dedicated wallet." }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's vehicle custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "createdBy": { "type": "string", "description": "ID of the user who registered the vehicle.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "updatedBy": { "type": "string", "description": "ID of the user who last changed the vehicle.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "createdAt": { "type": "string", "description": "When the vehicle was registered.", "example": "2026-10-17T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the vehicle was last changed.", "example": "2026-10-17T13:45:12.000Z", "format": "date-time" }, "wallet": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the wallet — the same as the vehicle's `external.walletId`.", "example": "6710b8e4c9e77b0012a4d6f3" }, "name": { "type": "string", "nullable": true, "description": "Name of the wallet: the vehicle's license plate when it was registered. Changing the vehicle's plate later doesn't rename the wallet.", "example": "BRA2E19" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "CANCELLING", "CANCELLED", "BLOCKED", "REPROVED", "FRAUD_ANALYSIS", "FRAUD_CONFIRMED" ], "description": "Status of the wallet. `BLOCKED` while the vehicle is archived.", "example": "ACTIVE" }, "currency": { "type": "string", "description": "Currency of the balances, as an ISO 4217 numeric code (`986` = BRL).", "example": "986" }, "totalBalance": { "type": "number", "description": "Total balance of the wallet across all of its categories, in cents.", "example": 35000 }, "balances": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "FLEX_NATIONAL", "FLEX_INTERNATIONAL", "FOOD", "GAS", "MOBILITY", "TOLL", "FLEX_NATIONAL_WITHOUT_WITHDRAWALS", "ADS", "SAAS", "HOTEL", "AIRLINES", "TRAVEL", "BLOCKED", "CASHBACK" ], "description": "Balance category.", "example": "GAS" }, "amount": { "type": "number", "description": "Balance of the category, in cents.", "example": 35000 } }, "required": [ "category", "amount" ], "description": "The balance of one category of the wallet." }, "description": "Balance per category. Empty while the wallet is being created." }, "shared": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the user.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "role": { "type": "string", "enum": [ "OWNER", "USER", "READ_ONLY" ], "description": "What the user can do with the wallet: `OWNER` manages it, `USER` spends from it, `READ_ONLY` only sees it.", "example": "OWNER" }, "firstName": { "type": "string", "description": "First name of the user.", "example": "Mariana" }, "lastName": { "type": "string", "description": "Last name of the user.", "example": "Costa" }, "email": { "type": "string", "description": "E-mail of the user.", "example": "mariana.costa@acme.com.br" } }, "required": [ "id", "role", "firstName", "lastName", "email" ], "description": "A user who can use the vehicle's wallet." }, "description": "Users who can use the wallet, and how." } }, "required": [ "id", "name", "status", "currency", "totalBalance", "balances", "shared" ], "description": "The vehicle's dedicated wallet. Omitted when the wallet can't be read at that moment (the vehicle itself is still returned), or when the list was requested with `includeWallet=false`." } }, "required": [ "customFields", "external", "id", "licensePlate", "make", "model", "name", "organizationId", "realmId", "status", "year" ], "description": "A vehicle, with its wallet's balance and users." }, "description": "Vehicles, newest first unless `order=ASC`." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "MjAyNi0xMC0xN1QxMzo0NToxMi4wMDBa" } }, "required": [ "items", "next" ], "description": "A page of vehicles." } } } }, "403": { "description": "`VEHICLE_MEMBERSHIP_REQUIRED` — You are not a member of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_MEMBERSHIP_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_MEMBERSHIP_REQUIRED", "origin": "VEHICLE", "message": "Organization membership required" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "BAD_REQUEST", "origin": "VEHICLE", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "name", "message": "Too big: expected string to have <=256 characters", "code": "NAME_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdVehicles", "summary": "Create a vehicle", "tags": [ "Vehicles" ], "x-p3-sidebar-order": 2, "description": "Registers a vehicle in the organization and creates its dedicated wallet.", "x-mint": { "content": "Every vehicle gets its own wallet in the organization's account, named after the license plate, so the vehicle's fuel and other card purchases are paid from it. The wallet is shared with the users in `shared` or, when you omit it, with you alone as `OWNER`. Every required vehicle custom field of the organization must have a value in `customFields`. A license plate is not unique: registering it again creates another vehicle, with a wallet of its own.\n\nOnly organization admins can register vehicles. An error from the wallet service — for example when no `OWNER` in `shared` is a member of the organization — is returned with its own status, `code` and `origin`, and no vehicle is created." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization to register the vehicle in.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Display name of the vehicle.", "example": "Delivery van 07" }, "licensePlate": { "type": "string", "minLength": 1, "maxLength": 16, "description": "License plate, in the old Brazilian format (`ABC1234`) or the Mercosul one (`ABC1D23`). Lowercase, hyphens and spaces are accepted and removed: `bra-2e19` is stored as `BRA2E19`.", "example": "BRA2E19" }, "make": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Manufacturer.", "example": "Fiat" }, "model": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Model.", "example": "Fiorino" }, "year": { "type": "integer", "minimum": 1900, "maximum": 2100, "description": "Model year.", "example": 2023 }, "shared": { "description": "Users who can use the vehicle's wallet. At least one must be an `OWNER`; a user who is not a member of the organization is left out. Omit it to share the wallet with you alone, as `OWNER`.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "ID of a user of the organization.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99" }, "role": { "type": "string", "enum": [ "OWNER", "USER", "READ_ONLY" ], "description": "What the user can do with the wallet: `OWNER` manages it, `USER` spends from it, `READ_ONLY` only sees it.", "example": "OWNER" }, "firstName": { "description": "Ignored: the name is read from the user.", "example": "Mariana", "type": "string" }, "lastName": { "description": "Ignored: the name is read from the user.", "example": "Costa", "type": "string" }, "email": { "description": "Ignored: the e-mail is read from the user.", "example": "mariana.costa@acme.com.br", "type": "string" } }, "required": [ "id", "role" ] } }, "customFields": { "description": "Values of the organization's vehicle custom fields, keyed by the custom field's `slug`. Every required one must have a value; `null`, `\"\"` and `[]` count as no value.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {} } }, "required": [ "name", "licensePlate", "make", "model", "year" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the vehicle.", "example": "6710b8e4c9e77b0012a4d6f1" }, "realmId": { "type": "string", "description": "ID of the realm the vehicle belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the vehicle belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Display name of the vehicle.", "example": "Delivery van 07" }, "licensePlate": { "type": "string", "description": "License plate, upper-cased with no hyphen or space: the old Brazilian format (`ABC1234`) or the Mercosul one (`ABC1D23`).", "example": "BRA2E19" }, "make": { "type": "string", "description": "Manufacturer.", "example": "Fiat" }, "model": { "type": "string", "description": "Model.", "example": "Fiorino" }, "year": { "type": "number", "description": "Model year.", "example": 2023 }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ], "description": "`ACTIVE`, or `ARCHIVED` once the vehicle was archived. An archived vehicle's wallet is blocked.", "example": "ACTIVE" }, "external": { "type": "object", "properties": { "walletId": { "type": "string", "description": "ID of the vehicle's dedicated wallet. Use it with the wallet, card and transaction endpoints of the Banking API.", "example": "6710b8e4c9e77b0012a4d6f3" }, "accountId": { "type": "string", "description": "ID of the organization's account the wallet belongs to.", "example": "66f2a1c7b4d3e80012c9a0b4" } }, "required": [ "walletId", "accountId" ], "description": "The vehicle's dedicated wallet." }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's vehicle custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "createdBy": { "type": "string", "description": "ID of the user who registered the vehicle.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "updatedBy": { "type": "string", "description": "ID of the user who last changed the vehicle.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "createdAt": { "type": "string", "description": "When the vehicle was registered.", "example": "2026-10-17T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the vehicle was last changed.", "example": "2026-10-17T13:45:12.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "name", "licensePlate", "make", "model", "year", "status", "external", "customFields" ], "description": "A vehicle of the organization's fleet." } } } }, "403": { "description": "`VEHICLE_ADMIN_REQUIRED` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_ADMIN_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_ADMIN_REQUIRED", "origin": "VEHICLE", "message": "Organization admin required" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID or the body failed validation; `fields` lists each offending field.\n\n`INVALID_LICENSE_PLATE` — `licensePlate` is in neither accepted format.\n\n`CUSTOM_FIELD_NOT_FOUND` — A `customFields` key is not the `slug` of an active vehicle custom field of the organization; `fields` names it.\n\n`CUSTOM_FIELD_INVALID_VALUE` — A `customFields` value doesn't fit its custom field's type or options; `fields` names it.\n\n`CUSTOM_FIELD_IS_REQUIRED` — A required vehicle custom field has no value in `customFields`; `fields` names it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "INVALID_LICENSE_PLATE", "CUSTOM_FIELD_NOT_FOUND", "CUSTOM_FIELD_INVALID_VALUE", "CUSTOM_FIELD_IS_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "BAD_REQUEST", "origin": "VEHICLE", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "name", "message": "Invalid input: expected string, received undefined", "code": "NAME_REQUIRED" } ] } } } }, "502": { "description": "`VEHICLE_BANKING_ACCOUNT_UNAVAILABLE` — The organization has no account to hold the vehicle's wallet; nothing was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_BANKING_ACCOUNT_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_BANKING_ACCOUNT_UNAVAILABLE", "origin": "VEHICLE", "message": "No banking account is provisioned for this organization" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/vehicles/{vehicleId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdVehiclesByVehicleId", "summary": "Get a vehicle", "tags": [ "Vehicles" ], "x-p3-sidebar-order": 3, "description": "Returns a vehicle of the organization, active or archived.", "x-mint": { "content": "The vehicle comes with its dedicated `wallet` — its balance and the users who can use it — unless the wallet can't be read at that moment, in which case the vehicle is returned without it." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the vehicle belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "vehicleId", "in": "path", "required": true, "description": "ID of the vehicle (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6710b8e4c9e77b0012a4d6f1" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the vehicle.", "example": "6710b8e4c9e77b0012a4d6f1" }, "realmId": { "type": "string", "description": "ID of the realm the vehicle belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the vehicle belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Display name of the vehicle.", "example": "Delivery van 07" }, "licensePlate": { "type": "string", "description": "License plate, upper-cased with no hyphen or space: the old Brazilian format (`ABC1234`) or the Mercosul one (`ABC1D23`).", "example": "BRA2E19" }, "make": { "type": "string", "description": "Manufacturer.", "example": "Fiat" }, "model": { "type": "string", "description": "Model.", "example": "Fiorino" }, "year": { "type": "number", "description": "Model year.", "example": 2023 }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ], "description": "`ACTIVE`, or `ARCHIVED` once the vehicle was archived. An archived vehicle's wallet is blocked.", "example": "ACTIVE" }, "external": { "type": "object", "properties": { "walletId": { "type": "string", "description": "ID of the vehicle's dedicated wallet. Use it with the wallet, card and transaction endpoints of the Banking API.", "example": "6710b8e4c9e77b0012a4d6f3" }, "accountId": { "type": "string", "description": "ID of the organization's account the wallet belongs to.", "example": "66f2a1c7b4d3e80012c9a0b4" } }, "required": [ "walletId", "accountId" ], "description": "The vehicle's dedicated wallet." }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's vehicle custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "createdBy": { "type": "string", "description": "ID of the user who registered the vehicle.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "updatedBy": { "type": "string", "description": "ID of the user who last changed the vehicle.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "createdAt": { "type": "string", "description": "When the vehicle was registered.", "example": "2026-10-17T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the vehicle was last changed.", "example": "2026-10-17T13:45:12.000Z", "format": "date-time" }, "wallet": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the wallet — the same as the vehicle's `external.walletId`.", "example": "6710b8e4c9e77b0012a4d6f3" }, "name": { "type": "string", "nullable": true, "description": "Name of the wallet: the vehicle's license plate when it was registered. Changing the vehicle's plate later doesn't rename the wallet.", "example": "BRA2E19" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "CANCELLING", "CANCELLED", "BLOCKED", "REPROVED", "FRAUD_ANALYSIS", "FRAUD_CONFIRMED" ], "description": "Status of the wallet. `BLOCKED` while the vehicle is archived.", "example": "ACTIVE" }, "currency": { "type": "string", "description": "Currency of the balances, as an ISO 4217 numeric code (`986` = BRL).", "example": "986" }, "totalBalance": { "type": "number", "description": "Total balance of the wallet across all of its categories, in cents.", "example": 35000 }, "balances": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "FLEX_NATIONAL", "FLEX_INTERNATIONAL", "FOOD", "GAS", "MOBILITY", "TOLL", "FLEX_NATIONAL_WITHOUT_WITHDRAWALS", "ADS", "SAAS", "HOTEL", "AIRLINES", "TRAVEL", "BLOCKED", "CASHBACK" ], "description": "Balance category.", "example": "GAS" }, "amount": { "type": "number", "description": "Balance of the category, in cents.", "example": 35000 } }, "required": [ "category", "amount" ], "description": "The balance of one category of the wallet." }, "description": "Balance per category. Empty while the wallet is being created." }, "shared": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the user.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "role": { "type": "string", "enum": [ "OWNER", "USER", "READ_ONLY" ], "description": "What the user can do with the wallet: `OWNER` manages it, `USER` spends from it, `READ_ONLY` only sees it.", "example": "OWNER" }, "firstName": { "type": "string", "description": "First name of the user.", "example": "Mariana" }, "lastName": { "type": "string", "description": "Last name of the user.", "example": "Costa" }, "email": { "type": "string", "description": "E-mail of the user.", "example": "mariana.costa@acme.com.br" } }, "required": [ "id", "role", "firstName", "lastName", "email" ], "description": "A user who can use the vehicle's wallet." }, "description": "Users who can use the wallet, and how." } }, "required": [ "id", "name", "status", "currency", "totalBalance", "balances", "shared" ], "description": "The vehicle's dedicated wallet. Omitted when the wallet can't be read at that moment (the vehicle itself is still returned), or when the list was requested with `includeWallet=false`." } }, "required": [ "customFields", "external", "id", "licensePlate", "make", "model", "name", "organizationId", "realmId", "status", "year" ], "description": "A vehicle, with its wallet's balance and users." } } } }, "403": { "description": "`VEHICLE_MEMBERSHIP_REQUIRED` — You are not a member of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_MEMBERSHIP_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_MEMBERSHIP_REQUIRED", "origin": "VEHICLE", "message": "Organization membership required" } } } }, "404": { "description": "`VEHICLE_NOT_FOUND` — No vehicle with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_NOT_FOUND", "origin": "VEHICLE", "message": "Vehicle not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "BAD_REQUEST", "origin": "VEHICLE", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "put": { "operationId": "putRealmsByRealmIdOrganizationsByOrganizationIdVehiclesByVehicleId", "summary": "Update a vehicle", "tags": [ "Vehicles" ], "x-p3-sidebar-order": 4, "description": "Replaces a vehicle's name, license plate, make, model and year.", "x-mint": { "content": "Send all five fields. `shared` replaces the users of the vehicle's wallet and `customFields` replaces all of the vehicle's custom field values; omit either to leave it as it is. Changing the license plate doesn't rename the wallet. An archived vehicle can't be updated — unarchive it first.\n\nOnly organization admins can update vehicles. An error from the wallet service — for example when no `OWNER` in `shared` is a member of the organization — is returned with its own status, `code` and `origin`, and the vehicle is not changed." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the vehicle belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "vehicleId", "in": "path", "required": true, "description": "ID of the vehicle (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6710b8e4c9e77b0012a4d6f1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Display name of the vehicle.", "example": "Delivery van 07" }, "licensePlate": { "type": "string", "minLength": 1, "maxLength": 16, "description": "License plate, in the old Brazilian format (`ABC1234`) or the Mercosul one (`ABC1D23`). Lowercase, hyphens and spaces are accepted and removed: `bra-2e19` is stored as `BRA2E19`.", "example": "BRA2E19" }, "make": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Manufacturer.", "example": "Fiat" }, "model": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Model.", "example": "Fiorino" }, "year": { "type": "integer", "minimum": 1900, "maximum": 2100, "description": "Model year.", "example": 2023 }, "shared": { "description": "Replaces the users who can use the vehicle's wallet. At least one must be an `OWNER`; a user who is not a member of the organization is left out. Omit it to keep them as they are.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "ID of a user of the organization.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99" }, "role": { "type": "string", "enum": [ "OWNER", "USER", "READ_ONLY" ], "description": "What the user can do with the wallet: `OWNER` manages it, `USER` spends from it, `READ_ONLY` only sees it.", "example": "OWNER" }, "firstName": { "description": "Ignored: the name is read from the user.", "example": "Mariana", "type": "string" }, "lastName": { "description": "Ignored: the name is read from the user.", "example": "Costa", "type": "string" }, "email": { "description": "Ignored: the e-mail is read from the user.", "example": "mariana.costa@acme.com.br", "type": "string" } }, "required": [ "id", "role" ] } }, "customFields": { "description": "Replaces ALL of the vehicle's custom field values, keyed by the custom field's `slug`: a field you leave out, or send as `null`, `\"\"` or `[]`, is cleared, and `{}` clears them all. Omit `customFields` to keep them as they are.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {} } }, "required": [ "name", "licensePlate", "make", "model", "year" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the vehicle.", "example": "6710b8e4c9e77b0012a4d6f1" }, "realmId": { "type": "string", "description": "ID of the realm the vehicle belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the vehicle belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Display name of the vehicle.", "example": "Delivery van 07" }, "licensePlate": { "type": "string", "description": "License plate, upper-cased with no hyphen or space: the old Brazilian format (`ABC1234`) or the Mercosul one (`ABC1D23`).", "example": "BRA2E19" }, "make": { "type": "string", "description": "Manufacturer.", "example": "Fiat" }, "model": { "type": "string", "description": "Model.", "example": "Fiorino" }, "year": { "type": "number", "description": "Model year.", "example": 2023 }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ], "description": "`ACTIVE`, or `ARCHIVED` once the vehicle was archived. An archived vehicle's wallet is blocked.", "example": "ACTIVE" }, "external": { "type": "object", "properties": { "walletId": { "type": "string", "description": "ID of the vehicle's dedicated wallet. Use it with the wallet, card and transaction endpoints of the Banking API.", "example": "6710b8e4c9e77b0012a4d6f3" }, "accountId": { "type": "string", "description": "ID of the organization's account the wallet belongs to.", "example": "66f2a1c7b4d3e80012c9a0b4" } }, "required": [ "walletId", "accountId" ], "description": "The vehicle's dedicated wallet." }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's vehicle custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "createdBy": { "type": "string", "description": "ID of the user who registered the vehicle.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "updatedBy": { "type": "string", "description": "ID of the user who last changed the vehicle.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "createdAt": { "type": "string", "description": "When the vehicle was registered.", "example": "2026-10-17T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the vehicle was last changed.", "example": "2026-10-17T13:45:12.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "name", "licensePlate", "make", "model", "year", "status", "external", "customFields" ], "description": "A vehicle of the organization's fleet." } } } }, "403": { "description": "`VEHICLE_ADMIN_REQUIRED` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_ADMIN_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_ADMIN_REQUIRED", "origin": "VEHICLE", "message": "Organization admin required" } } } }, "404": { "description": "`VEHICLE_NOT_FOUND` — No vehicle with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_NOT_FOUND", "origin": "VEHICLE", "message": "Vehicle not found" } } } }, "409": { "description": "`VEHICLE_NOT_ACTIVE` — The vehicle is archived; unarchive it first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_NOT_ACTIVE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_NOT_ACTIVE", "origin": "VEHICLE", "message": "Vehicle is not active — it has already been archived" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID or the body failed validation; `fields` lists each offending field.\n\n`INVALID_LICENSE_PLATE` — `licensePlate` is in neither accepted format.\n\n`CUSTOM_FIELD_NOT_FOUND` — A `customFields` key is not the `slug` of a vehicle custom field of the organization; `fields` names it.\n\n`CUSTOM_FIELD_INVALID_VALUE` — A `customFields` value doesn't fit its custom field's type or options; `fields` names it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "INVALID_LICENSE_PLATE", "CUSTOM_FIELD_NOT_FOUND", "CUSTOM_FIELD_INVALID_VALUE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "BAD_REQUEST", "origin": "VEHICLE", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "name", "message": "Invalid input: expected string, received undefined", "code": "NAME_REQUIRED" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/vehicles/{vehicleId}/archive": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdVehiclesByVehicleIdArchive", "summary": "Archive a vehicle", "tags": [ "Vehicles" ], "x-p3-sidebar-order": 5, "description": "Archives a vehicle and blocks its wallet.", "x-mint": { "content": "The wallet's available balance goes back to the organization's default wallet — a blocked or cashback balance stays in it — and the wallet is blocked, so it can no longer pay for anything; the vehicle's `status` then becomes `ARCHIVED`. An archived vehicle is still listed and can still be read, and unarchive reactivates it. No request body.\n\nOnly organization admins can archive vehicles. If the wallet can't be emptied or blocked, that error is returned with its own status, `code` and `origin` and the vehicle stays `ACTIVE`; sending the request again is safe." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the vehicle belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "vehicleId", "in": "path", "required": true, "description": "ID of the vehicle (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6710b8e4c9e77b0012a4d6f1" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the vehicle.", "example": "6710b8e4c9e77b0012a4d6f1" }, "realmId": { "type": "string", "description": "ID of the realm the vehicle belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the vehicle belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Display name of the vehicle.", "example": "Delivery van 07" }, "licensePlate": { "type": "string", "description": "License plate, upper-cased with no hyphen or space: the old Brazilian format (`ABC1234`) or the Mercosul one (`ABC1D23`).", "example": "BRA2E19" }, "make": { "type": "string", "description": "Manufacturer.", "example": "Fiat" }, "model": { "type": "string", "description": "Model.", "example": "Fiorino" }, "year": { "type": "number", "description": "Model year.", "example": 2023 }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ], "description": "`ACTIVE`, or `ARCHIVED` once the vehicle was archived. An archived vehicle's wallet is blocked.", "example": "ARCHIVED" }, "external": { "type": "object", "properties": { "walletId": { "type": "string", "description": "ID of the vehicle's dedicated wallet. Use it with the wallet, card and transaction endpoints of the Banking API.", "example": "6710b8e4c9e77b0012a4d6f3" }, "accountId": { "type": "string", "description": "ID of the organization's account the wallet belongs to.", "example": "66f2a1c7b4d3e80012c9a0b4" } }, "required": [ "walletId", "accountId" ], "description": "The vehicle's dedicated wallet." }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's vehicle custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "createdBy": { "type": "string", "description": "ID of the user who registered the vehicle.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "updatedBy": { "type": "string", "description": "ID of the user who last changed the vehicle.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "createdAt": { "type": "string", "description": "When the vehicle was registered.", "example": "2026-10-17T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the vehicle was last changed.", "example": "2026-10-17T13:45:12.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "name", "licensePlate", "make", "model", "year", "status", "external", "customFields" ], "description": "A vehicle of the organization's fleet." } } } }, "403": { "description": "`VEHICLE_ADMIN_REQUIRED` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_ADMIN_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_ADMIN_REQUIRED", "origin": "VEHICLE", "message": "Organization admin required" } } } }, "404": { "description": "`VEHICLE_NOT_FOUND` — No vehicle with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_NOT_FOUND", "origin": "VEHICLE", "message": "Vehicle not found" } } } }, "409": { "description": "`VEHICLE_NOT_ACTIVE` — The vehicle is already archived.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_NOT_ACTIVE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_NOT_ACTIVE", "origin": "VEHICLE", "message": "Vehicle is not active — it has already been archived" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "BAD_REQUEST", "origin": "VEHICLE", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/vehicles/{vehicleId}/unarchive": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdVehiclesByVehicleIdUnarchive", "summary": "Unarchive a vehicle", "tags": [ "Vehicles" ], "x-p3-sidebar-order": 6, "description": "Reactivates an archived vehicle: its wallet is unblocked.", "x-mint": { "content": "The vehicle's `status` goes back to `ACTIVE` and its wallet can pay again. Archiving moved the wallet's available balance to the organization's default wallet, so add funds before using it. No request body.\n\nOnly organization admins can unarchive vehicles. If the wallet can't be unblocked, that error is returned with its own status, `code` and `origin` and the vehicle stays `ARCHIVED`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the vehicle belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "vehicleId", "in": "path", "required": true, "description": "ID of the vehicle (24 hexadecimal characters).", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$" }, "example": "6710b8e4c9e77b0012a4d6f1" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the vehicle.", "example": "6710b8e4c9e77b0012a4d6f1" }, "realmId": { "type": "string", "description": "ID of the realm the vehicle belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the vehicle belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Display name of the vehicle.", "example": "Delivery van 07" }, "licensePlate": { "type": "string", "description": "License plate, upper-cased with no hyphen or space: the old Brazilian format (`ABC1234`) or the Mercosul one (`ABC1D23`).", "example": "BRA2E19" }, "make": { "type": "string", "description": "Manufacturer.", "example": "Fiat" }, "model": { "type": "string", "description": "Model.", "example": "Fiorino" }, "year": { "type": "number", "description": "Model year.", "example": 2023 }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ], "description": "`ACTIVE`, or `ARCHIVED` once the vehicle was archived. An archived vehicle's wallet is blocked.", "example": "ACTIVE" }, "external": { "type": "object", "properties": { "walletId": { "type": "string", "description": "ID of the vehicle's dedicated wallet. Use it with the wallet, card and transaction endpoints of the Banking API.", "example": "6710b8e4c9e77b0012a4d6f3" }, "accountId": { "type": "string", "description": "ID of the organization's account the wallet belongs to.", "example": "66f2a1c7b4d3e80012c9a0b4" } }, "required": [ "walletId", "accountId" ], "description": "The vehicle's dedicated wallet." }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Values of the organization's vehicle custom fields, keyed by the custom field's `slug`. Empty when none were set.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" } }, "createdBy": { "type": "string", "description": "ID of the user who registered the vehicle.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "updatedBy": { "type": "string", "description": "ID of the user who last changed the vehicle.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "createdAt": { "type": "string", "description": "When the vehicle was registered.", "example": "2026-10-17T13:45:12.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the vehicle was last changed.", "example": "2026-10-17T13:45:12.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "name", "licensePlate", "make", "model", "year", "status", "external", "customFields" ], "description": "A vehicle of the organization's fleet." } } } }, "403": { "description": "`VEHICLE_ADMIN_REQUIRED` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_ADMIN_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_ADMIN_REQUIRED", "origin": "VEHICLE", "message": "Organization admin required" } } } }, "404": { "description": "`VEHICLE_NOT_FOUND` — No vehicle with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_NOT_FOUND", "origin": "VEHICLE", "message": "Vehicle not found" } } } }, "409": { "description": "`VEHICLE_NOT_ARCHIVED` — The vehicle is not archived.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "VEHICLE_NOT_ARCHIVED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "VEHICLE_NOT_ARCHIVED", "origin": "VEHICLE", "message": "Vehicle is not archived — it is already active" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "VEHICLE" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "BAD_REQUEST", "origin": "VEHICLE", "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.", "fields": [ { "field": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } } } }