canonical: https://jentic.com/apis/mypuma.net/mypuma

# Mypuma Swagger Internal Transfer request - OpenAPI 3.0

The PUMA Internal Transfer Request API submits batches of internal transfer requests to PUMA's sourcing automation service, moving a sales order line to a factory. Each request in the array carries a request_id, purchase_requisition, season, article, so_number, factory_code, updated_at, and updated_by. The service validates every item and returns field-level errors, such as an so_number that is not all digits or a season that does not end in 11 for spring or 21 for autumn. A separate token operation exchanges a client_id and client_secret for a bearer access token.

## For AI agents

Submit validated batches of PUMA internal transfer requests that move a sales order article to a factory code, after exchanging client credentials for a bearer token.

## Scope

Does not create or look up sales orders, track shipments, or report stock levels. Use for submitting PUMA internal transfer requests only.

## Capabilities

- Exchange a client_id and client_secret for a bearer access_token with its expires_in value through POST `/auth/token`
- Submit a batch of internal transfer requests, each tying an so_number and article to a factory_code, through POST `/chatbot/internal-transfer`
- Record who changed a transfer with the updated_by email and updated_at date on each item
- Read field-level validation errors keyed by path, such as payload.0.season, to fix a rejected batch

## Use cases

### Agent-submitted factory transfers through Jentic

A sourcing coordinator asks an agent, connected through Jentic, to move several sales order lines to a different factory. The agent builds one array item per line with so_number, article, season, factory_code, purchase_requisition, request_id, and the coordinator's updated_by email, then submits the batch in a single call and reports the status and message from the response.

Example prompt: Call POST `/chatbot/internal-transfer` with an array containing one item: request_id='2945245', purchase_requisition='3004718909', season='202611', article='406887 05', so_number='0123296842', factory_code='FCNRF', updated_at='2026-11-09', updated_by='coordinator@example.com'

### Fixing a rejected transfer batch

When a batch fails, the service returns HTTP 422 with an error and a details array, where each entry names the failing field by path, such as payload.1.factory_code, and gives a readable message. An agent reads those paths, corrects the matching items, for example padding a season to six digits ending in 11 or 21, and resubmits only once the batch is clean.

Example prompt: Submit the batch to POST `/chatbot/internal-transfer`, and on a 422 response read each details[].field and details[].error, correct the named items, and resubmit

### Token handling for the sourcing service

Calls to the transfer endpoint carry a bearer access token. The token operation takes a client_id and client_secret and returns an access_token with token_type Bearer and an expires_in value, which the caller reuses until it expires instead of requesting a new token for every batch.

Example prompt: Call POST `/auth/token` with client_id and client_secret, store access_token and expires_in, and use the token on POST `/chatbot/internal-transfer` until it expires

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/chatbot/internal-transfer` | Submit internal transfer requests |
| POST | `/auth/token` | Request an access token |

## Key resources

- **Internal transfer requests** — Batches of sales order lines moved to a factory, keyed by so_number, article, season, and factory_code
- **Access tokens** — Bearer tokens issued from a client_id and client_secret

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 57 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 68 / 100
  - AI-Readiness & Agent Experience: 36 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 38 / 100
- **View full report:** https://jentic.com/apis/mypuma.net/mypuma/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring this API by hand means exchanging a client_id and client_secret for a bearer token, tracking expires_in, choosing the production or staging host, and matching the season, article, and so_number patterns. Through Jentic you install once, import it from the API Directory, store the client credentials once, and your agent calls it.
- **Permission scoping:** This API carries the sales order and factory inside the request body, so rules bound which operations your agent may call, not which factory or order. Limit the agent to the operations it needs, such as submitting transfer requests.
- **Credential handling:** Your PUMA client secret and bearer token are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'submit an internal transfer request' or 'move a sales order to a factory', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Katana API** — Manufacturing ERP covering sales orders, products, and locations
- **Megaventory API** — Inventory, sales order, and purchase order management with suppliers

## FAQ

### What authentication does the PUMA Internal Transfer Request API use?

Per its OpenAPI spec, the API declares a JWT bearer scheme, sent as Authorization: Bearer. POST `/auth/token` takes a client_id and client_secret in the request body and returns an access_token, a token_type of Bearer, and expires_in. Through Jentic, the client secret and token are stored once by your own Jentic One instance and injected at call time.

### What does each internal transfer request contain?

POST `/chatbot/internal-transfer` takes an array, so one call can carry several requests. Each item has request_id, purchase_requisition, season, article, so_number, factory_code, updated_at, and updated_by. The spec patterns require season to be six digits, so_number to be digits only, and article to end in a space and two digits, as in 406887 05, and updated_by must be an email address.

### What happens when a transfer request fails validation?

The service returns HTTP 422 with an error string and a details array. Each detail gives a field path such as payload.0.so_number and a message, for example that the season must end in 11 for spring or 21 for autumn, or that factory_code must be a non-empty string.

### What are the rate limits for the PUMA Internal Transfer Request API?

The OpenAPI spec does not specify rate limits. It lists a production host at sourcing-automation.pdss.mypuma.net and a staging host at sourcing-automation.pdssstage.mypuma.net; test batches against staging and check with the PUMA sourcing team that issued your client credentials for current limits.

### How do I submit a transfer request through Jentic?

Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import the API from the API Directory, and store your client credentials once. Your agent searches for 'submit an internal transfer request', gets the transfer operation with its input schema, and calls POST `/chatbot/internal-transfer` with the batch. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the PUMA Internal Transfer Request API?

Yes. A rule can allow POST `/chatbot/internal-transfer` and leave out POST `/auth/token`, so your Jentic One instance handles the token and the agent only submits transfers. Because the factory and sales order travel in the request body, a rule cannot restrict which factory_code the agent sends.