Bem-vindo à documentação do Módulo de Serviços, Manutenções e Notas Fiscais. Este módulo é responsável por gerenciar todo o ciclo de vida de manutenção da frota, integrando veículos, motoristas, oficinas credenciadas, orçamentos, aprovações e o posterior faturamento com controle de notas fiscais.

Esta documentação está dividida em 4 seções principais:

Fundamentos — Entenda as regras de negócio, status e conceitos-chave.
Fluxo de Trabalho (Workflow) — Compreenda a ordem correta das integrações e ciclo de aprovação.
Referência de Endpoints — Veja as especificações técnicas de cada rota (Headers, Payloads e Schemas).
Erros e Resolução de Problemas — Saiba como tratar as respostas da API e solucionar problemas operacionais.

Fundamentos

Antes de iniciar o desenvolvimento de suas integrações de manutenção, familiarize-se com os conceitos essenciais que regem as regras de negócio deste módulo.

Conceitos-Chave

Solicitação de Serviço (Service Request): É a intenção de manutenção registrada para um veículo. Pode ser do tipo Preventiva (baseada em planos de manutenção periódicos e quilometragem) ou Corretiva (reparos de danos ou falhas imprevistas relatadas).
Oficina (Car Workshop): Estabelecimento parceiro credenciado na rede para prestar serviços de manutenção. Cada oficina possui restrições de marcas que atende, especialidades de serviço e tabelas de preços negociadas.
Orçamento (Budget): Documento gerado pela oficina detalhando as peças (budgetPartItems) e serviços (budgetServiceItems) necessários, com seus respectivos custos e taxas. Passa por fluxo de aprovação obrigatório do cliente antes da execução.
Faturamento e Notas Fiscais (Billing): Fase posterior à execução do serviço. Consolida os valores aprovados e exige a validação e upload dos respectivos documentos fiscais (NF-e de peças e NFS-e de serviços).

Estrutura de Estados (Ciclo da Manutenção)

Uma Solicitação de Serviço passa por múltiplos estados lógicos até o faturamento final:

Agendamento → Pendente Backoffice → Em Regulação (Orçamento) → Orçamento Aprovado → Serviço Concluído → Faturado

Entidades Operacionais na API

Entidade Operacional	Identificador em API	Descrição
Solicitação	`serviceRequestId`	Código exclusivo da ordem de serviço.
Orçamento	`budgetId`	ID do orçamento associado à solicitação.
Faturamento	`billingId`	Registro de controle financeiro e fiscal da manutenção.

Fluxo de Trabalho (Workflow)

Esta seção descreve os fluxos sequenciais recomendados para realizar agendamentos, aprovar orçamentos e anexar documentos fiscais sem quebra de regras de negócio.

Pré-requisitos de Integração

Possuir um veículo ativo (vehicleId) cadastrado no sistema.
Utilizar credenciais válidas com escopo para o cliente corporativo demandante.

Fluxo 1: Do Agendamento à Emissão do Orçamento

Para agendar e preparar uma manutenção de forma correta, o fluxo deve transcorrer da seguinte forma:

Buscar Categorias de Serviço → Buscar Oficinas Próximas (obter carWorkshopId) → Criar Agendamento → Aguardar Orçamento

Serviços Disponíveis: O motorista ou gestor consulta as categorias de serviço aplicáveis para identificar o escopo correto.
Localizar Oficinas: Com base na geolocalização e raio de atendimento, busca-se as oficinas que atendem à marca do veículo e oferecem o serviço desejado.
Agendar: Envia-se a solicitação de agendamento vinculando o veículo à oficina e definindo a data e período.

Fluxo 2: Aprovação de Orçamento com Itens Removidos

Nota de Integração: Durante a regulação, o cliente pode optar por rejeitar partes do orçamento proposto pela oficina (como marcas de óleo específicas ou serviços adicionais). O endpoint de aprovação permite o envio de coleções de itens removidos.

Consultar Orçamento (Obter IDs de Peças/Serviços) → Decisão do Cliente

Se Aprovar Integralmente → Enviar arrays vazios → Chamar POST /approve

Se Aprovar Parcialmente → Informar IDs em removedPartsIds/removedServicesIds → Chamar POST /approve

Referência de Endpoints

Oficinas e Categorias de Serviço

Serviços Oferecidos

Retorna a listagem de categorias e códigos de serviços homologados na plataforma.

Endpoint: api/service-categories

Método: GET

Exemplo de Requisição:

GET /api/service-categories HTTP/1.1
Host: api.developer.platform.com
Authorization: Bearer <TOKEN>
Content-Type: application/json

Resposta de Exemplo:

[
  {
    "id": 1,
    "code": "BASIC_MAINTENANCE"
  },
  {
    "id": 2,
    "code": "TIRES_ALIGNMENT"
  }
]

Listagem de Oficinas Próximas

Busca oficinas parceiras com base na localização atual, serviços necessários e compatibilidade com a marca do veículo.

Endpoint: api/car-workshops/nearby-paginated

Método: POST

Query Parameters:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`page`	integer	Não	0	Índice da página a ser retornada.
`pageSize`	integer	Não	5	Quantidade de registros por página.

Exemplo de Payload de Envio (Request Body):

{
  "latitude": -23.5505,
  "longitude": -46.6333,
  "vehicleBrandId": 1,
  "requiredServiceCategories": [1]
}

Resposta de Exemplo (Simplificada):

{
  "totalElements": 1,
  "totalPages": 1,
  "size": 5,
  "content": [
    {
      "id": 2893,
      "tradingName": "Oficina Central Bosch",
      "address": {
        "id": 12,
        "district": "Pinheiros",
        "street": "Rua dos Pinheiros",
        "number": "1000",
        "city": "São Paulo",
        "state": "SP",
        "country": "Brasil"
      },
      "distance": 1.2,
      "provideDesiredServices": true,
      "acceptVehicleBrand": true,
      "email": "contato@oficinabosch.com.br",
      "phone": "+5511999999999"
    }
  ],
  "number": 0,
  "first": true,
  "last": true,
  "empty": false
}

Agendamentos e Solicitações de Serviço

Criar Novo Agendamento

Registra uma solicitação de serviço na rede para avaliação física e orçamento na oficina selecionada.

Endpoint: api/scheduling-requests

Método: POST

Exemplo de Payload de Envio (Request Body):

{
  "clientId": 1,
  "parentId": null,
  "vehicleId": 17273,
  "drivers": [],
  "currentKm": 45000,
  "preventiveReviewKm": "50000",
  "correctiveDescription": "Troca preventiva de pastilhas de freio",
  "observations": "Veículo trepidando ao frear",
  "serviceType": "CORRECTIVE",
  "status": "SCHEDULED",
  "carWorkshopId": 2893,
  "date": "2025-09-26T13:00:00.000Z",
  "period": "AFTERNOON"
}

Detalhe dos Campos de Entrada

Campo	Tipo	Obrigatório	Descrição
`clientId`	integer	Sim	ID do cliente solicitante.
`vehicleId`	integer	Sim	ID do veículo agendado.
`currentKm`	integer	Sim	Quilometragem atualizada do veículo.
`serviceType`	string	Sim	Tipo de manutenção. Valores aceitos: `PREVENTIVE`, `CORRECTIVE`, `TIRES`.
`carWorkshopId`	integer	Sim	ID da oficina escolhida para a realização da manutenção.
`date`	string	Sim	Data pretendida para o serviço em formato ISO 8601.
`period`	string	Sim	Período de preferência. Valores: `MORNING`, `AFTERNOON`.

Resposta de Exemplo:

{
  "message": "Solicitação de Serviço salvo(a) com sucesso.",
  "payLoad": {
    "id": 10038,
    "requestId": "CDFBR_AAA5656_202508290848",
    "stepStatus": "BACKOFFICE_PENDING",
    "vehicleId": 17273,
    "clientId": 2414,
    "currentKm": 45000,
    "serviceType": "TIRES",
    "status": "SCHEDULED",
    "displayConfirmedScheduling": "26/09/2025 - Tarde",
    "carWorkshopId": 2893,
    "date": "2025-09-26T00:00:00.000-03:00",
    "period": "AFTERNOON"
  },
  "warning": false
}

Detalhes da Solicitação de Serviço

Retorna o prontuário completo de uma ordem de serviço, incluindo dados do veículo, andamento em formato stepper, faturamento e orçamento aprovado.

Endpoint: api/service-requests/{id}

Método: GET

Query Parameters:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`web`	boolean	Não	true	Se true, retorna metadados adicionais e informações estruturadas de faturamento e progresso.

Exemplo de Requisição:

GET /api/service-requests/8904?web=true HTTP/1.1
Host: api.developer.platform.com
Authorization: Bearer <TOKEN>

Resposta de Exemplo (Estruturada):

{
  "id": 8904,
  "requestId": "UNVGO_OMQ6428_202111011743",
  "client": {
    "id": 10,
    "tradingName": "Transportes Helix",
    "taxIdentifier": "12345678000199"
  },
  "vehicle": {
    "id": 3706,
    "licensePlate": "EZY-1749",
    "brand": "FORD",
    "name": "Fusion",
    "motor": "2.5"
  },
  "carWorkshop": {
    "id": 85,
    "tradingName": "Oficina Centro-Oeste",
    "taxIdentifier": "98765432000188"
  },
  "currentKm": 45000,
  "serviceType": "PREVENTIVE",
  "status": "FINISHED",
  "displayStatus": "Finalizado",
  "stepStatus": "SERVICE_COMPLETED",
  "budget": {
    "id": 1111,
    "status": "BUDGET_APPROVED",
    "billingId": 4333
  },
  "billing": {
    "id": 4333,
    "status": "BILLED",
    "invoiceStatus": "INVOICE_WAITING_UPLOAD",
    "osPartsValue": 320.0,
    "osServiceValue": 160.0
  },
  "stepper": {
    "steps": [
      {
        "order": 1,
        "step": "SERVICE_REQUEST_CREATED",
        "processed": "COMPLETED"
      },
      {
        "order": 2,
        "step": "SERVICE_REQUEST_COMMERCIAL_ANALYSIS",
        "processed": "COMPLETED"
      },
      {
        "order": 3,
        "step": "BUDGET_REGULATION",
        "processed": "COMPLETED"
      },
      {
        "order": 4,
        "step": "WAITING_APPROVAL_FOR_EXECUTION",
        "processed": "COMPLETED"
      },
      {
        "order": 5,
        "step": "BUDGET_APPROVED",
        "processed": "COMPLETED"
      },
      {
        "order": 6,
        "step": "MAINTENANCE_IN_EXECUTION",
        "processed": "COMPLETED"
      },
      {
        "order": 7,
        "step": "MAINTENANCE_FINISHED",
        "processed": "COMPLETED"
      }
    ]
  }
}

Orçamentos e Aprovações

Consultar Orçamento Emitido

Recupera os detalhes do orçamento fornecido pela oficina para verificação de valores, peças aplicadas e taxas administrativas associadas.

Endpoint: api/budgets/{id}

Método: GET

Resposta de Exemplo:

{
  "id": 125,
  "serviceRequestId": 8904,
  "status": "WAITING_CLIENT_APPROVAL",
  "createdAt": "2025-09-11T18:48:28.375Z",
  "budgetServiceItems": [
    {
      "id": 501,
      "serviceId": 12,
      "clientPrice": 160.0,
      "carWorkshopPrice": 140.0,
      "serviceName": "Troca de pastilhas de freio dianteiras",
      "amountOfHours": 1.5
    }
  ],
  "budgetPartItems": [
    {
      "id": 901,
      "partId": 34,
      "clientPrice": 320.0,
      "carWorkshopPrice": 280.0,
      "partAmount": 1.0,
      "partManufacturerName": "Bosch",
      "partName": "Pastilha de Freio Cerâmica"
    }
  ]
}

Aprovar Orçamento

Aprova a execução da ordem de serviço. Permite desconsiderar peças e serviços específicos enviando seus respectivos identificadores nos arrays de remoção.

Endpoint: api/budgets/{budgetId}/approve

Método: POST

Exemplo de Payload de Envio (Request Body):

{
  "id": 125,
  "removedPartsIds": [902],
  "removedServicesIds": [],
  "approvalCode": 123456,
  "observations": "Aprovado sem a troca do filtro de ar de cabine"
}

Detalhe dos Campos de Entrada

Campo	Tipo	Obrigatório	Descrição
`id`	integer	Sim	Identificador interno do orçamento.
`removedPartsIds`	array	Não	Lista de IDs de itens de peças (`budgetPartItems`) que não devem ser executados ou faturados.
`removedServicesIds`	array	Não	Lista de IDs de serviços (`budgetServiceItems`) que foram rejeitados pelo cliente.
`approvalCode`	integer	Não	Código de validação gerado pelo sistema interno do cliente.

Resposta de Exemplo:

{
  "message": "Orçamento aprovado com sucesso.",
  "payLoad": {
    "id": 125,
    "serviceRequestId": 8904,
    "status": "BUDGET_APPROVED"
  },
  "warning": false
}

Reagendamento e Cancelamento

Reagendamento de Manutenção

Altera parâmetros de agendamento (como data, período de atendimento ou mesmo a oficina de destino) antes do início da execução dos trabalhos.

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

Método: PUT

Exemplo de Payload de Envio (Request Body):

{
  "carWorkshopId": 2893,
  "date": "2025-09-16T14:30:00.000Z",
  "period": "AFTERNOON"
}

Cancelamento de Solicitação

Cancela a solicitação de serviço informando o motivo operacional.

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

Método: PUT

Query Parameters (ou form-data):

Parâmetro	Tipo	Obrigatório	Descrição
`reason`	string	Sim	Código do motivo (Ex: `REASON_CAR_WORKSHOP_DOESNT_ATTEND_ME`).
`observation`	string	Não	Descrição livre justificando o cancelamento da ordem de serviço.

Resposta de Exemplo:

{
  "message": "Solicitação de serviço cancelada com sucesso.",
  "payLoad": {
    "id": 8904,
    "status": "CANCELED",
    "reasonCancel": "REASON_CAR_WORKSHOP_DOESNT_ATTEND_ME",
    "observationCancel": "Oficina sem agenda disponível para hoje"
  },
  "warning": true
}

Recomendação de Serviços e Produtos

Consultar Plano de Recomendação de Serviço

Permite que o sistema avalie as necessidades preventivas ativas calculadas para o veículo, baseado nas regras e quilometragem salvas.

Endpoint: api/service-recommendation-plan/vehicle/{vehicleId}/{servicePlanId}

Método: GET

Resposta de Exemplo:

[
  {
    "id": 5,
    "key": "ADDITIONAL_MAINTENANCE",
    "displayValue": "Manutenção Adicional",
    "enabled": true,
    "mandatoryFields": "{\"requiredFields\": [\"comments\"]}",
    "nextServiceStatus": "DANGER",
    "isSelected": false
  },
  {
    "id": 1,
    "key": "OEM_SERVICE_PLAN_NEEDS",
    "displayValue": "Plano de Serviço de Fábrica (OEM)",
    "enabled": true,
    "mandatoryFields": "{}",
    "nextServiceStatus": "WARNING",
    "isSelected": true
  }
]

Erros e Resolução de Problemas

Sempre que a sua aplicação interagir com as nossas APIs de serviços, garanta o tratamento adequado das respostas através dos códigos de status HTTP recomendados.

Códigos de Status HTTP

Status HTTP	Causa Provável	Ação Recomendada
200 OK / 201 Created	A agendamento, orçamento ou faturamento foi processado com sucesso.	Prossiga com o direcionamento do usuário no fluxo operacional.
400 Bad Request	Parâmetros de filtro inconsistentes, falta de campos ou formatação de data errada.	Revise se as strings de data estão no formato ISO 8601 (`YYYY-MM-DDTHH:mm:ss.SSSZ`).
401 Unauthorized	Token do desenvolvedor ausente ou expirado.	Renove as credenciais do seu gateway utilizando as chaves de integração corporativas.
403 Forbidden	Usuário não tem permissões para realizar agendamento no veículo de outro cliente.	Verifique se o `clientId` informado coincide com a posse hierárquica do `vehicleId`.
404 Not Found	ID da oficina, orçamento ou solicitação inexistente na base.	Confirme se a entidade não foi cancelada anteriormente ou revise o ID passado na URI.
422 Unprocessable Entity	Conflito com regras de negócio da manutenção (ex: veículo já com manutenção em andamento).	Valide o estado atual do veículo antes de disparar novos agendamentos para o mesmo ativo.
500 Internal Error	Erro imprevisto de processamento interno ou queda de parceiros externos de geolocalização.	Aguarde o tempo de retração técnica e tente novamente mais tarde.

Dicas de Resolução de Problemas

Tentativa de Duplo Agendamento (Código 422): Um veículo não pode possuir duas solicitações de serviço ativas simultaneamente com status de execução sobrepostos. Caso precise incluir novos serviços em uma ida à oficina, use o fluxo de Ajustes de Orçamento ou adicione itens complementares ao orçamento inicial em vez de criar um novo agendamento separado.
Exclusão Automática de Itens em Aprovações de Orçamento: Ao enviar IDs de peças para exclusão no endpoint /approve, o sistema recalcula de forma automática o valor total autorizado, as taxas administrativas, margens de intermediação e o valor do faturamento posterior. Garanta que os IDs passados em removedPartsIds correspondam estritamente ao orçamento do identificador (budgetId) fornecido no payload.