Error messages – Planning | Maplink Developers

Erros de validação

As seguintes mensagens de erros podem ser retornadas devido a omissão ou o preenchimento errado de algum parâmetro. O código de erro retornado na API será 400 (Bad Request), o json retornádo terá a seguinte estrutura:

{
    "logId": "5e8f64f0-0ece-4e26-84c3-7ff889eff092",
    "message": "Validation failed",
    "errors": [
        "sites may not be empty",
        "operations[0].customerSite reference not found",
        "operations[1].customerSite reference not found"
    ]
}

A tabela abaixo mostra as validações aplicadas para cada entidade e a mensagem de erro retornada:

Parâmetro	Validações	Mensagens de Erro
sites	notEmpty	may not be empty
depots	notEmpty	may not be empty
operations	notEmpty	may not be empty
vehicleTypes	notEmpty	may not be empty
vehicles	notEmpty	may not be empty
products	notEmpty	may not be empty
legislationProfiles	notEmpty	may not be empty
logisticConstraints	notEmpty	may not be empty
optimizationProfile	notBlank	is mandatory
optimizationProfile	invalid profile	optimizationProfile {name} not found
tripsProfile	notBlank	is mandatory
startDate	notNull	is mandatory

Tabela de regras de validação para as principais entidades

As tabelas abaixos mostram as validações aplicadas para cada entidade específica:

operations
Parâmetro	Validações	Mensagens de Erro
id	notBlank, unique	is mandatory, already exists
weight	notNull, notNegative	is mandatory, may not be negative
volume	notNull, notNegative	is mandatory, may not be negative
product	notBlank, validReference	is mandatory, reference not found
type	notBlank, isContainedIn	is mandatory, does not have a valid value. Allowed values: [COLLECTION, DELIVERY]
priority	notNegative	may not be negative
depotSite	notBlank, validReference	is mandatory, reference not found
customerSite	notBlank, validReference	is mandatory, reference not found
customerTimeWindows	notEmpty	may not be empty

Tabela de regras de validação para o parâmetro operations

vehicles
Parâmetro	Validações	Mensagens de Erro
name	notBlank, unique	is mandatory, already exists
vehicleType	notBlank, validReference	is mandatory, reference not found
legislationProfile	notBlank, validReference	is mandatory, reference not found
availablePeriods	notEmpty	may not be empty
priority	notNegative	may not be negative

Tabela de regras de validação para o parâmetro vehicles

vehicleTypes
Parâmetro	Validações	Mensagens de Erro
name	notNull, unique	is mandatory, already exists
maxWeight	notNull, notNegative	is mandatory, may not be negative
maxVolume	notNull, notNegative	is mandatory, may not be negative
size	notNegative	may not be negative
maxSitesNumber	notNegative	may not be negative
compartmentsAccessMode	notNull, isContainedIn	is mandatory, does not have a valid value. Allowed values: [ALL_COMPARTMENTS, REAR_ACCESS]
trip.calculationMode	notNull	is mandatory
trip.toll.vehicleType	notNull	is mandatory

Tabela de regras de validação para o parâmetro vehicleTypes

sites e depots
Parâmetro	Validações	Mensagens de Erro
name	notBlank, unique	is mandatory, already exists
coordinates	notNull	is mandatory
coordinates.latitude	notNull, range(-90, 90)	is mandatory, must be between -90 and 90
coordinates.longitude	notNull, range(-180, 180)	is mandatory, must be between -180 and 180
logisticConstraints	notBlank, validReference	is mandatory, reference not found

Tabela de regras de validação para os parâmetro sites e depots

legislationProfile
Parâmetro	Validações	Mensagens de Erro
name	notBlank, unique	is mandatory, already exists
maxContinuousDrivingTime	greaterThanZero	must be greater than zero
drivingPauseDuration	greaterThanZero	must be greater than zero
maxContinuousWorkingTime	greaterThanZero	must be greater than zero
workingPauseDuration	greaterThanZero	must be greater than zero

Tabela de regras de validação para o parâmetro legislationProfile

callback
Parâmetro	Validações	Mensagens de Erro
url	notNull	is mandatory
url	Invalid url	does not have a valid value. Example of allowed values: http://www.foo.br, https://www.foo.br, http://www.foo.br/bar

Tabela de regras de validação para o parâmetro callback

As validações abaixo se aplicam às janelas horárias descritas nos parâmetros vehicles[n].availablePeriods, operations[n].customerTimeWindows e operations[n].depotTimeWindows:

timeWindow
Parâmetro	Validações	Mensagens de Erro
start	notNull	is mandatory
end	notNull	is mandatory
start, end	start < end	must have the start less than to the end
start, end	start != end	must not start the same as the end
end	end < startDate	must have at least one timeWindow with end after problem’s startDate

Tabela de regras de validação para os parâmetros referentes à janela horária.

Erros de processamento

As seguintes mensagens de erros podem ser retornadas ao consultar o status de processamento da requisição através dos endpoints https://api.maplink.global/planning/v1/events?jobId={{planningId}} e https://api.maplink.global/planning/v1/jobs/{{planningId}}.

A mensagem de erro seguem a seguinte estrutura:

{
        "id": "688d267a74be5d22a1ac9002",
        "jobId": "688d26787766ef668397ff50",
        "type": "ERROR",
        "description": "{'logId':'db496388-c45a-4902-af42-0971578cbb38','errors':[{'code':'TECHNICAL_ERROR','description':'global.maplink.matrixinprocessor.exception.ProcessException: [ProcessError(code=INVALID_SITE_POSITION, description=Some sites have not been positionned, detail=[Cliente1])]'}]}",
        "createdAt": 1754080890262
    }

O evento retorna com o type igual a ERROR e as seguintes mensagens podem ser retornadas em description:

Mensagem de erro	Causa
{‘logId’:’{{logId}}‘,’errors’: [{‘code’:’TECHNICAL_ERROR’,’description’:’Not possible to create route between sites {{siteId}} and {{siteId}}‘}]}	Não foi possível achar um caminho entre os dois pontos. Pode ser que o ponto esteja mal-posicionado ou realmente não exista um caminho, como um ponto em uma via sem sáida e com mão única, por exemplo.
Error in process MRS: Cannot find point {{latitude}},{{longitude}}	Não foi possível encontrar a localização das coordenadas informadas. Pode ser que alguma coordenada seja inválida, caindo no ocenao por exemplo.

Tabela de mensagens de erros de processamento

Exemplo de uma rota com mensagem de erro:

[
    {
        "id": "688d29735e59ee6e88b67adb",
        "jobId": "688d29737766ef668397ff52",
        "type": "STATUS_CHANGE",
        "description": "ENQUEUED",
        "createdAt": 1754081651310
    },
    {
        "id": "688d297374be5d22a1ac900b",
        "jobId": "688d29737766ef668397ff52",
        "type": "STATUS_CHANGE",
        "description": "CONVERT_TO_MATRIX",
        "createdAt": 1754081651314
    },
    {
        "id": "688d29735e59ee6e88b67adc",
        "jobId": "688d29737766ef668397ff52",
        "type": "PERCENT_CHANGE",
        "description": "1",
        "createdAt": 1754081651317
    },
    {
        "id": "688d297308fc0e441d9e9d23",
        "jobId": "688d29737766ef668397ff52",
        "type": "STATUS_CHANGE",
        "description": "PROCESSING",
        "createdAt": 1754081651339
    },
    {
        "id": "688d29745e59ee6e88b67add",
        "jobId": "688d29737766ef668397ff52",
        "type": "ERROR",
        "description": "{'logId':'e687f91b-e4ce-4cbf-b6c5-8e304e281617','errors':[{'code':'TECHNICAL_ERROR','description':Not possible to create route between sites OP-1 and OP-2'}]},
        "createdAt": 1754081652037
    }
]

Artigo anterior Planning

Status Codes – Planning

Próximo artigo Trip