Envia.com Utilities API

openapi: 3.2.0
info:
  title: Envia Shipping API — Complete Documentation Utilities API
  version: v2.3.0
  description: 'Shipping API to connect with over 100 couriers worldwide. Shipping made simple for e-commerces and enterprises. Envia''s Shipping Web Services offers solutions that applications can use to quote, create labels, request pickups, track packages, cancel shipments and many other logistics operations in USA, Mexico, Colombia, Brazil, India, Canada, Argentina, Chile, Guatemala, Spain, Italy and France. This API is built for e-commerce platforms, logistics teams, and enterprise applications that need a single integration to access multi-carrier shipping capabilities. Core features include real-time rate comparison, label generation, package tracking, pickup scheduling, shipment cancellation, and webhook-based event notifications.


    **Important Information:**

    - State codes must be 2 digits

    - Country codes must be 2 digits

    - Validate the shipping address structure

    - Make sure the zip code or locality are correct


    **Custom Keys:** Custom Keys are used when you have a direct account with a carrier. This way you create labels with your rates with an additional small fee for service.'
  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://api-test.envia.com
  description: Sandbox/Test
- url: https://api.envia.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Utilities
  description: Utility endpoints for shipping operations
paths:
  /locate:
    post:
      tags:
      - Utilities
      summary: Locate a City (Colombia)
      description: 'Resolve a Colombian city name to its 8-digit DANE municipal code and validated postal code — required for all Colombian carriers (Coordinadora, ServiEntrega, TCC, etc.).


        **When to use:** Call this endpoint before `/ship/rate` or `/ship/generate` when shipping within Colombia. Colombian carriers require the DANE code in the `city` field of origin and destination addresses, not the human-readable city name.


        **Key behaviors:**

        - Full-text search against the official DANE municipality catalog

        - Returns the DANE code (`city`), normalized name (`name`), and department code (`state`)

        - No authentication required

        - Colombia only (`country: "CO"`)'
      operationId: locateColombiaCity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - city
              - state
              - country
              properties:
                city:
                  type: string
                  description: City name to search. Accepts partial or full city name.
                  example: Soledad
                state:
                  type: string
                  description: 2-letter Colombian department code (e.g. AT for Atlántico, CN for Cundinamarca).
                  example: AT
                country:
                  type: string
                  description: ISO country code. Must be CO (Colombia).
                  example: CO
            examples:
              LocateSoledad:
                summary: Locate Soledad, Atlántico
                value:
                  city: Soledad
                  state: AT
                  country: CO
              LocateBogota:
                summary: Locate Bogotá
                value:
                  city: Bogota
                  state: CN
                  country: CO
              LocateMedellin:
                summary: Locate Medellín, Antioquia
                value:
                  city: Medellin
                  state: AN
                  country: CO
      responses:
        '200':
          description: City resolved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  city:
                    type: string
                    description: 8-digit DANE municipal code. Use this value in the city field of origin/destination in /ship/rate and /ship/generate for Colombian carriers.
                    example: 08758000
                  name:
                    type: string
                    description: Normalized municipality name as registered in the DANE catalog.
                    example: SOLEDAD
                  state:
                    type: string
                    description: 2-letter department code.
                    example: AT
              examples:
                Soledad:
                  summary: Soledad, Atlántico
                  value:
                    city: 08758000
                    name: SOLEDAD
                    state: AT
                Bogota:
                  summary: Bogotá
                  value:
                    city: '11001000'
                    name: BOGOTA
                    state: CN
        '422':
          description: A required field (city, state or country) is missing, or the city/state/country combination could not be resolved to a DANE code
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: string
                    example: error
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 1149
                      description:
                        type: string
                        example: Invalid Option
                      message:
                        type: string
                        example: 'Missing required field(s): country.'
              examples:
                Missing required field:
                  summary: country was omitted from the request body
                  value:
                    meta: error
                    error:
                      code: 1149
                      description: Invalid Option
                      message: 'Missing required field(s): country.'
                City not found:
                  summary: city/state/country combination did not match any DANE municipality
                  value:
                    meta: error
                    error:
                      code: 1149
                      description: Invalid Option
                      message: Address cannot be validated.
      security: []
  /utils/classify-hscode:
    post:
      tags:
      - Utilities
      summary: Classify an HS Code
      description: 'Look up or validate a Harmonized System (HS) code for a product using its description or a known HS code. The endpoint returns the best-matching HS code along with a confidence score and product classification details.


        **When to use:** Call this endpoint when preparing international shipments and you need the correct HS code for customs declarations, commercial invoices, or duty/tax estimation.


        **Prerequisites:**

        - Valid JWT authentication token (Bearer)

        - At least one of: a product text description (`description`) or an existing HS code to validate (`hsCodeProvided`)


        **Key behaviors:**

        - Powered by the Zonos classification engine for accurate tariff lookup

        - Returns a confidence score — low-confidence results should be reviewed manually

        - You can optionally provide destination country codes to get country-specific classifications

        - If both `description` and `hsCodeProvided` are supplied, the API cross-references them for higher accuracy

        - Use the returned HS code in the `/ship/commercial-invoice` and `/ship/generate/` endpoints for international shipments'
      operationId: classify-hs-code
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  description: Product description for HS code classification. Required if hsCodeProvided is not provided.
                  example: Cotton t-shirt, men's clothing
                hsCodeProvided:
                  type: string
                  description: Customer or third party provided HS code. When provided, the classification will be guided by this code. Required if description is not provided.
                  example: 6109.10.00
                shipToCountries:
                  type: array
                  description: List of destination countries for shipping
                  items:
                    type: string
                  example:
                  - US
                  - CA
                  - MX
                includeAlternatives:
                  type: boolean
                  description: Whether to include alternative HS code suggestions in the response
                  default: true
                  example: true
            examples:
              BasicClassification:
                summary: Basic product classification
                value:
                  description: Cotton t-shirt, men's clothing
              WithHsCodeProvided:
                summary: Classification using provided HS code
                value:
                  hsCodeProvided: 6109.10.00
                  description: Cotton t-shirt
              HsCodeProvidedOnly:
                summary: Classification using only HS code (no description)
                value:
                  hsCodeProvided: 8471.30.01
                  shipToCountries:
                  - US
                  - MX
              AdvancedClassification:
                summary: Classification with destination countries
                value:
                  description: Electronic device, smartphone with lithium battery
                  shipToCountries:
                  - US
                  - CA
                  - MX
                  - GB
      responses:
        '200':
          description: Successful HS code classification
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indicates if the request was successful
                  data:
                    type: object
                    description: HS code classification data
                    properties:
                      hsCode:
                        type: string
                        description: Harmonized System code
                        example: 6109.10.00
                      description:
                        type: string
                        description: Friendly description of the HS code
                        example: T-shirts, singlets and other vests, of cotton
                      fullDescription:
                        type: string
                        description: Full detailed description of the HS code
                        example: T-shirts, singlets and other vests, of cotton, knitted or crocheted
                      confidenceScore:
                        type: number
                        description: Confidence score for the classification (0-1)
                        example: 0.95
              examples:
                Success:
                  summary: Successful classification
                  value:
                    success: true
                    data:
                      hsCode: 6109.10.00
                      description: T-shirts, singlets and other vests, of cotton
                      fullDescription: T-shirts, singlets and other vests, of cotton, knitted or crocheted
                      confidenceScore: 0.95
                LowConfidence:
                  summary: Low confidence classification
                  value:
                    success: true
                    data:
                      hsCode: 8471.30.01
                      description: Portable automatic data processing machines
                      fullDescription: Portable automatic data processing machines, comprising in the same housing at least a central processing unit and an input and output unit
                      confidenceScore: 0.65
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/cancel-shipment.md
  - https://docs.envia.com/reference/classify-hs-code.md
  - https://docs.envia.com/reference/create-commercial-invoice.md
  - https://docs.envia.com/reference/create-shipping-label.md
  - https://docs.envia.com/reference/create-shipping-manifest.md
  - https://docs.envia.com/reference/locatecolombiacity.md
  - https://docs.envia.com/reference/schedule-pickup.md
  - https://docs.envia.com/reference/shipping-rates.md
  - https://docs.envia.com/reference/test-webhook-endpoint.md
  - https://docs.envia.com/reference/track-shipments.md
  - https://docs.envia.com/reference/upload-customs-documents.md
  merge:
    pages: 11
    deduped: 10
    conflicts_kept_first: 0