openapi: 3.0.0
info:
  title: Enviame API
  description: |-
    # Intro 
     Hello world, this is the new Enviame API v3 definition. 
     # Authentication 
     Before using this API version, you have to request an initial setup of your company's account to our support team. You'll be provided with a cURL example to an **Auth0 application** that we will have created for you (we're sorry for this unsophisticated way, we are working on a better setup). The Auth0 app provides valid access tokens to call our API methods.
  version: 3.0.0
  license:
    name: Apache 2.0
host: api.enviame.io
basePath: /enviame
schemes:
  - https
produces:
  - application/json
consumes:
  - application/json
servers:
  - url: https://api.enviame.io/v3
    description: Production server
  - url: https://stage.api.enviame.io/v3
    description: Staging server
paths:
  /export-pickups:
    post:
      tags:
        - Pickups
      summary: Export pickups
      operationId: export-pickups-v3
      description: Export pickups to a excel file
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pickup_date_from:
                  type: string
                  format: date
                  description: Pickup date from
                pickup_date_to:
                  type: string
                  format: date
                  description: Pickup date to
                pickup_date:
                  type: string
                  format: date
                  description: >-
                    Pickup date. If this parameter is set, the pickup_date_from
                    and pickup_date_to parameters will be ignored
                updated_at_from:
                  type: string
                  format: date
                  description: Updated at from
                updated_at_to:
                  type: string
                  format: date
                  description: Updated at to
                shipper_id:
                  type: integer
                  format: int64
                  description: Shipper ID
                organization_id:
                  type: integer
                  format: int64
                  description: Organization ID
                carrier_code:
                  type: string
                  description: Carrier Code
                carrier_pickup_number:
                  type: string
                  description: >-
                    The carrier's pickup number. This is the number that the
                    carrier uses to identify the pickup
                status_code:
                  type: array
                  items:
                    type: string
                    enum:
                      - scheduled
                      - done
                      - failed
                      - canceled
                  description: Status of the pickup
                type:
                  type: string
                  enum:
                    - return
                  description: Type of pickup
      responses:
        '200':
          description: The excel file was created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                    description: Status of the request
                  data:
                    type: object
                    properties:
                      url:
                        type:
                          - string
                          - null
                        format: uri
                        description: URL to download the excel file.
        '422':
          description: The request was not successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  tags:
    - name: Pickups
      description: Pickups operations
    - name: Tickets
      description: Tickets operations
  /pudos:
    get:
      tags:
        - PUDOs
      summary: List PUDOs by place
      description: Retrieves a list of PUDOs, based on the provided place.
      parameters:
        - name: type
          in: query
          description: |
            The type of PUDOs that you want to retrieve.
          required: true
          schema:
            type: string
            enum:
              - store
              - courier
            example: store
        - name: place_name
          in: query
          description: |
            Specifies the name of the smallest geographic administrative unit
            for the specified country. For Chile, this refers to the name of
            the commune; for Colombia, it corresponds to the municipality; for
            Peru, it refers to the name of the district. In the case of Mexico,
            this parameter accepts the name of any administrative division such
            as neighborhood, city, municipality, or state.
          required: true
          schema:
            type: string
        - name: parent_place_name
          in: query
          description: |
            <span class="required-text-description">required: </span> <span
            class="regular-text-description">only for Colombia and Peru.</span>

            Specifies the name of the parent administrative division of the
            given place for the specified country. For Chile and Peru, this
            refers to the name of the province; for Colombia, it
            corresponds to the department. **In the case of Mexico, this
            parameter is ignored and is not necessary**.
          required: false
          schema:
            type: string
          x-nullable: true
        - name: place_level_name
          in: query
          description: >
            <span class="required-text-description">required: </span> <span

            class="regular-text-description">for Mexico only.</span>


            Name of the geographical subdivision corresponding to the sent
            place.
          required: false
          schema:
            type: string
            enum:
              - state
              - municipality
              - city
              - neighborhood
            example: city
          x-nullable: true
        - name: zip_code
          in: query
          description: >
            <span class="required-text-description">applies: </span> <span

            class="regular-text-description">for Mexico only.</span>


            The zip code of the neighborhood.

            **If this field is provided, it is assumed that the place
            corresponds to a neighborhood**.
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: >
            The page number from which you want your page search results to be
            displayed.
          required: false
          schema:
            type: integer
          x-nullable: true
        - name: limit
          in: query
          description: |
            <span class="regular-text-description">Default 20 per
            page.</span>

            Number of results per page.
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiPudoSuccessfulResponse'
              examples:
                success:
                  summary: Example of a successful response
                  value:
                    status: success
                    message: PUDOs obtained successfully
                    paging:
                      page: 1
                      limit: 20
                      data_count: 1
                      page_count: 1
                    data:
                      - code: 0001-stgo
                        name: PUDO 1 of Stgo
                        address: address of pudo 0001-stgo
                        places:
                          place: Santiago Centro
                          level1: Santiago
                          level2: Región Metropolitana
                successWithoutPudos:
                  summary: Example of a successful response but without pudos
                  value:
                    status: success
                    message: PUDOs obtained successfully
                    paging:
                      page: 1
                      limit: 20
                      data_count: 0
                      page_count: 1
                    data: []
                successPudosFromMx:
                  summary: Example of a successful PUDOS from Mexico response
                  value:
                    status: success
                    message: PUDOs obtained successfully
                    paging:
                      page: 1
                      limit: 5
                      data_count: 2
                      page_count: 1
                    data:
                      - code: 0001-ABC
                        name: PUDO 1 of Mexico
                        address: address of pudo 0001-ABC
                        places:
                          neighborhood: Prado Churubusco
                          city: Ciudad de México
                          municipality: Coyoacán
                          state: Ciudad de México
                      - code: 0002-ABC
                        name: PUDO 2 of Mexico
                        address: address of pudo 0002-ABC
                        places:
                          neighborhood: Independencia
                          city: Ciudad de México
                          municipality: Benito Juárez
                          state: Ciudad de México
        '400':
          description: |
            Operation rejected because one or more received queries are invalid
            or the required ones were not received
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ApiInvalidPudoTypeResponse'
                  - $ref: '#/components/schemas/ApiPudoMissingRequiredQueryResponse'
              examples:
                invalidPudoType:
                  summary: Example of fail response due to invalid PUDO type
                  value:
                    status: fail
                    message: There was an error in the input data
                    errors:
                      - field: type
                        code: invalid_value
                        message: >-
                          Field must have one of the following values: courier,
                          store
                missingRequiredQuery:
                  summary: Example of fail response due to missing required parameter
                  value:
                    status: fail
                    message: There was an error in the input data
                    errors:
                      - field: place_name
                        code: required
                        message: Field required
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
              examples:
                success:
                  summary: Example of a unauthorized response
                  value:
                    status: success
                    message: We could not fetch PUDOs
                    errors:
                      - code: FORBIDDEN
                        message: You do not have permissions to perform this action
        '404':
          description: >-
            The operation was not completed because the received place name was
            not found
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ApiPudoPlaceNotFoundResponse'
              examples:
                invalidPudoType:
                  summary: Example of response for place name not found
                  value:
                    status: fail
                    message: >-
                      PUDOs not fetched because we could not find the received
                      place name
                    errors:
                      place_name: Taltel
                      description: Place name not found
        '500':
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /tickets:
    get:
      tags:
        - Tickets
      summary: Get all tickets
      operationId: get-tickets-v3
      description: Retrieve a list of tickets.
      parameters:
        - name: delivery_id
          in: query
          description: ID of the delivery
          required: false
          schema:
            type: integer
            format: int64
        - name: current_type
          in: query
          description: current type of the ticket
          required: false
          schema:
            type: string
        - name: current_status
          in: query
          description: current status of the ticket
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: page number to retrieve
          required: false
          schema:
            type: integer
            format: int64
        - name: limit
          in: query
          description: number of tickets per page to retrieve
          required: false
          schema:
            type: integer
            format: int64
        - name: delivery_status
          in: query
          description: filter ticket by current delivery status
          required: false
          schema:
            type: string
        - name: ticket_mode
          in: query
          description: filter by tickets mode (delivery or return)
          required: false
          schema:
            type: string
            enum:
              - delivery
              - return
        - name: order_by
          in: query
          description: >-
            order by a specific field. The available fields are: CREATED_AT_ASC,
            CREATED_AT_DESC, LAST_MESSAGE_ASC, LAST_MESSAGE_DESC,
            WAITING_DAYS_ASC, WAITING_DAYS_DESC
          required: false
          schema:
            type: string
            enum:
              - CREATED_AT_ASC
              - CREATED_AT_DESC
              - LAST_MESSAGE_ASC
              - LAST_MESSAGE_DESC
              - WAITING_DAYS_ASC
              - WAITING_DAYS_DESC
        - name: created_at_from
          in: query
          description: filter tickets created from a date in UTC timezone
          required: false
          schema:
            type: string
        - name: created_at_to
          in: query
          description: filter tickets created to a date in UTC timezone
          required: false
          schema:
            type: string
        - name: country
          in: query
          description: filter tickets where the carrier is from the specified country
          required: false
          schema:
            type: string
            enum:
              - CL
              - PE
              - CO
              - MX
        - name: carrier
          in: query
          description: filter tickets by carrier code
          required: false
          schema:
            type: string
        - name: shipper
          in: query
          description: filter tickets by shipper code
          required: false
          schema:
            type: string
        - name: shipper_id
          in: query
          description: filter tickets by shipper id
          required: false
          schema:
            type: string
        - name: current_status_date_from
          in: query
          description: >-
            filter tickets where the date of their current status is equal to or
            greater than a specified date in utc
          required: false
          schema:
            type: string
        - name: current_status_date_to
          in: query
          description: >-
            filter tickets where the date of their current status is equal to or
            less than a specified date in utc
          required: false
          schema:
            type: string
        - name: current_type_date_from
          in: query
          description: >-
            filter tickets where the date of their current subject is equal to
            or less than a specified date in utc
          required: false
          schema:
            type: string
        - name: current_type_date_to
          in: query
          description: >-
            filter tickets where the date of their current subject is equal to
            or less than a specified date in utc
          required: false
          schema:
            type: string
        - name: current_stage_date_from
          in: query
          description: >-
            filter tickets where the date of their current stage is equal to or
            less than a specified date in utc
          required: false
          schema:
            type: string
        - name: current_stage_date_to
          in: query
          description: >-
            filter tickets where the date of their current stage is equal to or
            less than a specified date in utc
          required: false
          schema:
            type: string
        - name: last_message_from
          in: query
          description: >-
            filter tickets where the date of their last message is equal to or
            less than a specified date in utc
          required: false
          schema:
            type: string
        - name: last_message_to
          in: query
          description: >-
            filter tickets where the date of their last message is equal to or
            less than a specified date in utc
          required: false
          schema:
            type: string
        - name: current_stage
          in: query
          description: filter tickets by current stage
          required: false
          schema:
            type: string
            enum:
              - ISSUE
              - COMPLAINT
              - COMPENSATION
              - CLOSED
              - DISAGREEMENT
        - name: fulfillment
          in: query
          description: filter tickets by fulfillment type
          required: false
          schema:
            type: boolean
        - name: organization
          in: query
          description: filter tickets by organization code
          required: false
          schema:
            type: string
        - name: organization_id
          in: query
          description: filter tickets by organization id
          required: false
          schema:
            type: integer
            format: int64
        - name: read_client
          in: query
          description: >-
            filter tickets where the last message has been read or not by the
            client
          required: false
          schema:
            type: boolean
        - name: read_agent
          in: query
          description: >-
            filter tickets where the last message has been read or not by the
            agent
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: The tickets were found successfully.
        '500':
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /ticket/{delivery_id}:
    get:
      tags:
        - Tickets
      summary: Get ticket details by delivery id
      operationId: get-ticket-v3
      description: Retrieve a ticket by delivery id.
      parameters:
        - name: delivery_id
          in: path
          description: ID of the delivery
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: The ticket was found successfully.
        '404':
          description: The ticket was not found.
        '500':
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /ticket/{delivery_id}/message:
    post:
      tags:
        - Tickets
      summary: Create a message for a ticket
      operationId: create-message-v3
      description: Create a message for a ticket.
      parameters:
        - name: delivery_id
          in: path
          description: ID of the delivery
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: The message to be sent.
                timezone:
                  type: string
                  description: The timezone of the message.
                type:
                  type: object
                  properties:
                    name:
                      type: string
                    code:
                      type: string
                extra_fields:
                  type: object
                  properties:
                    place_2:
                      type: object
                      properties:
                        label:
                          type: string
                        value:
                          type: string
                    place_1:
                      type: object
                      properties:
                        label:
                          type: string
                        value:
                          type: string
                    phone:
                      type: object
                      properties:
                        label:
                          type: string
                        value:
                          type: string
                    ref2:
                      type: object
                      properties:
                        label:
                          type: string
                        value:
                          type: string
                    place:
                      type: object
                      properties:
                        label:
                          type: string
                        value:
                          type: string
                    full_address:
                      type: object
                      properties:
                        label:
                          type: string
                        value:
                          type: string
                    ref1:
                      type: object
                      properties:
                        label:
                          type: string
                        value:
                          type: string
      responses:
        '200':
          description: The message was created successfully.
        '500':
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - fail
          description: Status of the request
        message:
          type: string
          description: A message describing that the request failed
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: >-
                  A unique code for the error. This code can be used to look up
                  more information about the error in our documentation.
              description:
                type: string
                description: >-
                  A human-readable explanation of the error, specific to this
                  occurrence of the problem.
              field:
                type:
                  - string
                  - null
                description: >-
                  The field that caused the error. If the error is not specific
                  to a field, this property will be null.
              value:
                type:
                  - string
                  - null
                description: >-
                  The value of the field that caused the error. If the error is
                  not specific to a field, this property will be null.
    UnauthorizedResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - fail
          description: Status of the request
        message:
          type: string
          description: >-
            A message describing that the request failed due to a lack of
            permissions
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: >-
                  A unique code for the error. This code can be used to look up
                  more information about the error in our documentation.
              description:
                type: string
                description: >-
                  A human-readable explanation of the error, specific to this
                  occurrence of the problem.
    ApiPudoSuccessfulResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        paging:
          type: object
          properties:
            page:
              type: integer
            limit:
              type: integer
            data_count:
              type: integer
            page_count:
              type: integer
        data:
          type: array
          minItems: 0
          items:
            type: object
            properties:
              name:
                type: string
              code:
                type: string
              address:
                type: string
              places:
                type: object
                properties:
                  place:
                    type: string
                  level1:
                    type: string
                  level2:
                    type: string
                  level3:
                    type: string
    ApiInvalidPudoTypeResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              code:
                type: string
              message:
                type: string
    ApiPudoMissingRequiredQueryResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              code:
                type: string
              message:
                type: string
    ApiPudoPlaceNotFoundResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        data:
          type: object
          properties:
            place_name:
              type: string
