> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Create a vehicle > Registers a vehicle in the organization and creates its dedicated wallet. 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. Only 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. ## OpenAPI ````yaml /api-reference/vehicle.openapi.json post /realms/{realmId}/organizations/{organizationId}/vehicles 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 security: [] tags: - name: Vehicles paths: /realms/{realmId}/organizations/{organizationId}/vehicles: post: tags: - Vehicles summary: Create a vehicle description: >- Registers a vehicle in the organization and creates its dedicated wallet. operationId: postRealmsByRealmIdOrganizationsByOrganizationIdVehicles parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `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. Format: `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. --- Example: `{"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. --- Example: `{"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. `INVALID_LICENSE_PLATE` — `licensePlate` is in neither accepted format. `CUSTOM_FIELD_NOT_FOUND` — A `customFields` key is not the `slug` of an active vehicle custom field of the organization; `fields` names it. `CUSTOM_FIELD_INVALID_VALUE` — A `customFields` value doesn't fit its custom field's type or options; `fields` names it. `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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.