APIs Field Services
API Agendamento
Descrição
A API Agendamento (Appointment) fornece um mecanismo padronizado para gerenciamento de visitas técnicas. Permite pesquisar intervalos de tempo livres (slots) para criar um agendamento, que poderá ser consultado, confirmado, remarcado ou excluído.
O tempo entre a pesquisa do tempo livre (Slots disponível) e a confirmação do agendamento, não pode ser superior a 4 minutos, após esse limite de 4 minutos, caso não ocorra a confirmação do agendamento, o Slot consultado será disponibilizado para novo agendamento.
A especificação, a seguir, inclui a definição dos recursos, bem como todas as operações disponíveis. No swagger público, é possível acessar o detalhamento das estruturas de dados e exemplos de utilização da API.
Com a utilização da versão 2.0 do API de Appointment será possível utilizar as novas funcionalidades de priorização de atividade de campo ( Instalação de BL ou Chamado Técnico), agendamento para remanejamento de ponto e para instalação devido a mudança de endereço, além das funcionalidades já existentes.
Adicionalmente, para o agendamento de orderType = 'Instalação' para clientes de Banda Larga junto com o produto Mesh ou FTTR (Fiber to the Room), deverão ser selecionados dois productType: um para o produto 'Banda Larga' e outro para 'Mesh' ou 'FTTR', com o número correto de pontos. Isso ocorre devido aos slots serem calculados com tempos de execução diferentes.
No caso de agendamento de orderType = 'Chamado Técnico' para reclamações de clientes que possuem Mesh ou FTTR (Fiber to the Room), deverá ser informado apenas um productType, referente ao produto Mesh ou FTTR existente no cliente, com o número correto de pontos.
Além disso, para o agendamento de orderType = 'Retirada' para clientes que possuem Banda Larga com Mesh ou FTTR, todos os productType existentes no cliente deverão ser selecionados, ou seja, o produto 'Banda Larga' e o produto 'Mesh' ou 'FTTR', com o número correto de pontos.
Premissas
Esta API somente poderá ser utilizada por clientes V.tal com contratos FTTH. Para os contratos FTTP, toda a parte de agendamento e força de campo, deverá ser feita pelo cliente V.tal.
Recursos
A API Agendamento possui os seguintes recursos disponíveis:
| RECURSO | DESCRIÇÃO |
|---|---|
| SEARCH TIME SLOT | Este recurso é usado para recuperar os intervalos de tempo disponíveis. Um desses horários é usado para criar ou remarcar um agendamento de visita técnica. |
| APPOINTMENT | Agendamento é uma marcação para realização de uma visita técnica em uma data e hora específica. Neste recurso são realizadas as operações referentes aos agendamentos. |
| APPOINTMENT CONFIRMATION | Neste recurso são realizadas operações referentes à confirmação de um agendamento de visita técnica. |
Operações
A API Agendamento possui as seguintes operações disponíveis:
| RECURSO | OPERAÇÃO | FUNCIONALIDADE |
|---|---|---|
| SEARCH TIME SLOT | RETRIEVE SEARCH TIME SLOT | Consulta de slot (janela de horário disponível) para um agendamento ou reagendamento. |
| APPOINTMENT | CREATE APPOINTMENT | Esta operação é responsável por criar no novo agendamento. |
| APPOINTMENT | LIST APPOINTMENT | Esta operação é responsável por consultar o histórico de agendamentos de um pedido. |
| APPOINTMENT | RETRIEVE APPOINTMENT | Esta operação é responsável por recuperar os dados de um agendamento específico. |
| APPOINTMENT | PATCH APPOINTMENT | Esta operação é responsável por atualizar dados do agendamento. |
| APPOINTMENT | DELETE APPOINTMENT | Esta operação é responsável por fazer a exclusão de um agendamento. |
| APPOINTMENT CONFIRMATION | APPOINTMENT CONFIRMATION | Esta operação é responsável por fazer a confirmação de um agendamento. |
Segue uma ilustração das estruturas listadas acima.
Nota:
A reserva de Slot realizada pela atendente (tenant) possui validade de 12h, ou seja, após a realização de um agendamento a ordem de serviço deverá ser aberta em até 12h, pois caso contrário a reserva será cancelada e será necessário realizar um novo agendamento.Notificações
Esta API não possui eventos de notificação.
URI base
https://{host}/api/appointment/v1/
https://{host}/api/appointment/v2/
- O nome das APIs e seus campos devem obedecer ao padrão lowerCamelCase.
- O nome das APIs serão case sensitive.