Passo 1.5 — Configuração do módulo SAT (sat-config) - Opcional

Existe um único registo de configuração por tenant, que altera o comportamento da criação de ordens de serviço e da impressão. Vale a pena lê-lo no arranque da integração, porque um dos campos torna obrigatório um campo que de outro modo é opcional.

Ler a configuração actual:

GET /gateway/sat-config
Authorization: Bearer {token}

Resposta 200 OK:

{
  "printServiceOrder": 0,
  "printIntervention": 0,
  "printInterventionResume": 0,
  "serviceOrderLayout": "5115481f-ba42-4a44-a865-5c76ae4bd0fa",
  "interventionLayout": "7707abf6-6fab-4031-b57e-ad562b3a4806",
  "interventionResumeLayout": "9fb2b7bd-1b27-479f-8a32-b3f342e4500f",
  "allowNumerationIntervals": false,
  "interventionToScheduler": false,
  "invoiceToCustomerRelatedEntity": false,
  "isEmployeeFillObligatory": false
}

atenção

Enquanto a configuração nunca tiver sido gravada, o GET devolve 404 ServiceOrderConfiguration.NotFound. Trate esse 404 como “usar os valores por omissão” (todos os booleanos a false e os três modos de impressão a 0), que é exactamente o que a aplicação faz.

Gravar a configuração

PUT /gateway/sat-config
Content-Type: application/json
Authorization: Bearer {token}

{
  "printServiceOrder": 1,
  "printIntervention": 0,
  "printInterventionResume": 2,
  "serviceOrderLayout": "5115481f-ba42-4a44-a865-5c76ae4bd0fa",
  "interventionLayout": "7707abf6-6fab-4031-b57e-ad562b3a4806",
  "interventionResumeLayout": "9fb2b7bd-1b27-479f-8a32-b3f342e4500f",
  "allowNumerationIntervals": false,
  "interventionToScheduler": false,
  "invoiceToCustomerRelatedEntity": false,
  "isEmployeeFillObligatory": true
}

Resposta: 204 No Content. O PUT é um upsert — cria o registo se ainda não existir, pelo que funciona mesmo quando o GET devolve 404.

atenção

O PUT é substituição total, não parcial: os campos omitidos ficam com o valor por omissão do tipo (false, 0, GUID vazio). Faça sempre GET, altere o campo pretendido e reenvie o objecto completo.

O que cada campo faz

Campo	Tipo	Efeito
isEmployeeFillObligatory	booleano	Torna o responsibleUserId obrigatório na criação e na actualização da ordem de serviço. É validado no servidor, não apenas no ecrã
printServiceOrder	0 | 1 | 2	Comportamento de impressão ao gravar a ordem de serviço
printIntervention	0 | 1 | 2	Comportamento de impressão ao gravar a intervenção
printInterventionResume	0 | 1 | 2	Comportamento de impressão ao fechar a ordem de serviço
serviceOrderLayout	GUID	Layout usado na impressão da ordem de serviço
interventionLayout	GUID	Layout usado na impressão da intervenção
interventionResumeLayout	GUID	Layout usado no resumo de intervenções
allowNumerationIntervals	booleano	Guardado, ainda sem efeito
interventionToScheduler	booleano	Guardado, ainda sem efeito
invoiceToCustomerRelatedEntity	booleano	Guardado, ainda sem efeito

Valores dos modos de impressão:

Valor	Significado
0	Perguntar sempre antes de imprimir
1	Imprimir directamente, sem perguntar
2	Não imprimir

atenção

Os três modos de impressão e os GUIDs de layout são interpretados pela aplicação no momento da gravação/fecho; não têm qualquer efeito em quem integra directamente pela API. Já allowNumerationIntervals é inerte também na aplicação: a numeração das ordens é sempre o maior número da série mais um, sem reaproveitar intervalos.

Como o isEmployeeFillObligatory afecta a criação de ordens

Com a configuração activa, o responsibleUserId (colaborador responsável) passa a ser obrigatório e tem de ser maior que zero:

Falha: responsibleUserId ausente ou a zero:

POST /gateway/service-order
Content-Type: application/json
Authorization: Bearer {token}

{
  "series": 2026,
  "status": "RECEB",
  "priority": "URG",
  "assistanceTypeKeyId": "REP"
}

Resposta 400 Bad Request com ServiceOrder.ResponsibleUserRequired ("The responsible user is required.").

Correcto:

POST /gateway/service-order
Content-Type: application/json
Authorization: Bearer {token}

{
  "series": 2026,
  "status": "RECEB",
  "priority": "URG",
  "assistanceTypeKeyId": "REP",
  "responsibleUserId": 7
}

A mesma validação corre no PUT /gateway/service-order/{guid}: uma actualização que deixe cair o responsibleUserId é rejeitada com o mesmo erro.

atenção

Não confunda responsibleUserId com o autor do registo: o utilizador que cria a ordem é determinado pelo servidor a partir do token e não é aceite no payload. O responsibleUserId é o colaborador a quem a ordem fica atribuída.

Seguinte

Contratos de assistência (opcional) ou equipamento.