openapi: 3.0.3
info:
  title: Skydropx Pro 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: Authentication
    description: OAuth2 client-credentials token issuance.
  - name: Quotations
    description: Multi-carrier rate quotations for a parcel.
  - name: Shipments
    description: Create, list, retrieve, cancel, and protect shipments.
  - name: Orders and Labels
    description: Orders and their generated shipping label URLs.
  - name: Pickups
    description: Schedule and manage carrier pickups (recolecciones).
  - name: Address Templates
    description: Reusable saved addresses and carrier validation.
  - name: Tracking
    description: Track shipments and report tracking events.
  - name: Finance
    description: Prepaid credit balance and extra charges.
  - name: Catalog
    description: Carrier services, packagings, and consignment-note codes.
paths:
  /oauth/token:
    post:
      operationId: createToken
      tags:
        - Authentication
      summary: Issue an OAuth2 access token
      description: >-
        Exchanges a client_id and client_secret for a Bearer access token using
        the client_credentials grant. Send as
        application/x-www-form-urlencoded. Tokens are valid for about two hours.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - client_id
                - client_secret
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                client_id:
                  type: string
                client_secret:
                  type: string
      responses:
        '200':
          description: An access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /quotations:
    post:
      operationId: createQuotation
      tags:
        - Quotations
      summary: Create a rate quotation
      description: >-
        Requests multi-carrier shipping rates for a parcel between an origin and
        destination postal code. Returns a quotation with available carrier
        services, prices, and delivery estimates. The chosen rate id is used to
        create a shipment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuotationInput'
      responses:
        '201':
          description: The created quotation with rates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quotation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /quotations/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getQuotation
      tags:
        - Quotations
      summary: Retrieve a quotation
      description: Retrieves a previously created quotation and its rates by id.
      responses:
        '200':
          description: The requested quotation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quotation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /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'
  /shipments/tracking/{tracking_number}:
    parameters:
      - name: tracking_number
        in: path
        required: true
        description: The carrier tracking number.
        schema:
          type: string
    get:
      operationId: trackShipment
      tags:
        - Tracking
      summary: Track a shipment
      description: Retrieves the current tracking status and event history for a tracking number.
      responses:
        '200':
          description: Tracking status and events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tracking'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /shipments/tracking:
    post:
      operationId: reportTrackingEvent
      tags:
        - Tracking
      summary: Report a tracking event
      description: Reports a tracking event for a fleet or externally fulfilled shipment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '201':
          description: The recorded tracking event.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /orders:
    get:
      operationId: listOrders
      tags:
        - Orders and Labels
      summary: List orders
      description: Lists all orders.
      responses:
        '200':
          description: A list of orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createOrder
      tags:
        - Orders and Labels
      summary: Create an order
      description: Creates a new order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
      responses:
        '201':
          description: The created order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /orders/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getOrder
      tags:
        - Orders and Labels
      summary: Retrieve an order
      description: Retrieves an order by id.
      responses:
        '200':
          description: The requested order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateOrder
      tags:
        - Orders and Labels
      summary: Update an order
      description: Updates an existing order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
      responses:
        '200':
          description: The updated order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /orders/{id}/labels:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getOrderLabels
      tags:
        - Orders and Labels
      summary: Get order label URLs
      description: Retrieves the generated shipping label URLs (PDF) for an order.
      responses:
        '200':
          description: Label URLs for the order.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Label'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /pickups:
    get:
      operationId: listPickups
      tags:
        - Pickups
      summary: List pickups
      description: Lists all scheduled carrier pickups.
      responses:
        '200':
          description: A list of pickups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Pickup'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPickup
      tags:
        - Pickups
      summary: Schedule a pickup
      description: Schedules a carrier pickup (recoleccion) for one or more shipments.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PickupInput'
      responses:
        '201':
          description: The scheduled pickup.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pickup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /pickups/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getPickup
      tags:
        - Pickups
      summary: Retrieve a pickup
      description: Retrieves a pickup by id.
      responses:
        '200':
          description: The requested pickup.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pickup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /pickups/reschedule:
    post:
      operationId: reschedulePickup
      tags:
        - Pickups
      summary: Reschedule a pickup
      description: Reschedules an existing pickup to a new date.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The rescheduled pickup.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pickup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /pickups/coverage:
    get:
      operationId: getPickupCoverage
      tags:
        - Pickups
      summary: Check pickup coverage
      description: Checks available pickup dates for a location and carrier.
      responses:
        '200':
          description: Available pickup dates.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /address_templates:
    get:
      operationId: listAddressTemplates
      tags:
        - Address Templates
      summary: List address templates
      description: Retrieves all saved address templates.
      responses:
        '200':
          description: A list of address templates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Address'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAddressTemplate
      tags:
        - Address Templates
      summary: Create an address template
      description: Creates a new saved address template.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Address'
      responses:
        '201':
          description: The created address template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /address_templates/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getAddressTemplate
      tags:
        - Address Templates
      summary: Retrieve an address template
      description: Retrieves a saved address template by id.
      responses:
        '200':
          description: The requested address template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateAddressTemplate
      tags:
        - Address Templates
      summary: Update an address template
      description: Updates a saved address template.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Address'
      responses:
        '200':
          description: The updated address template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      operationId: deleteAddressTemplate
      tags:
        - Address Templates
      summary: Delete an address template
      description: Deletes a saved address template.
      responses:
        '204':
          description: The address template was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /address_templates/{id}/verify_by_carriers:
    parameters:
      - $ref: '#/components/parameters/Id'
    post:
      operationId: verifyAddressByCarriers
      tags:
        - Address Templates
      summary: Validate an address with carriers
      description: Validates a saved address against carrier serviceability.
      responses:
        '200':
          description: Validation result per carrier.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /finance/credits:
    get:
      operationId: getCredits
      tags:
        - Finance
      summary: Get account credit balance
      description: Returns the current prepaid account credit (wallet) balance.
      responses:
        '200':
          description: The account credit balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credits'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /finance/extra-charges:
    get:
      operationId: listExtraCharges
      tags:
        - Finance
      summary: List extra charges
      description: Lists surcharges and extra charges applied to shipments, with pagination.
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: A page of extra charges.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /shipments/carrier_services:
    get:
      operationId: listCarrierServices
      tags:
        - Catalog
      summary: List carrier services
      description: Lists the carrier services available to the account.
      responses:
        '200':
          description: Available carrier services.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /shipments/packagings:
    get:
      operationId: listPackagings
      tags:
        - Catalog
      summary: List packaging codes
      description: Lists packaging type codes usable when creating shipments.
      responses:
        '200':
          description: Packaging codes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /shipments/consignment_notes:
    get:
      operationId: listConsignmentNotes
      tags:
        - Catalog
      summary: List consignment-note codes
      description: >-
        Lists SAT Carta Porte consignment-note codes (product classes, packaging)
        required for applicable Mexican shipments.
      responses:
        '200':
          description: Consignment-note codes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /office_points:
    get:
      operationId: listOfficePoints
      tags:
        - Catalog
      summary: List office / drop-off points
      description: Retrieves office and drop-off point locations for a carrier or rate.
      responses:
        '200':
          description: Office points.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  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: {}
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties: true
    AccessToken:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          description: Token lifetime in seconds (about 7200).
        created_at:
          type: integer
    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.
    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
    QuotationInput:
      type: object
      required:
        - zip_from
        - zip_to
        - parcel
      properties:
        zip_from:
          type: string
          description: Origin postal code.
        zip_to:
          type: string
          description: Destination postal code.
        parcel:
          $ref: '#/components/schemas/Parcel'
        carriers:
          type: array
          description: Optional list of carriers to restrict the quote to.
          items:
            type: string
      additionalProperties: true
    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
    Quotation:
      type: object
      properties:
        id:
          type: string
        zip_from:
          type: string
        zip_to:
          type: string
        parcel:
          $ref: '#/components/schemas/Parcel'
        rates:
          type: array
          items:
            $ref: '#/components/schemas/Rate'
      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
    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
    Label:
      type: object
      properties:
        id:
          type: string
        label_url:
          type: string
          format: uri
        tracking_number:
          type: string
        format:
          type: string
          example: pdf
      additionalProperties: true
    OrderInput:
      type: object
      properties:
        reference:
          type: string
        address_to:
          $ref: '#/components/schemas/Address'
        parcels:
          type: array
          items:
            $ref: '#/components/schemas/Parcel'
      additionalProperties: true
    Order:
      allOf:
        - $ref: '#/components/schemas/OrderInput'
        - type: object
          properties:
            id:
              type: string
            status:
              type: string
            created_at:
              type: string
              format: date-time
    PickupInput:
      type: object
      properties:
        carrier:
          type: string
        date:
          type: string
          format: date
        address:
          $ref: '#/components/schemas/Address'
        shipment_ids:
          type: array
          items:
            type: string
      additionalProperties: true
    Pickup:
      allOf:
        - $ref: '#/components/schemas/PickupInput'
        - type: object
          properties:
            id:
              type: string
            status:
              type: string
            confirmation_number:
              type: string
    Tracking:
      type: object
      properties:
        tracking_number:
          type: string
        status:
          type: string
          description: Current status, e.g. created, picked_up, in_transit, delivered, exception.
        events:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
              description:
                type: string
              occurred_at:
                type: string
                format: date-time
            additionalProperties: true
      additionalProperties: true
    Credits:
      type: object
      properties:
        balance:
          type: string
          description: Current prepaid wallet balance.
        currency:
          type: string
          example: MXN
      additionalProperties: true