openapi: 3.0.3
info:
  title: Skydropx Pro Address Templates Shipments API
  description: 'The Skydropx Pro API is a REST interface for the Skydropx multi-carrier shipping and logistics platform (Mexico and Latin America). It lets you request multi-carrier rate quotations, create shipments and purchase labels, schedule carrier pickups, manage saved address templates, track parcels, and read the prepaid account credit balance. All requests are authenticated with an OAuth2 client-credentials Bearer token obtained from POST /oauth/token using your client_id and client_secret. Tokens are valid for about two hours and requests are rate limited to roughly two per second.


    Grounding note: base URLs, the OAuth2 client-credentials flow, the token endpoint, the rate limit, and the resource paths below are grounded in Skydropx''s public API documentation (docs.skydropx.com and pro.skydropx.com/es-MX/api-docs). Request and response SCHEMAS are MODELED from documented fields and common shipping-API conventions and should be reconciled against the live reference before production use. A separate classic Skydropx API (https://api.skydropx.com/v1, authenticated with an `Authorization: Token token=API_KEY` header) and a Radar tracking API (https://radar-api.skydropx.com/v1) also exist and are not modeled here.'
  version: '1.0'
  contact:
    name: Skydropx
    url: https://www.skydropx.com/
servers:
- url: https://pro.skydropx.com/api/v1
  description: Skydropx Pro production
- url: https://sb-pro.skydropx.com/api/v1
  description: Skydropx Pro sandbox
security:
- oauth2ClientCredentials: []
tags:
- name: Shipments
  description: Create, list, retrieve, cancel, and protect shipments.
paths:
  /shipments:
    get:
      operationId: listShipments
      tags:
      - Shipments
      summary: List shipments
      description: Lists shipments, optionally filtered by status and date range.
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: status
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A page of shipments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Shipment'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createShipment
      tags:
      - Shipments
      summary: Create a shipment
      description: Creates a shipment from a quotation and a selected rate, purchasing the label and debiting the prepaid account balance. Requires SAT consignment-note (Carta Porte) codes for applicable Mexican shipments.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentInput'
      responses:
        '201':
          description: The created shipment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /shipments/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getShipment
      tags:
      - Shipments
      summary: Retrieve a shipment
      description: Retrieves a shipment by id, including its label URL and tracking data.
      responses:
        '200':
          description: The requested shipment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /shipments/{id}/cancellations:
    parameters:
    - $ref: '#/components/parameters/Id'
    post:
      operationId: cancelShipment
      tags:
      - Shipments
      summary: Cancel a shipment
      description: Requests cancellation of a shipment and refund of the label where eligible.
      responses:
        '201':
          description: The cancellation request.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /shipments/{id}/protect:
    parameters:
    - $ref: '#/components/parameters/Id'
    post:
      operationId: protectShipment
      tags:
      - Shipments
      summary: Add shipment protection
      description: Adds optional parcel protection / insurance coverage to a shipment.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '201':
          description: The protected shipment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Rate:
      type: object
      properties:
        id:
          type: string
        provider:
          type: string
          description: Carrier name, e.g. estafeta, fedex, dhl.
        service_level:
          type: string
        total_pricing:
          type: string
          description: Total price for the service.
        currency:
          type: string
          example: MXN
        days:
          type: integer
          description: Estimated transit days.
      additionalProperties: true
    Shipment:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        tracking_number:
          type: string
        label_url:
          type: string
          format: uri
        rate:
          $ref: '#/components/schemas/Rate'
        address_from:
          $ref: '#/components/schemas/Address'
        address_to:
          $ref: '#/components/schemas/Address'
        created_at:
          type: string
          format: date-time
      additionalProperties: true
    Error:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties: true
    ShipmentInput:
      type: object
      required:
      - quotation_id
      - rate_id
      - address_from
      - address_to
      properties:
        quotation_id:
          type: string
        rate_id:
          type: string
        address_from:
          $ref: '#/components/schemas/Address'
        address_to:
          $ref: '#/components/schemas/Address'
        parcels:
          type: array
          items:
            $ref: '#/components/schemas/Parcel'
        consignment_note_class_code:
          type: string
          description: SAT product classification code (Carta Porte).
        consignment_note_packaging_code:
          type: string
          description: SAT packaging code (Carta Porte).
      additionalProperties: true
    Address:
      type: object
      description: A shipping address (origin, destination, or saved template).
      properties:
        id:
          type: string
        name:
          type: string
        company:
          type: string
        street1:
          type: string
        street2:
          type: string
        city:
          type: string
        province:
          type: string
        zip:
          type: string
        country:
          type: string
          description: ISO country code, e.g. MX.
        phone:
          type: string
        email:
          type: string
        reference:
          type: string
      additionalProperties: true
    Parcel:
      type: object
      description: Parcel dimensions and weight.
      properties:
        length:
          type: number
          description: Length in centimeters.
        width:
          type: number
          description: Width in centimeters.
        height:
          type: number
          description: Height in centimeters.
        weight:
          type: number
          description: Weight in kilograms.
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: string
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      description: 'OAuth2 client-credentials flow. Exchange client_id and client_secret at POST /oauth/token for a Bearer access token, sent as `Authorization: Bearer ACCESS_TOKEN`. Tokens last about two hours.'
      flows:
        clientCredentials:
          tokenUrl: https://pro.skydropx.com/api/v1/oauth/token
          scopes: {}