Este módulo de integração de serviços visa automatizar a troca de dados financeiros e operacionais entre o sistema de gerenciamento de frotas/manutenção do cliente e o ERP de compras corporativo. A automação elimina processos manuais e garante que a liberação de reparos e a posterior liquidação das notas fiscais ocorram de forma eletrônica, segura e auditável.

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

Fundamentos — Entenda os atores, chaves estruturais e regras de negócio.
Fluxo de Trabalho (Workflow) — Compreenda a ordem correta das integrações e o fluxo de dados.
Tabelas de Domínio — Consulte os valores estáticos retornados pela API.
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.

Fundamentos

Antes de iniciar o desenvolvimento de suas integrações, familiarize-se com os principais atores, chaves estruturais e regras de negócio que compõem o ecossistema de integração de serviços/ERP de compras.

Atores e Chaves Estruturais

Solicitação de Serviço (Service Request): O registro principal do atendimento de um veículo, identificado exclusivamente pelo requestId (textual, ex: "REQ-778912") e o id (inteiro, ex: 10245).
Orçamento (Budget): O compilado de preços propostos pela oficina parceira, associado a um budgetId. Contém os arrays de itens físicos de serviços (budgetServiceItems) e peças (budgetPartItems).
Código de Aprovação / Pedido de Compra (approvalCode / orderId): O número identificador gerado pelo ERP de compras do cliente. Este código é inserido no sistema no momento da aprovação ou logo após ela para permitir que as Notas Fiscais emitidas sejam consolidadas sob o empenho correto de compra.
Faturamento e Notas Fiscais (Billings & Invoices): Registro dos arquivos fiscais emitidos após a conclusão física da manutenção, divididos em Nota Fiscal de Serviço (mão de obra) e Nota Fiscal de Peças.

Regras Gerais de Negócio

Unicidade de Pedido: O orderId deve ser exclusivo por veículo/solicitação para evitar conflitos de conciliação financeira no encerramento da ordem de serviço.
Sincronismo de Notas Fiscais: Os links de notas fiscais (partsNfPdfFilepath, partsNfXmlFilepath, serviceNfPdfFilepath) são gerados de forma assíncrona após o encerramento físico das atividades da oficina e o respectivo processamento eletrônico da NF.
Mapeamento de Chamados de Ação (CALLTOACTION): A plataforma retorna um campo dinâmico callToAction em várias rotas que traduz a situação exata da ordem de serviço, orientando o condutor do veículo ou o gestor sobre o próximo passo esperado no mundo real.

Fluxo de Trabalho (Workflow)

O fluxo operacional unificado descreve como os sistemas interagem de ponta a ponta durante as fases de aprovação (Ao Aprovar) e execução/faturamento (Após Aprovação).

Fase 1: Avaliação e Aprovação (Ao Aprovar)

Agendamento → Solicitação → Consulta Fila de Orçamentos Pendentes → Validação de Itens de Peças/Serviços → Aprovação com Pedido

Fase 2: Pós-Aprovação e Conciliação Fiscal (Após Aprovação)

Consulta Aprovadas → Criação do Pedido no ERP → Associação de orderId → Listagem de Billings → Download de NFs PDF/XML → Baixa Fiscal / XML

Tabelas de Domínio

As tabelas de domínio definem os valores estáticos e padronizados retornados pela API nas respostas de solicitações de serviço e orçamentos.

Período

Define a faixa de horário do dia reservada para atendimento ou execução na oficina parceira.

Chave API (Enum)	Tradução Comercial	Descrição de Uso
`MORNING`	Manhã	Atendimentos agendados entre as 08:00 e 12:00.
`AFTERNOON`	Tarde	Atendimentos agendados entre as 12:00 e 18:00.
`EVENING`	Noite	Atendimentos especiais noturnos (quando aplicável).

Status da Solicitação

Representa a situação de controle operacional e de workflow em que o atendimento do veículo se encontra.

Status (Enum)	Descrição do Estado
`SCHEDULED_TO_RUN`	Solicitação aprovada e autorizada para o início físico da manutenção na oficina parceira.
`RUNNING`	Solicitação em execução (veículo na oficina com serviços sendo realizados).
`BUDGET_APPROVAL`	Solicitação aguardando avaliação e aprovação do orçamento por parte do cliente.
`IN_BILLING`	Solicitação com serviços concluídos, atualmente em processo de faturamento das notas fiscais.
`FINISHED`	Solicitação finalizada com sucesso (serviço executado e faturamento concluído).
`CANCELED`	Solicitação cancelada pelas partes antes do início ou durante o processo.
`DISAPPROVED`	Solicitação reprovada pelo gestor de frotas (reparos negados de forma permanente).

Mapeamento de Chamados de Ação (CALLTOACTION)

O campo callToAction indica mensagens e fluxos operacionais direcionados de forma automática ao backoffice ou condutor do veículo com base na junção dos estados operacionais da solicitação.

Chave do CALLTOACTION	Mensagem Retornada (Frontend / ERP)
`BACKOFFICE_PENDING_SCHEDULED`	"Aguarde o orçamento para aprovar a manutenção."
`BACKOFFICE_PENDING_BLANK_SCHEDULED`	"O Condutor deve comparecer na oficina na data agendada para diagnóstico do veículo."
`BUDGET_APPROVAL_SCHEDULED`	"Aguarde o orçamento para aprovar a manutenção."
`WAIT_VEHICLE_ARRIVAL_SCHEDULED`	"O Condutor deve comparecer na oficina na data agendada para diagnóstico do veículo."
`EXECUTE_DIAGNOSTIC_SCHEDULED`	"Aguarde o orçamento para aprovar a manutenção."
`VEHICLE_AT_WORKSHOP_CHECKIN_FALSE_SCHEDULED`	"Aguarde o orçamento para aprovar a manutenção."
`VEHICLE_NOT_PRESENT_SCHEDULED`	"Não foi indicado o comparecimento do condutor na oficina. Confirme a chegada ou reagende para realizar o diagnóstico do veículo."
`EXECUTE_CHECKIN_OR_CONFIRM_NOT_PRESENT_SCHEDULED`	"Não foi indicado o comparecimento do condutor na oficina. Confirme a chegada ou reagende para realizar o diagnóstico do veículo."
`VEHICLE_NOT_PRESENT_IF_APPEAR_EXECUTE_CHECKIN_SCHEDULED`	"Não foi indicado o comparecimento do condutor na oficina. Confirme a chegada ou reagende para realizar o diagnóstico do veículo."
`BACKOFFICE_PENDING_VALIDATION_SCHEDULED`	"Aguarde o orçamento para aprovar a manutenção."
`BACKOFFICE_ADMIN_PENDING_SCHEDULED`	"Aguarde o orçamento para aprovar a manutenção."
`CLIENT_MUST_APPROVE`	"Aprove o orçamento para executar a manutenção."
`WAIT_VEHICLE_ARRIVAL_BUDGET_APPROVED`	"O Condutor deve comparecer na oficina na data agendada para executar a manutenção."
`VEHICLE_NOT_PRESENT_BUDGET_APPROVED`	"Não foi indicado o comparecimento do condutor na oficina. Confirme a chegada ou reagende para executar a manutenção."
`VEHICLE_NOT_PRESENT_INFORM_BY_WORKSHOP_BUDGET_APPROVED`	"O Condutor deve comparecer na oficina na data agendada para executar a manutenção."
`VEHICLE_NOT_APPEARED_VEHICLE_ARRIVAL_BUDGET_APPROVED`	"Não foi indicado o comparecimento do condutor na oficina. Confirme a chegada ou Reagende para executar a manutenção."
`VEHICLE_NOT_PRESENT_INFORM_BY_WORKSHOP_WITH_BLANK_BUDGET_BUDGET_APPROVED`	"Não foi indicado o seu comparecimento na oficina. Confirme a chegada ou reagende para executar a manutenção."
`VEHICLE_NOT_PRESENT_BLANK_BUDGET_BUDGET_APPROVED`	"Não foi indicado o comparecimento do condutor na oficina. Confirme a chegada ou Reagende para executar a manutenção."
`VEHICLE_EVALUTION_BUDGET_APPROVED`	"Veículo na oficina. Aguarde a execução da manutenção."
`SERVICE_RUNNING_BUDGET_APPROVED`	"Veículo na oficina. Aguarde a execução da manutenção."
`INVOICE_WAITING_UPLOAD`	"Manutenção finalizada."
`INVOICE_ON_APPROVAL`	"Manutenção finalizada."
`INVOICE_NOT_ACCEPTED`	"Manutenção finalizada."
`INVOICE_APPROVED`	"Manutenção finalizada."
`MAINTENANCE_FINISHED`	"Manutenção finalizada."
`MAINTENANCE_CANCELED`	"Manutenção cancelada."
`MAINTENANCE_REPROVED`	"Manutenção reprovada."
`ATTEND_WORKSHOP_ON_SCHEDULED_DATE`	"Compareça na Oficina na data agendada"

Referência de Endpoints

PARTE I: Fluxo de Aprovação de Orçamentos (Ao Aprovar)

Listar Solicitações a Aprovar

Retorna todas as solicitações pendentes de aprovação pelo perfil do cliente.

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

Método: GET

Exemplo de Resposta (Status 200 OK):

{
  "totalElements": 1,
  "totalPages": 1,
  "size": 10,
  "content": [
    {
      "id": 10245,
      "requestId": "REQ-778912",
      "blockName": "Frota Logística Sul",
      "carWorkshopName": "Centro Automotivo Bosch Curitiba",
      "budgetId": 55421,
      "totalBudgetClient": 1850.50,
      "workflowClientApprovalsCount": 0,
      "workflowClientApprovalsTotal": 1,
      "workflowClientIsLastApprover": true,
      "date": "2025-11-05T14:30:00.000Z",
      "clientApproverProfile": "MANAGER",
      "budgetStatus": "PENDING_CLIENT_APPROVAL"
    }
  ],
  "number": 0,
  "sort": {
    "empty": false,
    "sorted": true,
    "unsorted": false
  }
}

Verificar o Orçamento

Retorna os itens de serviços e peças de um orçamento específico (budgetId) para validação detalhada de custos e marcas de autopeças.

Endpoint: /api/budgets/{budgetId}

Método: GET

Exemplo de Resposta (Status 200 OK):

{
  "id": 55421,
  "serviceRequestId": 10245,
  "status": "WAITING_APPROVAL",
  "displayStatus": "Aguardando Aprovação do Cliente",
  "approvalCode": 0,
  "budgetServiceItems": [
    {
      "id": 881,
      "serviceName": "Mão de Obra - Substituição de Pastilhas de Freio",
      "clientPrice": 250.00,
      "amountOfHours": 2.0,
      "isPreventiveVerification": true
    }
  ],
  "budgetPartItems": [
    {
      "id": 7741,
      "partName": "Pastilhas e Discos Dianteiros (Kit Premium)",
      "partCode": "0986BB0740",
      "partManufacturerName": "Bosch",
      "clientPrice": 1600.00,
      "partAmount": 1.0,
      "isPreventiveVerification": true
    }
  ]
}

Aprovar a Solicitação

Aprova o orçamento informando o código do pedido (approvalCode) gerado pelo sistema do cliente para fins de conciliação de faturamento posterior.

Endpoint: /api/budgets/{budgetId}/approval

Método: PUT

Exemplo de Payload de Envio (Request Body):

{
  "approvalCode": 9984123,
  "observations": "Orçamento aprovado via integração. Centro de Custo CC-LOG-SUL."
}

Resposta (Status 200 OK):

{
  "status": "APPROVED",
  "message": "Orçamento aprovado com sucesso.",
  "budgetId": 55421,
  "approvalCode": 9984123,
  "approvedAt": "2025-11-05T15:45:10.123Z"
}

PARTE II: Fluxo de Automação e Faturamento de Pedidos (Após Aprovação)

Listar Solicitações Aprovadas

Retorna as solicitações que necessitam de providências de faturamento ou que já se encontram no status aprovado (BUDGET_APPROVAL).

Endpoint: /api/service-requests/filters

Método: POST

Payload de Envio (Request Body):

{
  "listStatus": [
    "BUDGET_APPROVAL"
  ],
  "filterCondition": "OR"
}

Exemplo de Resposta (Status 200 OK):

{
  "totalElements": 1,
  "totalPages": 1,
  "size": 10,
  "content": [
    {
      "id": 10245,
      "requestId": "REQ-778912",
      "modelName": "Mercedes-Benz Sprinter",
      "clientBlockName": "Frota Logística Sul",
      "displayConfirmedScheduling": "Agendamento Confirmado",
      "serviceType": "CORRECTIVE",
      "carWorkshopId": 1422,
      "carWorkshopName": "Centro Automotivo Bosch Curitiba",
      "orderId": null,
      "status": "BUDGET_APPROVED",
      "displayStatus": "Orçamento Aprovado",
      "date": "2025-08-29",
      "period": "MORNING",
      "partValue": 1600.00,
      "serviceValue": 250.00,
      "callToAction": "BACKOFFICE_PENDING_SCHEDULED"
    }
  ],
  "number": 0,
  "first": true,
  "last": true,
  "empty": false
}

Inserir Número de Pedido

Associa o número do pedido de compras (orderId) gerado pelo ERP do cliente à solicitação de serviço na nossa plataforma.

Endpoint: /api/scheduling-requests/{serviceId}/service-request-order-id

Método: PUT

Parâmetros de Path:

Parâmetro	Tipo	Obrigatório	Descrição
`serviceId`	integer	Sim	ID numérico da solicitação (campo `id` da resposta).

Payload de Envio (Request Body):

{
  "orderId": "PEDIDO-ERP-11116"
}

Resposta (Status 200 OK):

{
  "status": "SUCCESS",
  "message": "Número de pedido vinculado com sucesso.",
  "serviceId": 10245,
  "orderId": "PEDIDO-ERP-11116"
}

Obter Solicitação por Número do Pedido

Recupera os dados completos da solicitação utilizando o orderId como filtro de busca.

Endpoint: /api/service-requests/filters

Método: POST

Payload de Envio (Request Body):

{
  "orderId": "PEDIDO-ERP-11116",
  "filterCondition": "OR"
}

Resposta (Status 200 OK): Retorna um array idêntico ao modelo de resposta do endpoint Listar Solicitações Aprovadas, contendo a solicitação com o orderId filtrado.

Listagem de Notas Fiscais

Recupera as notas fiscais emitidas (peças e serviços) com os links diretos para download automático.

Endpoint: /api/billings/invoice-parts-services-queue

Método: GET

Parâmetros de Consulta (Query String):

Parâmetro	Tipo	Obrigatório	Descrição
`requestId`	string	Sim	Identificador de texto da solicitação (ex: "REQ-778912").

Resposta (Status 200 OK):

[
  {
    "billingId": 99812,
    "serviceRequestId": 10245,
    "requestId": "REQ-778912",
    "clientId": 88192,
    "clientName": "Robert Bosch GmbH",
    "vehicleLicensePlate": "ABC1D23",
    "invoiceStatus": "RECORDED",
    "partsNfStatus": "EMITTED",
    "serviceNfStatus": "EMITTED",
    "partsNfNumber": 44521,
    "partsNfIssueDate": "2025-09-03T13:29:18.318Z",
    "serviceNfNumber": 55120,
    "serviceNfIssueDate": "2025-09-03T13:29:18.318Z",
    "budgetId": 55421,
    "isInvoiceRecorded": true,
    "partsNfPdfFilename": "nf_pecas_44521.pdf",
    "partsNfXmlFilename": "nf_pecas_44521.xml",
    "serviceNfPdfFilename": "nf_servico_55120.pdf",
    "partsNfPdfFilepath": "https://api.platform.com/files/nf_pecas_44521.pdf",
    "partsNfXmlFilepath": "https://api.platform.com/files/nf_pecas_44521.xml",
    "serviceNfPdfFilepath": "https://api.platform.com/files/nf_servico_55120.pdf",
    "osServiceValue": 250.00,
    "osPartsValue": 1600.00
  }
]

Obter Arquivos da Nota Fiscal

Endpoints diretos gerados nas propriedades de caminho de arquivo para faturamento de peças e faturamento de serviços.

Arquivo PDF NF Peças: Enviar requisição GET para o endereço contido em partsNfPdfFilepath.
Arquivo XML NF Peças: Enviar requisição GET para o endereço contido em partsNfXmlFilepath.
Arquivo PDF NF Serviço: Enviar requisição GET para o endereço contido em serviceNfPdfFilepath (ou construído dinamicamente a partir do nome em serviceNfPdfFilename).

Buscar budgetId

Recupera o ID exclusivo de orçamento correspondente a uma solicitação ativa.

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

Método: GET

Resposta (Status 200 OK):

{
  "id": 10245,
  "requestId": "REQ-778912",
  "stepStatus": "COMPLETED",
  "vehicleId": 9812,
  "clientId": 88192,
  "budgetId": 55421,
  "status": "COMPLETED",
  "orderId": "PEDIDO-ERP-11116"
}

Erros e Resolução de Problemas

Siga as diretrizes de status HTTP e tratamento de falhas lógicas para garantir uma integração limpa entre os sistemas.

Tabela de Status HTTP Padrão

Status HTTP	Descrição / Significado
200 OK / 201 Created	Sucesso no processamento da solicitação de API.
400 Bad Request	Payload com formato malformado, falta de campos obrigatórios ou incompatibilidade de dados.
401 Unauthorized	Bearer token ausente ou expirado nos cabeçalhos da requisição.
403 Forbidden	O usuário autenticado não possui alçadas para aprovação corporativa.
404 Not Found	O ID da solicitação de serviço ou do orçamento não foi localizado no banco de dados.
500 Internal Server Error	Instabilidade em servidores centrais. Implementar fila com retentativa incremental de chamadas.

Exceções de Negócio Customizadas (Regras Internas)

BUDGET_ALREADY_APPROVED: Retornado quando há tentativa de aprovação em orçamento já aprovado anteriormente.
INVOICES_NOT_GENERATED: Ocorre ao consultar os caminhos de faturamento quando a oficina ainda está processando a liberação fiscal do veículo.
ORDER_ID_EXISTS: O número de pedido informado no orderId já foi associado a outra solicitação de forma concorrente.