# Getting Started

Canonical URL: https://api-docs.test-printeers.com/guides/getting-started

Learn how to set up your integration with the Printeers API.

## Prerequisites

Before you begin, you need:

- A Printeers partner account. [Create an account](https://dashboard.printeers.com/signup) if you don't have one.
- A V2 API secret key, generated in the [Printeers Dashboard](https://dashboard.printeers.com) under API Settings.

## Environments

Printeers provides two environments:

| Environment | Base URL | Purpose |
|-------------|----------|---------|
| Test | `https://api.test-printeers.com/v2` | Development and testing. Orders are not produced or invoiced. |
| Production | `https://api.printeers.com/v2` | Live orders. Created orders are produced, delivered, and billed. |

Always develop and test your integration against the test environment first.

## Authentication

All API requests require authentication via the `X-Printeers-Secret-Key` header:

```
X-Printeers-Secret-Key: YOUR_SECRET_KEY
```

Keep your secret key secure and never expose it in client-side code.

## Making Your First Request

Validate your credentials by calling the auth endpoint:

```bash
curl -i -X POST https://api.test-printeers.com/v2/auth/validate \
  -H "X-Printeers-Secret-Key: YOUR_SECRET_KEY"
```

A successful response confirms your credentials are valid:

```json
{
  "message": "Authentication is valid"
}
```

If authentication fails, you'll receive a `401 Unauthorized` response with an error message.

## Exploring the API

Once authenticated, you can explore available resources:

- **Catalog**: `GET /products` and `GET /packagings` to browse available products and packagings.
- **Renders**: `POST /renders` to create product mockups.
- **Orders**: `GET /orders/{orderReference}` to retrieve order details.
- **Shipments**: `GET /shipments/{shipmentReference}` for tracking information. See the [Shipments and Tracking](https://api-docs.test-printeers.com/guides/shipments-and-tracking.md) guide.

See the [API Reference](https://api-docs.test-printeers.com/reference/v2) for complete endpoint documentation.

## Error Handling

The API uses standard HTTP status codes:

| Code | Meaning |
|------|---------|
| `200` | Success |
| `400` | Bad request. Check your request data. |
| `401` | Unauthorized. Invalid or missing secret key. |
| `403` | Forbidden. Valid credentials but insufficient permissions. |
| `404` | Not found. Resource doesn't exist. |
| `501` | Not implemented. Endpoint not yet available. |
| `5xx` | Server error. Retry later. |

Error responses include a JSON body with details:

```json
{
  "code": "invalid_request",
  "message": "Description of what went wrong"
}
```

## Using AI coding agents

If an AI coding assistant (Claude Code, Cursor, Copilot or an agent framework) builds your integration, point it at the machine-readable sources instead of the HTML pages:

- [llms.txt](https://api-docs.test-printeers.com/llms.txt) indexes this documentation and links to the markdown version of every guide; [llms-full.txt](https://api-docs.test-printeers.com/llms-full.txt) is the full text of all guides in one file. Any guide is also available as markdown by appending `.md` to its URL.
- The [OpenAPI specification of the v2 API](https://api-docs.test-printeers.com/static/printeers-api-v2.openapi.json) is the source of truth for endpoints, parameters and schemas.

A starting point for your agent's project instructions (`AGENTS.md`, `CLAUDE.md` or similar):

```text
Printeers API: read https://api-docs.printeers.com/llms.txt first. The OpenAPI specification at https://api-docs.printeers.com/static/printeers-api-v2.openapi.json is the source of truth for endpoints and schemas. Develop and test against the test environment, https://api.test-printeers.com/v2, where orders are never produced or invoiced; switch to https://api.printeers.com/v2 only when explicitly asked. Authenticate with the X-Printeers-Secret-Key header and never commit the key. Set a unique customIdentifier on every order you create so a retried request cannot create a duplicate order.
```

## Next Steps

- Read the [Organization Structure](https://api-docs.test-printeers.com/guides/organization-structure.md) guide to understand accounts, stores, and brands.
- Browse the [API Reference](https://api-docs.test-printeers.com/reference/v2) for detailed endpoint documentation.
- Read the [API Versioning](https://api-docs.test-printeers.com/guides/api-versioning.md) guide to understand our release cycle.
- Learn how to [paginate through large result sets](https://api-docs.test-printeers.com/guides/pagination.md).