Sign up or Sign in with: E-mail

Ordem Serviço


Documentação Técnica da API – Integração Service Desk

Caro Cliente,

A Integração ServiceDesk permite a criação, acompanhamento e cancelamento de Ordens de Serviço (OS)
de forma automatizada, centralizada e segura.

  • Crie Ordens de Serviço diretamente do seu sistema de gestão de tickets, otimizando processos e ganhando eficiência operacional.
  • Acompanhamento: Consulte o status e o tracking das OS em tempo real.
  • Cancelamento: Gerencie o cancelamento de Ordens de Serviço de forma integrada.
  • Segurança: Garantia de autenticidade e segurança no tráfego de dados.

Ao longo desta documentação, você encontrará todas as informações necessárias para integrar e consumir nossas APIs.

Autenticação

A autenticação é feita por meio de uma Chave de Autenticação fornecida pela Simpress.
Essa chave deve ser incluída nas requisições conforme especificado em cada endpoint.

Considerações Técnicas

  • • Todos os endpoints utilizam o padrão REST.
  • • As respostas seguem o formato JSON.
  • • A autenticação é obrigatória em todos os endpoints.
  • • O serviço de criação é assíncrono, sendo necessário consultar o status posteriormente.

Resumo das Respostas de Erro HTTP
Os códigos de erro HTTP são divididos em categorias, e os mais comuns para APIs estão
na faixa 4xx (erros do cliente) e 5xx(erros do servidor):


Erros 4xx – Problemas na Requisição do Cliente

  Código   Significado   Quando ocorre?
400 Bad Request A requisição está malformada ou contém dados inválidos.
Exemplo: campos obrigatórios ausentes.
401 Unauthorized A autenticação falhou.
Exemplo: chave de API inválida ou expirada.
403 Forbidden O cliente está autenticado, mas não possui permissão para acessar o recurso.
404 Not Found O recurso solicitado não foi encontrado.
Exemplo: identificador inexistente.
422 Unprocessable Entity A requisição está correta, porém os dados não podem ser processados.
Exemplo: conflito de regras de negócio.

Erros 5xx – Problemas no Servidor

Código Significado Quando ocorre?
500 Internal Server Error Erro genérico no servidor.
Exemplo: falha inesperada no processamento.
502 Bad Gateway O servidor recebeu uma resposta inválida de outro servidor.
503 Service Unavailable O serviço está temporariamente indisponível.
Exemplo: manutenção ou sobrecarga.

Endpoints

  1. Criação de Ordem de Serviço
    Objetivo:
    Solicitar a abertura de uma Ordem de Serviço utilizando diversos dados que
    devem ser informados na requisição.
    Endpoint:
    /V2/OrdensDeServico
    Método:

    POST

    Descrição:
    Cria uma ordem de serviço de forma assíncrona,
    sendo necessário consultar o status posteriormente.

Entrada para Solicitação de Serviço:

  Campo   Descrição   Obrigatório   Tamanho Máximo
NumeroSerie ou Alias Número de série ou apelido do equipamento para o qual se solicita o serviço. Sim 100
CodigoTipoDefeito Código do tipo de defeito ocorrido, conforme lista de Tipos de Defeitos. Sim n/a
CodigoServicoCliente Código de serviço do sistema de origem. Não 100
CodigoSituacaoEquipamento Código da situação do equipamento, conforme lista de códigos permitidos. Sim n/a
ChaveAutenticacao Sequência única de caracteres fornecida pela Simpress. Sim n/a
Observacao Campo de texto livre para observações sobre a abertura da Ordem de Serviço. Não 500
Nome Nome do responsável pela solicitação. Sim 100
Email E-mail do responsável pela solicitação. Sim 100
DDD Código de área do telefone (somente números). Sim 2
Telefone Número do telefone (somente números). Sim 9
Departamento Nome do departamento do responsável pela solicitação. Sim 100
DadosAdicional1 Informação adicional para referência do cliente (presente nos retornos). Não 100
DadosAdicional2 Informação adicional para referência do cliente. Não 100
cdContrato Contrato disponibilizado pela Simpress. Sim n/a
DadosAdicional3 Informação adicional para referência do cliente (presente nos retornos). Não 100
DadosAdicional4 Informação adicional para referência do cliente (presente nos retornos). Não 100

Exemplo:


{
"NumeroSerie": "string",
"Alias": "string",
"CodigoTipoDefeito": 0,
"CodigoSituacaoEquipamento": 0,
"ChaveAutenticacao": "string",
"ServicoCliente": "string",
"Responsavel": {
"Nome": "string",
"Email": "string",
"DDD": "string",
"Telefone": "string",
"Departamento": "string",
"Observacao": "string"
},
"DadoAdicional": {
"DadoAdicional1": "string",
"DadoAdicional2": "string",
"DadoAdicional3": "string",
"DadoAdicional4": "string"
},
"Observacao": "string",
"CodigoServico": 0,
"CodigoServicoCliente": "string",
"CodigoOcorrencia": 0,
"CodigoCliente": 0
}

Resposta:

{
"idServico": 2,
"Retorno": "serviço adicionado na fila de execução com sucesso."
}

Código HTTP
201 Created
2.Consulta de Status da Ordem de Serviço
Endpoint:
/V2/OrdensDeServico/Status/{CodigoCliente}/{idServico}/{chave}
Método:
GET
Descrição:
Consulta o status de processamento da ordem de serviço criada.
Parâmetros de URL:
Contrato:
Código fornecido pela Simpress.
idServico:
ID retornado na criação da ordem.
chave:
Chave de autenticação.

Resposta:

{
"idServico": 2,
"Observacao": "Não é possível abrir uma ordem de serviço.",
"StatusProcessamento": "Erro",
"cdServico": null
}

Status Possíveis da Ordem de Serviço:

Status Descrição
PendenteDeProcessamento A requisição foi recebida pela Simpress, mas ainda não foi processada.
Processado A requisição foi processada com sucesso e a ordem de serviço foi gerada. Neste caso, o código da ordem é retornado.
Erro Ocorreu uma falha no processamento. A resposta incluirá o motivo do erro.
3. Consulta Ordem de Serviço por ID
Endpoint:
/V2/OrdensDeServico/{CodigoCliente}/{idServico}/{chave}
Método:
GET
Descrição:
Retorna os dados completos da ordem de serviço com base no identificador gerado no momento da criação.

Parâmetros de URL:

Parâmetro Descrição
cdContrato Código do contrato fornecido pela Simpress.
idServico Identificador da ordem de serviço (retornado na criação)
chave Chave de autenticação fornecida pela Simpress.

Observações

  • • A ordem de serviço deve ter sido previamente criada com sucesso.
  • • A chave de autenticação deve estar válida no momento da requisição.

4. Consulta por Contrato

Endpoint:

/V2/OrdensDeServico/Contrato/{cdContrato}/{chave}

Método:

GET

Descrição:

Retorna os últimos 15 atendimentos vinculados ao contrato informado.

Parâmetros de URL:

Parâmetro Descrição
cdContrato Código do contrato fornecido pela Simpress.
chave Chave de autenticação fornecida pela Simpress

Observações:

  • • A resposta contém os dados das últimas 15 ordens de serviço associadas ao contrato.
  • • É necessário fornecer uma chave válida para autenticação.

5. Consulta por Número de Série

Endpoint:

/V2/OrdensDeServico/Equipamento/{cdContrato}/{numeroserie}/{chave}

Método:

GET

Descrição:

Retorna as ordens de serviço associadas a um equipamento específico.

Parâmetros de URL

Parâmetro Descrição
cdContrato Código do contrato fornecido pela Simpress
numeroserie Número de série do equipamento
chave Chave de autenticação fornecida pela Simpress

Observações:

  • • Ideal para localizar o histórico de atendimentos de um equipamento específico.
  • • A resposta pode conter múltiplas ordens de serviço, dependendo do histórico do equipamento.

Documentação – Situação do Equipamento e Tipos de Defeitos

Situação do Equipamento

A situação do equipamento pode ser utilizada como referência para classificação do atendimento
e status operacional do equipamento.

Tabela de Referência – Situação do Equipamento

Código Descrição
1 Equipamento inoperante
2 Impressão inoperante
3 Copiadora inoperante
4 Equipamento normal
5 Funcionamento precário
6 Acessório inoperante

Tipos de Defeitos

Os tipos de defeitos podem ser utilizados de duas formas:

  • Fixa: utilizando diretamente a tabela de referência disponibilizada neste documento.
  • Dinâmica via API: realizando a consulta do endpoint de diagnósticos, informando o número de série do equipamento.

Tabela de Referência – Tipos de Defeitos

Código Descrição
6 Atolamento / Encravamento / Não reconhece papel
22 Cópia / Impressão cortada / Falhada / Riscada
23 Cópia / Impressão clara
27 Não inicializa / Não liga
38 Auditoria do parque
63 Kit de manutenção
94 Peça quebrada / Solta
96 Unidade fotocondutora
100 Vazamento de toner
101 Auditoria de contador
102 Indica falta de toner
148 Auditoria de consumo
259 Ruído excessivo
262 Configuração de driver de impressão
494 Código de erro no equipamento
540 Unidade de revelação
551 Atualização de firmware (FSA)
553 Captura / Digitalização com problema
554 Cópia / Impressão escuras
568 Acessório com falha
569 Não fixa toner no papel
570 Aquecimento excessivo
571 Encravamento / Não reconhece papel
572 Substituição do reservatório de toner usado
573 Configuração de função de cópia
574 Configuração de scanner
575 Configuração de fax
576 Dúvidas sobre contador do equipamento
577 Dúvidas sobre liberação por crachá / senha
578 Dúvidas / Configuração de bilhetagem
579 Erro na liberação por crachá / senha
580 Dúvidas sobre especificações do equipamento
581 Não digitaliza / Não envia fax
587 Garantia B2C
590 CPMI – Corretivo
592 Nova unidade de imagem
593 CPMI – Preventivo

API – Tipos de Defeitos

Método responsável por retornar os tipos de defeitos disponíveis para o equipamento selecionado. Para a consulta, é necessário informar o número de série do equipamento.

Endpoint


GET


{EndereçoBase}/v1/Equipamentos/Diagnosticos/{numeroSerie}

Entrada

Campo Descrição Obrigatório
{numeroSerie} Número de série do equipamento Sim

Saída

Campo Tipo Descrição
codigo Inteiro Código do tipo de defeito
descricao String Descrição do defeito

Exemplo de Retorno 


[
  {
    "codigo": 6,
    "descricao": "Atolamento / Encravamento / Não reconhece papel"
  },
  {
    "codigo": 22,
    "descricao": "Cópia / Impressão cortada / Falhada / Riscada"
  },
  {
    "codigo": 494,
    "descricao": "Código de erro no equipamento"
  }
]
Português, Brasil