# Visão geral da API

> Automatize lojas, scripts, alertas e relatórios PCI DSS do Proteside com a API REST v1 e receba eventos por webhook.

URL: https://docs.proteside.com/pt-BR/docs/api

A API pública v1 dá acesso, por código, a quase tudo o que você faz no dashboard. Use-a para integrar o Proteside ao
seu CI/CD, SIEM, ferramenta de tickets ou painel de parceiro, e os webhooks para reagir a eventos sem ficar
consultando a API.

## O que dá para automatizar
* **Lojas:** criar uma loja, obter a chave do SDK e o snippet de instalação, ajustar a configuração do SDK, rotacionar a
  chave e conferir se o SDK está instalado.
* **Páginas de pagamento:** cadastrar as URLs de checkout que o SDK deve proteger.
* **Scripts:** listar o inventário e autorizar ou bloquear scripts com justificativa (PCI DSS 4.0, requisito 6.4.3).
* **Regras:** criar, ativar, desativar e excluir regras de bloqueio ou permissão por domínio, URL ou hash.
* **Políticas de aprovação:** criar, simular e aplicar políticas que decidem scripts automaticamente.
* **Alertas:** listar, consultar, resolver e reabrir alertas.
* **Relatórios PCI DSS:** gerar e baixar relatórios em JSON, PDF ou CSV e agendar o envio semanal ou mensal.
* **Webhooks:** cadastrar endpoints, canais do Slack e do Microsoft Teams e disparar eventos de teste.
* **Parceiros:** criar organizações filhas, agir nelas e acompanhar o consumo de cada uma.

## Antes de começar
| Item            | Valor                                      |
| --------------- | ------------------------------------------ |
| Base URL        | `https://app.proteside.com/api/v1`         |
| Transporte      | HTTPS, corpo e respostas em JSON           |
| Nomes de campos | `snake_case`                               |
| Autenticação    | `Authorization: Bearer ps_live_…`          |
| Limite          | 120 requisições por minuto por organização |

> **Não existe ambiente de teste**
>
> Todo token emitido é `ps_live_` e toda chamada atua nos seus dados de produção. Para experimentar, use uma loja de
> homologação e tokens com escopos só de leitura.

A API foi feita para chamadas servidor a servidor: as rotas autenticadas não respondem a CORS, então chamadas feitas
direto do navegador são bloqueadas. Guarde o token no seu backend.

## Início rápido
### Crie um token
Em **Configurações → API**, clique em **Novo token**, dê um nome, marque o atalho **somente leitura** e clique em
**Criar token**. Copie o token na janela **Copie o token agora**: ele aparece uma única vez. O passo a passo completo
está em [Tokens e escopos](https://docs.proteside.com/pt-BR/docs/api/authentication).

### Faça a primeira requisição
Liste as lojas da sua organização:

```bash
export PROTESIDE_TOKEN="ps_live_SEU_TOKEN"

curl -s "https://app.proteside.com/api/v1/stores?limit=2" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN"
```

### Leia a resposta
As listas sempre vêm em `data`, com `next_cursor` para buscar a próxima página (`null` quando acabou):

```json
{
  "data": [
    {
      "id": "0c1d2e3f-1111-4222-8333-444455556666",
      "org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
      "name": "Minha Loja",
      "domain": "minhaloja.com.br",
      "country": "BR",
      "timezone": "America/Sao_Paulo",
      "status": "active",
      "sdk_key": "pk_live_SUA_CHAVE",
      "safe_slug": "minhaloja-ps3fa9c1",
      "emergency_contact": null,
      "created_at": "2026-09-27T10:01:00.000Z",
      "updated_at": "2026-09-27T10:01:00.000Z",
      "sdk_config": {
        "mode": "monitor",
        "payment_methods": ["pix", "card"],
        "release_channel": "stable"
      }
    }
  ],
  "next_cursor": null
}
```

Os headers `X-RateLimit-Limit` e `X-RateLimit-Remaining` mostram quanto do limite por minuto ainda resta. Veja
[Convenções](https://docs.proteside.com/pt-BR/docs/api/conventions) para paginação, erros e limites.

## Especificação OpenAPI
O contrato completo da API está em [`https://app.proteside.com/api/v1/openapi.json`](https://app.proteside.com/api/v1/openapi.json)
(OpenAPI 3.1, público, sem token). Importe esse endereço no Postman, no Insomnia ou no gerador de cliente da sua
linguagem. A [referência de endpoints](https://docs.proteside.com/pt-BR/docs/api/reference/stores/listStores) desta documentação é gerada a partir dele.

> **Nota**
>
> Quando esta documentação e o spec divergirem, vale o que está descrito aqui: as páginas conceituais registram o
> comportamento real da API, inclusive os pontos em que o spec ainda está desatualizado.

## Próximos passos
- [Tokens e escopos](https://docs.proteside.com/pt-BR/docs/api/authentication): Crie, use e revogue tokens com o menor privilégio possível.
- [Convenções](https://docs.proteside.com/pt-BR/docs/api/conventions): Paginação, erros, limite de requisições e idempotência.
- [Webhooks](https://docs.proteside.com/pt-BR/docs/api/webhooks): Receba eventos assinados e valide a assinatura.
- [Parceiros](https://docs.proteside.com/pt-BR/docs/api/partners): Gerencie organizações filhas com um único token.
- [Receitas](https://docs.proteside.com/pt-BR/docs/api/recipes): Fluxos completos com curl, do cadastro da loja ao relatório PCI.

## Referência de endpoints
- [Lojas](https://docs.proteside.com/pt-BR/docs/api/reference/stores/listStores): Criar, configurar, suspender e rotacionar a chave do SDK.
- [Páginas](https://docs.proteside.com/pt-BR/docs/api/reference/pages/listPages): Páginas de pagamento protegidas.
- [Scripts](https://docs.proteside.com/pt-BR/docs/api/reference/scripts/listScripts): Inventário, autorização e bloqueio.
- [Regras](https://docs.proteside.com/pt-BR/docs/api/reference/rules/listRules): Bloqueio e permissão por domínio, URL ou hash.
- [Políticas](https://docs.proteside.com/pt-BR/docs/api/reference/policies/listPolicies): Políticas de aprovação automática.
- [Alertas](https://docs.proteside.com/pt-BR/docs/api/reference/alerts/listAlerts): Consultar, resolver e reabrir.
- [Relatórios](https://docs.proteside.com/pt-BR/docs/api/reference/reports/getPciReport): Relatório PCI DSS e agendamentos.
- [Webhooks](https://docs.proteside.com/pt-BR/docs/api/reference/webhooks/listWebhooks): Canais de webhook, Slack e Teams.
- [Organizações](https://docs.proteside.com/pt-BR/docs/api/reference/organizations/listOrganizations): Organizações filhas e consumo.
- [Meta](https://docs.proteside.com/pt-BR/docs/api/reference/meta/getOpenApi): Documento OpenAPI.
