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

# API Reference

> Complete reference for the Rinne API

The Rinne API is organized around REST principles. It uses standard HTTP methods, authentication, and status codes. All requests and responses use JSON format.

## Base URLs

<CodeGroup>
  ```bash Sandbox theme={null}
  https://api-sandbox.rinne.com.br/core
  ```

  ```bash Production theme={null}
  https://api.rinne.com.br/core
  ```
</CodeGroup>

## Authentication

The API uses API key authentication via the `x-api-key` header:

```bash theme={null}
curl https://api-sandbox.rinne.com.br/core/v1/companies/me \
  -H "x-api-key: YOUR_API_KEY"
```

Some endpoints also support JWT authentication via the `Authorization` header:

```bash theme={null}
curl https://api-sandbox.rinne.com.br/core/v1/auth/me \
  -H "Authorization: Bearer JWT_TOKEN"
```

See the [Authentication guide](/guides/authentication) for details.

## Permissions

JWT-authenticated requests are subject to permission checks. Each endpoint requires specific permissions in the format `resource[.subresource].action` (e.g., `transaction.list`, `merchant.company.create`).

* **API key auth**: Bypasses permission checks
* **JWT auth**: Permissions are validated against the user's roles

Wildcard permissions grant broader access:

* `resource.*`: All actions for a resource
* `merchant.*`: All merchant-scoped operations
* `*.*`: All permissions

See the [User management guide](/guides/user-management#roles-and-permissions) for the full permission list.

## Request format

All POST, PATCH, and PUT requests must include a `Content-Type: application/json` header and a JSON body:

```bash theme={null}
curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Store Name Ltda.",
    "document_number": "16525269000121",
    ...
  }'
```

## Response format

### Success responses

Successful requests return the requested data directly:

```json theme={null}
{
  "id": "merchant-123",
  "name": "My Store",
  "status": "ACTIVE",
  ...
}
```

### Error responses

Errors return an `error` object with detailed information:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "status": 400,
    "details": {
      "issues": [...]
    }
  }
}
```

See the [Error handling guide](/guides/error-handling) for details.

## Pagination

All list endpoints return paginated responses with a unified structure. Use query parameters to control pagination:

| Parameter | Type    | Default | Description                   |
| --------- | ------- | ------- | ----------------------------- |
| `page`    | integer | 1       | Page number to retrieve       |
| `limit`   | integer | 20      | Items per page (maximum: 100) |

```bash theme={null}
curl "https://api-sandbox.rinne.com.br/core/v1/merchants?page=2&limit=10" \
  -H "x-api-key: YOUR_API_KEY"
```

Every paginated response wraps the results in a `data` array and includes a `pagination` object:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 10,
    "total": 50,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": true
  }
}
```

### Pagination fields

| Field        | Type    | Description                              |
| ------------ | ------- | ---------------------------------------- |
| `page`       | integer | Current page number                      |
| `limit`      | integer | Number of items per page                 |
| `total`      | integer | Total number of items matching the query |
| `totalPages` | integer | Total number of pages                    |
| `hasNext`    | boolean | Whether a next page exists               |
| `hasPrev`    | boolean | Whether a previous page exists           |

## Filtering and sorting

Many list endpoints support filtering and sorting:

### Filtering

```bash theme={null}
# Filter by status
GET /v1/merchants?status=ACTIVE,INACTIVE

# Filter by date range
GET /v1/transactions?created_at_from=2025-01-01T00:00:00Z&created_at_to=2025-01-31T23:59:59Z

# Filter by amount range
GET /v1/transactions?amount_from=5000&amount_to=20000
```

### Sorting

Use the `sort` parameter with field names. Prefix with `-` for descending order:

```bash theme={null}
# Sort by creation date (newest first)
GET /v1/merchants?sort=-created_at

# Multiple sort fields
GET /v1/transactions?sort=-created_at,amount
```

## Idempotency

Use the `request_id` field to make requests idempotent:

```json theme={null}
{
  "request_id": "unique-request-123",
  "amount": 10000,
  ...
}
```

If you retry a request with the same `request_id`, you'll receive the existing resource instead of creating a duplicate.

## Amounts in cents

All monetary values are represented as integers in cents:

* `10000` = R\$ 100.00
* `1050` = R\$ 10.50
* `99` = R\$ 0.99

<Warning>
  Never use decimal values or floating-point numbers for amounts.
</Warning>

## Date and time format

All timestamps use ISO 8601 format with UTC timezone:

```
2025-01-21T10:30:00.000Z
```

## Supported providers

The API supports multiple payment providers:

* `CELCOIN`: PIX integration and banking services
* `RINNE`: Internal provider

Provider names are case-insensitive in requests but always returned in uppercase.

## Rate limiting

The API enforces two request rate limits, each applied as a shared pool across all matching endpoints rather than per-endpoint:

* **1000 req/s** for every `POST` request for transaction creation and 3DS session creation and authentication.
* **50 req/s** for all other requests.

Limits behave identically across all environments, including sandbox. Requests within the limit always succeed; only the excess requests above the limit are rejected with a `429` status code, with no account block or penalty. See the [Rate limits guide](/guides/rate-limits) for full details.

## Webhooks

Rinne sends webhooks for real-time event notifications. See the [Webhooks guide](/guides/webhooks) for setup and handling.

## API versioning

The current API version is `v1`, indicated in the URL path:

```
/v1/transactions
/v1/merchants
```

Future versions will be released as `v2`, `v3`, etc. Version 1 will remain supported for backward compatibility.

## Next steps

<CardGroup cols={2}>
  <Card title="Card transactions" icon="credit-card" href="/guides/card-transactions">
    Implement credit and debit card API flows
  </Card>

  <Card title="Wallet transactions" icon="wallet" href="/guides/wallet-transactions">
    Process Apple Pay and Google Pay via backend APIs
  </Card>

  <Card title="3D Secure authentication" icon="shield-check" href="/guides/three-d-secure-authentication">
    Implement session-first and transaction-first 3DS flows
  </Card>

  <Card title="PIX payments" icon="qrcode" href="/guides/pix-payments">
    Build QR code and due date payment flows
  </Card>
</CardGroup>