openapi: 3.0.3
info:
title: API Version 3 coverage Orders 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: Orders
paths:
/api/v1/orders/multibox:
post:
tags:
- Orders
summary: Create multibox orders
description: 'Create multibox orders. N child shipments will be created plus the master shipment. The number of child shipments is determined by the `packages` field, and by default, always 1 master shipment is created.
'
operationId: createMultiboxOrder
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MultiboxOrderRequest'
responses:
'201':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BadRequestResponse1'
- $ref: '#/components/schemas/BadRequestResponse2'
- $ref: '#/components/schemas/BadRequestResponse3'
/api/v3/orders/{orderid}/confirm:
parameters:
- schema:
type: string
name: orderid
in: path
required: true
description: orderId of the order that will be confirmed
post:
operationId: orders_confirm_create
description: Confirm change the value draft to False for the given order id
tags:
- Orders
security:
- AuthJWT: []
- {}
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
traceId:
type: string
message:
type: string
data:
type: object
properties: {}
errors:
type: object
properties: {}
x-examples:
Example 1:
traceId: 5f57e3c6-5933-4e1b-a9dc-f77495604a59
message: order confirmed successfully
data: {}
errors: {}
examples:
Order confirmed:
value:
traceId: 5f57e3c6-5933-4e1b-a9dc-f77495604a59
message: order confirmed successfully
data: {}
errors: {}
/api/v3/orders/{id}:
parameters:
- schema:
type: string
name: id
in: path
required: true
description: Database identifier order id
get:
operationId: orders_retrieve
description: 'Return a order given an encoded order id.
The order id must be MongoDB identifier'
parameters:
- in: path
name: id
schema:
type: string
required: true
tags:
- Orders
security:
- AuthJWT: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
Retrieve order id:
value:
traceId: 7d4253dc-0785-468f-9d21-402d0797caac
message: OK
data:
- id: aG0yvr3yDwQin97ZRjyyyVkGi4NrNEob
shipments:
- sender:
firstName: Esteban
lastName: Ramirez
phone: '+52999999999'
email: esteban@gmail.com
recipient:
firstName: Carlos
lastName: Gonzalez
phone: '+52999999999'
email: esteban@gmail.com
origin:
lat: 19.413574
lng: -99.11359
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:
lat: 19.041694
lng: -98.2035678
address: Av 9 Pte 308, Centro histórico de Puebla, Puebla, Pue., México
country: MEX
type: private
reference: Torre 3 Apartamente 905
zipcode: '72000'
payments:
paymentMethod: ''
cashOnDelivery:
amount: 100
currency: MXN
options:
pickUpAfter: '2023-05-09T22:59:17.448000'
deliveryBetween:
start: '2023-01-01T08:00:00'
end: '2023-01-20T08:00:00'
notes: '**Information to be printed on the label**'
items:
- id: 6107173d-536c-4351-92ee-82a6402f19ee
size: l
description: This is the description
weight: 1000
length: 50
width: 30
height: 20
id: aG0yvr3yDwQin97ZRjyyyVkGi4NrNEoa
internalKey: 2aa0b908-edb1-4688-afe5-34489ecf8b53
deliveryType: SPT
trackingId: 2098099475
apiVersion: 3
account:
client_id: ''
apikey: ''
draft: false
createdAt: '2023-05-09T22:59:51.521000'
expiresAt: '2023-07-08T22:59:51.521000'
errors: []
description: ''
/api/v3/orders:
get:
operationId: orders_list
description: Get the list of active orders.
parameters:
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
- name: page_size
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
tags:
- Orders
security:
- AuthJWT: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedOrderList'
description: ''
post:
operationId: orders_create
description: Create orders.
tags:
- Orders
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
CreateOrderCoords-based:
value:
shipments:
- internalKey: ''
deliveryType: SPT
sender:
firstName: Esteban
lastName: Ramirez
phone: '+52999999999'
email: esteban@gmail.com
recipient:
firstName: Carlos
lastName: Gonzalez
phone: '+52999999999'
email: esteban@gmail.com
origin:
lat: 19.413574
lng: -99.11359
address: Av. del Taller 451, Jardín Balbuena, Álvaro Obregón, 15900 Ciudad de México, CDMX, México
country: MEX
reference: Primer Piso
city: Ciudad de México
zipcode: '15900'
destination:
lat: 19.041694
lng: -98.2035678
address: Av 9 Pte 308, Centro histórico de Puebla, Puebla, Pue., México
city: Ciudad de México
reference: Torre 3 Apartamente 905
country: MEX
zipcode: '72000'
payments:
paymentMethod: cash
cashOnDelivery:
amount: 100
currency: MXN
options:
pickUpAfter: '2022-02-01T08:00:00.000Z'
requiresIdentification: false
requiresSignature: false
twoFactorAuth: false
notes: '**Information to be printed on the label**'
items:
- size: s
description: lorem ipsum
weight: 1000
length: 50
width: 30
height: 20
draft: true
summary: Create order Coords-based
description: It is the option with the best precision to define an origin or destination. Latitude and longitude are taken to define the location
CreateOrderLocationId-based:
value:
shipments:
- internalKey: ''
deliveryType: SPT
sender:
firstName: Esteban
lastName: Ramirez
phone: '+52999999999'
email: esteban@gmail.com
recipient:
firstName: Carlos
lastName: Gonzalez
phone: '+52999999999'
email: esteban@gmail.com
origin:
locationId: 1d9dc137-137a-4966-897b-75b5f837d319
destination:
locationId: 441a79d4-0682-4bca-a2d6-1fff4c2c86fb
payments:
paymentMethod: cash
cashOnDelivery:
amount: 100
currency: MXN
options:
pickUpAfter: '2022-02-01T08:00:00.000Z'
requiresIdentification: false
requiresSignature: false
twoFactorAuth: false
notes: '**Information to be printed on the label**'
items:
- size: s
description: lorem ipsum
weight: 1000
length: 50
width: 30
height: 20
draft: true
summary: Create order LocationId-based
description: 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.
CreateOrderAddressString-based:
value:
shipments:
- internalKey: ''
deliveryType: SPT
sender:
firstName: Esteban
lastName: Ramirez
phone: '+52999999999'
email: esteban@gmail.com
recipient:
firstName: Carlos
lastName: Gonzalez
phone: '+52999999999'
email: esteban@gmail.com
origin:
address: C. de Venustiano, Centro Histórico, Cuauhtémoc, 06000 Ciudad de México, CDMX, México
country: MEX
city: Ciudad de México
reference: Piso 1
zipcode: '06000'
destination:
address: Calz. del Peñón 139, Azteca, Venustiano Carranza, 15320 Ciudad de México, CDMX, México
country: MEX
city: Ciudad de México
zipcode: '15320'
payments:
paymentMethod: cash
cashOnDelivery:
amount: 100
currency: MXN
options:
pickUpAfter: '2022-02-01T08:00:00.000Z'
requiresIdentification: false
requiresSignature: false
twoFactorAuth: false
notes: '**Information to be printed on the label**'
items:
- size: s
description: lorem ipsum
weight: 1000
length: 50
width: 30
height: 20
draft: true
summary: Create order Address string-based
description: 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
CreateOrderWithDeliveryDateRange:
value:
shipments:
- internalKey: ''
deliveryType: SPT
sender:
firstName: Esteban
lastName: Ramirez
phone: '+52999999999'
email: esteban@gmail.com
recipient:
firstName: Carlos
lastName: Gonzalez
phone: '+52999999999'
email: esteban@gmail.com
origin:
address: C. de Venustiano, Centro Histórico, Cuauhtémoc, 06000 Ciudad de México, CDMX, México
country: MEX
reference: Piso 1
zipcode: '06000'
destination:
address: Calz. del Peñón 139, Azteca, Venustiano Carranza, 15320 Ciudad de México, CDMX, México
country: MEX
zipcode: '15320'
payments:
paymentMethod: cash
cashOnDelivery:
amount: 100
currency: MXN
options:
pickUpAfter: '2022-02-01T08:00:00.000Z'
deliveryBetween:
start: '2022-02-02T12:00:00.000Z'
end: '2022-02-02T20:00:00.000Z'
requiresIdentification: false
requiresSignature: false
twoFactorAuth: false
notes: '**Information to be printed on the label**'
items:
- size: s
description: lorem ipsum
weight: 1000
length: 50
width: 30
height: 20
draft: true
summary: Create order with delivery date range
description: In the options field you can set a delivery date range. Start and end keys represent date on which the package can be delivered
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Order'
multipart/form-data:
schema:
$ref: '#/components/schemas/Order'
required: true
security:
- AuthJWT: []
- {}
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
examples:
OrderSuccessfullyCreated:
value:
traceId: fdecb33d-2769-458d-b319-835b1c73d8f6
message: order created successfully
data:
id: aFr0bwewwEm3EDChXLs2J5xbsbe3hEP5
shipments:
- sender:
firstName: Jorge benito
lastName: Ramon
phone: '+52999797429'
email: jorge@gmail.com
recipient:
firstName: Carlos
lastName: Gonzalez
phone: '+52999999'
email: esteban@gmail.com
origin:
lat: 19.413574
lng: -99.11359
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:
lat: 19.041694
lng: -98.2035678
address: Av 9 Pte 308, Centro histórico de Puebla, Puebla, Pue., México
country: MEX
type: private
reference: Torre 3 Apartamente 905
zipcode: '72000'
payments:
paymentMethod: ''
cashOnDelivery:
amount: 100
currency: MXN
options:
pickUpAfter: '2022-11-15T06:33:26.166575'
deliveryBetween:
start: '2022-02-02T12:00:00.000Z'
end: '2022-02-02T20:00:00.000Z'
notes: '**Information to be printed on the label**'
items:
- id: e0f954b2-d7fe-48e6-963f-d377149944d7
size: l
description: This is the description
weight: 1000
length: 50
width: 30
height: 20
id: aFr0bwewwEm3EDChXLs2J5xbsbe3hEP4
internalKey: 394e84ef-6837-48cd-b9af-9e2cf039d642
deliveryType: SPT
trackingId: 3186136841
account:
client_id: 57c38a44-d056-4f06-8d26-1ce40d0f7f05
apikey: 7cef77a8-70e1-4649-a104-c913e5d9f5b8
draft: false
createdAt: '2022-11-15T06:33:26.921806'
expiresAt: '2023-01-14T06:33:26.921806'
errors: {}
summary: Order successfully created
description: Order successfully created response
description: ''
'202':
content:
application/json:
schema:
type: object
properties:
traceId:
type: string
example: 248607db-e0c8-4b2c-816b-3ef0ab0ec06f
description: ID de traza para el seguimiento interno.
message:
type: string
example: Internal key already exists for the client.
description: Mensaje descriptivo del error.
data:
type: array
items: {}
description: Datos adicionales relacionados con el error.
errors:
type: object
description: Objeto que contiene detalles específicos del error.
description: ''
'400':
content:
application/json:
schema:
type: object
properties:
traceId:
type: string
example: 1861d6cc-11bc-4b8c-b881-c9341eedc5df
description: ID de traza para el seguimiento interno.
message:
type: string
example: The body data is invalid. Please check the docs
description: Mensaje descriptivo del error.
data:
type: array
items: {}
example: []
description: Datos adicionales relacionados con el error.
errors:
type: object
properties:
shipments:
type: array
items:
type: object
properties:
destination:
type: object
properties:
address:
type: array
items:
type: string
example:
- You must provide an address.
description: Detalles de los errores relacionados con la dirección de destino.
description: Objeto que contiene detalles específicos del error para los envíos.
description: Objeto que contiene detalles específicos del error.
description: ''
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseJWT'
examples:
ExampleErrorTokenResponse:
value:
message: Jwt is expired
code: 401
description: ''
'412':
content:
application/json:
schema:
type: object
properties:
traceId:
type: string
example: 5896c0d9-bccf-4b5d-a8fa-b8859a2fa9e2
description: ID de traza para el seguimiento interno.
message:
type: string
example: There is no coverage for the selected origin and destination. If you wish to validate our coverage in advance, please go to the /coverage endpoints
description: Mensaje descriptivo del error.
data:
type: array
items: {}
example: []
description: Datos adicionales relacionados con el error.
errors:
type: object
description: Objeto que contiene detalles específicos del error.
description: ''
/api/v3/orders/multibox:
post:
operationId: orders_multibox_create
description: 'Create a multibox order that groups multiple packages (children) under a single parent order (master). All children share the same origin, destination, sender and recipient. Useful when a single shipment contains multiple parcels that must travel together.
Minimum 1 child, maximum 20 children per order.
'
tags:
- Orders
security:
- AuthJWT: []
- {}
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MultiboxRequest'
examples:
MultiboxOrderExample:
value:
deliveryType: SMD
packageSize: xs
destination:
address: Calz. Gral. Mariano Escobedo 595, Ciudad de Mexico, Miguel Hidalgo, Bosque de Chapultepec I Secc, 11580
country: MEX
zipcode: '11580'
lat: 0
lng: 0
origin:
address: C. PUENTE 186 S/N COAPA TLALPAN CD DE MEXICO
country: MEX
zipcode: '14390'
lat: 0
lng: 0
options:
notes: Dejar en puerta
sender:
firstName: Cecilia
lastName: Magana
email: cecilia@99minutos.com
phone: '+525555555544'
recipient:
firstName: Laura
lastName: Flores
email: laura@99minutos.com
phone: '+525533668777'
internalKey: test123-1234567890123-0123456789
children:
- internalKey: test123-1234567-1
items:
- weight: 300
height: 10
width: 10
length: 10
size: xs
summary: Create multibox order
description: Example payload for creating a multibox order with one child package
responses:
'200':
description: Multibox order created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/MultiboxResponse'
examples:
MultiboxSuccessResponse:
value:
traceId: abc123def456
message: Multibox order received successfully
data:
master: 99M-XXXXXXXXXX
children:
- tracking_id: 99M-YYYYYYYYYY
internal_key: test123-1234567-1
client_id: client-id-123
errors: []
summary: Multibox order created
description: Successful multibox order creation response
'400':
description: Invalid request body. The JSON payload could not be parsed.
content:
application/json:
schema:
$ref: '#/components/schemas/MultiboxErrorResponse'
examples:
InvalidRequestBody:
value:
traceId: abc123def456
errors:
- code: GENERIC_INVALID_PARAMETERS
message: Invalid request body
'401':
description: Authentication error. JWT is missing, malformed, or expired.
content:
application/json:
schema:
$ref: '#/components/schemas/MultiboxErrorResponse'
examples:
JWTExpired:
value:
traceId: abc123def456
errors:
- code: JWT_EXPIRED
message: JWT token has expired
JWTMissing:
value:
error: Missing or invalid JWT token
code: '401'
'422':
description: Validation or business rule error. The request fields do not meet the required validations or a business rule was not satisfied.
content:
application/json:
schema:
$ref: '#/components/schemas/MultiboxErrorResponse'
examples:
ValidationError:
value:
traceId: abc123def456
errors:
- code: GENERIC_INVALID_PARAMETERS
message: origin.address must be between 10 and 300 characters
field: origin.address
CustomerInactive:
value:
traceId: abc123def456
errors:
- code: CUSTOMER_INACTIVE
message: Customer is not active
InternalKeyAlreadyExists:
value:
traceId: abc123def456
errors:
- code: INTERNAL_KEY_ALREADY_EXISTS
message: internalKey 'test123' already exists
DeliveryTypeNotActive:
value:
traceId: abc123def456
errors:
- code: CUSTOMER_DELIVERY_TYPE_NOT_ACTIVE
message: Delivery type SMD is not active for the customer
'500':
description: Internal server error. An unexpected error occurred during order processing.
content:
application/json:
schema:
$ref: '#/components/schemas/MultiboxErrorResponse'
examples:
GeocodingError:
value:
traceId: abc123def456
errors:
- code: GEOCODING_SERVICE_ERROR
message: Geocoding service returned empty response
StateMachineError:
value:
traceId: abc123def456
errors:
- code: STATE_MACHINE_ERROR_RESPONSE
message: 'state machine returned status code: 500'
GenericError:
value:
traceId: abc123def456
errors:
- code: GENERIC_500_ERROR
message: Internal server error
components:
schemas:
Destination:
type: object
properties:
receiver:
type: string
example: David Ludueña
nameReceiver:
type: string
example: David
lastNameReceiver:
type: string
example: Ludueña
emailReceiver:
type: string
example: ''
phoneReceiver:
type: string
example: '11111111'
addressDestination:
type: string
example: Calle Prol. Melchor, Miguel de la Madrid, Iztapalapa, 09698 Ciudad de México, CDMX
numberDestination:
type: string
example: s/r
codePostalDestination:
type: string
example: 09698
country:
type: string
enum:
- MEX
- CHL
- PER
- COL
example: MEX
CurrencyEnum:
enum:
- COP
- MXN
- CLP
- PEN
- ARP
type: string
MultiboxLocation:
type: object
description: Location for origin
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/99-minutos/refs/heads/main/openapi/99-minutos-orders-api-openapi.yml