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

# Referência da API

> Documentação completa de todos os endpoints da API StylePay

## Base URL

Todas as requisições da API devem ser feitas para:

```
https://api.stylepay.com.br
```

## Autenticação

Todas as requisições requerem autenticação via headers customizados:

```bash theme={null}
stpi: seu_client_id
stps: seu_client_secret
```

<Card title="Como autenticar" icon="key" href="/auth">
  Veja o guia completo de autenticação
</Card>

***

## Endpoints Disponíveis

### 💰 Gateway PIX

Endpoints para criar e gerenciar cobranças e pagamentos PIX.

<CardGroup cols={2}>
  <Card title="Gerar QR Code PIX" icon="qrcode" href="/gerar-qrcode-pix">
    `POST /api/v1/gateway/request-qrcode`

    Cria uma cobrança PIX e gera o QR Code para pagamento
  </Card>

  <Card title="Realizar Pagamento PIX" icon="paper-plane" href="/pagamento-pix">
    `POST /api/v1/gateway/pix-payment`

    Envia um pagamento PIX para qualquer chave
  </Card>
</CardGroup>

### 💼 Wallet (Carteira)

Endpoints para gerenciamento de saldo e transações.

<CardGroup cols={2}>
  <Card title="Consultar Saldo" icon="wallet" href="/wallet">
    `GET /api/v1/wallet/balance`

    Consulta o saldo disponível na carteira
  </Card>

  <Card title="Histórico de Transações" icon="clock-rotate-left" href="/wallet">
    `GET /api/v1/wallet/transactions`

    Lista todas as transações realizadas
  </Card>
</CardGroup>

### 🔔 Webhooks

Sistema de notificações em tempo real.

<Card title="Webhooks" icon="webhook" href="/webhooks">
  Configure URLs para receber notificações automáticas sobre mudanças de status em transações
</Card>

***

## Estrutura de Resposta

### Respostas de Sucesso

Todas as respostas bem-sucedidas retornam status HTTP `2xx`:

```json theme={null}
{
  "payment_id": "550e8400-e29b-41d4-a716-446655440000",
  "qrcode": "00020126580014br.gov.bcb.pix...",
  "status": "PENDING"
}
```

### Respostas de Erro

Erros retornam status HTTP `4xx` ou `5xx` com a seguinte estrutura:

```json theme={null}
{
  "statusCode": 400,
  "message": "Invalid request parameters",
  "error": "Bad Request"
}
```

#### Códigos de Status Comuns

<ResponseField name="200" type="OK">
  Requisição processada com sucesso
</ResponseField>

<ResponseField name="201" type="Created">
  Recurso criado com sucesso
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Parâmetros inválidos na requisição
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Credenciais de autenticação inválidas ou ausentes
</ResponseField>

<ResponseField name="404" type="Not Found">
  Recurso não encontrado
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Erro interno do servidor
</ResponseField>

***

## Rate Limiting

A API StylePay implementa rate limiting para garantir estabilidade:

<Info>
  **Limite padrão:** 100 requisições por minuto por Client ID
</Info>

Quando o limite é excedido, você receberá uma resposta `429 Too Many Requests`:

```json theme={null}
{
  "statusCode": 429,
  "message": "Rate limit exceeded",
  "error": "Too Many Requests",
  "retryAfter": 60
}
```

### Headers de Rate Limit

Todas as respostas incluem headers informativos:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000
```

***

## Tipos de Dados

### Valores Monetários

Todos os valores monetários são enviados e recebidos como números decimais em **reais (BRL)**:

```json theme={null}
{
  "amount": 100.50,  // R$ 100,50
  "tax": 1.50        // R$ 1,50
}
```

<Warning>
  Sempre use ponto (`.`) como separador decimal, nunca vírgula (`,`)
</Warning>

### Datas

Todas as datas seguem o formato **ISO 8601** com timezone UTC:

```json theme={null}
{
  "date": "2025-01-01T10:00:00.000Z"
}
```

### Documentos

CPF e CNPJ devem ser enviados **apenas com números**, sem pontos, traços ou barras:

```json theme={null}
{
  "document": "12345678900"     // CPF
}
```

```json theme={null}
{
  "document": "12345678000100"  // CNPJ
}
```

### Chaves PIX

Tipos de chave PIX aceitos:

| Tipo    | Formato            | Exemplo                                |
| ------- | ------------------ | -------------------------------------- |
| `CPF`   | 11 dígitos         | `12345678900`                          |
| `CNPJ`  | 14 dígitos         | `12345678000100`                       |
| `EMAIL` | Email válido       | `usuario@email.com`                    |
| `PHONE` | +55 + DDD + número | `+5511999999999`                       |
| `EVP`   | UUID v4            | `550e8400-e29b-41d4-a716-446655440000` |

***

## Idempotência

Para operações críticas como criação de pagamentos, use o campo `external_id` para garantir idempotência:

```json theme={null}
{
  "amount": 100.50,
  "external_id": "pedido_123_tentativa_1"
}
```

<Tip>
  Se você enviar a mesma requisição com o mesmo `external_id` múltiplas vezes, apenas uma transação será criada.
</Tip>

***

## Ambientes

### Produção

```
https://api.stylepay.com.br
```

<Warning>
  Este é o ambiente de produção. Todas as transações movimentam dinheiro real.
</Warning>

***

## Bibliotecas e SDKs

Estamos trabalhando em SDKs oficiais. Por enquanto, você pode integrar usando bibliotecas HTTP padrão:

<CodeGroup>
  ```javascript JavaScript/Node.js theme={null}
  // Usando fetch nativo
  const response = await fetch('https://api.stylepay.com.br/api/v1/endpoint', {
    method: 'POST',
    headers: {
      'stpi': process.env.STYLEPAY_CLIENT_ID,
      'stps': process.env.STYLEPAY_CLIENT_SECRET,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });
  ```

  ```python Python theme={null}
  # Usando requests
  import requests
  import os

  response = requests.post(
      'https://api.stylepay.com.br/api/v1/endpoint',
      headers={
          'stpi': os.getenv('STYLEPAY_CLIENT_ID'),
          'stps': os.getenv('STYLEPAY_CLIENT_SECRET'),
          'Content-Type': 'application/json'
      },
      json=data
  )
  ```

  ```php PHP theme={null}
  <?php
  // Usando cURL
  $ch = curl_init('https://api.stylepay.com.br/api/v1/endpoint');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'stpi: ' . getenv('STYLEPAY_CLIENT_ID'),
      'stps: ' . getenv('STYLEPAY_CLIENT_SECRET'),
      'Content-Type: application/json'
  ]);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  curl_close($ch);
  ?>
  ```

  ```ruby Ruby theme={null}
  # Usando net/http
  require 'net/http'
  require 'json'

  uri = URI('https://api.stylepay.com.br/api/v1/endpoint')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['stpi'] = ENV['STYLEPAY_CLIENT_ID']
  request['stps'] = ENV['STYLEPAY_CLIENT_SECRET']
  request['Content-Type'] = 'application/json'
  request.body = data.to_json

  response = http.request(request)
  ```
</CodeGroup>

***

## Webhooks

A API StylePay envia notificações automáticas para sua aplicação quando eventos importantes ocorrem:

<CardGroup cols={3}>
  <Card title="Cash-in" icon="arrow-down">
    Notificações de recebimentos
  </Card>

  <Card title="Cash-out" icon="arrow-up">
    Notificações de pagamentos
  </Card>

  <Card title="Refunds" icon="rotate-left">
    Notificações de estornos
  </Card>
</CardGroup>

<Card title="Configurar Webhooks" icon="gear" href="/webhooks">
  Veja como configurar e processar webhooks
</Card>

***

## Exemplos Práticos

### Fluxo Completo: Receber Pagamento

<Steps>
  <Step title="Criar QR Code">
    ```bash theme={null}
    POST /api/v1/gateway/request-qrcode
    ```

    Gera QR Code para o cliente pagar
  </Step>

  <Step title="Cliente Paga">
    O cliente escaneia o QR Code e confirma o pagamento no app do banco
  </Step>

  <Step title="Receber Webhook">
    ```json theme={null}
    {
      "event": "pix.cashin.paid",
      "statusTransaction": "PAID",
      "value": 100.50
    }
    ```

    Você recebe notificação automática do pagamento
  </Step>

  <Step title="Confirmar Saldo">
    ```bash theme={null}
    GET /api/v1/wallet/balance
    ```

    Consulta o saldo atualizado na carteira
  </Step>
</Steps>

### Fluxo Completo: Enviar Pagamento

<Steps>
  <Step title="Verificar Saldo">
    ```bash theme={null}
    GET /api/v1/wallet/balance
    ```

    Confirma que tem saldo suficiente
  </Step>

  <Step title="Enviar Pagamento">
    ```bash theme={null}
    POST /api/v1/gateway/pix-payment
    ```

    Envia PIX para a chave do destinatário
  </Step>

  <Step title="Receber Confirmação">
    ```json theme={null}
    {
      "event": "pix.cashout.paid",
      "statusTransaction": "PAID"
    }
    ```

    Webhook confirma que pagamento foi realizado
  </Step>
</Steps>

***

## Suporte

<CardGroup cols={3}>
  <Card title="Documentação" icon="book" href="/docs">
    Guias e tutoriais completos
  </Card>

  <Card title="Email" icon="envelope" href="mailto:suporte@stylepay.com.br">
    [suporte@stylepay.com.br](mailto:suporte@stylepay.com.br)
  </Card>

  <Card title="WhatsApp" icon="whatsapp" href="https://wa.me/5511999999999">
    +55 11 9999-9999
  </Card>
</CardGroup>

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Gerar QR Code PIX" icon="qrcode" href="/gerar-qrcode-pix">
    Comece criando sua primeira cobrança
  </Card>

  <Card title="Realizar Pagamento" icon="paper-plane" href="/pagamento-pix">
    Aprenda a enviar pagamentos PIX
  </Card>

  <Card title="Consultar Saldo" icon="wallet" href="/wallet">
    Gerencie o saldo da sua carteira
  </Card>

  <Card title="Configurar Webhooks" icon="webhook" href="/webhooks">
    Receba notificações em tempo real
  </Card>
</CardGroup>