LH (Line Haul) Monitoring - Incidents API

Authentication: All endpoints require OAuth.

Table of Contents

  1. Query Incident Types
  2. Create Incident
  3. Upload Incident Attachments
  4. Set Incident as Root Cause

1. Query Incident Types

Introduction

The Incident Types API provides the list of incident types that can be reported.

Important:

  • OAuth will be used for security

Request

GET https://api.mercadolibre.com/travel-execution/{site_id}/incidents/types?scope=stage
ParameterTypeDescription
site_idStringCountry identifier for the query. Example: Brazil (MLB)
scopeStringQuery scope. Example: stage (test environment) or production (production environment)

Response

json
1[
2  { "id": "REFUEL_VEHICLE", "description": "Fuel refill" },
3  { "id": "HEAVY_TRAFFIC", "description": "Heavy traffic" }
4]

The response returns HTTP status 200 (OK) with an array of objects containing the id and description fields. If no incident types exist, the array will be empty.

FieldTypeDescription
idStringIncident type ID
descriptionStringHuman-readable description of the incident type

The id field is used when creating an incident.

2. Create Incident

Introduction

The API allows creating new incidents in the travel execution system. This endpoint accepts incident data and creates a new incident record.

Important:

  • OAuth will be used for security
  • All fields in the request body are required
  • The incident type must be a valid type from the Incident Types API

Request

POST https://api.mercadolibre.com/travel-execution/incidents?scope=stage

The scope query parameter is required and must be stage for the test environment or production for the production environment.

ParameterTypeDescription
site_idStringCountry identifier for the incident. Example: MLB (Brazil)
travel_idStringUnique travel identifier
stop_sequenceNumberSequence number of the stop where the incident occurred
typeStringIncident type (must be a valid type from the Incident Types API)
affected_goal_idStringWhich goal is affected by the incident? (ORIGIN_EXPECTED_ARRIVAL_DATE, DESTINATION_EXPECTED_ARRIVAL_DATE, or CRITICAL_PULL_TIME)
date_occurredString (ISO 8601)Date and time when the incident occurred
expected_duration_in_minutesNumberExpected duration of the incident in minutes
descriptionStringDetailed description of the incident
location_referenceStringLocation reference where the incident occurred

Request Body

json
1{
2  "site_id": "MLB",
3  "travel_id": "1",
4  "stop_sequence": 1,
5  "type": "REFUEL_VEHICLE",
6  "affected_goal_id": "DESTINATION_EXPECTED_ARRIVAL_DATE",
7  "date_occurred": "2022-03-18T23:11:59Z",
8  "expected_duration_in_minutes": 40,
9  "description": "Fuel refill incident",
10  "location_reference": "Near São Paulo"
11}

Response

json
1{ "incident_id": 1 }

The response returns HTTP status 200 (OK) with the identifier of the created incident in the response body.

HTTP Status Codes

CodeDescription
200OK - Incident created successfully
400Bad Request - Invalid payload or missing required fields
403Forbidden - Creation not authorized
404Not Found - Travel not found

3. Upload Incident Attachments

Introduction

The API allows uploading files as attachments to existing incidents in the LH Monitoring system.

Important:

  • OAuth will be used for security
  • Files must be sent using multipart/form-data format
  • Supported file types: pdf, png, jpeg, and jpg

Request

POST https://api.mercadolibre.com/travel-execution/incidents/{incident_id}/attachments/upload?scope=stage
ParameterTypeDescription
incident_idStringUnique identifier of the incident to which the attachment will be uploaded
scopeStringOperation scope. Example: stage (test environment) or production (production environment)
attachmentFileThe file to be uploaded as an attachment (multipart/form-data)

Response

json
1{ "message": "attachment uploaded successfully" }

The response returns HTTP status 201 (Created) when the upload is successful.

HTTP Status Codes

CodeDescription
201Created - Upload completed successfully
400Bad Request - Invalid payload or missing required fields
403Forbidden - Upload not authorized
404Not Found - Incident not found

4. Set Incident as Root Cause

Introduction

The API allows marking (or unmarking) an existing incident as the root cause of a travel. Use this endpoint after creating one or more incidents on the same travel, when you need to point out which one was the underlying cause.

Important:

  • OAuth will be used for security
  • Send root_cause: true to mark the incident as root cause
  • Send root_cause: false to unmark — useful when the wrong incident was previously selected
  • The carrier identity is taken from your authenticated request; you do not need to send any user identifier

Request

PUT https://api.mercadolibre.com/travel-execution/incidents/{incident_id}/root-cause?scope=stage

The scope query parameter is required and must be stage for the test environment or production for the production environment.

ParameterTypeDescription
incident_idStringUnique identifier of the incident to mark or unmark as the root cause
scopeStringOperation scope. Example: stage (test environment) or production (production environment)
root_causeBooleanBody field. true marks the incident as root cause; false unmarks it

Request Body

json
1{
2  "root_cause": true
3}

Response

json
1{ "message": "incident set as root cause" }

The response returns HTTP status 200 (OK) when the operation is successful.

HTTP Status Codes

CodeDescription
200OK - Root cause flag updated successfully
400Bad Request - Invalid incident_id format or malformed body
403Forbidden - Carrier is not the owner of the travel that holds the incident
404Not Found - Incident not found