parcelLab Translation API

openapi: 3.2.0
info:
  title: parcelLab Translation API
  version: v4
  description: '# API Description


    ## Overview


    Use this API to interact with the parcelLab platform. It is currently in preview. For a reference of our current API, please refer to the API documentation.


    The API v4 allows for enhanced and more standardized interaction with our platform. It does however not yet cover all of the features of our v1/v2 APIs.


    ## Authentication


    Most endpoints in this API need authentication, unless otherwise stated. The authentication is done using the `Authorization` header with the value `Parcellab-API-Token `. You can generate the token in our portal, or ask our support team for one. The token needs to be base64 encoded together with the account ID, like: `base64encode(account_id:token)`. Here is an example of how to do it in Python:


    ```python

    import base64

    base64.b64encode(b''account_id:token'').decode(''utf-8'')

    ```


    ## Errors


    The API uses standard HTTP status codes to show the success or failure of a request. In case of an error, the response body will contain a JSON object with the following structure:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "error_code",

    "detail": "Error message.",

    "attr": "Optional additional information."

    }

    ]

    }

    ```


    ### 401 Unauthorized


    The API returns these errors with the status code 401 when the authentication fails. It also returns them when a request does not include the authentication information. Here are the 2 possible errors.


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "authentication_failed",

    "detail": "Incorrect authentication credentials.",

    "attr": null

    }

    ]

    }

    ```


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "not_authenticated",

    "detail": "Authentication credentials were not provided.",

    "attr": null

    }

    ]

    }

    ```


    ### 403 Forbidden


    The API returns this error when the authentication is correct but does not allow the request. For example, an API token with only the `read` scope gets this error on a POST. Here is how it looks:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "permission_denied",

    "detail": "You do not have permission to perform this action.",

    "attr": null

    }

    ]

    }

    ```


    ### 405 Method Not Allowed


    The API returns this error when you call an endpoint with an unexpected HTTP method. For example, if updating a user needs a POST request and you send a PATCH instead, you get this error. Here is how it looks:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "method_not_allowed",

    "detail": "Method “patch” not allowed.",

    "attr": null

    }

    ]

    }

    ```


    ### 406 Not Acceptable


    The API returns this error if you send an `Accept` header with a value other than `application/json`. Here is how the response would look:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "not_acceptable",

    "detail": "Could not satisfy the request Accept header.",

    "attr": null

    }

    ]

    }

    ```


    ### 415 Unsupported Media Type


    The API returns this error when the request content type is not JSON. Here is how the response would look:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "not_acceptable",

    "detail": "Unsupported media type “application/xml” in request.",

    "attr": null

    }

    ]

    }

    ```


    ### 500 Internal Server Error


    The API returns this error when the server encounters an unexpected error. Here is how the response would look:


    ```json

    {

    "type": "server_error",

    "errors": [

    {

    "code": "error",

    "detail": "A server error occurred.",

    "attr": null

    }

    ]

    }

    ```'
tags:
- name: Translation
paths:
  /v4/returns/translations/{id}/:
    get:
      operationId: returns_translations_retrieve
      description: 'Read a Returns Portal v2 translation and set individual strings by key.


        Complements the full-config replace: this sets one or more keys in place and

        leaves every other string untouched (the on-page inline editor''s model).'
      summary: Retrieve Translation
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this Returns Translation.
        required: true
      tags:
      - Translation
      security:
      - HeaderToken: []
      - OAuth2Authentication: []
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse403'
              examples:
                PermissionDenied:
                  value:
                    type: client_error
                    errors:
                    - code: permission_denied
                      detail: You do not have permission to perform this action.
                      attr: null
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnTranslation'
          description: ''
  /v4/returns/translations/{id}/strings/:
    patch:
      operationId: returns_translations_strings_partial_update
      description: 'Read a Returns Portal v2 translation and set individual strings by key.


        Complements the full-config replace: this sets one or more keys in place and

        leaves every other string untouched (the on-page inline editor''s model).'
      summary: Set Translation Strings
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this Returns Translation.
        required: true
      tags:
      - Translation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedTranslationStringsUpdateRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedTranslationStringsUpdateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedTranslationStringsUpdateRequest'
      security:
      - HeaderToken: []
      - OAuth2Authentication: []
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse403'
              examples:
                PermissionDenied:
                  value:
                    type: client_error
                    errors:
                    - code: permission_denied
                      detail: You do not have permission to perform this action.
                      attr: null
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationStringsUpdate'
          description: ''
components:
  schemas:
    PatchedTranslationStringsUpdateRequest:
      type: object
      description: Request body for setting one or more translation strings by dotted key.
      properties:
        translations:
          type: object
          additionalProperties:
            type: string
          description: 'Map of dotted translation key to value, e.g. {"return_initiate.tagline_sub": "Manage your return"}.'
    ErrorResponse403:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error403'
      required:
      - errors
      - type
    LanguagesISO639Enum:
      enum:
      - aa
      - ab
      - ae
      - af
      - ak
      - am
      - an
      - ar
      - as
      - av
      - ay
      - az
      - ba
      - be
      - bg
      - bi
      - bm
      - bn
      - bo
      - br
      - bs
      - ca
      - ce
      - ch
      - co
      - cr
      - cs
      - cu
      - cv
      - cy
      - da
      - de
      - dv
      - dz
      - ee
      - el
      - en
      - eo
      - es
      - et
      - eu
      - fa
      - ff
      - fi
      - fj
      - fo
      - fr
      - fy
      - ga
      - gd
      - gl
      - gn
      - gu
      - gv
      - ha
      - he
      - hi
      - ho
      - hr
      - ht
      - hu
      - hy
      - hz
      - ia
      - id
      - ie
      - ig
      - ii
      - ik
      - io
      - is
      - it
      - iu
      - ja
      - jv
      - ka
      - kg
      - ki
      - kj
      - kk
      - kl
      - km
      - kn
      - ko
      - kr
      - ks
      - ku
      - kv
      - kw
      - ky
      - la
      - lb
      - lg
      - li
      - ln
      - lo
      - lt
      - lu
      - lv
      - mg
      - mh
      - mi
      - mk
      - ml
      - mn
      - mr
      - ms
      - mt
      - my
      - na
      - nb
      - nd
      - ne
      - ng
      - nl
      - nn
      - 'no'
      - nr
      - nv
      - ny
      - oc
      - oj
      - om
      - or
      - os
      - pa
      - pi
      - pl
      - ps
      - pt
      - qu
      - rm
      - rn
      - ro
      - ru
      - rw
      - sa
      - sc
      - sd
      - se
      - sg
      - sh
      - si
      - sk
      - sl
      - sm
      - sn
      - so
      - sq
      - sr
      - ss
      - st
      - su
      - sv
      - sw
      - ta
      - te
      - tg
      - th
      - ti
      - tk
      - tl
      - tn
      - to
      - tr
      - ts
      - tt
      - tw
      - ty
      - ug
      - uk
      - ur
      - uz
      - ve
      - vi
      - vo
      - wa
      - wo
      - xh
      - yi
      - yo
      - za
      - zh
      - zu
      type: string
      description: '* `aa` - Afar (Aa)

        * `ab` - Abkhazian (Ab)

        * `ae` - Avestan (Ae)

        * `af` - Afrikaans (Af)

        * `ak` - Akan (Ak)

        * `am` - Amharic (Am)

        * `an` - Aragonese (An)

        * `ar` - Arabic (Ar)

        * `as` - Assamese (As)

        * `av` - Avaric (Av)

        * `ay` - Aymara (Ay)

        * `az` - Azerbaijani (Az)

        * `ba` - Bashkir (Ba)

        * `be` - Belarusian (Be)

        * `bg` - Bulgarian (Bg)

        * `bi` - Bislama (Bi)

        * `bm` - Bambara (Bm)

        * `bn` - Bengali (Bn)

        * `bo` - Tibetan (Bo)

        * `br` - Breton (Br)

        * `bs` - Bosnian (Bs)

        * `ca` - Catalan (Ca)

        * `ce` - Chechen (Ce)

        * `ch` - Chamorro (Ch)

        * `co` - Corsican (Co)

        * `cr` - Cree (Cr)

        * `cs` - Czech (Cs)

        * `cu` - Church Slavic (Cu)

        * `cv` - Chuvash (Cv)

        * `cy` - Welsh (Cy)

        * `da` - Danish (Da)

        * `de` - German (De)

        * `dv` - Divehi (Dv)

        * `dz` - Dzongkha (Dz)

        * `ee` - Ewe (Ee)

        * `el` - Modern Greek (1453-) (El)

        * `en` - English (En)

        * `eo` - Esperanto (Eo)

        * `es` - Spanish (Es)

        * `et` - Estonian (Et)

        * `eu` - Basque (Eu)

        * `fa` - Persian (Fa)

        * `ff` - Fulah (Ff)

        * `fi` - Finnish (Fi)

        * `fj` - Fijian (Fj)

        * `fo` - Faroese (Fo)

        * `fr` - French (Fr)

        * `fy` - Western Frisian (Fy)

        * `ga` - Irish (Ga)

        * `gd` - Scottish Gaelic (Gd)

        * `gl` - Galician (Gl)

        * `gn` - Guarani (Gn)

        * `gu` - Gujarati (Gu)

        * `gv` - Manx (Gv)

        * `ha` - Hausa (Ha)

        * `he` - Hebrew (He)

        * `hi` - Hindi (Hi)

        * `ho` - Hiri Motu (Ho)

        * `hr` - Croatian (Hr)

        * `ht` - Haitian (Ht)

        * `hu` - Hungarian (Hu)

        * `hy` - Armenian (Hy)

        * `hz` - Herero (Hz)

        * `ia` - Interlingua (International Auxiliary Language Association) (Ia)

        * `id` - Indonesian (Id)

        * `ie` - Interlingue (Ie)

        * `ig` - Igbo (Ig)

        * `ii` - Sichuan Yi (Ii)

        * `ik` - Inupiaq (Ik)

        * `io` - Ido (Io)

        * `is` - Icelandic (Is)

        * `it` - Italian (It)

        * `iu` - Inuktitut (Iu)

        * `ja` - Japanese (Ja)

        * `jv` - Javanese (Jv)

        * `ka` - Georgian (Ka)

        * `kg` - Kongo (Kg)

        * `ki` - Kikuyu (Ki)

        * `kj` - Kuanyama (Kj)

        * `kk` - Kazakh (Kk)

        * `kl` - Kalaallisut (Kl)

        * `km` - Khmer (Km)

        * `kn` - Kannada (Kn)

        * `ko` - Korean (Ko)

        * `kr` - Kanuri (Kr)

        * `ks` - Kashmiri (Ks)

        * `ku` - Kurdish (Ku)

        * `kv` - Komi (Kv)

        * `kw` - Cornish (Kw)

        * `ky` - Kirghiz (Ky)

        * `la` - Latin (La)

        * `lb` - Luxembourgish (Lb)

        * `lg` - Ganda (Lg)

        * `li` - Limburgan (Li)

        * `ln` - Lingala (Ln)

        * `lo` - Lao (Lo)

        * `lt` - Lithuanian (Lt)

        * `lu` - Luba-Katanga (Lu)

        * `lv` - Latvian (Lv)

        * `mg` - Malagasy (Mg)

        * `mh` - Marshallese (Mh)

        * `mi` - Maori (Mi)

        * `mk` - Macedonian (Mk)

        * `ml` - Malayalam (Ml)

        * `mn` - Mongolian (Mn)

        * `mr` - Marathi (Mr)

        * `ms` - Malay (Macrolanguage) (Ms)

        * `mt` - Maltese (Mt)

        * `my` - Burmese (My)

        * `na` - Nauru (Na)

        * `nb` - Norwegian Bokmål (Nb)

        * `nd` - North Ndebele (Nd)

        * `ne` - Nepali (Macrolanguage) (Ne)

        * `ng` - Ndonga (Ng)

        * `nl` - Dutch (Nl)

        * `nn` - Norwegian Nynorsk (Nn)

        * `no` - Norwegian (No)

        * `nr` - South Ndebele (Nr)

        * `nv` - Navajo (Nv)

        * `ny` - Chichewa (Ny)

        * `oc` - Occitan (Post 1500) (Oc)

        * `oj` - Ojibwa (Oj)

        * `om` - Oromo (Om)

        * `or` - Oriya (Macrolanguage) (Or)

        * `os` - Ossetian (Os)

        * `pa` - Panjabi (Pa)

        * `pi` - Pali (Pi)

        * `pl` - Polish (Pl)

        * `ps` - Pushto (Ps)

        * `pt` - Portuguese (Pt)

        * `qu` - Quechua (Qu)

        * `rm` - Romansh (Rm)

        * `rn` - Rundi (Rn)

        * `ro` - Romanian (Ro)

        * `ru` - Russian (Ru)

        * `rw` - Kinyarwanda (Rw)

        * `sa` - Sanskrit (Sa)

        * `sc` - Sardinian (Sc)

        * `sd` - Sindhi (Sd)

        * `se` - Northern Sami (Se)

        * `sg` - Sango (Sg)

        * `sh` - Serbo-Croatian (Sh)

        * `si` - Sinhala (Si)

        * `sk` - Slovak (Sk)

        * `sl` - Slovenian (Sl)

        * `sm` - Samoan (Sm)

        * `sn` - Shona (Sn)

        * `so` - Somali (So)

        * `sq` - Albanian (Sq)

        * `sr` - Serbian (Sr)

        * `ss` - Swati (Ss)

        * `st` - Southern Sotho (St)

        * `su` - Sundanese (Su)

        * `sv` - Swedish (Sv)

        * `sw` - Swahili (Macrolanguage) (Sw)

        * `ta` - Tamil (Ta)

        * `te` - Telugu (Te)

        * `tg` - Tajik (Tg)

        * `th` - Thai (Th)

        * `ti` - Tigrinya (Ti)

        * `tk` - Turkmen (Tk)

        * `tl` - Tagalog (Tl)

        * `tn` - Tswana (Tn)

        * `to` - Tonga (Tonga Islands) (To)

        * `tr` - Turkish (Tr)

        * `ts` - Tsonga (Ts)

        * `tt` - Tatar (Tt)

        * `tw` - Twi (Tw)

        * `ty` - Tahitian (Ty)

        * `ug` - Uighur (Ug)

        * `uk` - Ukrainian (Uk)

        * `ur` - Urdu (Ur)

        * `uz` - Uzbek (Uz)

        * `ve` - Venda (Ve)

        * `vi` - Vietnamese (Vi)

        * `vo` - Volapük (Vo)

        * `wa` - Walloon (Wa)

        * `wo` - Wolof (Wo)

        * `xh` - Xhosa (Xh)

        * `yi` - Yiddish (Yi)

        * `yo` - Yoruba (Yo)

        * `za` - Zhuang (Za)

        * `zh` - Chinese (Zh)

        * `zu` - Zulu (Zu)'
    TranslationStringsUpdate:
      type: object
      description: Request body for setting one or more translation strings by dotted key.
      properties:
        translations:
          type: object
          additionalProperties:
            type: string
          description: 'Map of dotted translation key to value, e.g. {"return_initiate.tagline_sub": "Manage your return"}.'
      required:
      - translations
    ErrorResponse404:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error404'
      required:
      - errors
      - type
    GenericErrorItem:
      type: object
      properties:
        code:
          type: string
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - code
      - detail
    Error400Response:
      type: object
      properties:
        type:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/GenericErrorItem'
      required:
      - errors
      - type
    ReturnTranslation:
      type: object
      description: A Returns Portal translation (one language) with its full key/value config.
      properties:
        id:
          type: integer
          readOnly: true
        account:
          type: integer
          readOnly: true
        language:
          allOf:
          - $ref: '#/components/schemas/LanguagesISO639Enum'
          readOnly: true
        config:
          type: object
          readOnly: true
          title: Configuration
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      required:
      - account
      - config
      - created_at
      - id
      - language
      - updated_at
    Error403:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode403Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    ClientErrorEnum:
      enum:
      - client_error
      type: string
      description: '* `client_error` - Client Error'
    ErrorCode404Enum:
      enum:
      - not_found
      type: string
      description: '* `not_found` - Not Found'
    ErrorCode403Enum:
      enum:
      - permission_denied
      type: string
      description: '* `permission_denied` - Permission Denied'
    Error404:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode404Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
  securitySchemes:
    HeaderToken:
      type: apiKey
      in: header
      name: Authorization
      x-gitbook-prefix: Parcellab-API-Token
      x-gitbook-token-placeholder: YOUR_BASE64_ENCODED_API_TOKEN
      description: 'Send `Authorization: Parcellab-API-Token <encoded-token>`.


        `<encoded-token>` = `base64(account_id:token)` as provided in the portal.'
    OAuth2Authentication:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Unbound access tokens use Authorization: Bearer <token>. DPoP-bound tokens use Authorization: DPoP <token> and a DPoP proof header signed with the bound key for each request. Supported proof algorithms: ES256 and RS256.'