> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagamerican.app/llms.txt
> Use this file to discover all available pages before exploring further.

# PagAmerican Data API

> Query your sales data programmatically, in near real time.

Welcome! This API lets you query your sales/purchases programmatically. In **3 steps** you'll make your first request.

<Info>
  **Prerequisite:** a credential pair (`clientId` + `apiKey`) provided by the PagAmerican team. The `apiKey` is shown **only once** at creation — store it securely.
</Info>

## Quickstart

<Steps>
  <Step title="Exchange your credentials for a token">
    ```bash theme={null}
    curl -X POST https://external-api-service.pagamerican.app/api/v1/auth \
      -H "Content-Type: application/json" \
      -d '{ "clientId": "YOUR_CLIENT_ID", "apiKey": "YOUR_API_KEY" }'
    ```

    Response:

    ```json theme={null}
    { "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6..." }
    ```
  </Step>

  <Step title="Query your purchases using the token">
    ```bash theme={null}
    curl -G https://external-api-service.pagamerican.app/api/v1/purchases \
      -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..." \
      --data-urlencode "from=2026-04-01" \
      --data-urlencode "to=2026-05-01" \
      --data-urlencode "limit=1000"
    ```
  </Step>

  <Step title="Done! You get the data as JSON">
    ```json theme={null}
    {
      "data": [{ "purchaseId": "pur_019dad28...", "transactionAmount": 97.0, "...": "..." }],
      "meta": { "count": 4, "limit": 1000, "from": "2026-04-01", "to": "2026-05-01", "truncated": false }
    }
    ```
  </Step>
</Steps>

<Tip>
  Generate the token once and **reuse it** across multiple requests while it's valid. Only generate a new one when you get a `401`.
</Tip>

## Key concepts

<CardGroup cols={2}>
  <Card title="Dates: `to` is exclusive" icon="calendar">
    To get the entire month of April, use `from=2026-04-01` and `to=2026-05-01` (the day after your intended last day). The maximum window is **90 days**.
  </Card>

  <Card title="Your data, only yours" icon="lock">
    You only see the data that belongs to you. There's no per-client filter parameter — it's enforced automatically by your token.
  </Card>

  <Card title="Rate limits" icon="gauge">
    **60 requests/min** and **50,000/day** per client. When exceeded: `429` with the `Retry-After` header.
  </Card>

  <Card title="Pagination" icon="layer-group">
    Use `limit` (up to 5000). If `meta.truncated` is `true`, there's more data — narrow the date window. Records come newest first.
  </Card>
</CardGroup>

## Errors

All errors follow the same shape:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "human-readable error description",
    "correlation_id": "a1b2c3d4-0000-0000-0000-000000000000"
  }
}
```

| Status | `code`            | When it happens                                         |
| ------ | ----------------- | ------------------------------------------------------- |
| `400`  | `invalid_request` | Invalid parameters (malformed dates, `from > to`)       |
| `401`  | `invalid_token`   | Token missing, invalid, or expired → generate a new one |
| `403`  | `forbidden`       | Token lacks permission for the resource                 |
| `422`  | `invalid_request` | Date window larger than 90 days                         |
| `429`  | `rate_limited`    | Rate limit exceeded                                     |
| `5xx`  | `internal_error`  | Internal error — try again later                        |

<Note>
  The `correlation_id` is always present in the response (and in the `x-correlation-id` header). **Include it when opening a support ticket** — it lets us trace your exact request.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Understand the token flow and security best practices.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/purchases/list-purchases">
    Explore the endpoints with the "Try it" playground.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks/overview">
    Get notified in near real time about checkouts, orders, and refunds.
  </Card>
</CardGroup>