Visitas agendadas
Listar
GET /api/v1/scheduled_visits
Filtros
Os parâmetros abaixo podem ser passados como uma query string. Datas devem ser passadas no formato yyyy-mm-dd.
Este serviço suporta paginação.
start_date: filtra visitas agendadas a partir da data informada.
end_date: filtra visitas agendadas até a data informada.
Retorno
É retornado um JSON contendo um array. Cada elemento do array contém os seguintes campos:
id: o id da visita agendada
creator_id: o id do usuário que criou a visita
created_at: a data de criação da visita agendada, no formato ISO 8601
updated_at: a data de atualização da visita agendada, no formato ISO 8601
date: a data para a qual a visita foi agendada, no formato yyyy-mm-dd
completed_at: a data em que a visita foi liberada para o VMpay Visitor
vacant_amounts_required: se a visita exige preenchimento de espaços vazios
ignore_categorization_visitor: se a visita permite retornar produtos fora da categorização da agenda
supply_category_id: o id da categoria de abastecimento da visita
checkpoints: lista dos checkpoints da visita; cada elemento contém:
id: o id do checkpoint
installation_id: o id da instalação
pick_list_scheduled: se deve agendar a geração da pick list
pick_list_scheduled_at: data de agendamento da geração de pick list, no formato ISO 8601
pick_list_generated: se o pick list já foi gerado ou não
restock: se deve efetuar reabastecimento na visita
cash_collect: se deve efetuar coleta na visita
only_visit: se não é necessário reabastecimento ou coleta na visita
pending_inventory_adjustment: se o ajuste de inventário está pendente
finished: se está finalizado
finished_at: a data em que o checkpoint foi finalizado
scheduled_visit_routes: lista das rotas da visita; cada elemento contém:
id: o id da rota da visita
route_id: o id da rota
Exemplo:
[
{
"id": 13080,
"creator_id": 84,
"created_at": "2017-11-23T10:30:50.000000Z",
"updated_at": "2017-11-23T10:50:00.000000Z",
"date": "2017-11-24",
"completed_at": null,
"vacant_amounts_required": true,
"ignore_categorization_visitor": true,
"supply_category_id": 1,
"checkpoints": [
{
"id": 84652,
"installation_id": 1982,
"pick_list_scheduled": false,
"pick_list_scheduled_at": null,
"pick_list_generated": false,
"restock": false,
"cash_collect": false,
"only_visit": true,
"pending_inventory_adjustment": false,
"finished": true,
"finished_at": "2016-12-21T16:39:20.000Z"
},
{
"id": 84640,
"installation_id": 7687,
"pick_list_scheduled": true,
"pick_list_scheduled_at": "2017-11-24T12:00:00.000Z",
"pick_list_generated": true,
"restock": true,
"cash_collect": false,
"only_visit": false,
"pending_inventory_adjustment": true,
"finished": true,
"finished_at": "2016-12-21T14:39:20.000Z"
}
],
"scheduled_visit_routes": [
{
"id": 16707,
"route_id": 377
}
]
},
{
"id": 13074,
"created_at": "2017-11-14T15:33:18.000000Z",
"updated_at": "2017-11-16T18:14:21.000000Z",
"date": "2017-12-17",
"completed_at": "2017-11-14T15:56:25.000000Z",
"vacant_amounts_required": true,
"ignore_categorization_visitor": false,
"supply_category_id": 1,
"checkpoints": [
{
"id": 84638,
"installation_id": 7690,
"pick_list_scheduled": false,
"pick_list_scheduled_at": null,
"pick_list_generated": false,
"restock": false,
"cash_collect": true,
"only_visit": false,
"pending_inventory_adjustment": false,
"finished": true,
"finished_at": "2016-12-21T16:39:20.000Z"
},
{
"id": 84639,
"installation_id": 7688,
"pick_list_scheduled": false,
"pick_list_scheduled_at": null,
"pick_list_generated": false,
"restock": true,
"cash_collect": true,
"only_visit": false,
"pending_inventory_adjustment": true,
"finished": true,
"finished_at": "2016-12-21T18:39:20.000Z"
}
],
"scheduled_visit_routes": [
{
"id": 16707,
"route_id": 377
}
]
},
{
"id": 13062,
"created_at": "2017-11-12T15:33:18.000000Z",
"updated_at": "2017-11-14T18:14:21.000000Z",
"date": "2017-12-15",
"completed_at": "2017-11-12T15:56:25.000000Z",
"vacant_amounts_required": true,
"ignore_categorization_visitor": true,
"supply_category_id": 1,
"checkpoints": [
{
"id": 84638,
"installation_id": 7690,
"pick_list_scheduled": false,
"pick_list_scheduled_at": null,
"pick_list_generated": false,
"restock": false,
"cash_collect": false,
"only_visit": true,
"pending_inventory_adjustment": false,
"finished": true,
"finished_at": "2016-12-21T16:39:20.000Z"
},
{
"id": 84639,
"installation_id": 7688,
"pick_list_scheduled": false,
"pick_list_scheduled_at": null,
"pick_list_generated": false,
"restock": false,
"cash_collect": false,
"only_visit": true,
"pending_inventory_adjustment": true,
"finished": true,
"finished_at": "2016-12-21T18:39:20.000Z"
}
],
"scheduled_visit_routes": [
{
"id": 16707,
"route_id": 377
}
]
}
]
Ver
GET /api/v1/scheduled_visits/[id]
Parâmetros de URL:
parâmetro |
descrição |
obrigatório |
|---|---|---|
id |
id da visita |
sim |
Retorno
status |
descrição |
|---|---|
200 |
OK |
Exemplo:
{
"id": 13074,
"creator_id": 84,
"created_at": "2017-11-14T15:33:18.000000Z",
"updated_at": "2017-11-16T18:14:21.000000Z",
"date": "2017-12-17",
"completed_at": "2017-11-14T15:56:25.000000Z",
"vacant_amounts_required": true,
"ignore_categorization_visitor": true,
"supply_category_id": 1,
"checkpoints": [
{
"id": 84638,
"installation_id": 7690,
"pick_list_scheduled": false,
"pick_list_scheduled_at": null,
"pick_list_generated": false,
"restock": false,
"cash_collect": true,
"only_visit": false,
"pending_inventory_adjustment": true,
"finished": true,
"finished_at": "2017-11-16T12:14:21.000Z"
},
{
"id": 84639,
"installation_id": 7688,
"pick_list_scheduled": false,
"pick_list_scheduled_at": null,
"pick_list_generated": false,
"restock": true,
"cash_collect": true,
"only_visit": false,
"pending_inventory_adjustment": false,
"finished": true,
"finished_at": "2017-11-17T14:14:21.000Z"
},
{
"id": 84640,
"installation_id": 7687,
"pick_list_scheduled": true,
"pick_list_scheduled_at": "2018-12-19T12:00:00.000Z",
"pick_list_generated": false,
"restock": false,
"cash_collect": false,
"only_visit": true,
"pending_inventory_adjustment": false,
"finished": false,
"finished_at": null
}
],
"scheduled_visit_routes": [
{
"id": 16707,
"route_id": 377
}
]
}
Erros
status |
descrição |
response body |
|---|---|---|
404 |
visita não encontrada |
{ “error”: “Registro não encontrado” } |
Criar
POST /api/v1/scheduled_visits
Request:
{
"scheduled_visit": {
"vacant_amounts_required": true,
"ignore_categorization_visitor": true,
"creator_id": 84,
"date": "2017-12-18",
"supply_category_id": 1,
"scheduled_visit_routes_attributes": [{
"route_id": 299
}],
"checkpoints_attributes": [{
"installation_id": 7687,
"restock": true,
"cash_collect": false,
"pick_list_scheduled": true,
"pick_list_scheduled_hour": 10,
"pick_list_scheduled_minutes": 15
}, {
"installation_id": 7690,
"restock": false,
"cash_collect": true
}, {
"installation_id": 7688,
"restock": true,
"cash_collect": true
}, {
"installation_id": 7687,
"only_visit": true
}]
}
}
Campos
Obrigatórios
scheduled_visit
date: Data do agendamento.
supply_category_id: id da categoria de reabastecimento (Caso utilize mais de uma categoria de abastecimento, esse campo é obrigatório)
Opcionais
scheduled_visit
vacant_amounts_required: Se exige preenchimento de espaços vazios.
Valores permitidos: true se exige o preenchimento ou false se não exige.
ignore_categorization_visitor: Se permite retornar produtos fora da categorização.
Valores permitidos: true se permite ou false se não permite.
creator_id: Id do usuário que está criando.
scheduled_visit_routes_attributes: Array com atributos das rotas associadas
route_id: Id da rota associada ao agendamento
scheduled_visit_checkpoints: Array com atributos dos checkpoints associados ao agnedamento
installation_id: Id da instalação
restock: Se deve efetuar o reabastecimento na visita
Valores permitidos: true para efetuar o reabastecimento ou false se não.
cash_collect: Se deve efetuar a coleta na visita
Valores permitidos: true para efetuar a coleta ou false se não.
only_visit: Se não é necessário reabastecimento ou coleta na visita
Valores permitidos: true para ignorar reabastecimento e coleta na visita ou false para levar em consideração os valores de reabastecimento e coleta
pick_list_scheduled: Se deve agendar a geração do pick list
Valores permitidos: true para agendar a geração ou false se não.
pick_list_scheduled_hour: hora(UTC) da geração da pick list caso seja agendada a data será a mesma do scheduled_visit.date
Default 0 caso pick_list_scheduled seja true.
pick_list_scheduled_minutes: minutos da geração da pick list caso seja agendada a data será a mesma do scheduled_visit.date
Default 0 caso pick_list_scheduled seja true.
Retorno
status |
descrição |
|---|---|
201 |
Criado com sucesso |
Exemplo:
{
"id": 13081,
"created_at": "2017-11-23T11:01:24.000000Z",
"updated_at": "2017-11-23T11:01:24.000000Z",
"date": "2017-12-18",
"completed_at": null,
"vacant_amounts_required": true,
"ignore_categorization_visitor": true,
"supply_category_id": 1,
"checkpoints": [
{
"id": 84653,
"installation_id": 7687,
"pick_list_scheduled": true,
"pick_list_scheduled_at": "2017-12-18T10:15:00.000Z",
"pick_list_generated": true,
"restock": true,
"cash_collect": false,
"only_visit": false,
"pending_inventory_adjustment": true,
"finished": true,
"finished_at": "2016-12-21T16:39:20.000Z"
}
{
"id": 84654,
"installation_id": 7690,
"pick_list_scheduled": false,
"pick_list_scheduled_at": null,
"pick_list_generated": false,
"restock": false,
"cash_collect": true,
"only_visit": false,
"pending_inventory_adjustment": false,
"finished": true,
"finished_at": "2016-12-21T18:39:20.000Z"
},
{
"id": 84655,
"installation_id": 7688,
"pick_list_scheduled": false,
"pick_list_scheduled_at": null,
"pick_list_generated": false,
"restock": true,
"cash_collect": true,
"only_visit": false,
"pending_inventory_adjustment": true,
"finished": true,
"finished_at": "2016-12-21T17:39:20.000Z"
}
],
"scheduled_visit_routes": [
{
"id": 16707,
"route_id": 377
}
]
}
Erros
status |
descrição |
response body |
|---|---|---|
400 |
parâmetros faltando |
{ “status”: “400”, “error”: “Bad Request” } |
Atualizar
PATCH /api/v1/scheduled_visits/[id]
Parâmetros de URL:
parâmetro |
descrição |
obrigatório |
|---|---|---|
id |
id da visita |
sim |
Request:
{
"scheduled_visit": {
"vacant_amounts_required": false
}
}
Campos
Ao menos um campo interno a scheduled_visit deve ser passado.
É possível passar valores referentes a rotas (scheduled_visit_routes_attributes) e também aos checkpoints (checkpoints_attributes)
Não é permitido alterar a categoria de abastecimento, caso já exista uma visita programada/concluída.
Exemplo atualização:
{
"scheduled_visit": {
"id:" 13081,
"checkpoints_attributes": [{
"id": 84653,
"cash_collect": true
}, {
"id": 84654,
"restock": false
}, {
"id": 84655,
"only_visit": true
}]
}
}
Caso se deseje remover uma rota, deve-se adicionar o atributo _destroy com valor true à chamada como no exemplo abaixo:
Exemplo exclusão de rota:
{
"scheduled_visit": {
"id:" 13081,
"scheduled_visit_routes_attributes": [{
"id": 4421,
"_destroy": true
}]
}
}
Da mesma forma, é possível remover checkpoints associados a visita passando o mesmo atributo _destroy aos atributos dos checkpoints
Exemplo exclusão de checkpoint:
{
"scheduled_visit": {
"id:" 13081,
"checkpoints_attributes": [{
"id": 84653,
"_destroy": true
}]
}
}
Retorno
status |
descrição |
|---|---|
200 |
Atualizado com sucesso |
Exemplo:
{
"id": 13081,
"created_at": "2017-11-23T11:01:24.000000Z",
"updated_at": "2017-11-23T11:01:24.000000Z",
"date": "2017-12-18",
"completed_at": null,
"vacant_amounts_required": true,
"ignore_categorization_visitor": true,
"checkpoints": [
{
"id": 84654,
"installation_id": 7690,
"pick_list_scheduled": false,
"pick_list_scheduled_at": null,
"pick_list_generated": false,
"restock": false,
"cash_collect": true,
"only_visit": false,
"pending_inventory_adjustment": false,
"finished": true,
"finished_at": "2016-12-21T16:39:20.000Z"
},
{
"id": 84655,
"installation_id": 7688,
"pick_list_scheduled": false,
"pick_list_scheduled_at": null,
"pick_list_generated": false,
"restock": true,
"cash_collect": true,
"only_visit": false,
"pending_inventory_adjustment": true,
"finished": true,
"finished_at": "2016-12-21T18:39:20.000Z"
}
]
}
Erros
status |
descrição |
response body |
|---|---|---|
404 |
visita não encontrada |
“error”: “Registro não encontrado” |
422 |
erro ao atualizar |
ver exemplo abaixo |
422 - erro ao atualizar
{
"error": "Não é possível atualizar uma visita concluída liberada."
}
Excluir
DELETE /api/v1/scheduled_visits/[id]
Parâmetros de URL:
parâmetro |
descrição |
obrigatório |
|---|---|---|
id |
id da visita |
sim |
Retorno
status |
descrição |
response body |
|---|---|---|
204 |
Excluída com sucesso |
(vazio) |
Erros
status |
descrição |
response body |
|---|---|---|
404 |
visita não encontrada |
{ “error”: “Registro não encontrado” } |
422 |
erro ao excluir |
veja exemplo abaixo |
422 - erro ao excluir
{
"error": "Não é possível excluir um agendamento já liberado."
}
Liberar para o VMpay Visitor
PATCH /api/v1/scheduled_visits/[id]/complete
Parâmetros de URL:
parâmetro |
descrição |
obrigatório |
|---|---|---|
id |
id da visita |
sim |
Retorno
status |
descrição |
response body |
|---|---|---|
204 |
Excluído com sucesso |
(vazio) |
Desfazer liberação
É possível desfazer uma liberação de visita para o VMpay Visitor se a liberação ocorreu no último minuto, caso contrário não é mais possível desfazer uma liberação.
PATCH /api/v1/scheduled_visits/[id]/undo_complete
Parâmetros de URL:
parâmetro |
descrição |
obrigatório |
|---|---|---|
id |
id da visita |
sim |
Retorno
status |
descrição |
response body |
|---|---|---|
204 |
Excluído com sucesso |
(vazio) |
Erros
status |
descrição |
response body |
|---|---|---|
422 |
não é possível desfazer a liberação |
{vazios} |