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

# APIs Privadas

> As APIs privadas permitem que você faça chamadas para a BonifiQ via backend da sua aplicação

<Info>
  **Guias de desenvolvimento** Utilize nossos [Guias de Desenvolvimento](/guias/pos-integration) para mais detalhes sobre integrações de fluxos comuns
</Info>

## Limitações

Estes endpoints foram criados com intuito de comunicação entre sistemas (backend-to-backend) e, portanto, não são compatíveis com CORS e não podem ser utilizados em navegadores e frontends (como React, Angular, Javascript, etc). Se sua integração precisar de um browser você provavelmente deverá utilizar as APIs de Frontend.

## Autenticação

Todas as requisições para a API de PDV devem incluir as credenciais de autenticação no header usando **Basic Authentication**.

### Obtendo suas Credenciais

Para obter suas credenciais de API, acesse o painel administrativo da BonifiQ:

<Steps>
  <Step title="Acesse o Menu API">
    No painel administrativo, navegue até o menu **API** na barra lateral.
  </Step>

  <Step title="Criar Nova Credencial">
    Clique no botão **+ CREDENCIAL** para criar uma nova credencial de API.
  </Step>

  <Step title="Selecione o Tipo Privada">
    Escolha a opção **Privada** para gerar credenciais de acesso à API privada (POS).
  </Step>

  <Step title="Copie as Credenciais">
    Após a criação, você receberá um **usuário** e **senha** de API. Guarde essas informações em local seguro.
  </Step>
</Steps>

### Enviando a Autenticação

A autenticação deve ser enviada no header `Authorization` usando o esquema **Basic Auth**. O valor deve ser a codificação Base64 das credenciais no formato `usuario:senha`.

```bash theme={null}
Authorization: Basic {base64(usuario:senha)}
```

#### Exemplo de Implementação

<CodeGroup>
  ```bash cURL theme={null}
  # Credenciais de exemplo:
  # Usuário: meu_usuario_api
  # Senha: minha_senha_secreta

  # Codificação Base64 de "meu_usuario_api:minha_senha_secreta"
  # Resultado: bWV1X3VzdWFyaW9fYXBpOm1pbmhhX3NlbmhhX3NlY3JldGE=

  curl -X POST "https://api.bonifiq.com.br/v1/pvt/POS/rewards/available" \
    -H "Authorization: Basic bWV1X3VzdWFyaW9fYXBpOm1pbmhhX3NlbmhhX3NlY3JldGE=" \
    -H "Content-Type: application/json" \
    -d '{"customerId": "12345678900", "purchaseValue": 150.00}'
  ```

  ```javascript JavaScript theme={null}
  const usuario = 'meu_usuario_api';
  const senha = 'minha_senha_secreta';

  // Codifica as credenciais em Base64
  const credenciais = btoa(`${usuario}:${senha}`);

  const response = await fetch('https://api.bonifiq.com.br/v1/pvt/POS/rewards/available', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${credenciais}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      customerId: '12345678900',
      purchaseValue: 150.00
    })
  });
  ```

  ```csharp C# theme={null}
  var usuario = "meu_usuario_api";
  var senha = "minha_senha_secreta";

  // Codifica as credenciais em Base64
  var credenciais = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{usuario}:{senha}"));

  var client = new HttpClient();
  client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credenciais);

  var content = new StringContent(
      JsonSerializer.Serialize(new { customerId = "12345678900", purchaseValue = 150.00 }),
      Encoding.UTF8,
      "application/json"
  );

  var response = await client.PostAsync("https://api.bonifiq.com.br/v1/pvt/POS/rewards/available", content);
  ```

  ```python Python theme={null}
  import base64
  import requests

  usuario = 'meu_usuario_api'
  senha = 'minha_senha_secreta'

  # Codifica as credenciais em Base64
  credenciais = base64.b64encode(f'{usuario}:{senha}'.encode()).decode()

  response = requests.post(
      'https://api.bonifiq.com.br/v1/pvt/POS/rewards/available',
      headers={
          'Authorization': f'Basic {credenciais}',
          'Content-Type': 'application/json'
      },
      json={
          'customerId': '12345678900',
          'purchaseValue': 150.00
      }
  )
  ```
</CodeGroup>

<Warning>
  **Segurança das Credenciais**

  * Nunca exponha suas credenciais em código client-side (frontend, aplicativos mobile, etc.)
  * Armazene as credenciais em variáveis de ambiente ou cofres de segredos
  * Não versione arquivos contendo credenciais em repositórios de código
  * Rotacione as credenciais periodicamente
</Warning>