DriveB

35. Ordem de Serviço

Gerencia o ciclo de vida completo de uma Ordem de Serviço (ServiceRequest): criação, agendamento, execução, cancelamento, avaliação, comentários e consultas/filtros paginados.

Consultar entidade por Id

Retorna os dados completos de uma ordem de serviço específica.

Endpoint: /api/service-requests/{id}

Método: GET

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.

Response body (schema mestre ServiceRequest, reutilizado por diversos endpoints deste módulo):

{
"id": 0,
"requestId": "string",
"stepStatus": "string",
"vehicleId": 0,
"clientId": 0,
"parentId": 0,
"budgetId": 0,
"parentServiceRequestId": 0,
"parentRequestId": "string",
"currentKm": 0,
"correctiveDescription": "string",
"tiresDescription": "string",
"tiresAmount": 0,
"observations": "string",
"observationRemoveVehicle": "string",
"serviceType": "string",
"status": "string",
"displayConfirmedScheduling": "string",
"carWorkshopName": "string",
"carWorkshopId": 0,
"carWorkshopOriginId": 0,
"carWorkshopCityName": "string",
"preventiveReviewKm": 0,
"modifiedAt": "2024-01-01T00:00:00Z",
"modifiedBy": "string",
"serviceConfirmedDrive": true,
"isEmptyBudgetFlow": true,
"isComplementary": true,
"reasonCancel": "string",
"reasonsToCancel": [
"REASON_VEHICLE_NO_SHOW_FOR_APPOINTMENT"
],
"displayReasonCancel": "string",
"observationCancel": "string",
"date": "2024-01-01T00:00:00Z",
"period": "string",
"serviceRequestRatingId": 0,
"serviceRequestRating": {
"id": 0,
"createdAt": "2024-01-01T00:00:00Z",
"username": "string",
"carWorkshopAttendanceRating": 0,
"carWorkshopCleaningRating": 0,
"serviceRating": 0,
"platformRating": 0,
"observation": "string"
},
"completionPrediction": "2024-01-01T00:00:00Z",
"completionPredictionPeriod": "string",
"displayCompletionPredictionPeriod": "string",
"isPreApproved": true,
"isPreApprovedCarworkshop": true,
"checkinChecklistFilled": true,
"checkoutChecklistFilled": true,
"carWorkshopKm": 0,
"periodLimitCancel": "2024-01-01T00:00:00Z",
"vehicleArrivalConfirmationDate": "2024-01-01T00:00:00Z",
"vehicleArrivalConfirmationDateByUser": "2024-01-01T00:00:00Z",
"drivers": [
{
"id": 0,
"serviceRequestId": 0,
"driverId": 0,
"name": "string",
"telephoneNumber": "string",
"profilePicture": "string"
}
],
"serviceStartedAt": "2024-01-01T00:00:00Z",
"endedIn": "2024-01-01T00:00:00Z",
"vehicleArrived": true,
"isPuc": true,
"hadIntentionOnComplementaryService": true,
"workshopQuotationPrevisionDate": "2024-01-01T00:00:00Z",
"workshopQuotationPrevisionPeriod": "MORNING",
"workshopCompletionPrevisionDate": "2024-01-01T00:00:00Z",
"workshopCompletionPrevisionPeriod": "MORNING",
"vehicleAttendanceWorkshopStatus": "OUTSIDE_WORKSHOP",
"confirmedUnattendanceDate": "2024-01-01T00:00:00Z",
"billingCheckNfByBotPart": true,
"billingCheckNfByBotService": true,
"timeService": "2024-01-01T00:00:00Z",
"orderIdPart": "string",
"orderIdService": "string",
"serviceRecommendationPlans": [
{
"id": 0,
"nextServicePredictionId": 0,
"key": "string",
"displayValue": "string",
"enabled": true,
"mandatoryFields": "string",
"timeToService": {
"value": null,
"unit": null
},
"nextServiceStatus": "SCHEDULED",
"damageReports": [],
"seasonalNeeds": [],
"oemServices": [],
"isSelected": true
}
],
"createdAt": "2024-01-01T00:00:00Z",
"serviceInvoiceForCustomer": true,
"billingCorporateNameByPart": "string",
"billingTaxIdentifierByPart": "string",
"billingAddressByPart": "string",
"billingCorporateNameByService": "string",
"billingTaxIdentifierByService": "string",
"billingAddressByService": "string",
"billingCutOffDay": 0,
"billingRulesByCarWorkShop": "string",
"serverUrl": "string",
"categoryVehicleAttendanceEvidence": "MANDATORY",
"categoryServiceWearEvidence": "MANDATORY",
"categoryServiceFinishedEvidence": "MANDATORY",
"periodServiceCompleted": "2024-01-01T00:00:00Z",
"purchaseOrderPart": 0,
"isWhiteLabelClient": true,
"clientType": "DEFAULT",
"preventiveChangedToCorrective": true,
"rescheduled": true,
"creditLimit": 0,
"totalCreditUsed": 0,
"availableCredit": 0,
"finalizationWorkshopServiceDate": "2024-01-01",
"finalizationWorkshopServiceTime": "string",
"flowNotifications": [
{
"serviceRequest": {
"serviceRequestDTO": null,
"clientDTO": null,
"vehicleDTO": null,
"carWorkshopDTO": null,
"budgetDTO": null,
"id": null,
"notificationClientId": null,
"notificationCarWorkshopId": null,
"notificationDriverIds": null,
"serverUrl": null
},
"type": "SCHEDULE_REQUESTED"
}
],
"orderId": "string",
"fee": true,
"preventive": true,
"isFee": true
}

Atualizar entidade

Atualiza os dados de uma ordem de serviço existente.

Endpoint: /api/service-requests/{id}

Método: PUT

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.

Request body: Não detalhado na documentação de origem.

Response body: Mesmo schema ServiceRequest do endpoint "Consultar entidade por Id" (sem envelope message/payLoad).

Iniciar execução do serviço

Atualiza o status da OS para "em execução".

Endpoint: /api/service-requests/{id}/start-service

Método: PUT

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.

Response body:

{
"message": "string",
"payLoad": { /* mesmo schema ServiceRequest do endpoint "Consultar entidade por Id" */ },
"warning": true
}

Confirmar drive de serviço

Marca a confirmação do serviço pela Drive, com motivo e observação.

Endpoint: /api/service-requests/{id}/service-confirmed-drive

Método: PUT

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.
  • reason (query, obrigatório, string) — Motivo.
  • observation (query, obrigatório, string) — Observação.

Response body: Envelope { message, payLoad, warning }, onde payLoad segue o mesmo schema ServiceRequest do endpoint "Consultar entidade por Id".

Reagendar serviço

Atualiza a OS para um novo agendamento.

Endpoint: /api/service-requests/{id}/rescheduling

Método: PUT

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.

Request body:

{
"carWorkshopId": 0,
"date": "2024-01-01T00:00:00Z",
"period": "string",
"timeService": "2024-01-01T00:00:00Z"
}

Response body: Envelope { message, payLoad, warning }, onde payLoad segue o mesmo schema ServiceRequest.

Registrar retirada do veículo pelo motorista

Atualiza a OS indicando que o veículo foi coletado pelo motorista.

Endpoint: /api/service-requests/{id}/remove-vehicle

Método: PUT

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.
  • observationRemoveVehicle (query, obrigatório, string) — Observação sobre a retirada.

Request body:

{
"id": 0,
"modifiedAt": "2024-01-01T00:00:00Z",
"status": "string",
"stepStatus": "string"
}

Response body: Envelope { message, payLoad, warning }, onde payLoad segue o mesmo schema ServiceRequest.

Atualizar previsões definidas pela oficina

Atualiza as datas/períodos estimados de orçamento e conclusão informados pela oficina.

Endpoint: /api/service-requests/{id}/prevision-update

Método: PUT

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.

Request body:

{
"date": "2024-01-01T00:00:00Z",
"period": "MORNING"
}

Códigos de resposta:

  • 200 — Sucesso.
  • 403 — Não autorizado.
  • 500 — Erro interno.

Confirmar não comparecimento do veículo

Registra que o veículo não compareceu ao agendamento.

Endpoint: /api/service-requests/{id}/not-appear-schedule

Método: PUT

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da OS.

Códigos de resposta:

  • 200 — Não comparecimento confirmado.
  • 400 — Requisição inválida.
  • 401 — Não autenticado.
  • 403 — Acesso negado.
  • 500 — Erro interno.

Finalizar serviço

Marca a OS como concluída pela oficina.

Endpoint: /api/service-requests/{id}/finalize-service

Método: PUT

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da OS.

Request body:

{
"finalizationWorkshopServiceDate": "2024-01-01",
"finalizationWorkshopServiceTime": "string"
}

Response body: Envelope { message, payLoad, warning }, onde payLoad segue o mesmo schema ServiceRequest.

Reprovar solicitação de serviço

Reprova a OS, informando motivos.

Endpoint: /api/service-requests/{id}/disapprove

Método: PUT

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da OS.

Request body (o corpo abaixo é idêntico ao do endpoint "Finalizar serviço" na documentação de origem — recomenda-se confirmar se este é o payload correto para reprovação):

{
"finalizationWorkshopServiceDate": "2024-01-01",
"finalizationWorkshopServiceTime": "string"
}

Response body: Envelope { message, payLoad, warning }, onde payLoad segue o mesmo schema ServiceRequest.

Cancelar solicitação de serviço

Cancela a OS informando motivo e observação.

Endpoint: /api/service-requests/{id}/cancel

Método: PUT

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.
  • reason (query, obrigatório, string) — Motivo do cancelamento.
  • observation (query, obrigatório, string) — Observação.

Response body: Envelope { message, payLoad, warning }, onde payLoad segue o mesmo schema ServiceRequest.

Criar nova entidade

Cria uma nova ordem de serviço.

Endpoint: /api/service-requests

Método: POST

Request body: Mesmo schema ServiceRequest do endpoint "Consultar entidade por Id", enviado com os campos preenchidos para criação (incluindo drivers e flowNotifications com valores reais, ex.: "type": "SCHEDULE_REQUESTED").

Response body: Mesmo schema ServiceRequest (sem envelope message/payLoad), representando a entidade recém-criada.

Inserir comentário na OS

Adiciona um comentário à ordem de serviço.

Endpoint: /api/service-requests/{id}/service-request-comment

Método: POST

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.

Request body:

{
"id": 0,
"serviceRequestId": 0,
"createdAt": "2024-01-01T00:00:00Z",
"username": "string",
"comment": "string"
}

Response body:

{
"message": "string",
"payLoad": {
"id": 0,
"serviceRequestId": 0,
"createdAt": "2024-01-01T00:00:00Z",
"username": "string",
"comment": "string"
},
"warning": true
}

Gerar pedido de venda (fila assíncrona)

Cria uma mensagem de fila para gerar um pedido de venda (sales order).

Endpoint: /api/service-requests/{id}/sales-order

Método: POST

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.

Response body:

{}

Adicionar avaliação à OS

Registra uma avaliação de atendimento, limpeza, serviço e plataforma.

Endpoint: /api/service-requests/{id}/ratings

Método: POST

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.

Request body:

{
"id": 0,
"createdAt": "2024-01-01T00:00:00Z",
"username": "string",
"carWorkshopAttendanceRating": 0,
"carWorkshopCleaningRating": 0,
"serviceRating": 0,
"platformRating": 0,
"observation": "string"
}

Response body:

{
"message": "string",
"payLoad": {
"id": 0,
"createdAt": "2024-01-01T00:00:00Z",
"username": "string",
"carWorkshopAttendanceRating": 0,
"carWorkshopCleaningRating": 0,
"serviceRating": 0,
"platformRating": 0,
"observation": "string"
},
"warning": true
}

Gerar pedido de compra (fila assíncrona)

Cria uma mensagem de fila para gerar um pedido de compra (purchase order).

Endpoint: /api/service-requests/{id}/purchase-order

Método: POST

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.

Response body:

{}

Buscar OS por filtros (app mobile da oficina)

Busca paginada de OS via query params, usada pelo app mobile de oficinas.

Endpoint: /api/service-requests/filters

Método: GET

Parâmetros:

  • filterDTO (query, obrigatório, tipo não especificado) — Objeto de filtros.
  • page (query, obrigatório, tipo não especificado) — Paginação.

Response body (schema paginado ServiceRequestSummary, reutilizado nos endpoints "Buscar OS por filtros" e "Buscar OS por informações"):

{
"totalElements": 0,
"totalPages": 0,
"size": 0,
"content": [
{
"id": 0,
"requestId": "string",
"modelName": "string",
"clientBlockName": "string",
"displayConfirmedScheduling": "string",
"serviceType": "string",
"carWorkshopId": 0,
"carWorkshopName": "string",
"carWorkshopAddress": "string",
"categoryName": "string",
"cityStateName": "string",
"tags": [],
"orderIdPart": "string",
"orderIdService": "string",
"status": "string",
"displayStatus": "string",
"backofficePendency": true,
"carWorkshopPendency": true,
"date": "2024-01-01",
"period": "string",
"partValue": 0,
"serviceValue": 0,
"blockId": 0,
"clientType": "DEFAULT",
"callToAction": "BACKOFFICE_PENDING_SCHEDULED",
"vehicleId": 0,
"clientId": 0,
"checkoutType": "YES",
"workshopRefused": true,
"attendanceCategory": true,
"finishedCategory": true,
"timeService": "2024-01-01T00:00:00Z",
"serviceRecommendationTypes": [],
"serviceRecommendations": [],
"endedIn": "2024-01-01",
"observations": "string",
"drivers": "string",
"preventiveChangedToCorrective": true,
"totalResponsesFromWorkshop": 0,
"rated": true,
"logoImage": "string",
"uiConfigurationId": 0,
"franchiseUiConfiguration": 0,
"serviceRequestRatingId": 0,
"costCenter": "string",
"whiteLabelClient": true,
"puc": true,
"complementary": true,
"clientQuestioningPending": true,
"isFee": true
}
],
"number": 0,
"sort": {
"empty": true,
"sorted": true,
"unsorted": true
},
"pageable": {
"offset": 0,
"sort": {
"empty": true,
"sorted": true,
"unsorted": true
},
"pageNumber": 0,
"unpaged": true,
"paged": true,
"pageSize": 0
},
"numberOfElements": 0,
"first": true,
"last": true,
"empty": true
}

Buscar OS por filtros

Mesma busca do endpoint "Buscar OS por filtros (app mobile da oficina)", porém com filtros avançados enviados no corpo da requisição.

Endpoint: /api/service-requests/filters

Método: POST

Parâmetros:

  • page (query, obrigatório, tipo não especificado) — Paginação. (campo duplicado na documentação de origem — recomenda-se revisar)

Request body:

{
"id": 0,
"requestId": "string",
"clientCorporateName": "string",
"blockCode": "string",
"confirmationDate": "2024-01-01",
"confirmationDateISO": "2024-01-01",
"carWorkshopName": "string",
"status": "string",
"stepStatus": "string",
"serviceConfirmedDrive": true,
"isComplementary": true,
"isClientQuestioningPending": true,
"clientId": 0,
"carWorkshopId": 0,
"carWorkshopOriginId": 0,
"verifyCarWorkshopParent": true,
"categoryId": 0,
"driverId": 0,
"vehicleId": 0,
"vehicles": [
0
],
"serviceType": "string",
"cityId": "string",
"stateId": "string",
"countryId": "string",
"backofficeUserId": 0,
"backofficeAdminId": 0,
"licensePlate": "string",
"fleetAdministratorId": 0,
"confirmationMonth": "2024-01-01",
"backofficePendency": true,
"carWorkshopPendency": true,
"listStatus": [
"string"
],
"tags": [
"string"
],
"filterCondition": "EQUALS",
"vehicleArrived": true,
"blocks": [
0
],
"budgetAnalystId": 0,
"multipleCountries": [
"string"
],
"multipleCountriesIds": [
0
],
"workshopRefused": true,
"serviceIdModelDescription": "string",
"serviceRecommendationTypeId": 0,
"tagType": "string",
"franchiseIds": [
0
],
"listServiceRecommendationTypeIds": [
0
],
"listWorkshopIds": [
0
],
"preventiveChangedToCorrective": true,
"orderId": "string",
"haveGuaranteeOrCourtesy": true,
"filterByOrderIdPartNull": true,
"filterByOrderIdServiceNull": true,
"filterByHeadquarter": true,
"filterBySubsidiary": true,
"attendanceCategoryEvidence": true,
"finishedCategoryEvidence": true,
"opened": true,
"isVerifyCarWorkshopParent": true,
"complementary": true
}

Response body: Mesmo schema paginado ServiceRequestSummary do endpoint "Buscar OS por filtros (app mobile da oficina)".

Consultar SLAs da OS

Retorna os intervalos de SLA de orçamento e execução.

Endpoint: /api/service-requests/{id}/sla

Método: GET

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.
  • page (query, obrigatório, tipo não especificado) — Paginação. (presença deste parâmetro é incomum, já que a resposta não é paginada — recomenda-se revisar)

Response body:

{
"budgetSubmissionTimeInterval": "string",
"budgetApprovalTimeInterval": "string",
"serviceExecutionTimeInterval": "string"
}

Consultar histórico da OS

Retorna os eventos de histórico registrados para a OS.

Endpoint: /api/service-requests/{id}/history

Método: GET

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.

Response body:

[
{
"id": 0,
"serviceRequestId": 0,
"description": "string",
"username": "string",
"createdAt": "2024-01-01T00:00:00Z",
"historyProfile": "string"
}
]

Consultar tempo de processamento (check-in)

Retorna métricas de tempo entre etapas do processo, a partir do check-in.

Endpoint: /api/service-requests/{id}/checkin-process-time

Método: GET

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da OS.

Response body:

{
"serviceRequestId": 0,
"checkinToMoment": 0,
"checkinToQuoteWorkshop": 0,
"checkinToBudgetApprovalFleetManager": 0,
"checkinToFleetManagerApproval": 0,
"checkinToExecutionStarts": 0,
"checkinToCheckout": 0
}

Consultar informações de faturamento

Retorna dados de faturamento (razão social, CNPJ, endereço) de peças e serviço.

Endpoint: /api/service-requests/{id}/billing-info

Método: GET

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade.

Response body:

{
"part": {
"corporateName": "string",
"taxIdentifier": "string",
"address": "string",
"purchaseOrderPart": 0
},
"service": {
"corporateName": "string",
"taxIdentifier": "string",
"address": "string"
},
"billingCutOffDate": "2024-01-01",
"billingRulesByCarWorkShop": "string"
}

Disparar notificações (debug)

Endpoint utilitário para disparo manual de notificações — uso exclusivo de depuração.

Endpoint: /api/service-requests/trigger-notifications

Método: GET

Parâmetros:

  • id (path, obrigatório, integer) — Identificador da entidade. (a tabela de origem indica parâmetro path "id", porém o endpoint informado não contém {id} na URL — recomenda-se revisar)

Códigos de resposta:

  • 200 — OK.
  • 403 — Não autorizado.
  • 500 — Erro interno.

Consultar OS simplificadas

Retorna uma versão resumida de múltiplas OS a partir de uma lista de IDs.

Endpoint: /api/service-requests/simplified

Método: GET

Parâmetros:

  • ids (query, obrigatório, array<integer>) — Lista de identificadores das OS.

Response body:

[
{
"id": 0,
"requestId": "string",
"modelName": "string",
"clientName": "string",
"displayServiceType": "string",
"carWorkshopName": "string",
"cityStateName": "string",
"date": "2024-01-01T00:00:00Z",
"period": "string",
"displayConfirmedScheduling": "string",
"status": "string",
"displayStatus": "string"
}
]

Consultar todos os status de serviço

Retorna todos os status de serviço disponíveis (enum de status da OS).

Endpoint: /api/service-requests/service-status

Método: GET

Parâmetros:

  • ids (query, obrigatório, array<integer>) — Lista de identificadores das OS. (descrição herdada da documentação de origem — pode não se aplicar a este endpoint de listagem de status)

Response body:

[
{
"name": "string",
"value": "string"
}
]

Consultar motivos de cancelamento

Retorna a lista de motivos possíveis para cancelamento, filtrável por tipo.

Endpoint: /api/service-requests/reasons-cancellation

Método: GET

Parâmetros:

  • type (query, obrigatório, string) — Tipo de cancelamento.

Response body:

[
{
"name": "string",
"value": "string"
}
]

Fila de aprovação do cliente (paginada)

Retorna todas as OS pendentes de aprovação pelo cliente, paginadas.

Endpoint: /api/service-requests/client-approval-queue

Método: GET

Parâmetros:

  • page (query, obrigatório, tipo não especificado) — Paginação.

Response body (apesar do nome do endpoint indicar resposta "paginada", o exemplo de payload na documentação de origem mostra um objeto único, não um envelope de página — recomenda-se confirmar):

{
"id": 0,
"requestId": "string",
"blockName": "string",
"carWorkshopName": "string",
"budgetId": 0,
"totalBudgetClient": 0,
"workflowClientApprovalsCount": 0,
"workflowClientApprovalsTotal": 0,
"workflowClientIsLastApprover": true,
"date": "2024-01-01T00:00:00Z",
"clientApproverProfile": "DRIVER",
"budgetStatus": "string"
}

Buscar OS por informações

Busca paginada de OS via query params no endpoint raiz do recurso.

Endpoint: /api/service-requests/

Método: GET

Parâmetros:

  • filterDTO (query, obrigatório, tipo não especificado) — Objeto de filtros.
  • page (query, obrigatório, tipo não especificado) — Paginação.

Response body: Mesmo schema paginado ServiceRequestSummary do endpoint "Buscar OS por filtros (app mobile da oficina)".