Envia.com Shipments API

openapi: 3.2.0
info:
  title: Envia Queries Shipments API
  version: v2.3.1
  description: Read-only service for lookups, lists, and account utilities. This API provides access to countries, states, cities, carriers, services, and address structure information needed for shipping operations. Use this API to get the required information for building shipping forms and validating addresses. The Queries API is designed for developers who need read-only access to reference data such as supported carriers, available services, shipment history, and user account settings. It serves as the lookup layer of the Envia platform, enabling applications to populate dropdowns, validate inputs, and retrieve shipment details without modifying any data.
  contact:
    name: Envia API Support
    url: https://docs.envia.com/discuss
  license:
    name: Proprietary
    url: https://www.envia.com/terminos-y-condiciones
  termsOfService: https://www.envia.com/terminos-y-condiciones
servers:
- url: https://queries.test.envia.com/
  description: Sandbox/Test
- url: https://queries.envia.com/
  description: Production
security:
- bearerAuth: []
tags:
- name: Shipments
  description: Retrieve shipment details, history, and download labels
paths:
  /guide/{MM}/{YYYY}:
    get:
      tags:
      - Shipments
      summary: Get Shipments by Month and Year
      description: 'Retrieves all shipments created under your account for a specific calendar month and year. Returns a summary list including tracking numbers, carriers, statuses, and creation dates.


        **When to use:** Call this endpoint to build shipment history dashboards, generate monthly shipping reports, reconcile invoices, or audit shipment volumes for a given period.


        **Prerequisites:**

        - Valid JWT token in the Authorization header

        - Month (`MM`) as a zero-padded two-digit string (01-12)

        - Year (`YYYY`) as a four-digit string


        **Key behaviors:**

        - Returns all shipments for the authenticated account within the specified month

        - Results include `tracking_number`, `carrier`, `status`, and `created_at` for each shipment

        - The `tracking_number` from the response can be used with `GET /guide/{tracking_number}` to fetch full shipment details

        - Large result sets may be paginated; check the response for pagination metadata'
      operationId: shipments-by-month-year
      parameters:
      - name: MM
        in: path
        required: true
        description: Month (01-12)
        schema:
          type: string
          pattern: ^(0[1-9]|1[0-2])$
          example: '03'
      - name: YYYY
        in: path
        required: true
        description: Year (4 digits)
        schema:
          type: string
          pattern: ^[0-9]{4}$
          example: '2024'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indicates if the request was successful
                  data:
                    type: array
                    description: List of shipments
                    items:
                      type: object
                      properties:
                        tracking_number:
                          type: string
                          description: Tracking number
                        carrier:
                          type: string
                          description: Carrier name
                        status:
                          type: string
                          description: Shipment status
                        created_at:
                          type: string
                          format: date-time
                          description: Creation date
  /guide/{tracking_number}:
    get:
      tags:
      - Shipments
      summary: Get Single Shipment
      description: 'Retrieves the full details of a specific shipment, including origin/destination addresses, carrier, current status, and tracking history. This is the primary endpoint for looking up individual shipments and monitoring delivery progress.


        **When to use:** Call this endpoint to display shipment detail pages, check delivery status, provide tracking information to customers, or verify shipment data after creation.


        **Prerequisites:**

        - Valid JWT token in the Authorization header

        - A valid `tracking_number` from a previously created shipment (obtained from `GET /guide/{MM}/{YYYY}` or from the Shipping API shipment creation response)


        **Key behaviors:**

        - Returns comprehensive shipment data including `origin`, `destination`, `carrier`, `status`, `created_at`, and `updated_at`

        - The `status` field reflects the latest known delivery status from the carrier

        - This endpoint returns data for shipments created through your Envia account; it does not perform cross-carrier universal tracking

        - Use the `tracking_number` exactly as returned by other Envia endpoints (case-sensitive)'
      operationId: shipment-by-tracking
      parameters:
      - name: tracking_number
        in: path
        required: true
        description: Tracking number
        schema:
          type: string
          example: '1234567890'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indicates if the request was successful
                  data:
                    type: object
                    description: Shipment information
                    properties:
                      tracking_number:
                        type: string
                        description: Tracking number
                      carrier:
                        type: string
                        description: Carrier name
                      status:
                        type: string
                        description: Current status
                      origin:
                        type: object
                        description: Origin address
                      destination:
                        type: object
                        description: Destination address
                      created_at:
                        type: string
                        format: date-time
                        description: Creation date
                      updated_at:
                        type: string
                        format: date-time
                        description: Last update date
  /shipments/labels-bulk:
    post:
      tags:
      - Shipments
      summary: Download labels in bulk
      description: 'Download shipping labels (and optional additional files) in bulk for a list of shipments. Returns a single PDF file if all labels are PDF, or a ZIP archive if there is a mix of formats (PDF, ZPL, PNG, etc.).


        **When to use:** Call this endpoint when you need to download labels for multiple shipments at once — for example, for batch printing in a warehouse or fulfillment center.


        **Prerequisites:**

        - Valid JWT authentication token (Bearer)

        - One or more shipment IDs from previously generated labels


        **Key behaviors:**

        - Single shipment without additional files: returns the file directly with its original extension

        - Multiple shipments, all PDF: merges into a single PDF ordered by the `shipments` array

        - Mixed formats (PDF + ZPL/PNG): returns a ZIP file organized by extension folders

        - Packing slip layout is controlled by the company''s e-commerce config (`packing_print.option`): `after_label` places slips as separate pages after the label; `unify` combines the slip on the same page as the label (PDF only)


        **Response headers:**

        - `Content-Type`: `application/pdf` or `application/zip`

        - `Content-Disposition`: suggested filename for download

        - `x-file-extension`: `.pdf` or `.zip`

        - `x-filename`: filename of the returned file'
      operationId: downloadLabelsBulk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - shipments
              properties:
                shipments:
                  type: array
                  description: List of shipment IDs to download labels for. These are the numeric shipment IDs, not tracking numbers
                  items:
                    type:
                    - number
                    - string
                  example:
                  - 12345
                  - 12346
                  - 12347
                additional_files:
                  type: boolean
                  description: If true, includes additional shipment files (customs documents, carrier documents, etc.)
                  default: false
                additional_includes:
                  type: array
                  description: 'Filter additional files by document_type_id. Only used when `additional_files` is true. If empty, returns all available documents. Include `10` to also retrieve the Bill of Lading (file_bol).


                    **Available document_type_id values:**

                    | ID | Description |

                    |---|---|

                    | 1 | Shipment manifest |

                    | 6 | Proof of Delivery |

                    | 7 | Letter of Responsibility |

                    | 8 | Insurance Certificate |

                    | 9 | Return Receipt |

                    | 10 | Commercial Invoice |

                    | 11 | FTL Instructions Letter |

                    | 12 | FTL Additional Files |

                    | 13 | FTL Rate Confirmation |

                    | 14 | LTL Commercial Invoice |

                    | 15 | LTL Additional Files |

                    | 16 | Additional Files (tickets) |

                    | 17 | Certificate of Origin |

                    | 18 | USMCA / FTA Certificate |

                    | 19 | Export Declaration (EEI/SED) |

                    | 20 | Safety Data Sheet (MSDS) |

                    | 21 | Import Permit |

                    | 22 | Customs Power of Attorney |

                    | 23 | Tax ID / VAT Identification Form |

                    | 24 | Proforma Invoice |

                    | 25 | Packing List |

                    | 26 | Weight/sorter image from carrier (dispute resolution) |

                    | 27 | Auxiliary Electronic Content Declaration |'
                  items:
                    type:
                    - number
                    - string
                  default: []
                with_report:
                  type: boolean
                  description: If true, includes a report of processed labels (successes and errors)
                  default: false
                with_packing:
                  type: boolean
                  description: If true, generates and includes packing slips for each package in the associated order
                  default: false
                with_return_policy:
                  type: boolean
                  description: If true, appends the store's return policy page after each packing slip
                  default: false
            examples:
              Labels only:
                summary: Download labels only
                value:
                  shipments:
                  - 12345
                  - 12346
                  - 12347
              Labels + customs documents:
                summary: Labels with customs documents (document_type_id 3)
                value:
                  shipments:
                  - 12345
                  - 12346
                  additional_files: true
                  additional_includes:
                  - 3
              Labels + all extras:
                summary: Labels with all additional files, packing slips, and return policy
                value:
                  shipments:
                  - 12345
                  - 12346
                  - 12347
                  additional_files: true
                  additional_includes: []
                  with_report: true
                  with_packing: true
                  with_return_policy: true
      responses:
        '200':
          description: File download — returns a PDF or ZIP depending on label formats
          headers:
            Content-Disposition:
              schema:
                type: string
                example: attachment; filename=labels-1712345678.pdf
              description: Suggested filename for download
            x-file-extension:
              schema:
                type: string
                example: .pdf
              description: File extension of the returned file (.pdf or .zip)
            x-filename:
              schema:
                type: string
                example: labels-1712345678.pdf
              description: Filename of the returned file
            Cache-Control:
              schema:
                type: string
                example: no-cache, no-store, must-revalidate, proxy-revalidate
              description: Cache control directive
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/zip:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
              examples:
                Files not found:
                  summary: No downloadable files found
                  value:
                    data: Files not found
                Invalid data:
                  summary: Invalid request data
                  value:
                    data: Invalid data.
                Not found:
                  summary: No shipments matched the provided IDs
                  value:
                    data: not_found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Full Envia API Documentation
  url: https://docs.envia.com
x-provenance:
  method: searched
  source: https://docs.envia.com/reference
  harvested: '2026-10-27'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.envia.com/reference/active-notifications.md
  - https://docs.envia.com/reference/additional-services-by-locale.md
  - https://docs.envia.com/reference/additional-services.md
  - https://docs.envia.com/reference/addresses-by-type.md
  - https://docs.envia.com/reference/all-addresses.md
  - https://docs.envia.com/reference/all-countries.md
  - https://docs.envia.com/reference/all-packages.md
  - https://docs.envia.com/reference/all-provinces.md
  - https://docs.envia.com/reference/all-webhooks.md
  - https://docs.envia.com/reference/available-carriers-by-shipment-type.md
  - https://docs.envia.com/reference/available-couriers-detailed.md
  - https://docs.envia.com/reference/available-services.md
  - https://docs.envia.com/reference/cancel-dce.md
  - https://docs.envia.com/reference/carrier-actions-by-carrier.md
  - https://docs.envia.com/reference/carrier-branches.md
  - https://docs.envia.com/reference/carrier-by-id.md
  - https://docs.envia.com/reference/carrier-print-options.md
  - https://docs.envia.com/reference/carriers-by-country.md
  - https://docs.envia.com/reference/country-address-structure.md
  - https://docs.envia.com/reference/country-by-code.md
  - https://docs.envia.com/reference/country-locale.md
  - https://docs.envia.com/reference/create-ndr-request.md
  - https://docs.envia.com/reference/create-package.md
  - https://docs.envia.com/reference/create-shop-shipping-rule.md
  - https://docs.envia.com/reference/create-user-address.md
  - https://docs.envia.com/reference/create-webhook.md
  - https://docs.envia.com/reference/deactivate-company-notifications.md
  - https://docs.envia.com/reference/default-shop-services.md
  - https://docs.envia.com/reference/default-user-address.md
  - https://docs.envia.com/reference/default-user-print.md
  - https://docs.envia.com/reference/download-labels-bulk.md
  - https://docs.envia.com/reference/estafeta-branches-mexico.md
  - https://docs.envia.com/reference/generate-dce.md
  - https://docs.envia.com/reference/get-orders.md
  - https://docs.envia.com/reference/invoice-detail.md
  - https://docs.envia.com/reference/ndr-history.md
  - https://docs.envia.com/reference/ndr-shipment-actions.md
  - https://docs.envia.com/reference/payment-history.md
  - https://docs.envia.com/reference/province-by-code.md
  - https://docs.envia.com/reference/remove-package.md
  - https://docs.envia.com/reference/remove-user-address.md
  - https://docs.envia.com/reference/select-shipping-rule-for-order.md
  - https://docs.envia.com/reference/serviceable-countries.md
  - https://docs.envia.com/reference/services-by-carrier-and-country.md
  - https://docs.envia.com/reference/services-by-carrier.md
  - https://docs.envia.com/reference/shipment-by-tracking.md
  - https://docs.envia.com/reference/shipment-types.md
  - https://docs.envia.com/reference/shipments-by-month-year.md
  - https://docs.envia.com/reference/shop-by-url.md
  - https://docs.envia.com/reference/shop-shipping-rule.md
  - https://docs.envia.com/reference/shop-shipping-rules.md
  - https://docs.envia.com/reference/state-by-code.md
  - https://docs.envia.com/reference/states-by-country.md
  - https://docs.envia.com/reference/update-package.md
  - https://docs.envia.com/reference/update-shop-shipping-rules.md
  - https://docs.envia.com/reference/update-user-address.md
  - https://docs.envia.com/reference/update-webhook.md
  - https://docs.envia.com/reference/webhook-types.md
  merge:
    pages: 58
    deduped: 57
    conflicts_kept_first: 0