openapi: 3.0.3
info:
title: API Version 3 coverage shipments API
version: 3.0.0
description: "This is the documentation for the public api *(version 3)* of 99minutos. [https://www.99minutos.com/.](https://www.99minutos.com/.EnvironmentAPI)\n\n# First Steps\n\n1. Create an account in the sandbox website: [https://delivery-git-sandbox-99minutos.vercel.app/](https://delivery-git-sandbox-99minutos.vercel.app/)\n2. Go to Developers section\n3. On API Keys V3 section click on `Generar`\n4. After this the `client_id` and `client_secret` will be displayed\n \n\nUse the credentials to generate access tokens as shown below in the endpoint `create access token`\n\nFollow the same process in production.\n\n## Environments\n\n| **Environment** | **Website** | **API url** |\n| --- | --- | --- |\n| Sandbox | [https://delivery-git-sandbox-99minutos.vercel.app/](https://delivery-git-sandbox-99minutos.vercel.app/) | [https://sandbox.99minutos.com](https://sandbox.99minutos.com) |\n| Production | [https://envios.99minutos.com/developers](https://envios.99minutos.com/developers) | [https://delivery.99minutos.com](https://delivery.99minutos.com) |\n\n`Each environment has an independent set of credentials`"
servers:
- url: https://delivery.99minutos.com
description: Produccion
- url: https://sandbox.99minutos.com
description: Sandbox Environment
tags:
- name: shipments
paths:
/api/v3/shipments/{id}:
parameters:
- schema:
type: string
name: id
in: path
required: true
description: trackingId or internalKey
get:
summary: ''
tags:
- shipments
responses:
'200':
$ref: '#/components/responses/ShipmentDetailResponse'
operationId: get-api-v3-shipments-id
description: Return a shipment given an trackingId or internalKey
security:
- AuthJWT: []
patch:
operationId: shipments_partial_update
description: 'Update the destination address of a shipment. The shipment must be in one of the following statuses:
DRAFT
CONFIRMED
UNSUCCESSFULLPICKUP
ONROADTOPICKUP
COLLECTED
STORED'
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- shipments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedShipmentUpdate'
examples:
Payload example:
value:
destination:
address: Cda. de Guaymas 8, Roma Nte., Cuauhtémoc, 06700 Ciudad de México, CDMX, Mexico
country: MEX
reference: Torre 3 Apartamente 905
zipcode: '15900'
description: ''
security:
- AuthJWT: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentUpdate'
examples:
Example response:
value:
traceId: ad050ab1-9344-4753-b2ce-d5a218de14f8
message: OK
data:
sender:
firstName: Esteban
lastName: Ramirez
phone: '+52999999999'
email: esteban@gmail.com
recipient:
firstName: Carlos
lastName: Gonzalez
phone: '+52999999999'
email: esteban@gmail.com
origin:
locationId: 2753165a-c300-4710-ad69-a7a766a939c2
lat: 19.410353
lng: -99.09836
address: Av. del Taller 452, Jardín Balbuena, Álvaro Obregón, 15900 Ciudad de México, CDMX, México
country: MEX
type: private
reference: Primer Piso
zipcode: '15900'
destination:
locationId: d20f80ab-ce65-4424-a359-04b9ba6b48f5
lat: 19.425213
lng: -99.153984
address: Cda. de Guaymas 8, Roma Nte., Cuauhtémoc, 06700 Ciudad de México, CDMX, Mexico
country: MEX
type: private
reference: Torre 3 Apartamente 905
zipcode: '15900'
payments:
paymentMethod: cash
cashOnDelivery:
amount: 100
currency: MXN
options:
pickUpAfter: '2022-10-24T23:22:51.057000'
deliveryBetween: {}
notes: '**Information to be printed on the label**'
items:
- id: e034e8e4-4f35-4156-be4b-7b9cac4e4224
size: l
description: This is the description
weight: 1000
length: 50
width: 30
height: 20
id: aFqvmecyn29mAJ182qnS6vo1kLDtoKYi
internalKey: 1f5907e6-ae32-4c98-98e7-6f5bc8d2da82
deliveryType: SPT
trackingId: 2753512370
deactivated: false
errors: ''
description: ''
delete:
summary: ''
operationId: delete-api-v3-shipments-id
description: Cancels an order by trackingId or internalKey.
requestBody:
content:
application/json:
schema:
type: object
x-examples:
Example 1:
reason: Lorem impsm
properties:
reason:
type: string
description: Reason for cancellation
required:
- reason
examples:
Reason Cancellation example:
value:
reason: El cliente canceló
description: Must provide a reason
tags:
- shipments
responses:
'200':
$ref: '#/components/responses/ShipmentDeactiveResponse'
parameters:
- schema:
type: string
enum:
- trackingId
- internalKey
example: trackingId
in: query
name: by
description: specifies whether the order is to be searched by trackingId or internalKey
security:
- AuthJWT: []
/api/v3/shipments/tracking:
get:
operationId: shipments_tracking_retrieve
description: 'Track a shipment by the given identifier. Get all information about the shipments with the related events and data. **Remember that if you are thinking of implementing a recurring pull system on this endpoint, you must limit requests to a maximum of 8 per second. However, we also offer a real-time webhook notification system so you get every change in the status of the shipments, which is more efficient than pulling. For more information go to the webhooks section**
| **STATUS CODE** | **STATUS NAME** | **DESCRIPTION** |
| --- | --- | --- |
| 1001 | DRAFT | It is the first status when the shipment is created `in draft mode`. It means that the shipment is not yet ready by the client and its flow will not start until it is confirmed. Note that the draft value is passed when creating the order and defaults to false. Therefore, this status is only passed through if the draft was previously set to true when creating the order. |
| 1002 | CONFIRMED | The shipment has been confirmed. It is the first status to trigger the logistics operation. It is the first default state when creating an order (false draft) or when confirming a shipment that was previously created as a draft. |
| 2002 | ON_ROAD_TO_PICKUP | The shipment is on its way to be picked up. So a driver is heading to the point of origin. *`Does not apply to p99`* |
| 2003 | COLLECTED | The shipment has been collected and is in the domain of an associated driver of 99minutos. |
| 2101 | UNSUCCESSFUL_PICKUP | The shipment could not be collected. Within the response object, the attempt attribute is added with the number of collection attempts. `See examples` |
| 3001 | STORED | The shipment is stored in a wharehouse for 99minutos. |
| 3004 | ON_LINEHAUL | The shipment is in transit between stations for 99minutos `Not all shipments go through this state.` |
| 4001 | ON_ROAD_TO_DELIVERY | The shipment has left the network of 99minutos stations to the final destination |
| 4002 | DELIVERED | The shipment has been successfully delivered to its recipient |
| 4101 | UNSUCCESSFUL_DELIVERY | The shipment could not be delivered. Inside the response object, the attempt attribute is added with the number of delivery attempts. `See examples` |
| 5001 | ON_ROAD_TO_RETURN | Shipping on the way to return. The return occurs when it is not possible to deliver the package to the recipient and it is returned to the origin |
| 5002 | RETURNED | The shipment has been returned to the origin successfully |
| 5101 | UNSUCCESSFUL_RETURN | The shipment could not be returned. Inside the response object, the attempt attribute is added with the number of return attempts. `See examples` |
| 7101 | IN_CORRECTION | In some cases the information of origin, destination, etc. may not be precise enough to make the shipment. Therefore, this status indicates that some information of the shipment must be corrected. |
| 7102 | CORRECTED | If the shipment required correction, it indicates that this has already been done. |
| 8001 | STOLEN | In extremely rare cases for reasons other than 99minutos the shipment is stolen. `This is extremely rare.` |
| 8003 | CANCELLED | The shipment has been canceled via API by the client |
| 8004 | DAMAGED | The shipment was damaged during delivery. |'
parameters:
- in: query
name: identifier
schema:
type: integer
format: int64
description: The identifier represent a internalKey or trackingId of one shipment.
tags:
- shipments
security:
- AuthJWT: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TrackingResponse'
examples:
TrackingStatus:
value:
traceId: 73801b36-15d9-4bc2-9874-06772578ad95
message: Shipment found.
data:
events:
- statusCode: '1002'
statusName: CONFIRMED
data: {}
metadata: {}
createdAt: '2021-12-20 07:30:23'
- statusCode: '2003'
statusName: COLLECTED
data:
comment: Recolectada por el veloz Don veloz Base dd9932d
metadata: {}
createdAt: '2021-12-20 11:03:58'
- statusCode: '3001'
statusName: STORED
data:
comment: En estación MX2 por módulo de inducción
metadata: {}
createdAt: '2021-12-20 16:10:41'
- statusCode: '3004'
statusName: ON_LINEHAUL
data:
milleSegment: middle
comment: En camino a estación Toluca desde estación Tultitlán por operarios.tultitlan el número de orden 2727370887
metadata: {}
createdAt: '2021-12-20 16:36:01'
- statusCode: '3001'
statusName: STORED
data:
location: station
milleSegment: first
comment: Cambiado a la estación por jose.delgado el número de orden 2727370887
metadata: {}
createdAt: '2021-12-21 08:12:21'
- statusCode: '3001'
statusName: STORED
data:
location: station
milleSegment: first
comment: Cambiado a la estación por jose.delgado el número de orden 2727370887
metadata: {}
createdAt: '2021-12-21 08:13:48'
- statusCode: '4001'
statusName: ON_ROAD_TO_DELIVERY
data:
attempt: 1
comment: Auto-rea-asignada por el veloz Don veloz GUI TOL 65829
metadata: {}
createdAt: '2021-12-21 08:25:59'
- statusCode: '4001'
statusName: ON_ROAD_TO_DELIVERY
data:
attempt: 1
comment: Auto-rea-asignada por el veloz Don veloz GUI TOL 65829
metadata: {}
createdAt: '2021-12-21 08:34:29'
- statusCode: '4002'
statusName: DELIVERED
data:
attempt: 1
comment: Titular | alejandro castillo,
evidence:
- https://xxxxxx
metadata: {}
createdAt: '2021-12-21 14:32:42'
errors: {}
summary: Tracking status
description: Tracking status response
description: ''
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequest'
examples:
TooManyRequests:
value: 'HTTP/1.1 429 Too Many RequestsContent-type: text/htmlRetry-After: 3600'
summary: Too many requests
description: if you are thinking of implementing a recurring pull system on this endpoint, you must limit requests to a maximum of 8 per second.
description: ''
/api/v3/shipments/tracking/batch:
get:
operationId: shipments_tracking_batch_retrieve
description: 'Batch tracking can add multiple identifiers of the following format --> `/api/v3/shipments/tracking/batch?identifiers={trackingId}&identifiers={trackingId}`
Track a shipment by the given identifier. Get all information about the shipments with the related events and data. **Remember that if you are thinking of implementing a recurring pull system on this endpoint, you must limit requests to a maximum of 8 per second. However, we also offer a real-time webhook notification system so you get every change in the status of the shipments, which is more efficient than pulling. For more information go to the webhooks section**
| **STATUS CODE** | **STATUS NAME** | **DESCRIPTION** |
| --- | --- | --- |
| 1001 | DRAFT | It is the first status when the shipment is created `in draft mode`. It means that the shipment is not yet ready by the client and its flow will not start until it is confirmed. Note that the draft value is passed when creating the order and defaults to false. Therefore, this status is only passed through if the draft was previously set to true when creating the order. |
| 1002 | CONFIRMED | The shipment has been confirmed. It is the first status to trigger the logistics operation. It is the first default state when creating an order (false draft) or when confirming a shipment that was previously created as a draft. |
| 2002 | ON_ROAD_TO_PICKUP | The shipment is on its way to be picked up. So a driver is heading to the point of origin. *`Does not apply to p99`* |
| 2003 | COLLECTED | The shipment has been collected and is in the domain of an associated driver of 99minutos. |
| 2101 | UNSUCCESSFUL_PICKUP | The shipment could not be collected. Within the response object, the attempt attribute is added with the number of collection attempts. `See examples` |
| 3001 | STORED | The shipment is stored in a wharehouse for 99minutos. |
| 3004 | ON_LINEHAUL | The shipment is in transit between stations for 99minutos `Not all shipments go through this state.` |
| 4001 | ON_ROAD_TO_DELIVERY | The shipment has left the network of 99minutos stations to the final destination |
| 4002 | DELIVERED | The shipment has been successfully delivered to its recipient |
| 4101 | UNSUCCESSFUL_DELIVERY | The shipment could not be delivered. Inside the response object, the attempt attribute is added with the number of delivery attempts. `See examples` |
| 5001 | ON_ROAD_TO_RETURN | Shipping on the way to return. The return occurs when it is not possible to deliver the package to the recipient and it is returned to the origin |
| 5002 | RETURNED | The shipment has been returned to the origin successfully |
| 5101 | UNSUCCESSFUL_RETURN | The shipment could not be returned. Inside the response object, the attempt attribute is added with the number of return attempts. `See examples` |
| 7101 | IN_CORRECTION | In some cases the information of origin, destination, etc. may not be precise enough to make the shipment. Therefore, this status indicates that some information of the shipment must be corrected. |
| 7102 | CORRECTED | If the shipment required correction, it indicates that this has already been done. |
| 8001 | STOLEN | In extremely rare cases for reasons other than 99minutos the shipment is stolen. `This is extremely rare.` |
| 8003 | CANCELLED | The shipment has been canceled via API by the client |
| 8004 | DAMAGED | The shipment was damaged during delivery. |'
parameters:
- in: query
name: identifiers
schema:
type: integer
format: int64
description: The identifier represent a internalKey or trackingId of one shipment.
tags:
- shipments
security:
- AuthJWT: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TrackingBatchResponse'
description: ''
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequest'
examples:
TooManyRequests:
value: 'HTTP/1.1 429 Too Many RequestsContent-type: text/htmlRetry-After: 3600'
summary: Too many requests
description: if you are thinking of implementing a recurring pull system on this endpoint, you must limit requests to a maximum of 8 per second.
description: ''
components:
schemas:
DeliveryType2faEnum:
enum:
- SMD
- SPT
- 99M
- CO2F
- RET
- NAL
- P2P
type: string
CurrencyEnum:
enum:
- COP
- MXN
- CLP
- PEN
- ARP
type: string
Payment:
type: object
description: Payment options are included in this section
properties:
insured:
type: boolean
insuredValue:
type: number
format: double
description: Amount in local currency for which the shipment will be insured. The shipment will be insured in case of damage, loss, theft. Extra fees could be applied, check with your support agent.
cashOnDelivery:
allOf:
- $ref: '#/components/schemas/Embedded'
description: Cash on delivery (COD) applies to shipments paid by the recipient in cash at the time of delivery. If it is not sent in the payload, it is assumed that this does not happen, otherwise the amount and currency fields must be included
Option:
type: object
description: Options to customize the shipment.
properties:
pickUpAfter:
type: string
format: date-time
description: Date time from which the shipment is available for pickup
deliveryBetween:
type: object
additionalProperties:
type: string
format: date-time
requiresIdentification:
type: boolean
requiresSignature:
type: boolean
twoFactorAuth:
type: boolean
description: Code is required to mark the order as delivered. Needs to be activated previously
notes:
type: string
description: Notes that will be displayed on the label
PatchedShipmentUpdate:
type: object
description: 'Update shipment serializer.
Only the origin and destination fields can be updated.
The deliveryType is not in read only fields because
is required for the covered'
properties:
destination:
$ref: '#/components/schemas/Location'
x-examples:
Example update order destination:
destination:
address: Cda. de Guaymas 8, Roma Nte., Cuauhtémoc, 06700 Ciudad de México, CDMX, Mexico
country: MEX
reference: Torre 3 Apartamente 905
zipcode: '15900'
Event:
type: object
properties:
statusCode:
allOf:
- $ref: '#/components/schemas/StatusCodeEnum'
statusName:
allOf:
- $ref: '#/components/schemas/StatusNameEnum'
data:
type: object
additionalProperties: {}
readOnly: true
metadata:
type: object
additionalProperties: {}
readOnly: true
createdAt:
type: string
format: date-time
readOnly: true
required:
- statusCode
- statusName
- data
- metadata
- createdAt
Sender:
type: object
description: Person who will receive the shipment.
properties:
firstName:
type: string
description: Name of the person receiving or sending the shipment.
lastName:
type: string
description: Last name of the person receiving or sending the shipment.
phone:
type: string
description: Phone of the person receiving or sending the shipment. Must include the international code (+52, +51)
example: '+525547596221'
email:
type: string
format: email
description: Email of the person receiving or sending the shipment.
required:
- firstName
- lastName
- phone
- email
TrackingBatchResponse:
type: object
properties:
traceId:
type: string
example: c0510fb7-0e73-4cc1-8f0b-f1ae632d2bd6
message:
type: string
example: OK
data:
type: array
items:
type: object
properties:
trackingId:
type: string
example: '2763022166'
events:
type: array
items:
type: object
properties:
statusCode:
type: string
example: '8003'
statusName:
type: string
example: CANCELLED
data:
type: object
properties:
comment:
type: string
example: ''
metadata:
type: object
createdAt:
type: string
format: date-time
example: '2023-08-21T23:18:23.979000-05:00'
TrackingResponse:
type: object
properties:
traceId:
type: string
readOnly: true
message:
type: string
readOnly: true
data:
$ref: '#/components/schemas/Event'
errors:
type: object
additionalProperties: {}
readOnly: true
required:
- data
- errors
- message
- traceId
description: ''
Location:
type: object
description: 'Location where the package is picked up.
Depending on the flow you choose,
you must send different parameters.
A location is a geographical point that can be taken as the origin and/or destination of a shipment.
There are 3 ways in which you can define a location, feel free to choose the one that best suits your business rules.
Each one is described below.
1. Coords-based
It is the option with the best precision to define an origin or destination.
Latitude and longitude are taken to define the location
2. LocationId-based
A LocationId is a uuid that identifies a single geographic point.
The locationId is generated by this API (check out the Get Location id request in Locations folder).
By using locationId, no further data needs to be passed.
It is useful when you have the same point in several shipments since you can reuse the locationId.
3. Address string-based
In this option the client sends only the address. We will process the address to obtain the other data.
However, if the address does not contain information necessary to locate it,
the system will return a 400 error and the order will not be created, so you must handle the error.
It is important to emphasize that in the two previous flows there is no possibility to reject an order for the location'
properties:
locationId:
type: string
format: uuid
description: LocationId is a uuid that identifies a single geographic point.
lat:
type: number
format: double
maximum: 90
minimum: -90
description: Longitude coordinates
lng:
type: number
format: double
maximum: 180
minimum: -180
description: Lattitude coordinates
address:
type: string
description: Text sentence that references the location. This address will be printed on the labels.
country:
allOf:
- $ref: '#/components/schemas/LocationCountryEnum'
reference:
type: string
description: Any other text that enrich the address of the location such apartment, Suite, Box number, Tower, etc.
zipcode:
type: string
description: Location zipcode. If it is not included we will try to extract the zipcode from the address. So if your address does not include zipcode, you must include it in this field
nullable: true
city:
type: string
description: Text that reference the city of the location
Item:
type: object
description: Array of items/packages to send.
properties:
id:
type: string
format: uuid
readOnly: true
nullable: true
size:
$ref: '#/components/schemas/ItemSizeEnum'
description:
type: string
weight:
type: integer
minimum: 1
description: Measurement in grams of weight
length:
type: integer
minimum: 1
description: Horizontal measurement in centimeters take from one end to the other of the longer or longest side of an object
width:
type: integer
minimum: 1
description: Horizontal measurement in centimeters taken from one end to the other of theshorter or shortest side of an object
height:
type: integer
minimum: 1
description: Vertical measure in centimeters of distance from base to top
required:
- id
- size
- weight
TooManyRequest:
type: object
properties:
message:
type: string
required:
- message
Recipient:
type: object
description: Person who will receive the shipment.
properties:
firstName:
type: string
description: Name of the person receiving or sending the shipment.
lastName:
type: string
description: Last name of the person receiving or sending the shipment.
phone:
type: string
description: Phone of the person receiving or sending the shipment. Must include the international code (+52, +51)
example: '+525547596221'
email:
type: string
format: email
description: Email of the person receiving or sending the shipment.
required:
- firstName
- lastName
- phone
- email
ItemSizeEnum:
enum:
- xs
- s
- m
- l
- xl
- xxl
- unknown
- '-'
type: string
Embedded:
type: object
description: 'Serializer for EmbeddedDocuments.
Skips id field and uniqueness validation.
When saving, skips calling instance.save'
properties:
amount:
type: number
format: double
currency:
$ref: '#/components/schemas/CurrencyEnum'
required:
- amount
- currency
LocationCountryEnum:
enum:
- MEX
- COL
- CHL
- PER
type: string
StatusNameEnum:
enum:
- SHIPMENT_TO_BE_CONFIRMED
- CONFIRMED
- ON_ROAD_TO_PICKUP
- COLLECTED
- UNSUCCESSFUL_PICKUP
- STORED
- ON_LINEHAUL
- ON_ROAD_TO_DELIVERY
- DELIVERED
- UNSUCCESSFUL_DELIVERY
- ON_ROAD_TO_RETURN
- RETURNED
- UNSUCCESSFUL_RETURN
- IN_CORRECTION
- CORRECTED
- STOLEN
- CANCELLED
- DAMAGED
type: string
StatusCodeEnum:
enum:
- '1001'
- '1002'
- '2002'
- '2003'
- '2101'
- '3001'
- '3004'
- '4001'
- '4002'
- '4101'
- '5001'
- '5002'
- '5101'
- '7101'
- '7102'
- '8001'
- '8003'
- '8004'
type: string
ShipmentUpdate:
type: object
description: 'Update shipment serializer.
Only the origin and destination fields can be updated.
The deliveryType is not in read only fields because
is required for the covered'
properties:
sender:
$ref: '#/components/schemas/Sender'
recipient:
$ref: '#/components/schemas/Recipient'
origin:
$ref: '#/components/schemas/Location'
destination:
$ref: '#/components/schemas/Location'
payments:
$ref: '#/components/schemas/Payment'
options:
$ref: '#/components/schemas/Option'
items:
type: array
items:
$ref: '#/components/schemas/Item'
id:
type: string
readOnly: true
internalKey:
type: string
readOnly: true
description: Unique shipment identifier. You can use this field to store your unique identifier of the shipment. All of our tracking systems support searching by internalKey. We strongly suggest you always use this field and make sure it is unique.If its not given we will assign an uuid for this field.
deliveryType:
$ref: '#/components/schemas/DeliveryType2faEnum'
trackingId:
type: integer
readOnly: true
apiVersion:
type: integer
default: 3
required:
- deliveryType
- destination
- id
- internalKey
- items
- options
- origin
- recipient
- sender
- trackingId
se
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/99-minutos/refs/heads/main/openapi/99-minutos-shipments-api-openapi.yml