Bem-vindo à documentação do Módulo de Integração B2C. Este módulo foi desenhado para viabilizar jornadas de consumo final (Business-to-Consumer), permitindo o Onboarding simplificado de novos motoristas, descoberta inteligente de oficinas parceiras com base em proximidade geográfica e agendamento/gestão ponta a ponta de ordens de serviço e documentos fiscais.

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

Fundamentos — Entenda as regras de negócio e os conceitos-chave.
Fluxo de Trabalho (Workflow) — Compreenda a ordem correta das integrações e o fluxo de dados.
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 conceitos de negócio que compõem o ecossistema de atendimento B2C.

Conceitos-Chave

Categorias de Serviço: Representam as grandes divisões de manutenção que a plataforma suporta (ex: corretiva, preventiva, troca de pneus). Cada categoria direciona o veículo a um subgrupo específico de oficinas qualificadas para o atendimento.
Oficinas Não Vinculadas (Unlinked Workshops): São os prestadores de serviços automotivos cadastrados na plataforma que estão geograficamente próximos à coordenada enviada na requisição, contendo informações comerciais como rede de pertença, e-mail de contato, avaliações e faixas estimadas de preço (price_range).
Agendamento de Serviço (Service Schedule): Entidade transacional que registra o compromisso de manutenção em uma data, período (Manhã, Tarde ou Noite) e horário específicos. Representa a evolução física do serviço, que passa por constantes atualizações de status até seu faturamento e encerramento.
Períodos Indisponíveis (unavailable_periods): Cada oficina possui regras dinâmicas de capacidade e lotação. A API retorna restrições na listagem de oficinas (GET /workshop-list-unlinked), indicando quais períodos de uma determinada data estão bloqueados para novos agendamentos (ex: MORNING na data 2025-10-29).

Relação Geral entre os Recursos

O fluxo estrutural abaixo (mapeado a partir da arquitetura do sistema) demonstra como o cadastro de dados cadastrais se conecta ao motor de agendamento e faturamento:

Cadastro do Usuário → Cadastro do Cliente → Cadastro do Veículo (Associação via Placa) → Categorias de Serviço

Jornada de Agendamento (Scheduling): Lista de Oficinas → Agendar Serviço (POST) → Status do Serviço → Editar Serviço (PATCH) / Gestão de Notas Fiscais (GET)

Fluxo de Trabalho (Workflow)

Esta seção descreve os caminhos recomendados de consumo das APIs para garantir consistência cadastral e ótima experiência do usuário final durante a marcação do serviço.

Pré-requisitos de Integração

Chave de API ativa (API Key ou Bearer Token) enviada no header das requisições.
Coleta prévia da latitude e longitude do dispositivo móvel do usuário para listagem precisa de proximidade.

Fluxo 1: Onboarding de Cliente B2C

Antes de realizar qualquer agendamento, o usuário final e seu veículo precisam estar registrados na base central através de uma chamada atômica:

Informar CNPJ/CPF → Dados de Usuário → Placa do Veículo → POST /customer-register

Fluxo 2: Jornada Completa de Agendamento de Serviço

A marcação e acompanhamento de uma manutenção segue rigorosamente a sequência de interações abaixo:

Consumir GET /service-categories (Identificar tipo de manutenção) → Consumir GET /workshop-list-unlinked (Passar latitude, longitude, placa e categoria) → Validar Disponibilidade / Períodos

Se período ocupado → Sugerir outra data/oficina.

Se período vago → Consumir POST /service-schedule (Gera service_id) → Consumir GET /service-status/{id} (Acompanhar) → Consumir PATCH /service-edit (Se precisar reagendar) → Consumir GET /invoice-managment/{id} (Pós-serviço)

Categorias: Obtenha os códigos internos (ex: PREVENTIVE, TIRES) para parametrizar a busca.
Oficinas: Localize as oficinas próximas passando a categoria do serviço e a geolocalização do usuário.
Agendamento: Envie a data, o período livre e os IDs cadastrados para efetuar a reserva.

Referência de Endpoints

Categorias de Serviço

Obtenha as categorias de serviço disponíveis

Retorna a listagem de categorias operacionais válidas para o direcionamento de agendamentos.

Endpoint: /service-categories

Método: GET

Exemplo de Resposta (Status 200 OK):

[
  {
    "name": "Corretiva",
    "value": "CORRECTIVE"
  },
  {
    "name": "Plano Manutenção",
    "value": "PREVENTIVE"
  },
  {
    "name": "Pneus",
    "value": "TIRES"
  }
]

Oficinas Parceiras

Obtenha a listagem de oficinas

Retorna oficinas próximas à localização informada que possuem capacidade para atender a categoria de serviço solicitada.

Endpoint: /workshop-list-unlinked

Método: GET

Query Parameters:

Parâmetro	Tipo	Obrigatório	Descrição
`license_plate`	string	Sim	Placa do veículo que passará pela manutenção.
`service_category_id`	string	Sim	ID/Código da categoria (ex: PREVENTIVE).
`latitude`	double	Sim	Latitude atual do dispositivo móvel do usuário.
`longitude`	double	Sim	Longitude atual do dispositivo móvel do usuário.

Exemplo de Resposta (Status 200 OK):

[
  {
    "id": 1422,
    "tradingName": "Centro Automotivo Bosch Curitiba",
    "price_range": 250.00,
    "address": {
      "district": "Batel",
      "street": "Avenida do Batel",
      "number": "1200",
      "city": "Curitiba",
      "state": "PR",
      "country": "BR"
    },
    "unavailable_periods": [
      {
        "period": "MORNING",
        "date": "2025-10-29"
      }
    ],
    "distance": 2.4,
    "latitude": -25.442349,
    "longitude": -49.282267,
    "networkName": "PREMIUM",
    "email": "contato@boschbatel.com.br",
    "phone": "+554133333333",
    "name": "Ricardo Silva"
  }
]

Detalhamento dos Campos de Resposta (Workshop Schema)

Campo	Tipo	Descrição
`id`	integer	Identificador único da oficina na plataforma.
`tradingName`	string	Nome fantasia da oficina parceira.
`price_range`	double	Estimativa ou faixa de custo para o veículo/categoria informada.
`address`	object	Estrutura aninhada contendo os dados de endereço do estabelecimento.
`unavailable_periods`	array[object]	Lista de restrições de horários de atendimento da oficina por data.
`distance`	double	Distância calculada em quilômetros em relação à coordenada enviada.
`networkName`	string	Nome/Classificação da rede à qual a oficina pertence.

Registro de Clientes

New customer and vehicles registration

Cadastra simultaneamente o cliente responsável, seu usuário de acesso e a lista inicial de veículos da conta.

Endpoint: /customer-register

Método: POST

Headers: Content-Type: application/json

Exemplo de Payload de Envio (Request Body):

{
  "cnpj": "12345678000199",
  "user": {
    "name": "Pedro Silva",
    "email": "svp2ca@bosch.com",
    "phone": "+5511999999999"
  },
  "vehicles": [
    "ABC1D23",
    "XYZ9A87"
  ],
  "manager": true
}

Detalhes dos Campos de Entrada (Request Schema)

Campo	Tipo	Obrigatório	Descrição
`cnpj`	string	Sim	Documento fiscal do responsável (CNPJ ou CPF).
`manager`	boolean	Não	Indica se o usuário enviado deve ser configurado como gestor (Padrão: true).
`vehicles`	array[string]	Sim	Lista de placas de veículos a serem inseridas sob a gestão do cliente.
`user.name`	string	Sim	Nome completo do usuário administrador.
`user.email`	string	Sim	E-mail corporativo exclusivo do usuário.
`user.phone`	string	Não	Telefone de contato estruturado em padrão internacional.

Exemplo de Resposta (Status 200 OK):

{
  "customer_id": 88192
}

Agendamento e Edição

Service Schedule

Efetua a reserva e marcação do serviço na oficina escolhida pelo usuário.

Endpoint: /service-schedule

Método: POST

Exemplo de Payload de Envio (Request Body):

{
  "customer_id": 88192,
  "license_plate": "ABC1D23",
  "mileage": 45000,
  "observations": "Barulho ao frear e trepidação no volante.",
  "serviceType": "CORRECTIVE",
  "carWorkshopId": 1422,
  "date": "2025-10-29",
  "period": "AFTERNOON",
  "timeService": "14:30"
}

Detalhes dos Campos de Entrada (Request Schema)

Campo	Tipo	Obrigatório	Descrição
`customer_id`	integer	Sim	Identificador único do cliente (retornado no onboarding).
`license_plate`	string	Sim	Placa do veículo associado.
`mileage`	integer	Sim	Quilometragem atualizada informada pelo condutor.
`observations`	string	Não	Descrição detalhada sobre o problema do carro.
`serviceType`	string	Sim	ID ou código textual da categoria do serviço.
`carWorkshopId`	integer	Sim	Identificador único da oficina escolhida.
`date`	string	Sim	Data pretendida do serviço (YYYY-MM-DD).
`period`	string	Sim	Período de preferência (MORNING, AFTERNOON, EVENING).
`timeService`	string	Não	Horário exato pré-acordado (HH:MM).

Exemplo de Resposta (Status 200 OK):

{
  "service_id": 55421
}

Service Edit

Permite atualizar ou reagendar os dados de um agendamento já cadastrado que ainda não foi iniciado fisicamente.

Endpoint: /service-edit

Método: PATCH

Exemplo de Payload de Envio (Request Body):

{
  "service_id": 55421,
  "mileage": 45100,
  "observations": "Observação atualizada: Verificar também pastilhas de freio.",
  "serviceType": "CORRECTIVE",
  "carWorkshopId": 1422,
  "date": "2025-10-30",
  "period": "MORNING",
  "timeService": "09:00"
}

Detalhes dos Campos de Entrada (Request Schema)

Campo	Tipo	Obrigatório	Descrição
`service_id`	integer	Sim	Identificador do agendamento a ser modificado.
`mileage`	integer	Sim	Nova quilometragem para atualização cadastral do veículo.
`observations`	string	Não	Notas ou termos de modificação adicionais.
`serviceType`	string	Sim	Tipo de serviço a ser redefinido.
`carWorkshopId`	integer	Sim	Novo ID da oficina, em caso de alteração de local de atendimento.
`date`	string	Sim	Nova data de agendamento (YYYY-MM-DD).
`period`	string	Sim	Novo período de agendamento.
`timeService`	string	Não	Nova hora de agendamento (HH:MM).

Acompanhamento e Documentação Fiscal

Service Status

Retorna a situação operacional em tempo real do agendamento, detalhando a oficina executora, dados agendados e ações requeridas pelo usuário.

Endpoint: /service-status/{service-id}

Método: GET

Exemplo de Resposta (Status 200 OK):

{
  "id": 55421,
  "carWorkshop": {
    "id": 1422,
    "tradingName": "Centro Automotivo Bosch Curitiba",
    "street": "Avenida do Batel",
    "number": "1200",
    "district": "Batel",
    "city": "Curitiba",
    "state": "PR",
    "country": "BR"
  },
  "serviceType": "CORRECTIVE",
  "displayServiceType": "Manutenção Corretiva",
  "observations": "Barulho ao frear e trepidação no volante.",
  "status": "IN_PROGRESS",
  "displayStatus": "Veículo em Manutenção",
  "date": "2025-10-30",
  "period": "MORNING",
  "callToAction": "Aguardando diagnóstico final do mecânico",
  "timeService": "09:00"
}

Invoice management

Recupera metadados e os links diretos para downloads de PDFs e XMLs fiscais de peças e mão de obra após a conclusão do agendamento.

Endpoint: /invoice-managment/{service-id}

Método: GET

Exemplo de Resposta (Status 200 OK):

{
  "id": 55421,
  "licensePlate": "ABC1D23",
  "clientId": 88192,
  "carWorkshop": "Centro Automotivo Bosch Curitiba",
  "carWorkshopId": 1422,
  "status": "COMPLETED",
  "serviceNfPdfFilename": "nf_servico_55421.pdf",
  "partsNfPdfFilename": "nf_pecas_55421.pdf",
  "partsNfXmlFilename": "nf_pecas_55421.xml",
  "serviceNfPdfFilepath": "https://api.platform.com/files/nf_servico_55421.pdf",
  "partsNfPdfFilepath": "https://api.platform.com/files/nf_pecas_55421.pdf",
  "partsNfXmlFilepath": "https://api.platform.com/files/nf_pecas_55421.xml",
  "date": "2025-10-30T17:30:00Z"
}

Erros e Resolução de Problemas

Sempre que a sua aplicação interagir com as nossas APIs, verifique os códigos de status HTTP para determinar o sucesso ou a necessidade de correção das requisições.

Códigos de Status HTTP

Status HTTP	Causa Provável	Ação Recomendada
200 OK / 201 Created	Transação e processamento efetuados com sucesso.	Prossiga com o processamento dos dados retornados.
400 Bad Request	Dados de entrada inválidos (Invalid input data), falta de parâmetros obrigatórios ou datas em formato inválido.	Valide o contrato de dados. Verifique tipos de campos de geolocalização e datas.
401 Unauthorized	Credencial inválida (Invalid api key / Invalid credential) ou ausência de tokens de segurança.	Renove as chaves do ambiente de desenvolvimento e revise os headers de autorização da requisição.
500 Internal Error	Falha inesperada no processamento por parte dos nossos servidores internos.	Salve os detalhes do erro e aguarde alguns minutos antes de efetuar uma nova tentativa de envio.

Dicas de Resolução de Problemas

Lidando com Períodos Ocupados (unavailable_periods): Antes de disparar o agendamento no endpoint /service-schedule, verifique se o período desejado não consta no array unavailable_periods retornado pela oficina. Agendar em períodos marcados como indisponíveis gerará uma falha lógica de conciliação de horários.
Validação Cadastral Obrigatória: Na criação do agendamento, o campo mileage deve ser sempre igual ou superior à quilometragem prévia conhecida do carro. Tentativas de retroagir a quilometragem ativa do odômetro farão a requisição retornar HTTP 400 Bad Request por regras de segurança sistêmica.
Tratamento de Arquivos Fiscal Indisponíveis: Caso a resposta de /invoice-managment retorne strings vazias nos campos partsNfPdfFilepath ou serviceNfPdfFilepath, a ordem de serviço pode estar concluída, mas o processo de importação do arquivo fiscal no ERP do faturador ainda está pendente ou sob conciliação manual da oficina.