Documentação Técnica - API REST de Ordens
de Serviço
Visão Geral
Esta API REST fornece endpoints para gerenciamento completo de Ordens
de Serviço, permitindo operações de criação, consulta, atualização, exclusão e
finalização de OS. A API foi implementada utilizando o framework TOTVS
Protheus.
Base URL
/WSSERVIC
Endpoints
1. Listar Ordens de Serviço
Retorna uma lista paginada de todas as Ordens de Serviço.
Método: GET
Endpoint: /WSSERVIC/list/{page}/{pageSize}
Parâmetros de URL: - page (inteiro, opcional) - Número da página, padrão:
1 - pageSize (inteiro, opcional) - Quantidade de registros por página, padrão:
50, máximo: 100
Resposta de Sucesso:
{
"page": 1,
"pageSize": 50,
"total": 100,
"totalPages": 2,
"ordens": [
{
"numero": "000001",
"cliente": "000001",
"loja": "01",
"nome": "CLIENTE TESTE",
"emissao": "28/01/2024",
"status": "A",
"situacao": "1",
"atendente": "000001"
}
]
}
1
2. Criar Ordem de Serviço
Cria uma nova Ordem de Serviço.
Método: POST
Endpoint: /WSSERVIC
Corpo da Requisição:
{
"cliente": "000001",
"loja": "01",
"emissao": "28/01/2024",
"atendente": "000001",
"contato": "CONTATO TESTE",
"situacao": "1",
"observacao": "Observação teste",
"dtprev": "29/01/2024",
"hrprev": "14:00",
"codprob": "001",
"itens": [
{
"tipo": "1",
"produto": "000001",
"quantidade": 1
}
]
}
Campos Obrigatórios: - cliente - loja
Resposta de Sucesso:
{
"status": "sucesso",
"mensagem": "Ordem de Serviço criada com sucesso",
"numero": "000001"
}
3. Consultar Ordem de Serviço
Retorna os detalhes de uma Ordem de Serviço específica.
Método: GET
Endpoint: /WSSERVIC/{numero}
Parâmetros de URL: - numero (string) - Número da OS
Resposta de Sucesso:
2
{
"numero": "000001",
"cliente": "000001",
"loja": "01",
"nome": "CLIENTE TESTE",
"emissao": "28/01/2024",
"hora": "14:30",
"status": "A",
"situacao": "1",
"observacao": "Observação teste",
"atendente": "000001",
"contato": "CONTATO TESTE",
"dtprev": "29/01/2024",
"hrprev": "14:00",
"dtenc": "",
"hrenc": "",
"codprob": "001",
"solucao": "",
"causa": "",
"itens": [
{
"item": "01",
"tipo": "1",
"produto": "000001",
"quantidade": 1,
"qtdexecutada": 0,
"tempogasto": ""
}
]
}
4. Atualizar Ordem de Serviço
Atualiza os dados de uma Ordem de Serviço existente.
Método: PUT
Endpoint: /WSSERVIC/{numero}
Parâmetros de URL: - numero (string) - Número da OS
Corpo da Requisição:
{
"atendente": "000001",
"contato": "NOVO CONTATO",
"situacao": "2",
"observacao": "Nova observação",
"dtprev": "30/01/2024",
3
"hrprev": "16:00",
"itens": [
{
"tipo": "1",
"produto": "000001",
"quantidade": 2
}
]
}
Resposta de Sucesso:
{
"status": "sucesso",
"mensagem": "Ordem de Serviço atualizada com sucesso"
}
5. Excluir Ordem de Serviço
Exclui uma Ordem de Serviço existente.
Método: DELETE
Endpoint: /WSSERVIC/{numero}
Parâmetros de URL: - numero (string) - Número da OS
Resposta de Sucesso:
{
"status": "sucesso",
"mensagem": "Ordem de Serviço excluída com sucesso"
}
6. Finalizar Ordem de Serviço
Finaliza uma Ordem de Serviço, registrando informações de conclusão.
Método: POST
Endpoint: /WSSERVIC/finalize/{numero}
Parâmetros de URL: - numero (string) - Número da OS
Corpo da Requisição:
{
"observacao": "Serviço concluído",
"solucao": "001",
"causa": "001",
"itens": [
{
"item": "01",
4
"qtdexecutada": 1,
"tempogasto": "02:00"
}
]
}
Resposta de Sucesso:
{
"status": "sucesso",
"mensagem": "Ordem de Serviço finalizada com sucesso"
}
Códigos de Status
• 200: Requisição bem-sucedida
• 400: Erro de validação ou nos dados enviados
• 404: Ordem de Serviço não encontrada
Restrições e Validações
1. Não é possível modificar uma OS finalizada (status “E”)
2. Não é possível excluir uma OS finalizada
3. Não é possível finalizar uma OS já finalizada
4. O tamanho da página na listagem deve estar entre 1 e 100
5. O número da página deve ser maior que zero
6. Cliente e loja são campos obrigatórios na criação
Observações Técnicas
• A API utiliza o padrão REST para comunicação
• As respostas são sempre no formato JSON
• A autenticação é gerenciada pelo framework Protheus
• As operações são executadas através do ExecAuto TECA450
• Todas as operações são executadas dentro de uma transação
• Os erros do ExecAuto são capturados e retornados na resposta
Tabelas do Banco de Dados
• AB6: Cabeçalho da Ordem de Serviço
• AB7: Itens da Ordem de Serviço
• SA1: Cadastro de Clientes
Status das Ordens de Serviço
• A: Aberta
• E: Encerrada/Finalizada