Back Market Care API

openapi: 3.2.0
info:
  version: 0.1.1
  title: Back Market - API Guidelines Care API
  description: '## Table of contents


    1.'
  contact:
    name: Seller Support Center
    url: https://merchant-support.backmarket.com/hc/en-us
    x-slack: NA
    email: NA@NA.com
servers:
- url: https://preprod.backmarket.co.jp
  description: Preprod - AP
- url: https://www.backmarket.co.jp
  description: Prod - AP
- url: https://preprod.backmarket.fr
  description: Preprod - EU
- url: https://www.backmarket.fr
  description: Prod - EU
- url: https://preprod.backmarket.com
  description: Preprod - NA
- url: https://www.backmarket.com
  description: Prod - NA
tags:
- name: Care
paths:
  /ws/sav:
    get:
      operationId: getCareFolderList
      x-tier: 2
      parameters:
      - description: Retrieve Care Folders with an ID higher than `last_id`
        example: 123
        in: query
        name: last_id
        required: false
        schema:
          type: integer
      - description: "Retrieve Care Folders with state equal to `state`.\n  * 0 - OPEN\n  * 9 - CLOSED\n"
        example: 9
        in: query
        name: state
        required: false
        schema:
          enum:
          - 0
          - 9
          type: integer
      - description: Retrieve Care Folders for a specific Orderline
        example: 456
        in: query
        name: orderline
        required: false
        schema:
          type: integer
      - description: Retrieve Care Folders more recent than `last_modification_date`. Format is YYYY-MM-DD-hh-mm
        example: 1970-01-01-00-00
        in: query
        name: last_modification_date
        required: false
        schema:
          type: string
      - description: Retrieve Care Folders having messages more recent than `last_message_date`. Format is YYYY-MM-DD-hh-mm
        example: 1970-01-01-00-00
        in: query
        name: last_message_date
        required: false
        schema:
          type: string
      - description: Page number to retrieve (10 entries per page).
        example: 2
        in: query
        name: page
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getCareFolderListResponse'
          description: Retrieved
        '401':
          description: Guest user not allowed
        '403':
          description: Authenticated user not allowed
      summary: Get a list of Care Folders attached to a Seller
      description: '## Rate Limiting


        This endpoint is rate limited to 520 requests per minute and 4000 per day.

        If you exceed this limit, you will receive a `429` status code.'
      tags:
      - Care
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
  /ws/sav/{careFolderId}:
    get:
      operationId: getCareFolderDetails
      x-tier: 2
      parameters:
      - description: ID of the Care Folder to retrieve
        example: 123
        in: path
        name: careFolderId
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getCareFolderDetailsResponse'
          description: Retrieved
        '401':
          description: Guest user not allowed
        '403':
          description: Authenticated user not allowed
        '404':
          description: Care Folder does not exist
      summary: Get the details of a Care Folder
      description: '## Rate limiting


        This endpoint is rate limited to 600 requests per minute and 40000 requests per day.

        If you exceed this limit, you will receive a `429` status code.'
      tags:
      - Care
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
  /ws/sav/{careFolderId}/problem:
    post:
      operationId: postProblem
      x-tier: 2
      parameters:
      - description: ID of the Care Folder on which the problem is declared
        example: 123
        in: path
        name: careFolderId
        required: true
        schema:
          type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/postProblemRequest'
      responses:
        '201':
          description: Declared
        '401':
          description: Guest user not allowed
        '403':
          description: Forbidden
        '404':
          description: Care Folder does not exist
        '413':
          description: File too large or too many attachments
        '422':
          description: Attachments are mandatory for this problem type / Only OTHER problem type is allowed for IDs lower than 100,000,000 / Cannot declare problem on this Care Folder
      summary: Declare a problem on a Care Folder
      description: 'Declare a problem on a Care Folder.


        The `problem_type` field specifies the type of problem. If omitted, it defaults to `OTHER`.


        Attachments are **mandatory** for the following problem types: `DAMAGED_PACKAGE`, `ITEM_NOT_RECEIVED`, `OOW_ITEM`.


        For Care Folders with ID below 100,000,000, only `OTHER` is accepted and no message or attachments can be provided.


        ## Rate limiting


        This endpoint is rate limited to 750 requests per minute and 1000 requests per day.

        If you exceed this limit, you will receive a `429` status code.'
      tags:
      - Care
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
  /ws/sav/refund:
    post:
      operationId: postRefundCreate
      x-tier: 2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postRefundCreateRequest'
      responses:
        '201':
          content:
            text/plain:
              schema:
                description: Summary of the created refund
                example: 99€ refunded on the sku 123456
                type: string
          description: Refund Created
        '400':
          description: Payload not acceptable
        '401':
          description: Guest user not allowed
        '403':
          description: Authenticated user not allowed
        '404':
          description: Orderline does not exist
      summary: Create a refund on an Orderline
      description: '## Rate limiting


        This endpoint is rate limited to 500 requests per day.

        If you exceed this limit, you will receive a `429` status code.'
      tags:
      - Care
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
  /ws/sav/{careFolderId}/msg:
    post:
      operationId: postMessage
      x-tier: 2
      parameters:
      - description: ID of the Care Folder to retrieve
        example: 123
        in: path
        name: careFolderId
        required: true
        schema:
          type: integer
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/postMessageRequest'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postMessageResponse'
          description: Created
        '400':
          description: Payload not acceptable
        '401':
          description: Guest user not allowed
        '403':
          description: Authenticated user not allowed
        '404':
          description: Care Folder does not exist
      summary: Post a message on the After Sales Platform for a Care Folder
      description: 'Posting a message to a closed folder will reopen it.


        ## Rate limiting


        This endpoint is rate limited to 560 requests per minute and 40000 requests per day.

        If you exceed this limit, you will receive a `429` status code.'
      tags:
      - Care
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
  /ws/sav/{careFolderId}/item-transfer:
    post:
      operationId: postItemTransfer
      x-tier: 2
      parameters:
      - description: ID of the Care Folder on which the item is transferred back to the customer
        example: 123
        in: path
        name: careFolderId
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postItemTransferCreateRequest'
        required: true
      responses:
        '201':
          description: Success
        '400':
          description: An item transfer with this tracking number already exists
        '403':
          description: Authenticated user not allowed
        '404':
          description: Care folder does not exit
        '422':
          description: Cannot create item transfer / Care folders with ID above 100,000,000 are not yet supported on this endpoint due to an ongoing internal migration
        '500':
          description: Shipment registration failed or Internal server error
      summary: Declare an item transfer back to customer
      description: '## Rate limiting


        This endpoint is rate limited to 292 requests per minute and 500 requests per day.

        If you exceed this limit, you will receive a `429` status code.'
      tags:
      - Care
      security:
      - ApiKeyAuth: []
      - BasicAuth: []
components:
  schemas:
    message:
      type: object
      properties:
        id:
          type: integer
          description: ID of the message
          example: 123
        message:
          type: string
          description: Content of the message
          example: Lorem ipsum dolor sit amet
        date_creation:
          type: string
          description: Message's creation date (ISO 8601 format)
          format: date-time
          example: '1970-01-01T00:00:00+00:00'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/lightAttachment'
        initiator:
          type: string
          description: Entity that sent the message
          example: Merchant
        kind:
          type: string
          description: Kind of the message (SENDER_TO_RECEIVER)
          example: MERCHANT_TO_ALL
        is_informative:
          type: boolean
          description: _true_ if message is informative. Informative message do not trigger LRR
          example: false
    returnLabel:
      type: object
      properties:
        date_creation:
          type: string
          description: Label's creation date (ISO 8601 format)
          format: date-time
          example: '1970-01-01T00:00:00+00:00'
        state:
          type: string
          description: Label's state
          enum:
          - USED
          - ALIVE
          - EXPIRED
          example: ALIVE
        label:
          type: string
          description: URL to the label document
          example: https://www.mycdn.com/path/to/label.document
        initiator:
          type: string
          description: Entity that initiated the return
          enum:
          - Merchant
          - BackMarket
          example: Merchant
        kind:
          type: string
          description: The return's direction (SENDER_TO_RECEIVER)
          enum:
          - UNSET
          - CUSTOMER_TO_MERCHANT
          - MERCHANT_TO_CUSTOMER
          example: MERCHANT_TO_CUSTOMER
    postProblemRequest:
      properties:
        problem_type:
          description: 'The type of problem to declare on the Care Folder.


            If not provided, defaults to `OTHER`.


            **Attachment requirements:**

            - `DAMAGED_PACKAGE`, `ITEM_NOT_RECEIVED`, and `OOW_ITEM` require at least one attachment.

            - All other problem types have optional attachments.

            '
          type: string
          enum:
          - ACCOUNT_LOCKED
          - CODE_LOCKED
          - DAMAGED_PACKAGE
          - ITEM_NOT_RECEIVED
          - MISSING_PART
          - OOW_ITEM
          - PROBLEM_NOT_IDENTIFIED
          - WRONG_ITEM
          - OTHER
          default: OTHER
          example: OTHER
        message:
          description: Optional message to include with the problem declaration.
          type: string
          example: The package arrived damaged
        attachment:
          description: 'The local file(s) to be uploaded with the problem declaration.


            **Mandatory** for problem types `DAMAGED_PACKAGE`, `ITEM_NOT_RECEIVED`, and `OOW_ITEM`.


            **Limits:**

            - Maximum file size: 3 MB per file

            - Maximum number of files: 10 files

            '
          example: []
          items:
            format: binary
            type: string
          type: array
      type: object
    lightAttachment:
      type: object
      properties:
        id:
          type: integer
          description: ID of the attachment
          example: 123
        attachment:
          type: string
          description: URL of the attachment
          example: https://www.mycdn.com/path/to/the/attachment.file
        date_creation:
          type: string
          description: Attachment's creation date
          format: date-time
          example: '1970-01-01T00:00:00+00:00'
    claim:
      type: object
      properties:
        id:
          type: integer
          description: ID of the Claim
          example: 123
        tiles:
          type: array
          description: This field shouldn't be used anymore
          deprecated: true
          items:
            $ref: '#/components/schemas/tile'
        issues:
          type: array
          items:
            $ref: '#/components/schemas/issue'
        rate:
          type: integer
          description: This field shouldn't be used anymore
          deprecated: true
          example: 1
        score:
          type: integer
          description: This field shouldn't be used anymore
          deprecated: true
          example: 1
        state:
          type: integer
          description: "State of the Claim:\n  * 0 - OPEN\n  * 9 - CLOSED\n"
          example: 1
        withdraw:
          type: boolean
          description: This field shouldn't be used anymore
          deprecated: true
          example: false
        gras_savoye:
          type: boolean
          description: This field shouldn't be used anymore
          deprecated: true
          example: false
        warnings:
          type: array
          description: This field shouldn't be used anymore
          deprecated: true
          example: []
        resolution_choice:
          type: string
          description: Resolution option chosen by the customer
          enum:
          - REMOTE_ASSISTANCE
          - REPAIR
          - REPLACE
          - REPAIR_REPLACE
          - REFUND
          example: REPLACE
        declared_warranty_state:
          type: string
          description: Warranty state declared by the customer
          enum:
          - IN_WARRANTY
          - WATER_OR_DROPPED
          - THIRD_PARTY_REPAIR
          example: IN_WARRANTY
        return_labels:
          type: array
          items:
            $ref: '#/components/schemas/returnLabel'
    postMessageRequest:
      properties:
        attachment:
          description: 'The local file to be uploaded with the message.


            **Limits:**

            - Maximum file size: 3 MB per file

            - Maximum number of files: 10 files

            '
          example: []
          items:
            format: binary
            type: string
          type: array
        message:
          description: Message content to be sent on the conversation
          example: Hi there
          type: string
      required:
      - message
      type: object
    attachment:
      type: object
      properties:
        msg:
          type: integer
          description: ID of the message this attachment is attached to
          example: 123
        group:
          type: integer
          description: ID of the Care Folder this attachement is attached to
          example: 456
        sender:
          type: integer
          description: ID of the user that uploaded the attachment
          example: 789
        attachment:
          type: string
          description: Path to the attachment file
          example: /path/to/my/attachment.file
    snapshot:
      type: object
      properties:
        id:
          type: integer
          description: ID of the snapshot (always returns a static value of 0)
          deprecated: true
          example: 0
        product:
          $ref: '#/components/schemas/product'
        listing:
          type: integer
          description: id of the listing
          example: 456
        sku:
          type: string
          description: SKU of the product
          example: 0123456789012
        snowden:
          type: boolean
          description: Only for iPhones. _true_ if TouchID is broken, _false_ otherwise. This field shouldn't be used anymore
          deprecated: true
          example: false
        image:
          type: string
          description: URL of the image
          example: https://www.mycdn.com/path/to/the/image.file
    issue:
      type: object
      properties:
        customerIssue:
          type: string
          description: The detailed name of the issue
          example: BATTERY_NOT_CHARGING
        tag:
          type: string
          description: The tag of the issue
          example: TECHNICAL
    seller:
      type: object
      properties:
        id:
          type: integer
          description: ID of the Seller
          example: 123
        username:
          type: string
          description: Username of the Seller
          example: rose.bush@companymail.com
        first_name:
          type: string
          description: First name of the Seller
          example: Rose
        last_name:
          type: string
          description: Last name of the Seller
          example: Bush
    orderline:
      type: object
      properties:
        id:
          type: integer
          description: ID of the orderline
          example: 123
        order:
          $ref: '#/components/schemas/order'
        snapshot:
          $ref: '#/components/schemas/snapshot'
        quantity:
          type: integer
          description: Number of products
          example: 2
        price:
          type: string
          description: Price of the product
          example: '89.99'
        state:
          type: integer
          description: "State of the orderline:\n  * NEW - 0\n  * PAID - 1\n  * VALIDATED - 2\n  * SHIPPED - 3\n  * CANCELLED - 4\n  * REFUNDED_PRE_DELIVERY - 5\n  * REFUNDED_POST_DELIVERY - 6\n  * NOT_PAID - 7\n"
          example: 2
        trust_pack_plus:
          type: boolean
          description: Customer bought Trust Pack Plus. This field shouldn't be used anymore
          deprecated: true
          example: false
    careFolder:
      type: object
      properties:
        id:
          type: integer
          description: ID of the Care Folder
          example: 123
        client:
          type: integer
          description: ID of the customer related to the Care Folder
          example: 456
        merchant:
          type: integer
          description: ID of the Seller related to the Care Folder
          example: 789
        orderline:
          type: integer
          description: ID of the orderline
          example: 321
        date_creation:
          type: string
          description: Date of the Care Folder's creation (ISO 8601 format)
          format: date-time
          example: '1970-01-01T00:00:00+00:00'
        date_modification:
          type: string
          description: Date of the Care Folder's last modification (ISO 8601 format)
          format: date-time
          example: '1970-01-01T00:00:00+00:00'
        date_last_message:
          type: string
          description: Date of the Care Folder's last posted message (ISO 8601 format)
          format: date-time
          example: '1970-01-01T00:00:00+00:00'
        date_closed:
          type: string
          description: Date of the Care Folder's closing (ISO 8601 format)
          format: date-time
          example: '1970-01-01T00:00:00+00:00'
        state:
          type: integer
          description: "State of the Care Folder:\n  * 0 - OPEN\n  * 9 - CLOSED\n"
          example: 9
        lines:
          type: array
          description: List of Claim IDs related to the Care Folder
          items:
            type: integer
          example:
          - 731
          - 1252
          - 57189
        country_code:
          type: string
          description: Country locale of the order, lowercase
          example: fr-fr
        backcare:
          type: boolean
          description: True if Seller is backcare
          example: true
    postItemTransferCreateRequest:
      required:
      - shipperName
      - trackingNumber
      properties:
        shipperName:
          description: Name of the carrier used for the shipment
          example: DHL
          type: string
        trackingNumber:
          description: Tracking id issued by the carrier
          example: 123AZ0672
          type: string
        action:
          description: Action taken by the seller
          example: REPAIR
          enum:
          - REPAIR
          - REPLACE
          - NOTHING
          type: string
      type: object
    address:
      type: object
      properties:
        company:
          type: string
          description: Company related to the address
          example: My Company
        first_name:
          type: string
          description: First name related to the address
          example: John
        last_name:
          type: string
          description: Last name related to the address
          example: Smith
        street:
          type: string
          description: Street of the adress
          example: 1 rue du Paradis
        street2:
          type: string
          description: Complement on the street of the address
          example: ' '
        postal_code:
          type: string
          description: Postal code of the city of the address
          example: '33000'
        country:
          type: string
          description: Country of the address
          example: FR
        city:
          type: string
          description: City of the address
          example: Bordeaux
        phone:
          type: string
          description: Phone number related to the address
          example: 0123456789
        email:
          type: string
          description: Email related to the address
          example: john.smith@mycompany.com
        customer_id_number:
          type: string
          description: ID of the customer related to the address
          example: '123'
    postRefundCreateRequest:
      properties:
        amount:
          description: Amount of the refund. Only if refund type is 6
          example: 89.99
          type: number
        orderline_pk:
          description: ID of the Orderline to be refund
          example: 123
          type: integer
        refund_type:
          description: "Type of the refund:\n  * 4 - Full refund for an orderline with state 1\n  * 5 - Full refund for an orderline with state 2\n  * 6 - Partial or full refund for an orderline with state 3\n\nDetails of the orderline states:\n| State | Description                                    |\n|-------|------------------------------------------------|\n| 0     | New Orderline                                  |\n| 1     | Orderline paid by the customer                 |\n| 2     | Orderline accepted by the seller               |\n| 3     | Orderline delivered to the shipping provider   |\n| 4     | Orderline cancelled                            |\n| 5     | Orderline refunded before shipping             |\n| 6     | Orderline refunded after shipping              |\n| 7     | Orderline not paid                             |\n| 8     | Orderline pending customer payment             |\n"
          enum:
          - 4
          - 5
          - 6
          example: 4
          type: integer
      type: object
    order:
      type: object
      properties:
        order_id:
          type: integer
          description: ID of the order
          example: 123
        shipping_address:
          $ref: '#/components/schemas/address'
        billing_address:
          $ref: '#/components/schemas/address'
        tracking_number:
          type: string
          description: Tracking number
          example: ABC123
        tracking_url:
          type: string
          description: Tracking URL
          example: https://www.mycarrier.com/delivery/track
        shipper:
          type: integer
          description: ID of the shipper
          example: 456
        shipper_display:
          type: string
          description: Name of the Shipper
          example: Shipper
        date_creation:
          type: string
          description: Date of the order's creation (ISO 8601 format)
          format: date-time
          example: '1970-01-01T00:00:00+00:00'
        date_modification:
          type: string
          description: Date of the order's last modification (ISO 8601 format)
          format: date-time
          example: '1970-01-01T00:00:00+00:00'
        date_shipping:
          type: string
          description: Date of the order's shipping (ISO 8601 format)
          format: date-time
          example: '1970-01-01T00:00:00+00:00'
        date_payment:
          type: string
          description: Date of the order's payment (ISO 8601 format)
          format: date-time
          example: '1970-01-01T00:00:00+00:00'
        state:
          type: integer
          description: "Sate of the order:\n  * 0 - New\n  * 1 - Validated\n  * 3 - Merchant needs to send\n  * 8 - Failed\n  * 9 - Sent\n"
          enum:
          - 0
          - 1
          - 3
          - 8
          - 9
          example: 1
        price:
          type: string
          description: Price of the order
          example: '89.99'
        shipping_price:
          type: string
          description: Price of the order's shipping
          example: '5.99'
        currency:
          type: string
          description: Currency of the payment
          example: EUR
        country_code:
          type: string
          description: Country locale code of the plateform's location, lowercase
          example: fr-fr
    getCareFolderListResponse:
      properties:
        count:
          description: Number of Care Folders on the current page
          example: 3
          type: integer
        next:
          description: URL to the next page
          example: https://backmarket.fr/ws/sav/?page=2
          type: string
        previous:
          description: URL to the previous page
          example: 'null'
          type: string
        results:
          description: List of Care Folders
          items:
            $ref: '#/components/schemas/careFolder'
          type: array
      type: object
    tile:
      type: object
      properties:
        id:
          type: integer
          description: ID of the tile
          example: 123
        name:
          type: string
          description: Name of the tile
          example: Technical
    category_3:
      type: object
      properties:
        category_name:
          type: string
          description: Name of the product's category
          example: Smartphones
        parent:
          deprecated: true
          description: This field shouldn't be used anymore
          $ref: '#/components/schemas/category_3'
    client:
      type: object
      properties:
        id:
          type: integer
          description: ID of the customer (always returns a static value of 0)
          deprecated: true
          example: 0
        username:
          type: string
          description: Username of the customer (always returns empty)
          deprecated: true
          example: ''
        first_name:
          type: string
          description: First name of the customer
          example: John
        last_name:
          type: string
          description: Last name of the customer
          example: Doe
        email:
          type: string
          description: Email of the customer
          example: john.doe@mymail.com
    postMessageResponse:
      properties:
        attachment:
          $ref: '#/components/schemas/attachment'
        attachments:
          items:
            $ref: '#/components/schemas/attachment'
          type: array
        date_creation:
          description: The message's creation date (ISO 8601 format)
          example: '1970-01-01T00:00:00+00:00'
          format: date-time
          type: string
        group:
          description: ID of the Care Folder linked to the message
          example: 456
          type: integer
        id:
          description: ID of the message
          example: 123
          type: integer
        message:
          description: Message content
          example: Hi, how can I help?
          type: string
        sender:
          description: ID of the user who created the message
          example: 789
          type: integer
      type: object
    product:
      type: object
      properties:
        product_id:
          type: integer
          description: ID of the product
          example: 123
        category_3:
          $ref: '#/components/schemas/category_3'
    getCareFolderDetailsResponse:
      properties:
        backcare:
          description: True if Seller subscribed to BackCare
          example: true
          type: boolean
        client:
          $ref: '#/components/schemas/client'
        country_code:
          description: Country locale code, lowercase
          example: fr-fr
          type: string
        date_closed:
          description: Date of the Care Folder's closing (ISO 8601 format)
          example: '1970-01-01T00:00:00+00:00'
          format: date-time
          type: string
        date_creation:
          description: Date of the Care Folder's creation (ISO 8601 format)
          example: '1970-01-01T00:00:00+00:00'
          format: date-time
          type: string
        date_last_message:
          description: Date of the Care Folder's last posted message (ISO 8601 format)
          example: '1970-01-01T00:00:00+00:00'
          format: date-time
          type: string
        date_modification:
          description: Date of the Care Folder's last modification (ISO 8601 format)
          example: '1970-01-01T00:00:00+00:00'
          format: date-time
          type: string
        id:
          description: ID of the Care Folder
          example: 123
          type: integer
        lines:
          items:
            $ref: '#/components/schemas/claim'
          type: array
        merchant:
          $ref: '#/components/schemas/seller'
        messages:
          items:
            $ref: '#/components/schemas/message'
          type: array
        orderline:
          $ref: '#/components/schemas/orderline'
        state:
          description: "State of the Care Folder:\n  * 0 - OPEN\n  * 9 - CLOSED\n"
          enum:
          - 0
          - 9
          example: 9
          type: integer
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: Authorization
      type: apiKey
      description: 'Token authentication is done with Basic authentication.

        Prefix the value with \"Basic\" and use the token you created in the backoffice in the Integrations option page.'
    BasicAuth:
      type: http
      scheme: basic