Central do desenvolvedor uMov.me

# Recursos da API 2.0

# URL Base

A URL base da API 2.0 é: https://api.umov.me/v2
Abaixo segue a documentação dos recursos disponíveis:

# Agente

O endpoint /agents é responsável pela criação e manutenção dos agentes da plataforma uMov.me. Um agente representa uma pessoa que pode acessar a plataforma pela Web ou pelo aplicativo móvel, executar tarefas em campo, receber atividades, possuir agenda, dados de contato, endereço, imagem, campos customizáveis e regras de acesso.

Use este recurso para criar, atualizar e complementar agentes, incluindo credenciais de acesso, perfil de permissão, tipo de agente, imagem, idioma, fuso horário, endereço, capacidade operacional, atividades vinculadas e campos customizáveis. Em atualizações por identificador alternativo, informe o identificador alternativo do agente para que a API localize o cadastro correto.

# Possíveis erros de negócio

As operações do endpoint /agents podem retornar 400 Bad Request quando alguma regra de negócio do agente não for atendida. A mensagem pode variar conforme o idioma configurado na requisição, por isso use a chave do erro como referência principal para integrações e automações. A tabela abaixo apresenta a mensagem em português e explica, em linguagem direta, o motivo mais comum de cada retorno.

Quando a chave vier com complemento após :, esse complemento indica o campo, o identificador ou o contexto específico que causou a validação, por exemplo resource_not_found:alternativeIdentifier=agente-01. Os valores entre chaves, como {0} e {1}, são substituídos pela API com os dados da requisição ou do registro validado.

Chave Mensagem de referência Motivo do erro
empty_keys Deve ser informado o ID ou o identificador alternativo A requisição tentou localizar um agente, atividade, tipo de agente, jornada semanal, perfil de acesso ou outro recurso sem informar ID nem identificador alternativo.
resource_not_found Recurso não encontrado: {0} O agente ou outro recurso referenciado na requisição não foi encontrado para o cliente autenticado.
resource_not_found:activity={value} Recurso não encontrado: activity={value} A atividade informada não está vinculada ao agente no momento da remoção. Verifique se a atividade ainda faz parte do agente antes de removê-la.
internal_identifier_not_found O recurso não foi encontrado para o identificador interno informado. Verifique o ID e o cliente antes de continuar. O ID interno informado não pertence ao cliente autenticado ou não existe.
more_than_one_resource Foi encontrado mais de um recurso: {0} A requisição encontrou mais de um registro para a mesma referência. Use um identificador único antes de continuar.
more_than_one_resource:alternativeIdentifier={value} Foi encontrado mais de um recurso: alternativeIdentifier={value} O identificador alternativo informado encontrou mais de um agente ou recurso relacionado. Use o ID interno ou corrija a duplicidade.
field_required Campo deve ser preenchido: {0} Um campo obrigatório do agente não foi informado, como nome, login, senha, atividade ou outro campo definido como obrigatório na configuração do ambiente.
field_required:accessRole Campo deve ser preenchido: accessRole O agente foi marcado como usuário Web, mas o perfil de acesso não foi informado. Informe um perfil de acesso válido.
field_required:precision Campo deve ser preenchido: precision O provedor de rastreamento nativo foi informado, mas a precisão do rastreamento não foi enviada. Informe a precisão compatível com o provedor.
max_size {0}: Tamanho máximo de {1} caracteres Algum campo textual do agente excedeu o tamanho permitido, como login, endereço, cidade, estado, país, CEP ou descrição da imagem.
maxSize:Email Email: tamanho máximo excedido O e-mail do agente possui mais caracteres do que o permitido. Informe um e-mail menor antes de continuar.
invalid O valor informado é inválido: {0} Algum valor de domínio do agente é inválido, como provedor de GPS, política de senha, idioma, e-mail, geocoordenada, login reservado ou fuso horário.
invalid:Email O valor informado é inválido: Email O e-mail informado não possui um formato válido. Revise o endereço de e-mail antes de salvar o agente.
invalid:geoCoordinate O valor informado é inválido: geoCoordinate A geocoordenada manual do endereço não está no formato esperado de latitude e longitude numéricas.
invalid:login O valor informado é inválido: login O login informado usa um valor reservado pela plataforma. Escolha outro login para o agente.
invalid:passwordPolicy O valor informado é inválido: passwordPolicy A política de senha enviada não corresponde a um código aceito pela API.
invalid:provider O valor informado é inválido: provider O provedor ou a precisão de rastreamento enviados não correspondem a códigos aceitos pela API.
invalid:supportedLanguage O valor informado é inválido: supportedLanguage O idioma informado para o agente não está entre os idiomas suportados pela plataforma.
invalid:timeZoneOffset O valor informado é inválido: timeZoneOffset O fuso horário informado não corresponde a um identificador válido. Use um valor aceito pela API, como um fuso horário reconhecido pela plataforma.
invalid.agentAccessType O tipo de acesso do agente é inválido. Use um dos códigos de tipo de acesso suportados. O tipo de acesso do agente não está entre os valores aceitos, como acesso por senha, OAuth ou ambos, conforme configuração disponível.
idiom:notFound Idioma não encontrado O ID de idioma informado não existe ou não está disponível para o cliente autenticado.
should_be_greater_than {0} deve ser maior que {1} Um valor numérico do agente deve ser maior que o limite mínimo, como as capacidades operacionais capacity1 ou capacity2, que não aceitam valores negativos.
duplicated {0} já existe Já existe outro agente com o mesmo login ou, quando a configuração exige nome único, com o mesmo nome. Use valores únicos ou atualize o cadastro existente.
error.thereIsMoreThanOneAgentWithTheSameIdentifier Há mais de um agente com o mesmo identificador alternativo. Por favor, altere este identificador ou remova o outro que está em uso. O identificador alternativo informado para o agente já está em uso em outro cadastro. Corrija a duplicidade antes de continuar.
without.licence Não há licenças disponíveis. O cliente não possui licença disponível para ativar ou criar mais um agente ativo. Libere uma licença ou inative outro agente antes de continuar.
image.url.required A URL da imagem é obrigatória quando o ID de uma imagem existente não é informado. A requisição tentou criar ou atualizar a imagem do agente sem informar o ID de uma imagem existente nem a URL para importação.
media.image.not_found A imagem não foi encontrada ou não está disponível para este cliente. Verifique o ID da imagem antes de continuar. O ID de imagem informado no agente não existe, não pertence ao cliente autenticado ou não está disponível para uso.
error.size.image O tamanho da imagem deve ser menor que o tamanho configurado nos parâmetros do sistema A imagem enviada para o agente excede o tamanho máximo permitido na configuração do ambiente.
error.processing.imageUrl Erro ao processar a URL da imagem informada A API não conseguiu acessar ou validar a URL da imagem enviada para o agente. Verifique se a URL está acessível e tente novamente.
custom_field.required Campo customizável {0} deve ser preenchido Um campo customizável obrigatório do agente não foi informado.
custom_field.invalid_geocoordinate Campo customizável {0} deve ser uma geocoordenada válida O valor informado em um campo customizável de geocoordenada não está em um formato válido.
custom_field.invalid_multimidia_url Campo customizável {0} deve ser uma URL válida O valor informado em um campo customizável de mídia não é uma URL válida.
custom_field.invalid_multimidia_image.too_large A imagem informada no campo customizado multimídia é inválida ou excede o tamanho permitido. Use uma imagem válida. A imagem enviada em um campo customizável multimídia é inválida ou maior que o limite permitido.
customFieldValue.not_a_number O valor informado no campo customizável numérico {0} não é um numérico válido O valor enviado para um campo customizável numérico não pode ser convertido para número.
customFieldValue.not_a_valid_date O valor padrão para o campo {0} não é uma data válida. Use o formato dd/MM/yyyy. O valor enviado para um campo customizável de data não respeita o formato esperado.
customFieldValue.not_a_valid_time O valor padrão para o campo {0} não é uma hora válida. Use o formato HH:mm. O valor enviado para um campo customizável de hora não respeita o formato esperado.
customFieldValue.internalAndExternalValueRequired O valor interno e externo deve ser preenchido no campo customizável {0} A requisição enviou um campo customizável que exige valor interno e externo, mas um deles não foi informado.
customField.not_found O campo customizável {0} não foi encontrado O campo customizável informado não existe, não pertence ao cliente ou não está disponível para agente.
customField.without_identifier O campo customizável não foi encontrado. Forneça um identificador válido para que seja possível manipular o campo. A requisição tentou alterar campo customizável sem identificar qual campo deve ser manipulado.
error.not_found_custom_entity_value O valor do campo customizado {0} informado na requisição, referente ao valor da entidade customizada, é inválido. O valor enviado para um campo customizável de lista vinculada a cadastro customizável não existe.
custom_field.duplicated Campo customizável duplicado A requisição enviou o mesmo campo customizável de lista simples mais de uma vez.
custom_field_multivalued.duplicatedInternalValue Valor interno duplicado em campo customizável multivalorado A requisição enviou valores repetidos para o mesmo campo customizável multivalorado.
error.minimumCharacters A senha deve ter pelo menos {0} caractere(s) A senha do agente não possui a quantidade mínima de caracteres configurada na política de senha do cliente.
error.minimumLowerCharacters A senha deve ter pelo menos {0} caractere(s) minúsculos A senha do agente não possui a quantidade mínima de letras minúsculas configurada na política de senha do cliente.
error.minimumUpperCharacters A senha deve ter pelo menos {0} caractere(s) maiúsculos A senha do agente não possui a quantidade mínima de letras maiúsculas configurada na política de senha do cliente.
error.minimumNumericCharacters A senha deve ter pelo menos {0} caractere(s) numéricos A senha do agente não possui a quantidade mínima de números configurada na política de senha do cliente.
error.minimumSpecialCharacters A senha deve ter pelo menos {0} caractere(s) especiais A senha do agente não possui a quantidade mínima de caracteres especiais configurada na política de senha do cliente.
error.passwordReuse Você deve utilizar uma senha diferente de suas {0} últimas senhas A senha informada já foi usada recentemente pelo agente e a política do cliente impede reutilização de senhas anteriores.

# Ausência programada

O endpoint /absence é responsável pela criação e manutenção das ausências programadas dos agentes. Uma ausência programada define um período em que o agente ficará indisponível e informa como a plataforma deve tratar sua agenda, como ignorar a agenda, transferir os compromissos para outro agente ou impedir login durante o período.

Use este recurso para criar, atualizar e complementar ausências com período inicial e final, agente de origem, agente de destino quando houver transferência, tipo de ação, status, descrição e identificador alternativo.

# Possíveis erros de negócio

As operações do endpoint /absence podem retornar 400 Bad Request quando alguma regra de negócio da ausência programada não for atendida. A mensagem pode variar conforme o idioma configurado na requisição, por isso use a chave do erro como referência principal para integrações e automações. A tabela abaixo apresenta a mensagem em português e explica, em linguagem direta, o motivo mais comum de cada retorno.

Quando a chave vier com complemento após :, esse complemento indica o campo, o identificador ou o contexto específico que causou a validação, por exemplo resource_not_found:alternativeIdentifier=ausencia-01. Os valores entre chaves, como {0} e {1}, são substituídos pela API com os dados da requisição ou do registro validado.

Chave Mensagem de referência Motivo do erro
resource_not_found Recurso não encontrado: {0} A ausência programada informada na atualização não foi encontrada para o cliente autenticado. Verifique o ID ou o identificador alternativo antes de continuar.
more_than_one_resource Foi encontrado mais de um recurso: {0} A requisição encontrou mais de um registro para a mesma referência. Use um identificador único antes de continuar.
more_than_one_resource:alternativeIdentifier={value} Foi encontrado mais de um recurso: alternativeIdentifier={value} O identificador alternativo informado encontrou mais de uma ausência programada ou já está associado a uma ausência existente. Use o ID interno ou corrija a duplicidade.
field_required Campo deve ser preenchido: {0} Um campo obrigatório da ausência programada não foi informado, como active, action, initialDateTime, finalDateTime ou originAgentId.
field_required:destinationAgent Campo deve ser preenchido: destinationAgent A ação informada é transferência de agenda, mas o agente de destino não foi enviado. Informe quem receberá a agenda do agente ausente.
invalid O valor informado é inválido: {0} Algum valor de domínio da ausência programada não corresponde a um código aceito pela API. Revise o campo indicado no retorno.
invalid:absenceAction O valor informado é inválido: absenceAction A ação da ausência não está entre os códigos aceitos. Use 0 para ignorar agenda, 1 para transferir agenda ou 2 para não permitir login.
max_size {0}: Tamanho máximo de {1} caracteres Algum campo textual da ausência programada excedeu o tamanho permitido, como alternativeIdentifier, description ou action.
should_not_be_greater_than {0} não deve ser maior que {1} A data e hora inicial da ausência ficou maior que a data e hora final. Ajuste o período para que o início seja anterior ou igual ao fim.
origin_agent_not_found Agente origem informado não foi encontrado: {0} O agente de origem informado não existe ou não pertence ao cliente autenticado. Verifique o ID interno ou o identificador alternativo do agente.
destination_agent_not_found Agente destino informado não foi encontrado: {0} O agente de destino informado para receber a agenda não existe ou não pertence ao cliente autenticado. Verifique o ID interno ou o identificador alternativo do agente.
error.agentAbsence.origin_agent_and_destination_agent_cannot_be_the_same_when_it_is_a_transfer_action Agente de origem e destino não podem ser o mesmo. A transferência de agenda foi configurada para o próprio agente. Informe outro agente de destino.
error.agentAbsence.destination_agent_already_absence_with_origin_agent Transferência circular entre agentes já existe. Já existe uma ausência no período que transfere a agenda de volta para o agente de origem. Revise as ausências existentes.
error.requestTimeOut Sua solicitação excedeu o tempo limite. Faça uma nova tentativa. A API não conseguiu persistir a ausência dentro do tempo esperado. Tente novamente e, se o erro persistir, revise o volume de requisições ou acione o suporte.
persistence_error Ocorreu um erro de validação, verifique sua solicitação com o nome {0} e tente novamente. A API encontrou uma falha ao salvar a ausência programada. Revise os dados enviados e tente novamente.

# Cadastro customizável

O endpoint /custom-entity é responsável pela criação e manutenção dos cadastros customizáveis, também chamados de datasets, da plataforma uMov.me. Um cadastro customizável funciona como uma estrutura de dados configurável pelo cliente, que pode ser usada para armazenar listas próprias do negócio e servir como origem para campos customizáveis em entidades como agentes, itens, locais, tarefas e atividades.

Use este recurso para criar, atualizar e complementar a estrutura do cadastro customizável, incluindo descrição, identificador alternativo, rótulo da descrição, rótulo do identificador alternativo, status, envio para mobile, bloqueio de edição e flags de controle da estrutura. Para criar ou alterar os registros internos de um cadastro customizável, use o endpoint /custom-entity-entry.

# Possíveis erros de negócio

As operações do endpoint /custom-entity podem retornar 400 Bad Request quando alguma regra de negócio do cadastro customizável não for atendida. A mensagem pode variar conforme o idioma configurado na requisição, por isso use a chave do erro como referência principal para integrações e automações. A tabela abaixo apresenta a mensagem em português e explica, em linguagem direta, o motivo mais comum de cada retorno.

Quando a chave vier com complemento após :, esse complemento indica o campo, o identificador ou o contexto específico que causou a validação, por exemplo resource_not_found:alternativeIdentifier=clientes-vip. Os valores entre chaves, como {0} e {1}, são substituídos pela API com os dados da requisição ou do registro validado.

Chave Mensagem de referência Motivo do erro
resource_not_found Recurso não encontrado: {0} O cadastro customizável informado na atualização não foi encontrado para o cliente autenticado. Verifique o ID ou o identificador alternativo antes de continuar.
more_than_one_resource Foi encontrado mais de um recurso: {0} A requisição encontrou mais de um cadastro customizável para a mesma referência. Use um identificador único antes de continuar.
more_than_one_resource:id={value} Foi encontrado mais de um recurso: id={value} A criação foi enviada com ID interno preenchido. Para criar um cadastro customizável, não informe ID no corpo da requisição.
more_than_one_resource:alternativeIdentifier={value} Foi encontrado mais de um recurso: alternativeIdentifier={value} O identificador alternativo informado encontrou cadastro customizável já existente ou mais de um registro. Use um identificador alternativo único ou atualize o cadastro existente.
field_required Campo deve ser preenchido: {0} Um campo obrigatório do cadastro customizável não foi informado, como descrição, rótulo da descrição ou rótulo do identificador alternativo.
error.thereIsMoreThanOneCustomEntityWithTheSameDescription Já existe uma entidade customizada com esta descrição para este cliente. Use uma descrição única. Já existe outro cadastro customizável com a mesma descrição para o cliente autenticado. Use uma descrição única antes de continuar.
error.thereIsMoreThanOneCustomEntityWithTheSameIdentifier Já existe uma entidade customizada com este identificador alternativo para este cliente. Use um identificador alternativo único. Já existe outro cadastro customizável com o mesmo identificador alternativo para o cliente autenticado. Use um identificador alternativo único antes de continuar.

# Campo customizado

Campos customizados são os campos que podem ser criados nas entidades padrões da uMov.me (como pessoas, itens, locais, tarefa etc.) e também nas entidades customizadas (datasets). Esses campos permitem maior flexibilidade e personalização, adaptando o sistema às necessidades específicas de cada usuário ou negócio.

# Parâmetros:

  • alternativeIdentifier: Identificador alternativo único para o campo customizável.
  • description: Descrição ou nome do campo customizável.
  • size: Tamanho máximo do campo (informação obrigatória).
  • typeField: Tipo do campo customizável. Exemplos:
    • ALPHANUMERIC
    • CUSTOM_ENTITY_LIST
    • DATE
    • GEOCOORDINATE
    • MULTIMEDIA
    • MULTIVALUED
    • NUMERIC
    • PAYMENT_RECEIVER
    • TIME
  • subtypeField: Tipo de subcampo customizável. Pode ser utilizado de duas maneiras:
    • Quando o typeField é MULTIMEDIA, os subtipos são:
      • MULTIMIDIA_AUDIO
      • MULTIMIDIA_IMAGE
      • MULTIMIDIA_PDF
      • MULTIMIDIA_URL
      • MULTIMIDIA_VIDEO
      • MULTIMIDIA_XML
    • Quando o typeField é CUSTOM_ENTITY_LIST ou MULTIVALUED, os subtipos são:
      • MULTIPLE_LIST
      • SIMPLE_LIST
  • editableOnCenter: Indica se o campo é editável no center.
  • lockedEdition: Indica se a edição do campo está bloqueada.
  • mandatory: Indica se o campo é obrigatório.
  • showFilter: Indica se o campo deve ser exibido como um filtro nas pesquisas.

# Chamada POST para Criar um Campo Customizável em alguma entidade padrão

Para criar um campo customizável em uma entidade padrão (por exemplo, Tarefa) utilize a seguinte estrutura de requisição:

Entidades padrão da plataforma para utilização no endpoint:

  • AGENT
  • CUSTOM_ENTITY
  • ITEM
  • LOCAL_ITEM
  • SERVICE_LOCAL
  • TASK
  • TASK_ITEM

Endpoint: POST /customField/entity/{TASK}

Exemplo de Requisição:

{
    "active": true,
    "alternativeIdentifier": "cf_alternativeIdentifier",
    "description": "Descricao/Nome do Campo customizavel",
    "size": 10,
    "typeField": "NUMERIC",
    "editableOnCenter": true,
    "lockedEdition": false,
    "mandatory": false,
    "showFilter": false
}

# Chamada POST para Criar um Campo Customizável em algum cadastro customizavel (dataset)

Para criar um campo customizável em uma entidade customizada (dataset), utilize a seguinte estrutura de requisição como exemplo. Com este exemplo é possível criar um campo do tipo lista simples ou múltipla com origem em outro cadastro. Utilize o campo customEntity para especificar em qual cadastro o campo será criado, typeField para indicar o tipo do campo, subtypeField para definir se é uma SIMPLE_LIST ou MULTIPLE_LIST, e customEntityListReference para indicar a origem da lista, que pode ser de qualquer outro cadastro ou até do mesmo dataset.

  • Endpoint: POST /customField/entity/{CUSTOM_ENTITY}

Exemplo de Requisição:

{
    "alternativeIdentifier": "CustomFieldMultipleList",
    "description": "CustomFieldMultipleList",
    "typeField": "CUSTOM_ENTITY_LIST",
    "size": 10,
    "customEntity": { 
      "alternativeIdentifier": "custom_entity_example" 
    },
    "customEntityListReference": { 
      "alternativeIdentifier": "custom_entity_origin" 
    },
    "subtypeField": "MULTIPLE_LIST"
}

# Informações Opcionais:

Por padrão, os seguintes valores são atribuídos se não forem fornecidos na requisição:

{
    "active": true,
    "editableOnCenter": false,
    "lockedEdition": false,
    "mandatory": false,
    "showFilter": false
}

# Possíveis erros de negócio

As operações do endpoint /customField podem retornar 400 Bad Request ou 404 Not Found quando alguma regra de negócio do campo customizado não for atendida. A mensagem pode variar conforme o idioma configurado na requisição, por isso use a chave do erro como referência principal para integrações e automações. A tabela abaixo apresenta a mensagem em português e explica, em linguagem direta, o motivo mais comum de cada retorno.

Quando a chave vier com complemento após :, esse complemento indica o campo, o identificador ou o contexto específico que causou a validação, por exemplo customField.duplicateDescription:Status. Os valores entre chaves, como {0} e {1}, são substituídos pela API com os dados da requisição ou do registro validado.

Chave Mensagem de referência Motivo do erro
resource_not_found Recurso não encontrado: {0} O campo customizado, o cadastro customizável de origem ou o cadastro customizável usado como lista não foi encontrado para o cliente autenticado. Verifique o ID ou o identificador alternativo informado.
more_than_one_resource Foi encontrado mais de um recurso: {0} A requisição encontrou mais de um registro para a mesma referência. Use um identificador único antes de continuar.
more_than_one_resource:alternativeIdentifier={value} Foi encontrado mais de um recurso: alternativeIdentifier={value} O identificador alternativo informado encontrou mais de um registro relacionado ao campo customizado ou ao cadastro customizável usado como origem. Use o ID interno ou corrija a duplicidade.
field_required Campo deve ser preenchido: {0} Um campo obrigatório da configuração não foi informado, como description ou size.
max_size {0}: Tamanho máximo de {1} caracteres O identificador alternativo do campo customizado excedeu o tamanho permitido. Informe até 100 caracteres.
invalid:EntityType O valor informado é inválido: EntityType A entidade informada na rota não é suportada pelo endpoint. Use uma entidade válida, como AGENT, SERVICE_LOCAL, ITEM, TASK, TASK_ITEM, CUSTOM_ENTITY ou LOCAL_ITEM.
customField.thereIsNotTypeInformed Tipo do campo customizado não informado: {0} O campo customizado foi criado sem typeField. Informe o tipo do campo, como ALPHANUMERIC, NUMERIC, DATE, TIME, MULTIMEDIA, CUSTOM_ENTITY_LIST, GEOCOORDINATE ou MULTIVALUED.
custom_field_with_origin_dataset_without_origin Origem do dataset não informada: {0} A criação foi feita para a entidade CUSTOM_ENTITY, mas o cadastro customizável de origem não foi informado no campo customEntity. Informe o dataset onde o campo será criado.
customField.multimedia_without_subtype Subtipo multimídia não informado: {0} O campo foi criado como MULTIMEDIA, mas o subtypeField não foi informado. Informe o subtipo multimídia esperado, como imagem, URL, PDF, áudio, vídeo ou XML.
customField.customEntity_without_subtype Subtipo de lista de dataset não informado: {0} O campo foi criado como CUSTOM_ENTITY_LIST, mas o subtypeField não foi informado. Use SIMPLE_LIST ou MULTIPLE_LIST.
customField.duplicateDescription Nome de campo customizável já em uso: {0} Já existe outro campo customizado com a mesma descrição na entidade informada ou no mesmo cadastro customizável. Use uma descrição única.
customField.duplicateAlternativeIdentifier Identificador alternativo já em uso: {0} Já existe outro campo customizado com o mesmo identificador alternativo na entidade informada ou no mesmo cadastro customizável. Use um identificador alternativo único.
customFieldValue.not_a_number O valor informado no campo customizável numérico {0} não é um numérico válido O valor padrão de um campo NUMERIC não pode ser convertido para número. Informe um valor numérico válido.
customFieldValue.not_a_valid_date O valor padrão para o campo {0} não é uma data válida. O valor padrão de um campo DATE não respeita um formato de data aceito. Use um formato válido, como dd/MM/yyyy ou yyyy-MM-dd.
customFieldValue.not_a_valid_time O valor padrão para o campo {0} não é uma hora válida. O valor padrão de um campo TIME não respeita o formato de hora esperado. Use HH:mm.
custom_field.invalid_geocoordinate Campo customizável {0} deve ser uma geocoordenada válida O valor padrão de um campo GEOCOORDINATE não está em formato válido de latitude e longitude.
custom_field.invalid_multimidia_url Campo customizável {0} deve ser uma URL válida O valor padrão de um campo MULTIMEDIA com subtipo MULTIMIDIA_URL não é uma URL válida.
custom_field.required Campo customizável {0} deve ser preenchido Um campo customizado obrigatório foi usado em uma entidade sem valor. Esse erro aparece ao criar ou atualizar registros que possuem campos customizados obrigatórios.
customFieldValue.internalAndExternalValueRequired O valor interno e externo deve ser preenchido no campo customizável {0} Um campo customizado de lista foi enviado sem valor interno ou sem valor externo. Informe os dois valores quando o tipo do campo exigir essa relação.
error.not_found_custom_entity_value Valor de cadastro customizável inválido: {0} Um campo customizado de lista vinculada a cadastro customizável recebeu um valor que não existe no dataset de referência. Revise o valor interno ou externo enviado.
custom_field.duplicated Campo customizável duplicado A requisição enviou mais de um valor para o mesmo campo customizado de lista simples. Envie apenas um valor para esse tipo de campo.
custom_field_multivalued.duplicatedInternalValue Valor interno duplicado em campo customizável multivalorado A requisição enviou valores repetidos para o mesmo campo customizado multivalorado. Remova os valores duplicados antes de tentar novamente.
custom_field.invalid_multimidia_image.too_large Imagem multimídia inválida ou acima do tamanho permitido. Um valor de campo customizado multimídia de imagem é inválido ou maior que o limite permitido pela configuração do ambiente.
customField.not_found O campo customizável {0} não foi encontrado Uma operação que referencia valores de campos customizados informou um campo inexistente, inativo ou indisponível para a entidade enviada.
customField.without_identifier O campo customizável não foi encontrado. Uma operação que referencia valores de campos customizados não informou ID nem identificador alternativo do campo. Informe uma das duas referências.
error.requestTimeOut Sua solicitação excedeu o tempo limite. Faça uma nova tentativa. A API não conseguiu persistir o campo customizado dentro do tempo esperado. Tente novamente e, se o erro persistir, revise o volume de requisições ou acione o suporte.
persistence_error Ocorreu um erro de validação, verifique sua solicitação com o nome {0} e tente novamente. A API encontrou uma falha ao salvar o campo customizado. Revise os dados enviados e tente novamente.

# Equipe

O endpoint /team é responsável pela criação e manutenção das equipes da plataforma uMov.me. Uma equipe representa um agrupamento operacional de agentes e pode ser usada para organizar execução de tarefas, responsabilidade por locais, filtros de acesso e rotinas de operação.

Use este recurso para criar equipes, atualizar parcialmente seus dados, definir tipo de equipe, equipe responsável, agentes vinculados e relacionamentos com locais de atendimento. O próprio endpoint também permite vincular ou desvincular agentes e locais de uma equipe usando ID interno ou identificador alternativo.

# Possíveis erros de negócio

As operações do endpoint /team podem retornar 400 Bad Request quando alguma regra de negócio da equipe não for atendida. A mensagem pode variar conforme o idioma configurado na requisição, por isso use a chave do erro como referência principal para integrações e automações. A tabela abaixo apresenta a mensagem em português e explica, em linguagem direta, o motivo mais comum de cada retorno.

Quando a chave vier com complemento após :, esse complemento indica o campo, o identificador ou o contexto específico que causou a validação, por exemplo resource_not_found:alternativeIdentifier=equipe-campo. Os valores entre chaves, como {0} e {1}, são substituídos pela API com os dados da requisição ou do registro validado.

Chave Mensagem de referência Motivo do erro
resource_not_found Recurso não encontrado: {0} A equipe, agente, local, tipo de equipe ou equipe responsável informada na requisição não foi encontrada para o cliente autenticado.
resource_not_found:alternativeIdentifier={value} Recurso não encontrado: alternativeIdentifier={value} O identificador alternativo informado não encontrou equipe, agente ou local ativo para o cliente autenticado.
resource_not_found:id={value} Recurso não encontrado: id={value} O ID informado não encontrou equipe, agente ou local ativo para o cliente autenticado.
more_than_one_resource Foi encontrado mais de um recurso: {0} A requisição encontrou mais de um registro para a mesma referência. Use um identificador único antes de continuar.
more_than_one_resource:id={value} Foi encontrado mais de um recurso: id={value} A criação de equipe foi enviada com ID interno preenchido. Para criar uma equipe, não informe ID no corpo da requisição.
more_than_one_resource:alternativeIdentifier={value} Foi encontrado mais de um recurso: alternativeIdentifier={value} O identificador alternativo informado encontrou mais de uma equipe, agente, local ou recurso relacionado. Use o ID interno ou corrija a duplicidade.
field_required Campo deve ser preenchido: {0} Um campo obrigatório da equipe ou do vínculo não foi informado, como descrição da equipe ou ID do agente ao montar a lista de membros.
error.teamNameRequired O nome da equipe deve ser obrigatório A equipe foi criada ou atualizada sem nome. Informe a descrição da equipe antes de continuar.
error.teamNameAlreadyExists O nome da equipe {0} informado na solicitação já existe, favor informar outro nome para a equipe Já existe outra equipe com o mesmo nome para o cliente autenticado. Use um nome único antes de continuar.
error.teamAlternativeIdentifierAlreadyExists Identificador alternativo de equipe já existe Já existe outra equipe com o mesmo identificador alternativo para o cliente autenticado. Use um identificador alternativo único antes de continuar.
error.thereAreDuplicateAgentsInYourRequest Existem agentes duplicados em sua solicitação, por favor remova o agente repetido e tente novamente A lista de agentes enviada na criação ou atualização da equipe contém o mesmo agente mais de uma vez.
error.agentAlreadyIncludedInTheTeam Sua equipe já tem o agente informado na sua solicitação, por favor verifique e tente novamente A requisição tentou vincular à equipe um agente que já está vinculado a ela.
error.agentRequired Para adicionar um agente à equipe, é obrigatório que o mesmo seja informado A requisição tentou adicionar agente à equipe sem informar ID ou identificador alternativo do agente.
error.thereIsNotRelationship Não é possível excluir o agente informado, pois ele não faz parte da equipe e não possui nenhum relacionamento existente com a mesma. A requisição tentou remover da equipe um agente que não está vinculado a ela.
error.localAlreadyIncludedInTheTeam Este local de serviço já está vinculado à equipe. Remova o relacionamento existente ou escolha outro local de serviço. A requisição tentou vincular à equipe um local de atendimento que já está vinculado a ela.
error.localNotIncludedInTheTeam Este local de serviço não está vinculado à equipe, por isso não pode ser removido da equipe. A requisição tentou remover da equipe um local de atendimento que não está vinculado a ela.

# Item

O endpoint /item é responsável pela criação e manutenção dos itens da plataforma uMov.me. Um item representa algo que pode ser usado em atividades, seções, tarefas e locais, como produto, material, equipamento, ativo, checklist ou qualquer outro elemento operacional que precise ser selecionado, preenchido ou relacionado durante a execução.

Use este recurso para criar, atualizar e complementar itens com descrição, identificador alternativo, subgrupo, categoria, imagem, tags, exibição no Center e campos customizáveis. Em atualizações por identificador alternativo, informe o identificador alternativo do item para que a API localize o cadastro correto.

# Possíveis erros de negócio

As operações do endpoint /item podem retornar 400 Bad Request quando alguma regra de negócio do item não for atendida. A mensagem pode variar conforme o idioma configurado na requisição, por isso use a chave do erro como referência principal para integrações e automações. A tabela abaixo apresenta a mensagem em português e explica, em linguagem direta, o motivo mais comum de cada retorno.

Quando a chave vier com complemento após :, esse complemento indica o campo, o identificador ou o contexto específico que causou a validação, por exemplo resource_not_found:alternativeIdentifier=item-01. Os valores entre chaves, como {0} e {1}, são substituídos pela API com os dados da requisição ou do registro validado.

Chave Mensagem de referência Motivo do erro
empty_keys Deve ser informado o ID ou o identificador alternativo A requisição tentou localizar um item, subgrupo, categoria ou outro recurso relacionado sem informar ID nem identificador alternativo.
resource_not_found Recurso não encontrado: {0} O item, subgrupo, categoria ou outro recurso referenciado na requisição não foi encontrado para o cliente autenticado.
internal_identifier_not_found O recurso não foi encontrado para o identificador interno informado. Verifique o ID e o cliente antes de continuar. O ID interno informado não pertence ao cliente autenticado ou não existe.
more_than_one_resource Foi encontrado mais de um recurso: {0} A requisição encontrou mais de um registro para a mesma referência. Use um identificador único antes de continuar.
more_than_one_resource:alternativeIdentifier={value} Foi encontrado mais de um recurso: alternativeIdentifier={value} O identificador alternativo informado encontrou mais de um item ou recurso relacionado. Use o ID interno ou corrija a duplicidade.
field_required Campo deve ser preenchido: {0} Um campo obrigatório do item não foi informado, como descrição, subgrupo ou outro campo definido como obrigatório na configuração do ambiente.
max_size {0}: Tamanho máximo de {1} caracteres Algum campo textual do item excedeu o tamanho permitido, como descrição, tags ou identificador alternativo.
duplicated {0} já existe Já existe outro item com o mesmo identificador alternativo para o cliente autenticado. Use um identificador alternativo único ou atualize o cadastro existente.
image.url.required A URL da imagem é obrigatória quando o ID de uma imagem existente não é informado. A requisição tentou criar ou atualizar a imagem do item sem informar o ID de uma imagem existente nem a URL para importação.
media.image.not_found A imagem não foi encontrada ou não está disponível para este cliente. Verifique o ID da imagem antes de continuar. O ID de imagem informado no item não existe, não pertence ao cliente autenticado ou não está disponível para uso.
error.size.image O tamanho da imagem deve ser menor que o tamanho configurado nos parâmetros do sistema A imagem enviada para o item excede o tamanho máximo permitido na configuração do ambiente.
error.processing.imageUrl Erro ao processar a URL da imagem informada A API não conseguiu acessar ou validar a URL da imagem enviada para o item. Verifique se a URL está acessível e tente novamente.
custom_field.required Campo customizável {0} deve ser preenchido Um campo customizável obrigatório do item não foi informado.
custom_field.invalid_geocoordinate Campo customizável {0} deve ser uma geocoordenada válida O valor informado em um campo customizável de geocoordenada não está em um formato válido.
custom_field.invalid_multimidia_url Campo customizável {0} deve ser uma URL válida O valor informado em um campo customizável de mídia não é uma URL válida.
custom_field.invalid_multimidia_image.too_large A imagem informada no campo customizado multimídia é inválida ou excede o tamanho permitido. Use uma imagem válida. A imagem enviada em um campo customizável multimídia é inválida ou maior que o limite permitido.
customFieldValue.not_a_number O valor informado no campo customizável numérico {0} não é um numérico válido O valor enviado para um campo customizável numérico não pode ser convertido para número.
customFieldValue.not_a_valid_date O valor padrão para o campo {0} não é uma data válida. Use o formato dd/MM/yyyy. O valor enviado para um campo customizável de data não respeita o formato esperado.
customFieldValue.not_a_valid_time O valor padrão para o campo {0} não é uma hora válida. Use o formato HH:mm. O valor enviado para um campo customizável de hora não respeita o formato esperado.
customFieldValue.internalAndExternalValueRequired O valor interno e externo deve ser preenchido no campo customizável {0} A requisição enviou um campo customizável que exige valor interno e externo, mas um deles não foi informado.
customField.not_found O campo customizável {0} não foi encontrado O campo customizável informado não existe, não pertence ao cliente ou não está disponível para item.
customField.without_identifier O campo customizável não foi encontrado. Forneça um identificador válido para que seja possível manipular o campo. A requisição tentou alterar campo customizável sem identificar qual campo deve ser manipulado.
error.not_found_custom_entity_value O valor do campo customizado {0} informado na requisição, referente ao valor da entidade customizada, é inválido. O valor enviado para um campo customizável de lista vinculada a cadastro customizável não existe.
custom_field.duplicated Campo customizável duplicado A requisição enviou o mesmo campo customizável de lista simples mais de uma vez.
custom_field_multivalued.duplicatedInternalValue Valor interno duplicado em campo customizável multivalorado A requisição enviou valores repetidos para o mesmo campo customizável multivalorado.

# Roteiro

Roteiros definem regras de criação automática de tarefas com base em configurações de recorrência, dias da semana, agentes, locais, atividades e equipes vinculadas.

# Campos disponíveis:

Campo Descrição
alternativeIdentifier Identificador de integração único do roteiro.
description Descrição/nome do roteiro.
agentRelationship Tipo de relacionamento com agentes (0, 1, 2).
researchRelationship Tipo de relacionamento com atividades (A, S).
activityOrigin Origem da atividade (0 = padrão).
active Indica se o roteiro está ativo (1 = sim, 0 = não).
displayOrder Ordem de exibição do roteiro.
repeatedLocations Permite locais repetidos (1 = sim, 0 = não).
validateTaskInField Validar tarefa em campo (N ou S).
exclusive Roteiro exclusivo (N ou S).
createScheduleServiceLocal Criar tarefa para local (1 = sim, 0 = não).
monday a sunday Dias da semana ativos (1 = sim, 0 = não).
agents Lista de agentes vinculados ([{ agentId: 123 }]).
locais Lista de locais vinculados ([{ serviceLocalId: 456, treatmentOrder: 1 }]).
activities Lista de atividades vinculadas ([{ activityId: 789 }]).
teams Lista de equipes vinculadas ([{ teamId: 101 }]).

# Exemplo de Payload - Criar Roteiro

{
  "alternativeIdentifier": "roteiro_diario",
  "description": "Roteiro Diário de Visitas",
  "agentRelationship": "0",
  "researchRelationship": "A",
  "activityOrigin": "0",
  "active": "1",
  "displayOrder": 1,
  "repeatedLocations": "0",
  "validateTaskInField": "N",
  "exclusive": "N",
  "createScheduleServiceLocal": "0",
  "monday": "1",
  "tuesday": "1",
  "wednesday": "1",
  "thursday": "1",
  "friday": "1",
  "saturday": "0",
  "sunday": "0",
  "agents": [
    { "agentId": 232229 }
  ],
  "locais": [
    { "serviceLocalId": 86440322, "treatmentOrder": 1 }
  ],
  "activities": [
    { "activityId": 12345 }
  ],
  "teams": [
    { "teamId": 67890 }
  ]
}

# Jornada de Trabalho

A jornada de trabalho define um modelo padrão que pode ser reutilizado em diferentes dias da semana para configurar o expediente dos agentes.

# Exemplo de Payload - Jornada de Trabalho (WorkJourneyDTO)

{
  "alternativeIdentifier": "jornada_comercial",
  "description": "Jornada Comercial das 08h às 18h",
  "active": "ACTIVE",
  "taskCreationValidation": "ALLOW_CREATE_TASK_DURING_SHIFT"
}

# Campos disponíveis:

Campo Descrição
alternativeIdentifier Identificador de integração único da jornada.
description Descrição/nome da jornada.
active Indica se a jornada está ativa (true ou false).
taskCreationValidation Política de criação de tarefas com base na jornada (ex: ALLOW_CREATE_TASK_DURING_SHIFT).

# Jornada de Trabalho dia

O dia jornada de trabalho define um modelo padrão que pode ser reutilizado em diferentes dias da semana para configurar o expediente dos agentes.

# Campos disponíveis:

Campo Descrição
weekday Dias da semana relacionado à jornada : SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY.
initialHour1 Horário de início do primeiro turno (ex: 08:00).
finalHour1 Horário de término do primeiro turno (ex: 12:00).
initialHour2 Horário de início do segundo turno (ex: 13:00).
finalHour2 Horário de término do segundo turno (ex: 17:00).
initialHour3 (Opcional) Início do terceiro turno (ex: 18:00). Pode ser null.
finalHour3 (Opcional) Término do terceiro turno (ex: 20:00). Pode ser null.

# Local

O endpoint /locals é responsável pela criação e manutenção dos locais de atendimento da plataforma uMov.me. Um local representa onde uma tarefa será executada, como uma loja, cliente, endereço de visita, ponto de atendimento ou qualquer outro lugar relevante para a operação.

Use este recurso para criar, atualizar e complementar locais com endereço, responsável, equipe, tipo, classificação, grupo, imagem, campos customizáveis, atividades, itens e tags. Em atualizações por identificador alternativo, informe o identificador alternativo do local para que a API localize o registro correto.

# Possíveis erros de negócio

As operações do endpoint /locals podem retornar 400 Bad Request quando alguma regra de negócio do local não for atendida. A mensagem pode variar conforme o idioma configurado na requisição, por isso use a chave do erro como referência principal para integrações e automações. A tabela abaixo apresenta a mensagem em português e explica, em linguagem direta, o motivo mais comum de cada retorno.

Quando a chave vier com complemento após :, esse complemento indica o campo, o identificador ou o contexto específico que causou a validação, por exemplo resource_not_found:alternativeIdentifier=loja-01. Os valores entre chaves, como {0} e {1}, são substituídos pela API com os dados da requisição ou do registro validado.

Chave Mensagem de referência Motivo do erro
empty_keys Deve ser informado o ID ou o identificador alternativo A requisição tentou localizar um local, atividade, item, tipo, grupo ou classificação sem informar ID nem identificador alternativo.
resource_not_found Recurso não encontrado: {0} O local ou outro recurso referenciado na requisição não foi encontrado para o cliente autenticado.
internal_identifier_not_found O recurso não foi encontrado para o identificador interno informado. Verifique o ID e o cliente antes de continuar. O ID interno informado não pertence ao cliente autenticado ou não existe.
resource_not_found:alternativeIdentifier={value} Recurso não encontrado: alternativeIdentifier={value} O identificador alternativo informado não encontrou nenhum local para o cliente autenticado.
resource_not_found:id={value} Recurso não encontrado: id={value} O ID informado não encontrou nenhum local para o cliente autenticado.
resource_not_found:activity={value} Recurso não encontrado: activity={value} A atividade informada não está vinculada ao local no momento da remoção. Verifique se a atividade ainda faz parte do local antes de removê-la.
resource_not_found:tag={value} Recurso não encontrado: tag={value} A tag informada não foi encontrada ou não está ativa para o cliente autenticado.
more_than_one_resource Foi encontrado mais de um recurso: {0} A requisição encontrou mais de um registro para a mesma referência. Use um identificador único antes de continuar.
more_than_one_resource:alternativeIdentifier={value} Foi encontrado mais de um recurso: alternativeIdentifier={value} O identificador alternativo do local encontrou mais de um registro. Use o ID interno ou corrija a duplicidade.
more_than_one_resource_found Mais de um recurso foi encontrado para o identificador alternativo informado. Use o ID interno ou torne o identificador alternativo único antes de continuar. A remoção de tag encontrou locais duplicados para o identificador alternativo informado.
field_required Campo deve ser preenchido: {0} Um campo obrigatório do local não foi informado, como descrição, cliente, atividade ou algum campo definido como obrigatório na configuração do ambiente.
duplicated {0} já existe Já existe outro local com a mesma descrição para o cliente autenticado. Use uma descrição única ou altere o registro existente.
invalid O valor informado é inválido: {0} Algum valor de domínio do local é inválido, como localFilter ou outro campo com lista de valores controlada.
error.inactivateServiceLocalWithTasks Ops! Para inativar o local {0}, é necessário que todas as tarefas associadas estejam finalizadas. Verifique as tarefas pendentes ou em campo antes de tentar novamente. O local possui tarefas pendentes ou em campo e não pode ser inativado até que essas tarefas sejam finalizadas.
error.requestTimeOut Sua solicitação excedeu o tempo limite. Faça uma nova tentativa. A persistência do local excedeu o tempo limite de processamento. Tente novamente e, se o problema persistir, acione o suporte.
image.url.required A URL da imagem é obrigatória quando o id de uma imagem existente não é informado. A requisição tentou criar ou atualizar a imagem do local sem informar o ID de uma imagem existente nem a URL para importação.
media.image.not_found A imagem não foi encontrada ou não está disponível para este cliente. Verifique o id da imagem antes de continuar. O ID de imagem informado no local não existe, não pertence ao cliente autenticado ou não está disponível para uso.
error.size.image O tamanho da imagem deve ser menor que o tamanho configurado nos parâmetros do sistema A imagem enviada para o local excede o tamanho máximo permitido na configuração do ambiente.
error.processing.imageUrl Erro ao processar a URL da imagem informada A API não conseguiu acessar ou validar a URL da imagem enviada para o local. Verifique se a URL está acessível e tente novamente.
custom_field.required Campo customizável {0} deve ser preenchido Um campo customizável obrigatório do local ou da relação local/item não foi informado.
custom_field.invalid_geocoordinate Campo customizável {0} deve ser uma geocoordenada válida O valor informado em um campo customizável de geocoordenada não está em um formato válido.
custom_field.invalid_multimidia_url Campo customizável {0} deve ser uma URL válida O valor informado em um campo customizável de mídia não é uma URL válida.
custom_field.invalid_multimidia_image.too_large A imagem informada no campo customizado multimídia é inválida ou excede o tamanho permitido. Use uma imagem válida. A imagem enviada em um campo customizável multimídia é inválida ou maior que o limite permitido.
customFieldValue.not_a_number O valor informado no campo customizável numérico {0} não é um numérico válido O valor enviado para um campo customizável numérico não pode ser convertido para número.
customFieldValue.not_a_valid_date O valor padrão para o campo {0} não é uma data válida. Use o formato dd/MM/yyyy. O valor enviado para um campo customizável de data não respeita o formato esperado.
customFieldValue.not_a_valid_time O valor padrão para o campo {0} não é uma hora válida. Use o formato HH:mm. O valor enviado para um campo customizável de hora não respeita o formato esperado.
customFieldValue.internalAndExternalValueRequired O valor interno e externo deve ser preenchido no campo customizável {0} A requisição enviou um campo customizável que exige valor interno e externo, mas um deles não foi informado.
customField.not_found O campo customizável {0} não foi encontrado O campo customizável informado não existe, não pertence ao cliente ou não está disponível para o recurso enviado.
customField.without_identifier O campo customizável não foi encontrado. Forneça um identificador válido para que seja possível manipular o campo. A requisição tentou alterar campo customizável sem identificar qual campo deve ser manipulado.
error.not_found_custom_entity_value O valor do campo customizado {0} informado na requisição, referente ao valor da entidade customizada, é inválido. O valor enviado para um campo customizável de lista vinculada a cadastro customizável não existe.
custom_field.duplicated Campo customizável duplicado A requisição enviou o mesmo campo customizável de lista simples mais de uma vez.
custom_field_multivalued.duplicatedInternalValue Valor interno duplicado em campo customizável multivalorado A requisição enviou valores repetidos para o mesmo campo customizável multivalorado.
error.activityAlreadyExistsOnLocal A atividade informada {0} já existe no local {1}, verifique sua requisição, pois não é possível duplicar uma atividade no local A requisição tentou vincular ao local uma atividade que já está vinculada.
error.localItem.itemIsAlreadyAddedOnThisLocal Este item já está vinculado ao local. Remova o relacionamento existente ou escolha outro item. A requisição tentou vincular ao local um item que já está vinculado.
error.localItem.itemToBeDeletedIsNotInTheLocal Este item não está vinculado ao local, por isso não pode ser removido. A requisição tentou remover do local um item que não está vinculado a ele.
error.localItem.thereIsNotLocalItem Não há relacionamento entre o local {0} e o item {1} informado, verifique sua solicitação A requisição tentou editar campos customizáveis de uma relação local/item que não existe.
error.localItem.thereIsNotCustomField O identificador alternativo e o valor do campo customizável devem ser informados ao usar este endpoint A alteração de campo customizável da relação local/item foi enviada sem os dados do campo.
error.localItem.mismatchedCustomFieldAlternativeIdentifier O identificador alternativo na URI deve corresponder ao do objeto de solicitação O campo customizável informado na URI é diferente do campo customizável enviado no corpo da requisição.
error.tag.invalidEntityType Esta tag não está configurada para locais de serviço. Use uma tag cujo tipo de entidade seja local antes de vinculá-la. A tag informada existe, mas não foi criada para ser usada em locais de serviço.
error.tag.tagIsAlreadyAddedOnThisLocal Esta tag já está vinculada ao local. Remova o relacionamento existente ou escolha outra tag. A requisição tentou vincular ao local uma tag que já está vinculada.
error.tag.tagToBeDeletedIsNotInTheLocal Esta tag não está vinculada ao local, por isso não pode ser removida. A requisição tentou remover ou editar uma tag que não está vinculada ao local informado.

# Programação de tarefa

Programações de tarefas permitem a criação recorrente e configurável de tarefas na plataforma uMov.me.

# Registro de valores de cadastro customizável

Registros de valores cadastros customizáveis são as "linhas" de tabelas definidas pelo administrador do ambiente uMov.me.

# SubGrupo

A API de subgroup permite interagir com a parte "O Quê?" do uMov.me.

# Tarefa

O endpoint /tasks é responsável pela criação e manutenção de tarefas na plataforma uMov.me. Uma tarefa define quem deve executar o trabalho, onde ele será realizado, quais atividades precisam ser feitas e quando a execução deve acontecer.

Use este recurso para criar, atualizar, priorizar e complementar tarefas com atividades, itens e históricos. Em atualizações por identificador alternativo, informe o identificador alternativo da tarefa para que a API localize o registro correto. Para campos customizáveis multivalorados, consulte também a documentação de campos customizáveis e valores de campos customizáveis.

# Possíveis erros de negócio

As operações do endpoint /tasks podem retornar 400 Bad Request quando alguma regra de negócio da tarefa não for atendida. A mensagem pode variar conforme o idioma configurado na requisição, por isso use a chave do erro como referência principal para integrações e automações. A tabela abaixo apresenta a mensagem em português e explica, em linguagem direta, o motivo mais comum de cada retorno.

Quando a chave vier com complemento após :, esse complemento indica o campo ou o contexto específico que causou a validação, por exemplo field_required:initialDate. Os valores entre chaves, como {0} e {1}, são substituídos pela API com os dados da requisição ou do registro validado.

Chave Mensagem de referência Motivo do erro
no_data_provided Nenhum dado enviado O corpo da requisição não possui dados suficientes para criar ou alterar a tarefa.
resource_not_found Recurso não encontrado: {0} A tarefa, a atividade, o item, o campo de seção ou outro recurso informado na requisição não foi encontrado para o cliente autenticado.
resource_not_found:activity={id} Recurso não encontrado: activity={id} A atividade informada não está vinculada à tarefa no momento da remoção. Verifique se a atividade ainda faz parte da tarefa antes de removê-la.
more_than_one_resource:alternativeIdentifier={value} Foi encontrado mais de um recurso: alternativeIdentifier={value} O identificador alternativo informado localizou mais de um registro, use o ID interno ou corrija a duplicidade antes de tentar novamente.
field_required Campo deve ser preenchido: {0} Um campo obrigatório da tarefa não foi informado, como initialDate, initialHour, teamExecution ou fields no histórico.
field_without_informations Existe um campo sem nenhuma informação, é necessário fornecer pelo menos o identificador alternativo Um campo enviado no histórico da tarefa não possui valor nem identificador alternativo.
field_alternativeIdentifier_required O identificador alternativo do campo da seção com o valor {0} deve ser informado O histórico recebeu o valor de um campo, mas não recebeu o identificador alternativo do campo da seção.
notempty Campo não deve ser vazio: {0} Um campo estrutural obrigatório foi enviado vazio, como initialDate, serviceLocal, team ou teamExecution.
invalid O valor informado é inválido: {0} Algum valor de domínio da tarefa é inválido, como activityOrigin, teamExecution, tasktype, recorrência ou data fora da jornada de trabalho do agente.
numeric_invalid Valor numérico inválido Um valor de histórico para campo numérico não pode ser convertido para número.
invalid_quantity {0} está com uma quantidade inválida de {1} O ambiente exige equipes com apenas um agente, mas a equipe vinculada à tarefa não possui exatamente um agente.
should_not_be_greater_than {0} não deve ser maior que {1} A data/hora inicial da tarefa é maior que a data/hora final.
should_not_be_in_past Não deve ser no passado: {0} A data inicial da tarefa está no passado ou fora do limite de retroatividade permitido.
error.thereIsMoreThanOneTaskWithTheSameIdentifier Há mais de uma tarefa com o mesmo identificador alternativo. Altere este identificador ou remova a outra tarefa que está em uso. A consulta ou alteração por identificador alternativo encontrou tarefas duplicadas.
task_new_situation_permitted Uma nova tarefa pode ter apenas a situação em preparação ou pendente A criação tentou iniciar a tarefa com uma situação diferente de preparação ou pendente.
situation_not_permitted A transição de status da tarefa não é permitida. Você não pode transitar de {0} para {1}. Verifique o status atual da tarefa e escolha uma transição válida. A alteração de situação não respeita o ciclo de vida permitido para o status atual da tarefa.
task_situation_must_be_in_preparation Tarefa está com situação diferente de 'Em preparação' A operação exige uma tarefa em preparação, mas a tarefa está em outra situação.
task_inactive Tarefa está inativa A operação foi solicitada para uma tarefa inativa.
task_end_situation Esta operação não é permitida para tarefas retornadas do campo ou canceladas A tarefa já está em situação final e a operação tentou alterar dados que não podem mais ser modificados.
persistenceError.task_end_situation Não é permitido retroceder a tarefa quando sua situação está finalizada, verifique a tarefa {0} A operação tentou mover de volta uma tarefa já finalizada.
there_is_no_history_on_the_task Não é permitido alterar a situação da tarefa para retornada de campo, pois ela não possui histórico A tarefa foi enviada para retorno de campo sem possuir histórico de execução.
task_activities_with_histories Esta operação não é permitida. A atividade {0} possui histórico A operação tentou remover ou alterar uma atividade que já possui histórico na tarefa.
invalid_origin_local O local de origem é inválido ou não está disponível. Verifique o local de origem e tente novamente. O local de origem informado não pode ser usado pela tarefa.
invalid_destination_local O local de destino é inválido ou não está disponível. Verifique o local de destino e tente novamente. O local de destino informado não pode ser usado pela tarefa.
origin_service_local_has_already_been_informeed Não é possível editar o local de origem da tarefa, pois ele já foi informado A tarefa já possui local de origem e a alteração tentou modificá-lo em uma regra que não permite troca.
origin_service_local_informeed_with_null Não é possível definir o local de origem como nulo, pois ele já foi informado anteriormente. Se precisar alterar a origem, crie uma nova tarefa ou contate o suporte. A tarefa já possui local de origem e a alteração tentou remover esse valor.
invalid_agent_and_local Combinação de agente e local é inválida: {0} O agente informado não é responsável pelo local de serviço, conforme a validação de carteira ou portfólio.
already_in_use_by_agent Agente já possui tarefas agendadas para esse período O agente já possui outra tarefa no mesmo período.
has_ignore_schedule_absence Existe ausência programada configurada para a pessoa no período informado A tarefa foi criada/alterada para um agente que possui ausência programada no período.
cycle_related_field_changed Não é possível modificar este campo quando a tarefa está vinculada a um ciclo de trabalho. Os seguintes campos são protegidos: local de serviço, agente, data de início e data de término. Conclua o ciclo atual ou crie uma nova tarefa. A tarefa está vinculada a ciclo de trabalho e a alteração tentou modificar serviceLocal, agent, initialDate, finalDate ou reativar um registro protegido.
can_not_be_activated Não é possível reativar este registro porque ele está vinculado a um ciclo de trabalho ou agendamento. Crie um novo registro ou mantenha este inativo ou cancelado. A alteração tentou reativar tarefa vinculada a ciclo de trabalho ou agendamento.
should_not_be_canceled_or_retrieved Esta operação não é permitida para tarefas que foram canceladas ou retornadas do campo. Verifique o status da tarefa e tente novamente. A operação não pode ser executada em tarefa cancelada ou retornada do campo.
task.routeplan.update.forbidden_situation O plano de rota somente pode ser removido nas seguintes situações: preparação ou pendente de envio para campo A operação tentou remover o plano de rota em uma situação não permitida.
no_activities_added Nenhuma atividade foi informada: {0} A origem das atividades exige atividades informadas manualmente, mas a lista de atividades foi enviada vazia.
no_default_activity_configured_for Não existem atividades padrão configuradas para {0} A tarefa usa atividades padrão por origem, mas não há atividades configuradas para ambiente, pessoa, local de serviço ou tipo de tarefa.
error.taskActivityWithoutIdentifier Uma ou mais atividades informadas na criação da tarefa estão com identificador nulo Alguma atividade enviada na tarefa não possui ID ou identificador alternativo.
error.taskItemWithoutIdentifier Um ou mais itens informados na criação da tarefa estão com identificador nulo Algum item enviado na tarefa não possui ID ou identificador alternativo.
error.taskWithDuplicateItems Tarefa com itens duplicados: um ou mais itens informados na tarefa foram enviados mais de uma vez, verifique a requisição A lista de itens possui o mesmo item repetido.
error.taskObservationExceededCharacterLimit A observação da tarefa está excedendo o limite de caracteres permitido, o máximo de caracteres é 500. A observação da tarefa possui mais de 500 caracteres.
activityHistory.historyId.required O historyId é obrigatório. Uma operação de histórico de atividade foi enviada sem historyId.
task.distribution.execution_date_not_today A tarefa não pode ser distribuída porque a data de execução é diferente da data atual. A distribuição só permite tarefas com execução prevista para a data corrente.
task.distribution.already_has_agent A tarefa não pode ser distribuída porque já possui um agente vinculado A tarefa já está atribuída a um agente.
task.distribution.team_required A tarefa não possui equipe vinculada. A tarefa precisa ter equipe para ser distribuída.
distribution.action_type.invalid Tipo de ação inválido. O tipo de ação informado para distribuição não é suportado.
task.distribution.different_teams Tarefas com equipes diferentes O grupo informado para distribuição contém tarefas de equipes diferentes.
task.distribution.group_without_tasks Não há tarefas para o grupo solicitado O grupo solicitado não possui tarefas elegíveis para distribuição.
error.prioritizeTasks Erro ao priorizar tarefas Ocorreu um erro ao alterar a prioridade ou o período pelo endpoint de priorização.
unexpected_error Ocorreu um erro inesperado ao processar sua requisição. Tente novamente. Se o problema persistir, contate o suporte com o código de erro fornecido. A regra de negócio retornou uma inconsistência inesperada durante criação, edição ou alteração parcial da tarefa.

# Tipos de agente

O endpoint /agentType é responsável pela criação e manutenção dos tipos de agente da plataforma uMov.me. Um tipo de agente representa uma categoria de pessoa de campo ou usuário operacional, como entregador, motorista, gerente, analista, supervisor ou qualquer outra classificação necessária ao negócio.

Use este recurso para criar, atualizar, complementar e remover tipos de agente. Depois de criado, o tipo pode ser usado no cadastro de agentes para classificar perfis operacionais, facilitar filtros, organizar equipes e adaptar a gestão de pessoas à operação do cliente.

# Possíveis erros de negócio

As operações do endpoint /agentType podem retornar 400 Bad Request ou 404 Not Found quando alguma regra de negócio do tipo de agente não for atendida. A mensagem pode variar conforme o idioma configurado na requisição, por isso use a chave do erro como referência principal para integrações e automações. A tabela abaixo apresenta a mensagem em português e explica, em linguagem direta, o motivo mais comum de cada retorno.

Quando a chave vier com complemento após :, esse complemento indica o campo, o identificador ou o contexto específico que causou a validação, por exemplo error.agentTypeAlreadyExists:Supervisor. Os valores entre chaves, como {0} e {1}, são substituídos pela API com os dados da requisição ou do registro validado.

Chave Mensagem de referência Motivo do erro
resource_not_found Recurso não encontrado: {0} O tipo de agente informado na atualização não foi encontrado para o cliente autenticado. Verifique o ID ou o identificador alternativo antes de continuar.
more_than_one_resource Foi encontrado mais de um recurso: {0} A requisição encontrou mais de um registro para a mesma referência. Use um identificador único antes de continuar.
more_than_one_resource:alternativeIdentifier={value} Foi encontrado mais de um recurso: alternativeIdentifier={value} O identificador alternativo informado já está associado a um tipo de agente existente ou encontrou mais de um registro. Use o ID interno ou corrija a duplicidade.
field_required Campo deve ser preenchido: {0} Um campo obrigatório do tipo de agente não foi informado, como description.
error.teamNameRequired O nome da equipe deve ser obrigatório A descrição do tipo de agente não foi informada ou foi enviada vazia. Informe um nome para identificar o tipo de agente.
error.agentTypeAlreadyExists Já existe um tipo ou jornada de trabalho com esta descrição para este cliente. Use uma descrição única. Já existe outro tipo de agente com a mesma descrição para o cliente autenticado. Use uma descrição única antes de continuar.
error.thereIsMoreThanOneAgentTypeWithTheSameIdentifier Há mais de um tipo de agente com o mesmo identificador alternativo. Por favor, altere este identificador ou remova o outro que está em uso. O identificador alternativo informado está duplicado entre tipos de agente ou já pertence a outro tipo. Ajuste o identificador alternativo antes de criar, atualizar ou remover o registro.
error.agentTypeNotFound Tipo de agente não encontrado. Por favor, verifique o identificador fornecido e tente novamente. A remoção foi solicitada para um tipo de agente inexistente ou indisponível para o cliente autenticado. Verifique o ID ou o identificador alternativo antes de tentar novamente.
error.requestTimeOut Sua solicitação excedeu o tempo limite. Por favor, faça uma nova tentativa. A API não conseguiu persistir o tipo de agente dentro do tempo esperado. Tente novamente e, se o erro persistir, revise o volume de requisições ou acione o suporte.
persistence_error Ocorreu um erro de validação, verifique sua solicitação com o nome {0} e tente novamente. A API encontrou uma falha ao salvar o tipo de agente. Revise os dados enviados e tente novamente.

# Tipos de tarefa

"Os tipos de tarefa no umov.me representam categorias personalizáveis que podem ser definidas com base no contexto e nas necessidades do seu negócio. Por exemplo, é possível criar tipos como 'entregas', 'avaliações' ou quaisquer outras categorias relevantes para a sua operação.

Uma vez criado, o tipo de tarefa pode ser utilizado ao configurar novas tarefas, permitindo especificar seu propósito e categoria. Essa funcionalidade proporciona maior flexibilidade e personalização na gestão de tarefas, garantindo que o sistema esteja alinhado às particularidades do seu negócio."

# Tipos de atividade

A API de tipo de atividades.

# Tipos de locais

A API de tipo de locais.

# Tags

A API de tags.

Última atualização: 6/17/2026, 2:21:08 PM

←