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

# Introdução

> Entenda os conceitos gerais, códigos de resposta e estratégias de autenticação.

## URL Base

A API da Pingback é construída seguindo os princípios **REST**. Exigimos **HTTPS** em todas as requisições para melhorar a segurança, integridade e privacidade dos dados. A API não oferece suporte a **HTTP**.

Todas as requisições utilizam a seguinte URL base:

```json theme={null}
https://connect.pingback.com/v2
```

## **Autenticação**

A API da Pingback utiliza chaves de API (API keys) para autenticar as requisições. Você pode solicitar e gerenciar suas chaves de API na [página de API Key](https://pingback.com/publish/settings/account/api-key).

Para autenticar uma requisição, é necessário adicionar um header com o seguinte conteúdo: `x-api-key: ***`, onde `***` é a sua API Key.

```json theme={null}
x-api-key: ***
```

Sua API key é exclusiva da sua conta e deve ser mantida em segurança. Não compartilhe sua API key em locais públicos, como repositórios no GitHub, código client-side, entre outros.

Além disso, armazenamos sua API key de forma criptografada em nosso banco de dados, utilizando criptografia `AES-256`, garantindo sua segurança.

## Códigos de resposta

A Pingback utiliza códigos HTTP padrão para indicar o sucesso ou a falha das requisições.

De forma geral, códigos HTTP `2xx` indicam sucesso, códigos `4xx` representam falhas relacionadas à requisição do usuário, e códigos `5xx` indicam problemas de infraestrutura.

| Status | Description                                |
| :----- | :----------------------------------------- |
| 200    | Requisição realizada com sucesso.          |
| 201    | O recurso foi criado.                      |
| 400    | Corpo da requisição ausente                |
| 403    | Acesso negado.                             |
| 404    | Recurso não encontrado.                    |
| 409    | Conflito.                                  |
| 422    | Entrada inválida.                          |
| 429    | Muitas requisições.                        |
| 500    | Indica um erro nos servidores da Pingback. |

## Limite de requisições

A Pingback aplica limites de requisição para garantir o uso justo da API. Caso você ultrapasse esse limite, receberá um código de status `429`.

O número máximo de requisições permitido é de **5 requisições por segundo**.

O limite de pico (burst rate) é de **2 requisições simultâneas**.

Para evitar esse erro, recomendamos reduzir a taxa de requisições à API. Isso pode ser feito utilizando um mecanismo de fila ou diminuindo o número de requisições concorrentes por segundo. Caso tenha necessidades específicas, entre em contato com o [**time de suporte**](https://helpcenter.pingback.com/).

## Modo do desenvolvedor

A API da Pingback possui um modo desenvolvedor que permite testar integrações sem impactar os dados de produção. Para ativar o modo desenvolvedor, adicione o seguinte header à requisição:

```json theme={null}
x-developer-mode: true
```

Esse modo é útil para testar integrações e garantir que seu código esteja funcionando corretamente. Todos os dados retornados no modo desenvolvedor são fictícios e não afetam seus dados de produção.