# Alterações no formato da API - 15200

Este documento descreve as diferenças entre os formatos antigo e novo da API para solicitações, módulos personalizados, associações personalizadas e relacionamentos de CI.

O novo formato da API será aplicável para clientes que atualizaram para a build **15200** do ServiceDesk Plus. Recomendamos usar os novos formatos para todas as novas integrações.

[Alterações no formato da API de solicitações](#alterações-no-formato-da-api-de-solicitações)

## Principais alterações no formato da API

- Os campos contêiner de UDF, como *cm_fields* e *udf_fields*, foram removidos das APIs de módulo personalizado, associação personalizada e relacionamento de CI.
- A compatibilidade retroativa é suportada para as APIs de módulo personalizado e relacionamento de CI.
- As convenções de nomenclatura para campos adicionais foram padronizadas:
  - **Módulos padrão**:
    - Esta atualização se aplica aos seguintes módulos: Usuário, Técnico, CMDB, Release, Projeto, Registro de trabalho, Tarefa, Espaço, Instalação, Fornecedor, Associação de tipo de CI, Ativo, Grupos de suporte e Departamento.
    - Os nomes dos campos da API agora seguem o formato *udf_<entrada do usuário>*.

| Formato antigo | Novo formato |
|---|---|
| *udf_<tipo_do_campo>_<entrada_do_usuário>* (Exemplo: udf_date_date_of_birth)<br>ou,<br>*<tipo_do_campo>_<entrada_do_usuário>* (Exemplo: date_date_of_birth) | *udf_<entrada do usuário>* (Exemplo: udf_date_of_birth) |

- **Módulos personalizados e associações personalizadas**:
  - Os nomes dos campos da API agora são totalmente definidos pelo usuário e não incluem o prefixo *udf_*. (Exemplo: date_of_birth). Esta atualização se aplica apenas aos campos criados após a migração.
  - Os campos criados antes da migração permanecerão inalterados e manterão seu comportamento atual.

## API de módulo personalizado

| Método | URL | Formato antigo | Novo formato |
|---|---|---|---|
| POST / PUT | /api/v3/cm_test<br>/api/v3/cm_test/<ID> | ```json
input_data
{
  "cm_test": {
    "title": "test",
    "description": "desc",
    "cm_fields": {
      "sline_test": "sample",
      "per_percentage": "10"
    }
  }
}
``` | ```json
input_data
{
  "cm_test": {
    "title": "test",
    "description": "desc",
    "test": "sample",
    "percentage": "10"
  }
}
``` |
| GET | /api/v3/cm_test/<ID> | ```json
{
  "response_status": {
    "status_code": 2000,
    "status": "success"
  },
  "cm_test": {
    "created_time": {
      "display_value": "25/08/2025 05:32 PM",
      "value": "<id>"
    },
    "updated_time": {
      "display_value": "25/08/2025 05:32 PM",
      "value": "<id>"
    },
    "cm_fields": {
      "sline_test": "test",
      "per_percentage": "10.00"
    },
    "is_trashed": false,
    "description": null,
    "id": "602",
    "title": "test"
  }
}
``` | ```json
{
  "response_status": {
    "status_code": 2000,
    "status": "success"
  },
  "cm_test": {
    "created_time": {
      "display_value": "25/08/2025 05:32 PM",
      "value": "<id>"
    },
    "updated_time": {
      "display_value": "25/08/2025 05:32 PM",
      "value": "<id>"
    },
    "test": "test",
    "percentage": "10.00",
    "is_trashed": false,
    "description": null,
    "id": "602",
    "title": "test"
  }
}
``` |

## API de relacionamento de CI

| Método | URL | Formato antigo | Novo formato |
|---|---|---|---|
| POST | /api/v3/cmdb_apache_instance/1/assoc_apache_connected_to_windows_workstations | ```json
{
  "assoc_apache_connected_to_windows_workstations": [
    {
      "destination": { "id": "2" },
      "udf_fields": {
        "udf_source_no": "001",
        "udf_technician": { "id": "5" }
      }
    }
  ]
}
``` | ```json
{
  "assoc_apache_connected_to_windows_workstations": [
    {
      "destination": { "id": "2" },
      "udf_source_no": "001",
      "udf_technician": { "id": "5" }
    }
  ]
}
``` |

## Alterações de compatibilidade retroativa

O suporte à compatibilidade retroativa será descontinuado a partir da próxima versão de funcionalidade. Recomendamos atualizar para o novo formato da API e ajustar o **GlobalConfig** adequadamente.

Durante a migração, os nomes de API dos módulos personalizados existentes ("web_tab", "configuration", "hidden", "association", and "published") e os relacionamentos de CI são definidos para o atributo *paramvalue* em **GlobalConfig**.

```xml
<GlobalConfig helpdeskid="IT Helpdesk"
  category="CM_BACKWARD_COMPATIBILITY"
  parameter="CM_MODULES_LIST"
  paramvalue="<entity_api_name>"
  description="Para oferecer suporte à compatibilidade retroativa para módulos personalizados antigos"/>
```

Uma mensagem de aviso será exibida durante a migração, como mostrado:

![](https://www.manageengine.com/userfiles/866/14262/ckfinder/images/qu/2025/2025_11_07_09_38_291.png)

Após a migração, uma mensagem de aviso será exibida na página de detalhes dos módulos personalizados e relacionamentos de CI para os quais a compatibilidade retroativa for fornecida.

*Módulos personalizados*

![](https://www.manageengine.com/userfiles/866/14262/ckfinder/images/qu/2025/2025_11_07_09_39_542.png)

**Relacionamentos de CI**

![](https://www.manageengine.com/userfiles/866/14262/ckfinder/images/qu/2025/2025_11_07_09_40_353.png)

Scripts Python, funções personalizadas, widgets personalizados, regras de campo e formulário, scripts personalizados e todo acesso externo à API continuarão seguindo o formato antigo até que a compatibilidade retroativa seja removida por meio da remoção do nome da API do módulo do GlobalConfig.

Somente as APIs acionadas a partir da interface do ServiceDesk Plus seguirão o novo formato.

## Gerenciando a compatibilidade retroativa

Para adicionar ou remover módulos do suporte à compatibilidade retroativa, use a seguinte consulta:

```sql
update globalconfig
set paramvalue = '<entity_api_name>'
where category = 'CM_BACKWARD_COMPATIBILITY';
```

# Alterações no formato da API de solicitações

Este documento descreve as diferenças entre os formatos antigo e novo da API para campos obrigatórios, transições, estados conectados, níveis de aprovação, checklists e APIs de horário operacional.

O novo formato da API será aplicável para clientes que atualizaram para a build 15200.

## Melhorias no fluxo de trabalho

### API de campos obrigatórios

|  | Formato antigo | Novo formato |
|---|---|---|
| **URL** | api/v3/requests/status_mandatory_fields<br>api/v3/requests/id/status_mandatory_fields | api/v3/requests/get_mandatory_fields<br>api/v3/requests/id/get_mandatory_fields |
| **Dados de entrada** | `{"template_id":5,"status_id":2}` | `{"template_id":"1","state_id":"2"}` |
| **Resposta** | `status_mandatory_fields` | `mandatory_fields` |

**Observação**: Os campos checklists, tasks e depends_on_requests aparecem na resposta somente quando são marcados como obrigatórios.

### API de obtenção de transições

|  | Formato antigo | Novo formato |
|---|---|---|
| **URL** | api/v3/requests/id/_get_transitions | api/v3/requests/id/_get_transitions |
| **Resposta** | `"transitions": [...]` | `"transitions": [...]` |

### API de obtenção de status conectados

|  | Formato antigo | Novo formato |
|---|---|---|
| **URL** | api/v3/requests/id/_get_connected_statuses | api/v3/requests/id/_get_connected_states |
| **Dados de entrada** | `"status_id"` | `"state_id"` |
| **Resposta** | `"statuses": [...]` | `"status": [...]` |

### API de obtenção de nós conectados

|  | Formato antigo | Novo formato |
|---|---|---|
| **URL** | api/v3/request_lifecycles/<lifecycleid>/get_connected_nodes | /api/v3/request_workflows/<workflowid>/get_connected_nodes |
| **Dados de entrada** | `{"node_entity_id":0,"module":{"name":"request"}}` | `{"state_id":0,"module":{"name":"request"}}` |

## Resposta de nível de aprovação

O campo `rule.value` na resposta do nível de aprovação da solicitação usa os valores atualizados conforme mostrado abaixo:

| Valor antigo | Novo valor |
|---|---|
| anyone | anyone_approves |
| all | everyone_approves |
| first_response | first_response_action |

## API de horário operacional

### Principais diferenças no nível da entidade

| Chave antiga | Nova chave | Observações |
|---|---|---|
| site | associated_sites | Os detalhes do site foram alterados para o formato de array. |
| days_of_operation | days |  |
| hours_of_operation | hours |  |
| site_type | (removido) | O tipo de site é selecionado com base no valor de horário global. |
| day_type | (removido) | O tipo de dia é selecionado com base na chave is_standard. |
| exclude_weeks | exception_rules | exclude_weeks foi removido do objeto day e uma nova chave foi colocada externamente. |

## Melhorias em checklists

### Principais diferenças

Consulte a tabela abaixo para uma comparação rápida das principais alterações introduzidas com as atualizações da API.

### Alterações no formato de entrada da API de checklist

| API | URL da API (ANTIGA) | URL da API (NOVA) | FORMATO DE ENTRADA ANTIGO | FORMATO DE ENTRADA NOVO |
|---|---|---|---|---|
| **Adicionar (campo de opção)** | /api/v3/additional_fields | /api/v3/item_details | ... | ... |