Bem-vindo à documentação do Módulo de Notas Fiscais e Orçamentos. Este módulo é responsável por gerenciar os fluxos de aprovação de orçamentos de manutenção, faturamento integrado e disponibilização de arquivos fiscais digitais (PDF e XML) associados aos serviços prestados.

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 Notas Fiscais e Orçamentos.

Conceitos-Chave

Orçamento (Budget): Representa a proposta de valores para manutenção de um veículo, emitida por uma oficina credenciada. O orçamento é composto por itens de peças, itens de serviços, margens operacionais e taxas administrativas. Um orçamento precisa ser aprovado para que o serviço seja executado.
Código de Autorização (approvalCode): Representa o identificador gerado pelo ERP/sistema interno do cliente (geralmente um número de Pedido de Compra ou Purchase Order - PO) no momento em que a manutenção é aprovada internamente. Esse código deve ser trafegado obrigatoriamente no fluxo de aprovação para garantir a rastreabilidade financeira.

Estrutura de Itens do Orçamento

Cada orçamento é dividido em duas categorias de itens, permitindo a separação e conciliação financeira detalhada de valores:

Orçamento (budgetId) → Itens de Peças (budgetPartItems) — clientPrice, carWorkshopPrice, etc.

Orçamento (budgetId) → Itens de Serviços (budgetServiceItems) — clientPrice, carWorkshopPrice, etc.

Faturamento e Notas Fiscais

Após a conclusão física do serviço na oficina, é gerado um registro de faturamento associado. O faturamento consolida as Notas Fiscais emitidas, dividindo-as por tipo:

Tipo de Nota Fiscal	Identificador / Arquivo	Descrição
NF de Peças	`partsNfNumber`	Documento fiscal emitido referente às peças aplicadas. Disponibilizado em PDF e XML.
NF de Serviço	`serviceNfNumber`	Documento fiscal emitido referente à mão de obra prestada. Disponibilizado em PDF.

Status de Processamento Fiscal (invoiceStatus)

As notas fiscais passam por uma esteira de estados sistêmicos na plataforma, representados pelo campo invoiceStatus:

INVOICE_WAITING_UPLOAD → AVAILABLE → RECORDED

INVOICE_WAITING_UPLOAD: A manutenção foi concluída e o sistema aguarda o upload/emissão das Notas Fiscais pela oficina.
AVAILABLE: Os arquivos físicos das Notas Fiscais foram carregados com sucesso e estão disponíveis para download.
RECORDED (ou wasInvoiceRecorded): Indica se o arquivo da Nota Fiscal já foi devidamente exportado ou integrado pelo sistema ERP do cliente.

Relação Geral entre os Recursos

A árvore estrutural abaixo demonstra de forma gráfica como os recursos de orçamentos e faturamento estão relacionados dentro do ecossistema de manutenção:

Solicitação de Serviço (requestId) → Orçamento (budgetId) → aprovado via Código de Autorização (approvalCode) → Faturamento (billingId)

Faturamento → NF Peças → PDF / XML Filepath

Faturamento → NF Serviço → PDF Filepath

Fluxo de Trabalho (Workflow)

Esta seção descreve os caminhos de integração recomendados para garantir que sua aplicação utilize as APIs de forma otimizada e livre de inconsistências fiscais ou financeiras.

Pré-requisitos de Integração

Consumir as credenciais de autenticação válidas (Bearer Token) associadas ao perfil do parceiro/cliente.
Configurar o sistema local para receber ou realizar varreduras (polling) de orçamentos pendentes.
Compreender os mapeamentos de dados detalhados na etapa de Fundamentos.

Fluxo 1: Esteira de Aprovação de Orçamentos (Criação de Pedido de Compras)

Para realizar a aprovação de uma manutenção de forma automatizada, o fluxo sistêmico deve seguir a ordem de chamadas abaixo:

Consumir GET /client-approval-queue → Validar Paginação

Se empty: true → Fim da fila / Sem orçamentos pendentes.

Se empty: false → Processar itens do array content → Enviar PATCH /client-approval (injetando approvalCode)

Obter Fila de Pendentes: Monitore periodicamente as solicitações que necessitam de aprovação de orçamento do cliente.
Avaliar Custos: Para cada solicitação na fila, consulte os detalhes do orçamento para avaliar os valores de peças e serviços.
Enviar Aprovação: Após aprovar o orçamento em seu ERP interno e gerar o código de autorização, envie a aprovação para a plataforma via PATCH.

Nota de Integração: O envio de um approvalCode nulo ou igual a zero (0) em contas parametrizadas para exigência de Pedido de Compra resultará em rejeição imediata da chamada.

Fluxo 2: Captura e Importação de Notas Fiscais

Para capturar e fazer o download automático de documentos fiscais e vinculá-los ao seu ERP de contas a pagar, execute o seguinte fluxo periódico:

Consultar GET /invoice-parts-services-queue (isInvoiceRecorded: false) → Há Notas Disponíveis?

Se Não → Aguardar próximo ciclo de polling.

Se Sim → Para cada registro: Download PDF Peças (partsNfPdfFilepath) / Download XML Peças (partsNfXmlFilepath) / Download PDF Serviço (serviceNfPdfFilepath).

Referência de Endpoints

Orçamentos e Aprovações

Listar solicitações a aprovar

Retorna a listagem paginada de todas as solicitações de manutenção que necessitam de aprovação de orçamento por parte do cliente.

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

Método: GET

Query Parameters:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`page`	integer	Não	0	Número da página a ser recuperada.
`size`	integer	Não	20	Limite de registros por página.
`sort`	array[string]	Não	-	Ordenação dos resultados (ex: `date,desc`).

Exemplo de Requisição:

GET api/service-requests/client-approval-queue?page=0&size=1 HTTP/1.1
Host: api.developer.platform.com
Authorization: Bearer <TOKEN>
Content-Type: application/json

Estrutura da Resposta (Schema):

Campo	Tipo	Descrição
`totalElements`	integer	Total acumulado de registros no banco de dados.
`totalPages`	integer	Total de páginas disponíveis para consulta baseadas no size.
`size`	integer	Quantidade de registros solicitada por página.
`content`	array[object]	Lista de solicitações de serviço aguardando aprovação (ver campos abaixo).

Campos dentro do Array content:

Campo	Tipo	Descrição
`id`	integer	Identificador da solicitação de serviço.
`requestId`	string	Código textual identificador da solicitação.
`blockName`	string	Nome do bloco operacional associado.
`carWorkshopName`	string	Nome da oficina mecânica executora.
`budgetId`	integer	Identificador do orçamento pendente de aprovação.
`totalBudgetClient`	double	Valor total do orçamento proposto para o cliente.
`workflowClientApprovalsCount`	integer	Quantidade de aprovações já realizadas neste orçamento.
`workflowClientApprovalsTotal`	integer	Quantidade total de aprovações necessárias para liberação.
`workflowClientIsLastApprover`	boolean	Indica se a aprovação atual será a última necessária na esteira.
`date`	string	Data e hora de criação da solicitação (Formato ISO-8601).
`clientApproverProfile`	string	Perfil de aprovação requerido (ex: DRIVER, MANAGER).
`budgetStatus`	string	Status do orçamento.

Exemplo de Resposta (Status 200 OK):

{
  "totalElements": 1,
  "totalPages": 1,
  "size": 1,
  "content": [
    {
      "id": 10564,
      "requestId": "REQ-2025-009",
      "blockName": "Mecânica Geral",
      "carWorkshopName": "Oficina Central Bosch",
      "budgetId": 7525,
      "totalBudgetClient": 450.50,
      "workflowClientApprovalsCount": 1,
      "workflowClientApprovalsTotal": 2,
      "workflowClientIsLastApprover": true,
      "date": "2025-09-18T16:04:11.784Z",
      "clientApproverProfile": "DRIVER",
      "budgetStatus": "PENDING_APPROVAL"
    }
  ],
  "number": 0,
  "sort": {
    "empty": false,
    "sorted": true,
    "unsorted": false
  },
  "pageable": {
    "offset": 0,
    "sort": {
      "empty": false,
      "sorted": true,
      "unsorted": false
    },
    "pageNumber": 0,
    "unpaged": false,
    "paged": true,
    "pageSize": 1
  },
  "numberOfElements": 1,
  "first": true,
  "last": true,
  "empty": false
}

Verificar o orçamento

Retorna de forma analítica e detalhada todos os itens de peças, mão de obra, margens de intermediação e caminhos de arquivo associados a um orçamento específico.

Endpoint: api/budgets/{budgetId}

Método: GET

Exemplo de Requisição:

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

Estrutura da Resposta (Schema) — Detalhes Gerais:

Campo	Tipo	Descrição
`id`	integer	Identificador único do orçamento.
`serviceRequestId`	integer	ID da solicitação de serviço vinculada.
`billingId`	integer	ID de faturamento correspondente (se gerado).
`status`	string	Status interno do orçamento (ex: WAITING_CLIENT_APPROVAL).
`displayStatus`	string	Descrição textual legível do status em tela.
`approvalCode`	integer	Código de aprovação (PO) vinculado ao orçamento.
`creatorUser`	string	Usuário criador do orçamento.
`createdAt`	string	Data e hora de criação do orçamento.
`budgetServiceItems`	array[object]	Lista de serviços inclusos no orçamento.
`budgetPartItems`	array[object]	Lista de peças inclusas no orçamento.
`carWorkshopPdfFilename`	string	Nome do arquivo PDF de orçamento gerado pela oficina.
`carWorkshopPdfFilepath`	string	Caminho de download para o arquivo PDF da oficina.
`workflowClientIsLastApprover`	boolean	Indica se o perfil do cliente corrente é o último aprovador.

Detalhamento do Objeto de Serviços (budgetServiceItems):

Campo	Tipo	Descrição
`id`	integer	Identificador único do item de serviço.
`serviceId`	integer	ID do serviço cadastrado na base.
`clientPrice`	double	Preço final a ser cobrado do cliente pelo serviço.
`carWorkshopPrice`	double	Preço repassado à oficina pelo serviço.
`intermediationFee`	double	Taxa de intermediação aplicada.
`admFee`	double	Taxa administrativa.
`serviceName`	string	Nome do serviço prestado.
`serviceCode`	string	Código técnico do serviço.
`amountOfHours`	double	Quantidade de horas estimadas para execução.

Detalhamento do Objeto de Peças (budgetPartItems):

Campo	Tipo	Descrição
`id`	integer	Identificador único do item de peça.
`partId`	integer	ID da peça cadastrada na base.
`clientPrice`	double	Preço final cobrado do cliente pela peça.
`carWorkshopPrice`	double	Preço cobrado pela oficina parceira.
`partAmount`	double	Quantidade de peças físicas utilizadas.
`partManufacturerName`	string	Fabricante da peça (ex: Bosch).
`partCode`	string	Código de fábrica da peça.
`partName`	string	Nome descritivo da peça.
`measurementUnit`	string	Unidade de medida (ex: UN, LT).

Exemplo de Resposta (Status 200 OK):

{
  "id": 7525,
  "serviceRequestId": 1289,
  "billingId": 9821,
  "status": "WAITING_CLIENT_APPROVAL",
  "displayStatus": "Aguardando Aprovação",
  "approvalCode": 0,
  "creatorUser": "sistema.oficina",
  "perfil": "OFICINA",
  "createdAt": "2025-09-18T17:49:21.665Z",
  "modifiedAt": "2025-09-18T17:49:21.665Z",
  "clientApprovalAvailableAt": "2025-09-18T17:49:21.665Z",
  "modifiedBy": "string",
  "budgetServiceItems": [
    {
      "id": 123,
      "budgetId": 7525,
      "serviceId": 55,
      "clientPrice": 150.00,
      "carWorkshopPrice": 120.00,
      "intermediationFee": 15.00,
      "admFee": 5.00,
      "driveBMargin": 10.00,
      "serviceName": "Alinhamento e Balanceamento",
      "serviceCode": "ALIN-001",
      "amountOfHours": 1.0,
      "modifiedBy": "sistema.oficina",
      "isPreventiveVerification": true,
      "isPreventiveVerificationConfirmed": true
    }
  ],
  "budgetPartItems": [
    {
      "id": 456,
      "budgetId": 7525,
      "partId": 989,
      "clientPrice": 300.50,
      "carWorkshopPrice": 250.00,
      "partAmount": 1.0,
      "intermediationFee": 20.00,
      "admFee": 10.50,
      "driveBMargin": 20.00,
      "partManufacturerName": "Bosch",
      "partCode": "B-98122",
      "partName": "Pastilha de Freio",
      "measurementUnit": "UN",
      "modifiedBy": "sistema.oficina",
      "isPreventiveVerification": true,
      "isPreventiveVerificationConfirmed": true,
      "pnErpCode": "PN-12345",
      "tire": false,
      "isInternalReferenceBase": true
    }
  ],
  "budgetValidations": [],
  "carWorkshopPdfFilename": "orcamento_7525.pdf",
  "carWorkshopPdfFilepath": "/files/budgets/7525/pdf",
  "clientApproverProfile": "DRIVER",
  "workflowClientApprovalsCount": 1,
  "workflowClientApprovalsTotal": 2,
  "workflowClientIsLastApprover": true,
  "inRenegotiation": false,
  "version": 1,
  "hasChangedValue": false,
  "empty": false
}

Aprovar a solicitação

Realiza a aprovação formal do orçamento de manutenção, autorizando o início dos serviços físicos. É mandatório o envio do número de Pedido de Compra gerado pelo sistema do cliente em approvalCode.

Endpoint: api/budgets/{budgetId}/events/client-approval

Método: PATCH

Exemplo de Requisição (Request Payload):

PATCH api/budgets/7525/events/client-approval HTTP/1.1
Host: api.developer.platform.com
Authorization: Bearer <TOKEN>
Content-Type: application/json

{
  "approvalCode": 987654321,
  "observations": "Orçamento aprovado via integração de ERP - Setor Frota."
}

Detalhe dos Campos de Entrada (Request Schema):

Campo	Tipo	Obrigatório	Descrição
`approvalCode`	integer	Sim	Número do Pedido de Compras (PO) gerado pelo sistema do cliente para faturamento.
`observations`	string	Não	Observações adicionais sobre o ato de aprovação ou recusa do orçamento.

Exemplo de Resposta (Status 204 No Content):

(Resposta de sucesso sem corpo de retorno, apenas cabeçalho confirmando o processamento).

Faturamento e Listagem Fiscal

Listagem de Notas Fiscais

Recupere a listagem de registros de faturamento e notas fiscais geradas pelas oficinas e faturadores para posterior processamento ou exportação.

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

Método: GET

Filters / Query Parameters:

Parâmetro	Tipo	Obrigatório	Descrição
`isInvoiceRecorded`	boolean	Não	Filtra por notas fiscais já exportadas/registradas (true/false).
`requestId`	string	Não	Filtra faturamentos de um ID de solicitação específico.
`clientId`	integer	Não	ID único do cliente.
`carWorkshopId`	integer	Não	ID da oficina emitente da nota fiscal.
`vehicleLicensePlate`	string	Não	Placa do veículo associado à manutenção.
`partsNfNumber`	integer	Não	Número exato da nota fiscal de peças.
`servicesNfNumber`	integer	Não	Número exato da nota fiscal de serviços.
`nfIssueInitialDate`	string (date)	Não	Filtro de data inicial de emissão fiscal (YYYY-MM-DD).
`nfIssueFinalDate`	string (date)	Não	Filtro de data final de emissão fiscal (YYYY-MM-DD).
`invoiceStatus`	string	Não	Status de faturamento (ex: AVAILABLE).
`isPartsInvoiceAvailable`	string	Não	Disponibilidade do arquivo de peças (AVAILABLE, NOT_AVAILABLE).
`isServiceInvoiceAvailable`	string	Não	Disponibilidade do arquivo de serviços (AVAILABLE, NOT_AVAILABLE).

Exemplo de Resposta (Status 200 OK):

[
  {
    "billingId": 9821,
    "serviceRequestId": 1289,
    "requestId": "REQ-2025-009",
    "clientId": 442,
    "clientName": "Bosch Latin America",
    "clientType": "CORPORATE",
    "clientCountryId": 1,
    "vehicleLicensePlate": "ABC1D23",
    "invoiceStatus": "AVAILABLE",
    "partsNfStatus": "EMITTED",
    "serviceNfStatus": "EMITTED",
    "partsNfNumber": 4567,
    "partsNfIssueDate": "2025-09-03T13:29:18.318Z",
    "serviceNfNumber": 8812,
    "serviceNfIssueDate": "2025-09-03T13:29:18.318Z",
    "budgetId": 7525,
    "carWorkshopId": 12,
    "carWorkshopName": "Oficina Central Bosch",
    "blockCode": "BLOCK-MEC-01",
    "isInvoiceRecorded": false,
    "isInvoicePartPdfReplaced": false,
    "isInvoicePartXmlReplaced": false,
    "isInvoiceServicePdfReplaced": false,
    "status": "COMPLETED",
    "wasInvoiceRecorded": false,
    "isServiceInvoiceAvailable": "AVAILABLE",
    "isPartsInvoiceAvailable": "AVAILABLE",
    "approvalCode": "987654321",
    "provider": "PREFEITURA_MUNICIPAL",
    "clientPriceNfService": 150.00,
    "clientPriceNfParts": 300.50,
    "serviceNfExpirationDate": "2025-10-03T00:00:00Z",
    "partsNfExpirationDate": "2025-10-03T00:00:00Z",
    "serviceNfPdfFilename": "nf_servico_8812.pdf",
    "partsNfPdfFilename": "nf_pecas_4567.pdf",
    "partsNfXmlFilename": "nf_pecas_4567.xml",
    "serviceNfPdfFilepath": "/api/files/invoices/services/pdf/8812",
    "partsNfPdfFilepath": "/api/files/invoices/parts/pdf/4567",
    "partsNfXmlFilepath": "/api/files/invoices/parts/xml/4567",
    "partsNfSendFileDate": "2025-09-03T14:00:00Z",
    "serviceNfSendFileDate": "2025-09-03T14:15:00Z",
    "osServiceValue": 120.00,
    "osPartsValue": 250.00,
    "serviceInvoiceForCustomer": true
  }
]

Arquivos de Notas Fiscais

Efetue o download dos arquivos em formato PDF ou XML vinculados a um faturamento utilizando os caminhos dinâmicos retornados pela listagem de notas fiscais.

Obter Arquivo PDF NF Peças

Endpoint: Utilizar a URL contida no campo de resposta partsNfPdfFilepath (ex: /api/files/invoices/parts/pdf/4567)

Método: GET

Obter Arquivo XML NF Peças

Endpoint: Utilizar a URL contida no campo de resposta partsNfXmlFilepath (ex: /api/files/invoices/parts/xml/4567)

Método: GET

Obter Arquivo PDF NF Serviço

Endpoint: Utilizar a URL contida no campo de resposta serviceNfPdfFilepath (ex: /api/files/invoices/services/pdf/8812)

Método: GET

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 ou 204 No Content	A transação foi efetuada, validada e processada com sucesso.	Prossiga com o processamento normal ou passe para a próxima etapa do fluxo de integração.
400 Bad Request	Envio de payloads inválidos, campos obrigatórios ausentes ou tipos incorretos de variáveis.	Valide a estrutura do JSON. Certifique-se de que os IDs numéricos não estão sendo enviados como textos e verifique campos obrigatórios.
401 Unauthorized	O token de autenticação enviado é inválido, está expirado ou ausente nos headers.	Renove o Bearer Token de autenticação e certifique-se de adicioná-lo corretamente no cabeçalho Authorization.
403 Forbidden	O cliente autenticado não possui acesso à filial solicitada ou privilégios de faturamento.	Entre em contato com o suporte ou gestor de conta para garantir que seu escopo de API permita operações fiscais.
404 Not Found	O identificador do orçamento (budgetId) ou faturamento (billingId) fornecido não existe na base.	Verifique se os IDs informados foram digitados corretamente ou se não pertencem a outro ambiente/ambiente de teste.
422 Unprocessable Entity	O payload está correto, mas viola alguma regra lógica de negócio (ex: orçamento já aprovado anteriormente).	Verifique o status atual do recurso consultando o endpoint correspondente antes de disparar eventos de transição de estado.
500 Internal Server Error	Falha inesperada no processamento por parte dos nossos servidores internos.	Armazene os detalhes do log de erro e aguarde alguns minutos antes de realizar uma nova tentativa automatizada.

Dicas de Resolução de Problemas

Erro de Conciliação Financeira (Falta de PO): Caso o sistema local tente aprovar um orçamento através do endpoint /client-approval enviando "approvalCode": 0, a transação será rejeitada por regras internas quando o faturamento exigir código. Certifique-se de tratar a geração e passagem deste campo de forma integrada em seu ERP.
Notas Fiscais Indisponíveis no Download: Se ao tentar baixar os arquivos pelas URLs retornadas em partsNfPdfFilepath a API responder com 404 Not Found, realize uma verificação no status da nota. É possível que os metadados fiscais tenham sido criados no sistema da oficina, mas o arquivo físico correspondente ainda não tenha concluído o processo de upload. Garanta que isPartsInvoiceAvailable == AVAILABLE antes de disparar o download.
Gerenciamento de Escopo Multicliente: APIs integradas a múltiplas filiais (franquias) devem enviar o parâmetro opcional franchiseIds na listagem de notas fiscais para segregar de forma correta e rápida os documentos fiscais em canais de contas a pagar diferentes.