Referência

Oficinas mecânicas

A oficina de viaturas e motorizadas: a ficha da viatura com livro de quilómetros, documentos com validade e plano de manutenção; o catálogo de operações com tempos padrão; a ordem de reparação (recepção, diagnóstico, inspecção, orçamento por trabalhos, decisão do cliente, execução, qualidade e entrega), o pátio, as garantias e os lembretes. A entrega cobra com um documento fiscal do núcleo, pelo fluxo de sempre.

Operação	O que faz
GET `/api/oficina/definicoes`	As definições da oficina: os tipos de oficina, o diagnóstico, a validade do orçamento, os avisos do pátio, as taxas e o termo de entrada.
PUT `/api/oficina/definicoes`	Define as definições da oficina.
GET `/api/oficina/modelos`	O catálogo de modelos de partida: as operações e os pontos de inspecção que se podem carregar para a empresa.
POST `/api/oficina/catalogo/carregar-partida`	Acrescenta ao catálogo da empresa as operações e os pontos de inspecção de partida dos tipos de oficina indicados (por omissão, os da configuração), saltando os que já existem.
GET `/api/oficina/operacoes`	As operações do catálogo da oficina, com os tempos padrão e as garantias.
POST `/api/oficina/operacoes`	Cria uma operação do catálogo.
PUT `/api/oficina/operacoes/{id}`	Altera uma operação do catálogo.
POST `/api/oficina/operacoes/de-modelo`	Cria uma operação a partir de um modelo de partida (`chave`), ligada ao artigo de serviço indicado.
PUT `/api/oficina/operacoes/{id}/activa`	Activa ou desactiva uma operação.
GET `/api/oficina/pontos`	Os pontos de inspecção do catálogo.
POST `/api/oficina/pontos`	Cria um ponto de inspecção.
PUT `/api/oficina/pontos/{id}`	Altera um ponto de inspecção.
PUT `/api/oficina/pontos/{id}/activo`	Activa ou desactiva um ponto de inspecção.
GET `/api/oficina/boxes`	Os boxes (postos de trabalho) da oficina.
POST `/api/oficina/boxes`	Cria um box.
PUT `/api/oficina/boxes/{id}`	Altera um box.
GET `/api/oficina/zonas`	As zonas do pátio.
POST `/api/oficina/zonas`	Cria uma zona do pátio.
PUT `/api/oficina/zonas/{id}`	Altera uma zona do pátio.
GET `/api/oficina/viaturas`	As viaturas registadas.
GET `/api/oficina/viaturas/{id}`	Uma viatura completa: dados, proprietário e donos anteriores, quilómetros, documentos e plano de manutenção.
POST `/api/oficina/viaturas`	Regista uma viatura.
PUT `/api/oficina/viaturas/{id}`	Altera a matrícula, o VIN e os dados de uma viatura.
POST `/api/oficina/viaturas/{id}/transferir`	Transfere a viatura para outro proprietário (outro cliente da empresa).
PUT `/api/oficina/viaturas/{id}/activa`	Activa ou desactiva uma viatura.
POST `/api/oficina/viaturas/{id}/km`	Regista a quilometragem lida (pelo condutor ou pela recepção).
GET `/api/oficina/viaturas/{id}/livro`	O livro da viatura: as entradas do historial, o que está por fazer, as garantias e os registos de quilómetros.
GET `/api/oficina/viaturas/{id}/garantias`	As garantias activas da viatura.
POST `/api/oficina/viaturas/{id}/documentos`	Acrescenta um documento da viatura (seguro, inspecção, selo…), com a referência e a validade.
PUT `/api/oficina/viaturas/{id}/documentos/{documentoId}`	Altera um documento da viatura.
DELETE `/api/oficina/viaturas/{id}/documentos/{documentoId}`	Remove um documento da viatura.
POST `/api/oficina/viaturas/{id}/plano`	Acrescenta um item ao plano de manutenção da viatura, com os intervalos em quilómetros e em meses.
PUT `/api/oficina/viaturas/{id}/plano/{itemId}`	Altera um item do plano de manutenção.
DELETE `/api/oficina/viaturas/{id}/plano/{itemId}`	Remove um item do plano de manutenção.
GET `/api/oficina/lembretes`	A lista accionável de lembretes: documentos a expirar ou expirados e revisões a breve ou em atraso, de todas as viaturas activas.
GET `/api/oficina/ordens`	As ordens de reparação.
GET `/api/oficina/ordens/{id}`	Uma ordem de reparação completa: recepção, inspecção, trabalhos, orçamento, fotografias e entrega.
GET `/api/oficina/quadro`	O quadro da oficina: as ordens por fase.
GET `/api/oficina/patio`	O pátio: onde está cada viatura, há quantos dias e porquê.
POST `/api/oficina/ordens`	Recebe uma viatura: abre a ordem de reparação com a quilometragem de entrada, o combustível, os objectos, o pedido do cliente e os danos.
POST `/api/oficina/ordens/{id}/termo`	Regista a aceitação do termo de entrada pelo cliente (`aceitePor`).
POST `/api/oficina/ordens/{id}/patio`	Move a viatura no pátio (zona, lugar e código da chave).
POST `/api/oficina/ordens/{id}/prazo`	Define (ou retira) o prazo prometido da ordem.
POST `/api/oficina/ordens/{id}/diagnostico`	Regista o diagnóstico: o texto, o tempo gasto e os códigos OBD.
POST `/api/oficina/ordens/{id}/inspeccao`	Regista o resultado de um ponto de inspecção, com a cor, a medição e a nota.
POST `/api/oficina/ordens/{id}/trabalhos`	Propõe um trabalho na ordem.
POST `/api/oficina/ordens/{id}/trabalhos/de-operacao`	Propõe um trabalho a partir de uma operação do catálogo.
PUT `/api/oficina/ordens/{id}/trabalhos/{trabalhoId}`	Altera um trabalho proposto.
DELETE `/api/oficina/ordens/{id}/trabalhos/{trabalhoId}`	Remove um trabalho proposto.
POST `/api/oficina/ordens/{id}/orcamento`	Envia o orçamento ao cliente: uma versão nova com todos os trabalhos por aprovar.
POST `/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/decisao`	Regista a decisão do cliente sobre um trabalho, dada ao balcão, ao telefone ou presencialmente.
POST `/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/peca-em-falta`	Marca (ou desmarca) um trabalho como à espera de peça, com a data prevista.
POST `/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/atribuir`	Atribui um trabalho a um mecânico e/ou a um box.
POST `/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/iniciar`	Inicia a execução de um trabalho (num box, se indicado).
POST `/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/pausar`	Pausa a execução de um trabalho, com motivo.
POST `/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/terminar`	Termina a execução de um trabalho.
POST `/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/linhas/{linhaId}/aplicar`	Aplica (consome do stock) uma quantidade de uma peça de um trabalho.
POST `/api/oficina/ordens/{id}/qualidade/aprovar`	Aprova a qualidade da ordem, com o test-drive (quilómetros) e uma nota.
POST `/api/oficina/ordens/{id}/qualidade/reprovar`	Reprova a qualidade da ordem: os trabalhos indicados voltam à execução, com motivo.
GET `/api/oficina/ordens/{id}/entrega/preparacao`	O que se cobraria agora pela ordem, calculado pelo mesmo caminho que a emissão (promoções, retenções e arredondamento incluídos).
POST `/api/oficina/ordens/{id}/entrega`	Entrega a viatura: emite um documento pelo mesmo comando do «Novo documento», grava a entrega e emite as garantias.
POST `/api/oficina/ordens/{id}/cancelar`	Cancela uma ordem, com motivo.
POST `/api/oficina/ordens/{id}/responsabilidade`	Define a responsabilidade da garantia numa ordem aberta ao abrigo de uma garantia.
POST `/api/oficina/garantias/{garantiaId}/reclamar`	Abre uma ordem de reparação ao abrigo de uma garantia.
POST `/api/oficina/ordens/{id}/fotos`	Anexa uma fotografia a uma ordem (ou a um trabalho ou inspecção).
GET `/api/oficina/fotos/{id}`	Descarrega uma fotografia de uma ordem.
GET `/api/oficina/indicadores`	Os indicadores da oficina num período.

GET/api/oficina/definicoes#

As definições da oficina: os tipos de oficina, o diagnóstico, a validade do orçamento, os avisos do pátio, as taxas e o termo de entrada.

Permissão Oficina.Ler

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/definicoes' \
  -H 'X-Api-Key: <a-sua-chave>'

PUT/api/oficina/definicoes#

Define as definições da oficina.

Permissão Oficina.Configurar

perfis, diagnosticoIncluido, validadeDoOrcamentoDias, horasSemRespostaParaAlerta, diasNoPatioParaAviso, artigoMaoDeObraId, as taxas (taxaMecanica, taxaElectrica, taxaDiagnostico, taxaChaparia, taxaPintura, taxaMotos) e o termoDeEntrada.

Devolve 204, sem corpo.

Corpo do pedido (JSON · DefinirDefinicoesDaOficinaCommand)

Campo	Tipo	Obrigatório
`perfis`	lista de texto	sim
`diagnosticoIncluido`	verdadeiro/falso	sim
`validadeDoOrcamentoDias`	número inteiro	sim
`horasSemRespostaParaAlerta`	número inteiro	sim
`diasNoPatioParaAviso`	número inteiro	sim
`artigoMaoDeObraId`	identificador (UUID) ou nulo
`taxaMecanica`	número ou nulo
`taxaElectrica`	número ou nulo
`taxaDiagnostico`	número ou nulo
`taxaChaparia`	número ou nulo
`taxaPintura`	número ou nulo
`taxaMotos`	número ou nulo
`termoDeEntrada`	texto ou nulo

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/oficina/definicoes' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "perfis": [
    "texto"
  ],
  "diagnosticoIncluido": false,
  "validadeDoOrcamentoDias": 1,
  "horasSemRespostaParaAlerta": 1,
  "diasNoPatioParaAviso": 1
}'

GET/api/oficina/modelos#

O catálogo de modelos de partida: as operações e os pontos de inspecção que se podem carregar para a empresa.

Permissão Oficina.Ler

perfil limita a um tipo de oficina.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`perfil`	na pesquisa	texto

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/modelos' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/oficina/catalogo/carregar-partida#

Acrescenta ao catálogo da empresa as operações e os pontos de inspecção de partida dos tipos de oficina indicados (por omissão, os da configuração), saltando os que já existem.

Permissão Oficina.CatalogoEditar
Idempotência aceita Idempotency-Key

As operações entram sem artigo, sem preços e sem garantias: a oficina liga-as ao seu artigo de serviço e ajusta tudo (os tempos são sugestões).

Corpo do pedido (JSON · CarregarCatalogoDePartidaCommand)

Campo	Tipo	Obrigatório
`perfis`	lista de texto ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/catalogo/carregar-partida' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET/api/oficina/operacoes#

As operações do catálogo da oficina, com os tempos padrão e as garantias.

Permissão Oficina.Ler

apenasActivas (por omissão, verdadeiro).

Parâmetros

Nome	Onde	Tipo	Obrigatório
`apenasActivas`	na pesquisa	verdadeiro/falso

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/operacoes' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/oficina/operacoes#

Cria uma operação do catálogo.

Permissão Oficina.CatalogoEditar
Idempotência aceita Idempotency-Key

codigo, nome, sistema, dificuldade, tipoDeTrabalho, produtoServicoId (o artigo de serviço que se factura), valorFixo, garantiaDias, garantiaKm, intervaloKm, intervaloMeses e tempos entre outros.

Corpo do pedido (JSON · GuardarOperacaoCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`codigo`	texto	sim	O código curto.
`nome`	texto	sim	O nome.
`descricaoTecnica`	texto ou nulo
`sistema`	texto	sim
`dificuldade`	texto	sim
`competencia`	texto ou nulo
`tipoDeTrabalho`	texto	sim
`produtoServicoId`	identificador (UUID) ou nulo
`valorFixo`	número ou nulo
`interna`	verdadeiro/falso	sim
`garantiaDias`	número inteiro ou nulo
`garantiaKm`	número inteiro ou nulo
`intervaloKm`	número inteiro ou nulo
`intervaloMeses`	número inteiro ou nulo
`perfis`	lista de texto ou nulo
`modeloOrigem`	texto ou nulo
`tempos`	lista de objectos ou nulo
`tempos[].categoria`	texto	sim
`tempos[].minutos`	número inteiro	sim
`pecas`	lista de objectos ou nulo
`pecas[].produtoId`	identificador (UUID)	sim	O artigo.
`pecas[].quantidade`	número	sim	A quantidade.

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/operacoes' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "codigo": "texto",
  "nome": "texto",
  "sistema": "texto",
  "dificuldade": "texto",
  "tipoDeTrabalho": "texto",
  "interna": false
}'

PUT/api/oficina/operacoes/{id}#

Altera uma operação do catálogo.

Permissão Oficina.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · GuardarOperacaoCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`codigo`	texto	sim	O código curto.
`nome`	texto	sim	O nome.
`descricaoTecnica`	texto ou nulo
`sistema`	texto	sim
`dificuldade`	texto	sim
`competencia`	texto ou nulo
`tipoDeTrabalho`	texto	sim
`produtoServicoId`	identificador (UUID) ou nulo
`valorFixo`	número ou nulo
`interna`	verdadeiro/falso	sim
`garantiaDias`	número inteiro ou nulo
`garantiaKm`	número inteiro ou nulo
`intervaloKm`	número inteiro ou nulo
`intervaloMeses`	número inteiro ou nulo
`perfis`	lista de texto ou nulo
`modeloOrigem`	texto ou nulo
`tempos`	lista de objectos ou nulo
`tempos[].categoria`	texto	sim
`tempos[].minutos`	número inteiro	sim
`pecas`	lista de objectos ou nulo
`pecas[].produtoId`	identificador (UUID)	sim	O artigo.
`pecas[].quantidade`	número	sim	A quantidade.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/oficina/operacoes/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "codigo": "texto",
  "nome": "texto",
  "sistema": "texto",
  "dificuldade": "texto",
  "tipoDeTrabalho": "texto",
  "interna": false
}'

POST/api/oficina/operacoes/de-modelo#

Cria uma operação a partir de um modelo de partida (chave), ligada ao artigo de serviço indicado.

Permissão Oficina.CatalogoEditar
Idempotência aceita Idempotency-Key

Corpo do pedido (JSON · CriarOperacaoDeModeloCommand)

Campo	Tipo	Obrigatório	Significado
`chave`	texto	sim
`produtoServicoId`	identificador (UUID) ou nulo
`nome`	texto ou nulo		O nome.

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/operacoes/de-modelo' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "chave": "texto"
}'

PUT/api/oficina/operacoes/{id}/activa#

Activa ou desactiva uma operação.

Permissão Oficina.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ActivoPedido)

Campo	Tipo	Obrigatório	Significado
`activo`	verdadeiro/falso	sim	Se está activo.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/oficina/operacoes/<id>/activa' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "activo": false
}'

GET/api/oficina/pontos#

Os pontos de inspecção do catálogo.

Permissão Oficina.Ler

Filtros: apenasActivos (por omissão, verdadeiro) e perfil.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`apenasActivos`	na pesquisa	verdadeiro/falso
`perfil`	na pesquisa	texto

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/pontos' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/oficina/pontos#

Cria um ponto de inspecção.

Permissão Oficina.CatalogoEditar
Idempotência aceita Idempotency-Key

Corpo do pedido (JSON · GuardarPontoDeInspeccaoCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`codigo`	texto	sim	O código curto.
`nome`	texto	sim	O nome.
`grupo`	texto	sim
`unidade`	texto ou nulo
`perfis`	lista de texto ou nulo
`ordem`	número inteiro	sim

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/pontos' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "codigo": "texto",
  "nome": "texto",
  "grupo": "texto",
  "ordem": 1
}'

PUT/api/oficina/pontos/{id}#

Altera um ponto de inspecção.

Permissão Oficina.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · GuardarPontoDeInspeccaoCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`codigo`	texto	sim	O código curto.
`nome`	texto	sim	O nome.
`grupo`	texto	sim
`unidade`	texto ou nulo
`perfis`	lista de texto ou nulo
`ordem`	número inteiro	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/oficina/pontos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "codigo": "texto",
  "nome": "texto",
  "grupo": "texto",
  "ordem": 1
}'

PUT/api/oficina/pontos/{id}/activo#

Activa ou desactiva um ponto de inspecção.

Permissão Oficina.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ActivoPedido)

Campo	Tipo	Obrigatório	Significado
`activo`	verdadeiro/falso	sim	Se está activo.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/oficina/pontos/<id>/activo' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "activo": false
}'

GET/api/oficina/boxes#

Os boxes (postos de trabalho) da oficina.

Permissão Oficina.Ler

apenasActivas (por omissão, verdadeiro). lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`lojaId`	na pesquisa	identificador (UUID)
`apenasActivas`	na pesquisa	verdadeiro/falso

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/boxes' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/oficina/boxes#

Cria um box.

Permissão Oficina.CatalogoEditar
Idempotência aceita Idempotency-Key

lojaId é opcional quando a chave só tem um estabelecimento.

Corpo do pedido (JSON · GuardarBoxCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`nome`	texto	sim	O nome.
`tipo`	texto	sim
`activa`	verdadeiro/falso	sim

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/boxes' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "tipo": "texto",
  "activa": false
}'

PUT/api/oficina/boxes/{id}#

Altera um box.

Permissão Oficina.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · GuardarBoxCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`nome`	texto	sim	O nome.
`tipo`	texto	sim
`activa`	verdadeiro/falso	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/oficina/boxes/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "tipo": "texto",
  "activa": false
}'

GET/api/oficina/zonas#

As zonas do pátio.

Permissão Oficina.Ler

apenasActivas (por omissão, verdadeiro). lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`lojaId`	na pesquisa	identificador (UUID)
`apenasActivas`	na pesquisa	verdadeiro/falso

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/zonas' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/oficina/zonas#

Cria uma zona do pátio.

Permissão Oficina.CatalogoEditar
Idempotência aceita Idempotency-Key

lojaId é opcional quando a chave só tem um estabelecimento.

Corpo do pedido (JSON · GuardarZonaDePatioCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`nome`	texto	sim	O nome.
`ordem`	número inteiro	sim
`activa`	verdadeiro/falso	sim

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/zonas' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "ordem": 1,
  "activa": false
}'

PUT/api/oficina/zonas/{id}#

Altera uma zona do pátio.

Permissão Oficina.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · GuardarZonaDePatioCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`nome`	texto	sim	O nome.
`ordem`	número inteiro	sim
`activa`	verdadeiro/falso	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/oficina/zonas/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "ordem": 1,
  "activa": false
}'

GET/api/oficina/viaturas#

As viaturas registadas.

Permissão Oficina.Ler

Filtros: texto (matrícula, VIN, proprietário…), clienteId, apenasActivas (por omissão, verdadeiro) e tamanho (por omissão 30).

Parâmetros

Nome	Onde	Tipo
`texto`	na pesquisa	texto
`clienteId`	na pesquisa	identificador (UUID)
`apenasActivas`	na pesquisa	verdadeiro/falso
`tamanho`	na pesquisa	número inteiro

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/viaturas' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/oficina/viaturas/{id}#

Uma viatura completa: dados, proprietário e donos anteriores, quilómetros, documentos e plano de manutenção.

Permissão Oficina.Ler

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/viaturas/<id>' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/oficina/viaturas#

Regista uma viatura.

Permissão Oficina.Receber
Idempotência aceita Idempotency-Key

matricula, proprietarioId (um cliente da empresa), dados da viatura, e, se houver, o vin e o km actual.

Corpo do pedido (JSON · RegistarViaturaCommand)

Campo	Tipo	Obrigatório
`matricula`	texto	sim
`vin`	texto ou nulo
`proprietarioId`	identificador (UUID)	sim
`dados`	objecto	sim
`dados.categoria`	texto	sim
`dados.marca`	texto	sim
`dados.modelo`	texto	sim
`dados.versao`	texto ou nulo
`dados.ano`	número inteiro ou nulo
`dados.cor`	texto ou nulo
`dados.combustivel`	texto ou nulo
`dados.cilindradaCc`	número inteiro ou nulo
`dados.caixa`	texto ou nulo
`dados.usoDaMoto`	texto ou nulo
`dados.condutorHabitual`	texto ou nulo
`dados.empresaId`	identificador (UUID) ou nulo
`dados.gestorDeFrota`	texto ou nulo
`dados.pneusMedida`	texto ou nulo
`dados.notas`	texto ou nulo
`km`	número inteiro ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/viaturas' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "matricula": "texto",
  "proprietarioId": "00000000-0000-0000-0000-000000000000",
  "dados": {
    "categoria": "texto",
    "marca": "texto",
    "modelo": "texto"
  }
}'

PUT/api/oficina/viaturas/{id}#

Altera a matrícula, o VIN e os dados de uma viatura.

Permissão Oficina.Receber

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ViaturaPedido)

Campo	Tipo	Obrigatório
`matricula`	texto	sim
`vin`	texto ou nulo
`dados`	objecto	sim
`dados.categoria`	texto	sim
`dados.marca`	texto	sim
`dados.modelo`	texto	sim
`dados.versao`	texto ou nulo
`dados.ano`	número inteiro ou nulo
`dados.cor`	texto ou nulo
`dados.combustivel`	texto ou nulo
`dados.cilindradaCc`	número inteiro ou nulo
`dados.caixa`	texto ou nulo
`dados.usoDaMoto`	texto ou nulo
`dados.condutorHabitual`	texto ou nulo
`dados.empresaId`	identificador (UUID) ou nulo
`dados.gestorDeFrota`	texto ou nulo
`dados.pneusMedida`	texto ou nulo
`dados.notas`	texto ou nulo

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/oficina/viaturas/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "matricula": "texto",
  "dados": {
    "categoria": "texto",
    "marca": "texto",
    "modelo": "texto"
  }
}'

POST/api/oficina/viaturas/{id}/transferir#

Transfere a viatura para outro proprietário (outro cliente da empresa).

Permissão Oficina.Receber
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · TransferenciaPedido)

Campo	Tipo	Obrigatório
`novoProprietarioId`	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/viaturas/<id>/transferir' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "novoProprietarioId": "00000000-0000-0000-0000-000000000000"
}'

PUT/api/oficina/viaturas/{id}/activa#

Activa ou desactiva uma viatura.

Permissão Oficina.Receber

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ActivoPedido)

Campo	Tipo	Obrigatório	Significado
`activo`	verdadeiro/falso	sim	Se está activo.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/oficina/viaturas/<id>/activa' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "activo": false
}'

POST/api/oficina/viaturas/{id}/km#

Regista a quilometragem lida (pelo condutor ou pela recepção).

Permissão Oficina.Receber
Idempotência aceita Idempotency-Key

Um valor menor que o último exige justificação («painel trocado») e fica assinalado.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · KmPedido)

Campo	Tipo	Obrigatório
`km`	número inteiro	sim
`origem`	texto ou nulo
`justificacao`	texto ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/viaturas/<id>/km' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "km": 1
}'

GET/api/oficina/viaturas/{id}/livro#

O livro da viatura: as entradas do historial, o que está por fazer, as garantias e os registos de quilómetros.

Permissão Oficina.Ler

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/viaturas/<id>/livro' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/oficina/viaturas/{id}/garantias#

As garantias activas da viatura.

Permissão Oficina.Ler

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/viaturas/<id>/garantias' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/oficina/viaturas/{id}/documentos#

Acrescenta um documento da viatura (seguro, inspecção, selo…), com a referência e a validade.

Permissão Oficina.Receber
Idempotência aceita Idempotency-Key

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · DocumentoDaViaturaPedido)

Campo	Tipo	Obrigatório
`tipo`	texto	sim
`referencia`	texto ou nulo
`validadeAte`	data (AAAA-MM-DD) ou nulo
`nota`	texto ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/viaturas/<id>/documentos' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "tipo": "texto"
}'

PUT/api/oficina/viaturas/{id}/documentos/{documentoId}#

Altera um documento da viatura.

Permissão Oficina.Receber

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`documentoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · DocumentoDaViaturaPedido)

Campo	Tipo	Obrigatório
`tipo`	texto	sim
`referencia`	texto ou nulo
`validadeAte`	data (AAAA-MM-DD) ou nulo
`nota`	texto ou nulo

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/oficina/viaturas/<id>/documentos/<documentoId>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "tipo": "texto"
}'

DELETE/api/oficina/viaturas/{id}/documentos/{documentoId}#

Remove um documento da viatura.

Permissão Oficina.Receber

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`documentoId`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X DELETE 'https://<endereço-da-API>/api/oficina/viaturas/<id>/documentos/<documentoId>' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/oficina/viaturas/{id}/plano#

Acrescenta um item ao plano de manutenção da viatura, com os intervalos em quilómetros e em meses.

Permissão Oficina.Receber
Idempotência aceita Idempotency-Key

operacaoId liga o item a uma operação do catálogo; sem ela, indique a descricao.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ItemDoPlanoPedido)

Campo	Tipo	Significado
`operacaoId`	identificador (UUID) ou nulo
`descricao`	texto ou nulo	A descrição.
`intervaloKm`	número inteiro ou nulo
`intervaloMeses`	número inteiro ou nulo
`ultimoKm`	número inteiro ou nulo
`ultimaData`	data (AAAA-MM-DD) ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/viaturas/<id>/plano' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

PUT/api/oficina/viaturas/{id}/plano/{itemId}#

Altera um item do plano de manutenção.

Permissão Oficina.Receber

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`itemId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ItemDoPlanoPedido)

Campo	Tipo	Significado
`operacaoId`	identificador (UUID) ou nulo
`descricao`	texto ou nulo	A descrição.
`intervaloKm`	número inteiro ou nulo
`intervaloMeses`	número inteiro ou nulo
`ultimoKm`	número inteiro ou nulo
`ultimaData`	data (AAAA-MM-DD) ou nulo

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/oficina/viaturas/<id>/plano/<itemId>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE/api/oficina/viaturas/{id}/plano/{itemId}#

Remove um item do plano de manutenção.

Permissão Oficina.Receber

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`itemId`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X DELETE 'https://<endereço-da-API>/api/oficina/viaturas/<id>/plano/<itemId>' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/oficina/lembretes#

A lista accionável de lembretes: documentos a expirar ou expirados e revisões a breve ou em atraso, de todas as viaturas activas.

Permissão Oficina.Ler

É uma lista, não uma mensagem: não se envia nada sozinho. dias (por omissão 30) é a antecedência.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`dias`	na pesquisa	número inteiro

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/lembretes' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/oficina/ordens#

As ordens de reparação.

Permissão Oficina.Ler

Filtros: texto, estado, soAbertas (por omissão, verdadeiro), mecanicoId, viaturaId, clienteId e tamanho (por omissão 60). lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo
`texto`	na pesquisa	texto
`estado`	na pesquisa	texto
`soAbertas`	na pesquisa	verdadeiro/falso
`mecanicoId`	na pesquisa	identificador (UUID)
`viaturaId`	na pesquisa	identificador (UUID)
`clienteId`	na pesquisa	identificador (UUID)
`lojaId`	na pesquisa	identificador (UUID)
`tamanho`	na pesquisa	número inteiro

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/ordens' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/oficina/ordens/{id}#

Uma ordem de reparação completa: recepção, inspecção, trabalhos, orçamento, fotografias e entrega.

Permissão Oficina.Ler

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/ordens/<id>' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/oficina/quadro#

O quadro da oficina: as ordens por fase.

Permissão Oficina.Ler

lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`lojaId`	na pesquisa	identificador (UUID)

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/quadro' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/oficina/patio#

O pátio: onde está cada viatura, há quantos dias e porquê.

Permissão Oficina.Ler

O valor parado são as ordens prontas por levantar e as ordens à espera de peça. Mostra dias e avisa, mas não cobra: a taxa de permanência só existe com o texto jurídico validado pelo titular. lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`lojaId`	na pesquisa	identificador (UUID)

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/patio' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/oficina/ordens#

Recebe uma viatura: abre a ordem de reparação com a quilometragem de entrada, o combustível, os objectos, o pedido do cliente e os danos.

Permissão Oficina.Receber
Idempotência aceita Idempotency-Key

viaturaId, kmEntrada, combustivel e pedidoDoCliente são obrigatórios. Opcionais: clienteId, o prazo prometido, a marcação de origem e o lugar no pátio. lojaId é opcional quando a chave só tem um estabelecimento.

Corpo do pedido (JSON · ReceberViaturaCommand)

Campo	Tipo	Obrigatório	Significado
`viaturaId`	identificador (UUID)	sim
`clienteId`	identificador (UUID) ou nulo		O cliente do documento.
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`kmEntrada`	número inteiro	sim
`justificacaoDoKm`	texto ou nulo
`combustivel`	texto	sim
`objectos`	texto ou nulo
`chaveCodigo`	texto ou nulo
`pedidoDoCliente`	texto	sim
`danos`	lista de objectos ou nulo
`danos[].zona`	texto	sim
`danos[].descricao`	texto	sim	A descrição.
`danos[].gravidade`	texto	sim
`decisorNome`	texto ou nulo
`decisorContacto`	texto ou nulo
`prometidoParaUtc`	data e hora (ISO 8601) ou nulo
`marcacaoId`	identificador (UUID) ou nulo
`zonaDePatioId`	identificador (UUID) ou nulo
`lugarNoPatio`	texto ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "viaturaId": "00000000-0000-0000-0000-000000000000",
  "kmEntrada": 1,
  "combustivel": "texto",
  "pedidoDoCliente": "texto"
}'

POST/api/oficina/ordens/{id}/termo#

Regista a aceitação do termo de entrada pelo cliente (aceitePor).

Permissão Oficina.Receber
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · TermoPedido)

Campo	Tipo	Obrigatório
`aceitePor`	texto	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/termo' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "aceitePor": "texto"
}'

POST/api/oficina/ordens/{id}/patio#

Move a viatura no pátio (zona, lugar e código da chave).

Permissão Oficina.Receber
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · PatioPedido)

Campo	Tipo	Obrigatório
`zonaDePatioId`	identificador (UUID) ou nulo
`lugarNoPatio`	texto ou nulo
`chaveCodigo`	texto ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/patio' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/oficina/ordens/{id}/prazo#

Define (ou retira) o prazo prometido da ordem.

Permissão Oficina.Receber
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · PrazoPedido)

Campo	Tipo	Obrigatório
`prometidoParaUtc`	data e hora (ISO 8601) ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/prazo' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/oficina/ordens/{id}/diagnostico#

Regista o diagnóstico: o texto, o tempo gasto e os códigos OBD.

Permissão Oficina.Orcamentar
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · DiagnosticoPedido)

Campo	Tipo	Obrigatório
`texto`	texto	sim
`tempoMin`	número inteiro ou nulo
`codigosObd`	texto ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/diagnostico' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "texto": "texto"
}'

POST/api/oficina/ordens/{id}/inspeccao#

Regista o resultado de um ponto de inspecção, com a cor, a medição e a nota.

Permissão Oficina.Orcamentar
Idempotência aceita Idempotency-Key

Indique o pontoId do catálogo ou, para um ponto avulso, o nome e o grupo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · InspeccaoPedido)

Campo	Tipo	Obrigatório	Significado
`pontoId`	identificador (UUID) ou nulo
`nome`	texto ou nulo		O nome.
`grupo`	texto ou nulo
`cor`	texto	sim
`medicao`	número ou nulo
`unidade`	texto ou nulo
`nota`	texto ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/inspeccao' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "cor": "texto"
}'

POST/api/oficina/ordens/{id}/trabalhos#

Propõe um trabalho na ordem.

Permissão Oficina.Orcamentar
Idempotência aceita Idempotency-Key

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · TrabalhoPedido)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`notas`	texto ou nulo
`urgencia`	texto ou nulo
`operacaoId`	identificador (UUID) ou nulo
`garantiaDias`	número inteiro ou nulo
`garantiaKm`	número inteiro ou nulo
`linhas`	lista de objectos ou nulo
`linhas[].tipo`	texto	sim
`linhas[].descricao`	texto ou nulo		A descrição.
`linhas[].produtoId`	identificador (UUID) ou nulo		O artigo.
`linhas[].operacaoId`	identificador (UUID) ou nulo
`linhas[].quantidade`	número	sim	A quantidade.
`linhas[].precoUnitario`	número ou nulo		O preço de uma unidade, sem imposto.
`linhas[].descontoPct`	número	sim
`linhas[].origem`	texto ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/trabalhos' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto"
}'

POST/api/oficina/ordens/{id}/trabalhos/de-operacao#

Propõe um trabalho a partir de uma operação do catálogo.

Permissão Oficina.Orcamentar
Idempotência aceita Idempotency-Key

operacaoId; urgencia, notas e comPecas são opcionais.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · TrabalhoDeOperacaoPedido)

Campo	Tipo	Obrigatório
`operacaoId`	identificador (UUID)	sim
`urgencia`	texto ou nulo
`notas`	texto ou nulo
`comPecas`	verdadeiro/falso	sim

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/trabalhos/de-operacao' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "operacaoId": "00000000-0000-0000-0000-000000000000",
  "comPecas": false
}'

PUT/api/oficina/ordens/{id}/trabalhos/{trabalhoId}#

Altera um trabalho proposto.

Permissão Oficina.Orcamentar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`trabalhoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · TrabalhoPedido)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`notas`	texto ou nulo
`urgencia`	texto ou nulo
`operacaoId`	identificador (UUID) ou nulo
`garantiaDias`	número inteiro ou nulo
`garantiaKm`	número inteiro ou nulo
`linhas`	lista de objectos ou nulo
`linhas[].tipo`	texto	sim
`linhas[].descricao`	texto ou nulo		A descrição.
`linhas[].produtoId`	identificador (UUID) ou nulo		O artigo.
`linhas[].operacaoId`	identificador (UUID) ou nulo
`linhas[].quantidade`	número	sim	A quantidade.
`linhas[].precoUnitario`	número ou nulo		O preço de uma unidade, sem imposto.
`linhas[].descontoPct`	número	sim
`linhas[].origem`	texto ou nulo

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/oficina/ordens/<id>/trabalhos/<trabalhoId>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto"
}'

DELETE/api/oficina/ordens/{id}/trabalhos/{trabalhoId}#

Remove um trabalho proposto.

Permissão Oficina.Orcamentar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`trabalhoId`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X DELETE 'https://<endereço-da-API>/api/oficina/ordens/<id>/trabalhos/<trabalhoId>' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/oficina/ordens/{id}/orcamento#

Envia o orçamento ao cliente: uma versão nova com todos os trabalhos por aprovar.

Permissão Oficina.Orcamentar
Idempotência aceita Idempotency-Key

Com comLigacao, devolve o código da ligação pública uma única vez (só se guarda o hash). O sistema não envia o WhatsApp: o balcão abre-o com o texto e a ligação.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · EnvioPedido)

Campo	Tipo	Obrigatório
`comLigacao`	verdadeiro/falso	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/orcamento' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "comLigacao": false
}'

POST/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/decisao#

Regista a decisão do cliente sobre um trabalho, dada ao balcão, ao telefone ou presencialmente.

Permissão Oficina.AprovarNoBalcao
Idempotência aceita Idempotency-Key

decisao, canal e decididoPor são obrigatórios: a decisão fica com o nome de quem a registou e o de quem decidiu. Ao aprovar, o sistema verifica o stock das peças: se faltam, o trabalho fica à espera de peça.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`trabalhoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · DecisaoPedido)

Campo	Tipo	Obrigatório
`decisao`	texto	sim
`canal`	texto	sim
`decididoPor`	texto	sim
`nota`	texto ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/trabalhos/<trabalhoId>/decisao' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "decisao": "texto",
  "canal": "texto",
  "decididoPor": "texto"
}'

POST/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/peca-em-falta#

Marca (ou desmarca) um trabalho como à espera de peça, com a data prevista.

Permissão Oficina.Distribuir
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`trabalhoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · PecaEmFaltaPedido)

Campo	Tipo	Obrigatório
`emFalta`	verdadeiro/falso	sim
`previstaPara`	data (AAAA-MM-DD) ou nulo
`nota`	texto ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/trabalhos/<trabalhoId>/peca-em-falta' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "emFalta": false
}'

POST/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/atribuir#

Atribui um trabalho a um mecânico e/ou a um box.

Permissão Oficina.Distribuir
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`trabalhoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · AtribuicaoPedido)

Campo	Tipo	Obrigatório
`mecanicoId`	identificador (UUID) ou nulo
`boxId`	identificador (UUID) ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/trabalhos/<trabalhoId>/atribuir' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/iniciar#

Inicia a execução de um trabalho (num box, se indicado).

Permissão Oficina.Executar
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`trabalhoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · IniciarPedido)

Campo	Tipo	Obrigatório
`boxId`	identificador (UUID) ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/trabalhos/<trabalhoId>/iniciar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/pausar#

Pausa a execução de um trabalho, com motivo.

Permissão Oficina.Executar
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`trabalhoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · PausaPedido)

Campo	Tipo	Obrigatório
`motivo`	texto	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/trabalhos/<trabalhoId>/pausar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "motivo": "texto"
}'

POST/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/terminar#

Termina a execução de um trabalho.

Permissão Oficina.Executar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`trabalhoId`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/trabalhos/<trabalhoId>/terminar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/oficina/ordens/{id}/trabalhos/{trabalhoId}/linhas/{linhaId}/aplicar#

Aplica (consome do stock) uma quantidade de uma peça de um trabalho.

Permissão Oficina.Executar
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`trabalhoId`	no caminho	identificador (UUID)	sim
`linhaId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · AplicarPedido)

Campo	Tipo	Obrigatório	Significado
`quantidade`	número	sim	A quantidade.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/trabalhos/<trabalhoId>/linhas/<linhaId>/aplicar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "quantidade": 0
}'

POST/api/oficina/ordens/{id}/qualidade/aprovar#

Aprova a qualidade da ordem, com o test-drive (quilómetros) e uma nota.

Permissão Oficina.Qualidade
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · QualidadePedido)

Campo	Tipo	Obrigatório
`testDriveKm`	número inteiro ou nulo
`nota`	texto ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/qualidade/aprovar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/oficina/ordens/{id}/qualidade/reprovar#

Reprova a qualidade da ordem: os trabalhos indicados voltam à execução, com motivo.

Permissão Oficina.Qualidade
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ReprovacaoPedido)

Campo	Tipo	Obrigatório
`trabalhoIds`	lista de identificador (UUID) ou nulo
`motivo`	texto ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/qualidade/reprovar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET/api/oficina/ordens/{id}/entrega/preparacao#

O que se cobraria agora pela ordem, calculado pelo mesmo caminho que a emissão (promoções, retenções e arredondamento incluídos).

Permissão Oficina.Entregar

Quem cobra deve cobrar este valor, nunca um calculado à parte. Não emite nada. armazemId (opcional).

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`armazemId`	na pesquisa	identificador (UUID)

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/ordens/<id>/entrega/preparacao' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/oficina/ordens/{id}/entrega#

Entrega a viatura: emite um documento pelo mesmo comando do «Novo documento», grava a entrega e emite as garantias.

Permissão Oficina.Entregar
Idempotência aceita Idempotency-Key

Factura/recibo se se paga no acto, factura a crédito se não há pagamentos e o cliente a tem. entregaId identifica a entrega (repetir com o mesmo valor devolve a mesma), pagamentos, kmSaida, levantadoPor e armazemId.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · EntregaPedido)

Campo	Tipo	Obrigatório	Significado
`entregaId`	identificador (UUID)	sim
`pagamentos`	lista de objectos ou nulo
`pagamentos[].metodoPagamentoId`	identificador (UUID)	sim	O método de pagamento.
`pagamentos[].valor`	número	sim	O valor.
`kmSaida`	número inteiro ou nulo
`levantadoPor`	texto ou nulo
`armazemId`	identificador (UUID) ou nulo		O armazém de onde saiu (ou para onde voltou) o stock.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/entrega' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "entregaId": "00000000-0000-0000-0000-000000000000"
}'

POST/api/oficina/ordens/{id}/cancelar#

Cancela uma ordem, com motivo.

Permissão Oficina.Entregar
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · MotivoPedido)

Campo	Tipo	Obrigatório
`motivo`	texto	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/cancelar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "motivo": "texto"
}'

POST/api/oficina/ordens/{id}/responsabilidade#

Define a responsabilidade da garantia numa ordem aberta ao abrigo de uma garantia.

Permissão Oficina.Garantia
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ResponsabilidadePedido)

Campo	Tipo	Obrigatório
`responsabilidade`	texto	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/responsabilidade' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "responsabilidade": "texto"
}'

POST/api/oficina/garantias/{garantiaId}/reclamar#

Abre uma ordem de reparação ao abrigo de uma garantia.

Permissão Oficina.Garantia
Idempotência aceita Idempotency-Key

pedidoDoCliente, kmEntrada e combustivel são obrigatórios; responsabilidade, o lugar no pátio e o prazo prometido são opcionais.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`garantiaId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ReclamacaoPedido)

Campo	Tipo	Obrigatório
`pedidoDoCliente`	texto	sim
`kmEntrada`	número inteiro	sim
`justificacaoDoKm`	texto ou nulo
`combustivel`	texto	sim
`responsabilidade`	texto ou nulo
`zonaDePatioId`	identificador (UUID) ou nulo
`lugarNoPatio`	texto ou nulo
`prometidoParaUtc`	data e hora (ISO 8601) ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/garantias/<garantiaId>/reclamar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "pedidoDoCliente": "texto",
  "kmEntrada": 1,
  "combustivel": "texto"
}'

POST/api/oficina/ordens/{id}/fotos#

Anexa uma fotografia a uma ordem (ou a um trabalho ou inspecção).

Permissão Oficina.Ler

Envio de ficheiro (multipart/form-data): a fotografia vai no campo ficheiro e o momento é obrigatório; trabalhoId, inspeccaoId e nota são opcionais.

Um ficheiro vazio, ou que exceda o limite de tamanho, é recusado.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`momento`	na pesquisa	texto	sim
`trabalhoId`	na pesquisa	identificador (UUID)
`inspeccaoId`	na pesquisa	identificador (UUID)
`nota`	na pesquisa	texto

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/oficina/ordens/<id>/fotos' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/oficina/fotos/{id}#

Descarrega uma fotografia de uma ordem.

Permissão Oficina.Ler

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Resposta

Devolve 200 com a imagem.

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/fotos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/oficina/indicadores#

Os indicadores da oficina num período.

Permissão Oficina.IndicadoresVer

de e ate são datas obrigatórias.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`de`	na pesquisa	data (AAAA-MM-DD)	sim
`ate`	na pesquisa	data (AAAA-MM-DD)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/oficina/indicadores' \
  -H 'X-Api-Key: <a-sua-chave>'