Error messages – Planning
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 |
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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
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 |
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. |
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
}
]
