naftiko: 1.0.0-alpha2
info:
  label: parcelLab API — Returns
  description: parcelLab API — Returns. Return registrations, configurations, and document templates.
  tags:
  - ParcelLab
  - Returns
  - Post-Purchase
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    PARCELLAB_API_TOKEN: PARCELLAB_API_TOKEN
capability:
  consumes:
  - type: http
    namespace: parcellab-returns
    baseUri: https://api.parcellab.com
    description: parcelLab Returns surface.
    resources:
    - name: return-registrations
      path: /v4/returns/return-registrations/
      operations:
      - name: listreturnregistrations
        method: GET
        description: List return registrations for the account.
        outputRawFormat: json
        outputParameters: [{ name: result, type: object, value: $. }]
        inputParameters:
        - { name: account, in: query, type: integer, required: false }
        - { name: limit, in: query, type: integer, required: false }
        - { name: offset, in: query, type: integer, required: false }
        - { name: ordering, in: query, type: string, required: false }
      - name: createreturnregistration
        method: POST
        description: Create a new return registration.
        outputRawFormat: json
        outputParameters: [{ name: result, type: object, value: $. }]
        inputParameters:
        - { name: body, in: body, type: object, required: true, description: ReturnRegistration payload. }
    - name: return-registration-item
      path: /v4/returns/return-registrations/{external_id}/
      operations:
      - name: getreturnregistration
        method: GET
        description: Get a return registration by external_id.
        outputRawFormat: json
        outputParameters: [{ name: result, type: object, value: $. }]
        inputParameters:
        - { name: external_id, in: path, type: string, required: true }
    - name: returns-configurations
      path: /v4/returns/returns-configurations/
      operations:
      - name: listreturnconfigurations
        method: GET
        description: List return configuration sets.
        outputRawFormat: json
        outputParameters: [{ name: result, type: object, value: $. }]
        inputParameters:
        - { name: account, in: query, type: integer, required: false }
    - name: returns-configuration-item
      path: /v4/returns/returns-configurations/{id}/
      operations:
      - name: getreturnconfiguration
        method: GET
        description: Get a return configuration set.
        outputRawFormat: json
        outputParameters: [{ name: result, type: object, value: $. }]
        inputParameters:
        - { name: id, in: path, type: string, required: true }
    - name: document-templates
      path: /v4/returns/document-templates/
      operations:
      - name: listdocumenttemplates
        method: GET
        description: List document templates for return labels and slips.
        outputRawFormat: json
        outputParameters: [{ name: result, type: object, value: $. }]
        inputParameters:
        - { name: account, in: query, type: integer, required: false }
    authentication:
      type: header
      header: Authorization
      value: 'Parcellab-API-Token {{env.PARCELLAB_API_TOKEN}}'
  exposes:
  - type: rest
    namespace: parcellab-returns-rest
    port: 8080
    description: REST adapter for parcelLab Returns.
    resources:
    - path: /v1/return-registrations
      name: return-registrations
      operations:
      - method: GET
        name: listreturnregistrations
        description: List return registrations.
        call: parcellab-returns.listreturnregistrations
        with: { account: rest.account, limit: rest.limit, offset: rest.offset, ordering: rest.ordering }
        outputParameters: [{ type: object, mapping: $. }]
      - method: POST
        name: createreturnregistration
        description: Create a return registration.
        call: parcellab-returns.createreturnregistration
        with: { body: rest.body }
        outputParameters: [{ type: object, mapping: $. }]
    - path: /v1/return-registrations/{external_id}
      name: return-registration-item
      operations:
      - method: GET
        name: getreturnregistration
        description: Get a return registration.
        call: parcellab-returns.getreturnregistration
        with: { external_id: rest.external_id }
        outputParameters: [{ type: object, mapping: $. }]
  - type: mcp
    namespace: parcellab-returns-mcp
    port: 9090
    transport: http
    description: MCP adapter for parcelLab Returns.
    tools:
    - name: list-return-registrations
      description: List return registrations for the account.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: parcellab-returns.listreturnregistrations
      with: { account: tools.account, limit: tools.limit, offset: tools.offset, ordering: tools.ordering }
      outputParameters: [{ type: object, mapping: $. }]
    - name: create-return-registration
      description: Create a return registration.
      hints: { readOnly: false, destructive: false, idempotent: false }
      call: parcellab-returns.createreturnregistration
      with: { body: tools.body }
      outputParameters: [{ type: object, mapping: $. }]
    - name: get-return-registration
      description: Get a return registration by external_id.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: parcellab-returns.getreturnregistration
      with: { external_id: tools.external_id }
      outputParameters: [{ type: object, mapping: $. }]
    - name: list-return-configurations
      description: List return configuration sets.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: parcellab-returns.listreturnconfigurations
      with: { account: tools.account }
      outputParameters: [{ type: object, mapping: $. }]
    - name: get-return-configuration
      description: Get a return configuration by id.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: parcellab-returns.getreturnconfiguration
      with: { id: tools.id }
      outputParameters: [{ type: object, mapping: $. }]
    - name: list-document-templates
      description: List document templates.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: parcellab-returns.listdocumenttemplates
      with: { account: tools.account }
      outputParameters: [{ type: object, mapping: $. }]