---
title: "API v2 - Convenções e comportamentos compartilhados"
slug: "api-v2-conventions-and-shared-behaviors"
updated: 2026-11-03T14:47:50Z
published: 2026-11-03T14:47:50Z
canonical: "docs.senhasegura.io/api-v2-conventions-and-shared-behaviors"
---

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

# API v2 - Convenções e comportamentos compartilhados

Este documento descreve os comportamentos padrão, regras e formatos que se aplicam a todos os endpoints da API v2 do **A2A**. Leia este documento antes de integrar com qualquer endpoint v2.

---

## Headers de resposta

Toda resposta da API v2 inclui os headers a seguir, independentemente do endpoint ou do código de status HTTP.

| Header | Descrição |
| --- | --- |
| `X-Request-Id` | Identificador único da requisição, atribuído pela Segura™. Use este valor ao reportar problemas ao suporte. |
| `ETag` | Hash que representa o estado atual do recurso retornado. Use com `If-None-Match` para leituras condicionais. |
| `X-RateLimit-Limit` | Número máximo de requisições permitidas na janela de tempo atual. |
| `X-RateLimit-Remaining` | Número de requisições restantes na janela de tempo atual. |
| `X-RateLimit-Reset` | Timestamp Unix em que a janela de rate limit atual é redefinida. |

> **Nota:** Quando o limite de requisições é excedido, a API retorna `429 Too Many Requests`. Aguarde até `X-RateLimit-Reset` antes de tentar novamente.

---

## Ações do recurso (`meta.actions`)

Respostas que retornam um único recurso incluem um objeto `meta.actions`. Cada chave nomeia uma ação disponível para aquele recurso, e seu valor é o caminho que executa a ação. Esse objeto é a forma prevista de uma integração descobrir o que pode fazer com um recurso, em vez de fixar caminhos no código.

| Campo | Descrição |
| --- | --- |
| `meta.links.self` | URL do próprio recurso. |
| `meta.actions.<action>` | Caminho de uma ação disponível para o recurso. A chave é omitida quando a ação não se aplica ao recurso no estado atual e quando a autorização não a permite. |

Uma chave ausente não é um erro. O objeto reflete o estado atual do recurso, então um recurso ativo não oferece a ação de ativação.

---

## Requisições condicionais

### `If-None-Match` — leituras condicionais (`GET`)

Use o valor do `ETag` de uma resposta anterior como header `If-None-Match` em uma requisição `GET` subsequente. Se o recurso não tiver sido alterado, o servidor retorna `304 Not Modified` sem corpo, economizando largura de banda.

```
GET /api/v2/pam/credentials/101
If-None-Match: "abc123etag"
```

| Resposta | Significado |
| --- | --- |
| `200 OK` | O recurso foi alterado. O corpo completo da resposta é retornado. |
| `304 Not Modified` | O recurso não foi alterado. Nenhum corpo é retornado; use a versão em cache. |

### `If-Match` — escritas condicionais (`PUT`, `PATCH`, `DELETE`)

Use o valor do `ETag` de uma leitura anterior como header `If-Match` em uma requisição de escrita. Isso impede a sobrescrita de alterações feitas por outro processo desde a sua última leitura (controle de concorrência otimista).

```
PUT /api/v2/pam/credentials/101
If-Match: "abc123etag"
```

| Resposta | Significado |
| --- | --- |
| `2xx` | O ETag correspondeu. A escrita foi aplicada. |
| `412 Precondition Failed` | O ETag não correspondeu. O recurso foi modificado desde a sua última leitura. Refaça a leitura antes de tentar novamente. |

---

## Formato de erros

Todas as respostas de erro v2 usam uma estrutura JSON consistente, independentemente do endpoint.

```
{
    "error": {
        "code": "api.fields.invalid",
        "message": "One or more requested fields do not exist in the canonical model.",
        "details": [
            {
                "field": "credential.nonexistent",
                "reason": "Field not found in CredentialV2 schema."
            }
        ]
    }
}
```

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `error.code` | string | Identificador de erro legível por máquina. Use para tratamento programático de erros. |
| `error.message` | string | Descrição legível do erro. |
| `error.details` | array de objetos | Contexto adicional sobre o erro. Pode estar vazio para erros genéricos. |
| `error.details[].field` | string | O campo ou parâmetro que causou o erro, quando aplicável. |
| `error.details[].reason` | string | Motivo específico pelo qual o campo ou parâmetro foi rejeitado. |

---

## Política de `403` vs `404`

A API v2 distingue deliberadamente entre falhas de autorização e recursos inexistentes.

| Código | Quando é retornado |
| --- | --- |
| `403 Forbidden` | O recurso existe, mas a autorização não tem permissão para acessá-lo, ou a requisição contém um campo sensível. A Segura™ retorna `403` mesmo quando o chamador poderia inferir a existência pelo retorno. |
| `404 Not Found` | O recurso genuinamente não existe ou o ID está malformado. |

> **Nota:** A Segura™ nunca retorna `404` para mascarar um `403`. Se você receber `404`, o recurso não existe. Se receber `403`, o recurso existe, mas está fora do escopo da sua autorização.

---

## Paginação

Todos os endpoints de listagem suportam duas estratégias de paginação. Cada endpoint documenta quais estratégias são suportadas.

### Paginação por offset

Use para navegação padrão e conjuntos de dados de tamanho moderado.

| Parâmetro | Tipo | Padrão | Descrição |
| --- | --- | --- | --- |
| `page` | integer | `1` | Número da página a recuperar. |
| `limit` | integer | `50` | Número de resultados por página. |

**Campos da resposta:**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `meta.pagination.page` | integer | Número da página atual. |
| `meta.pagination.limit` | integer | Resultados por página. |
| `meta.pagination.total_items` | integer | Total de registros correspondentes. Pode ser `null` ou uma estimativa para conjuntos de dados grandes. |
| `meta.pagination.total_pages` | integer | Número total de páginas. |
| `meta.pagination.count` | integer | Número de itens na página atual. |
| `meta.links.self` | string | URL da página atual. |
| `meta.links.first` | string | URL da primeira página. |
| `meta.links.prev` | string | URL da página anterior. `null` na primeira página. |
| `meta.links.next` | string | URL da próxima página. `null` na última página. |
| `meta.links.last` | string | URL da última página. |

### Paginação por cursor

Recomendada para conjuntos de dados acima de 100.000 registros. Mais eficiente que a paginação por offset para grandes volumes.

| Parâmetro | Tipo | Descrição |
| --- | --- | --- |
| `cursor` | string | Token de cursor opaco retornado em `meta.pagination.next_cursor`. Não decodifique nem construa cursors manualmente. Os cursors expiram após 24 horas. |

**Campos da resposta:**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `meta.pagination.cursor` | string | Cursor representando a posição atual. |
| `meta.pagination.next_cursor` | string | Cursor para a próxima página. `null` quando não há mais resultados. |
| `meta.pagination.has_more` | boolean | Indica se existem mais resultados além da página atual. |

> **Aviso:** `page`/`limit` e `cursor` são mutuamente exclusivos. Enviar ambos na mesma requisição retorna `422 Unprocessable Content`. Para conjuntos de dados grandes onde calcular `total_items` seria impraticável, o campo pode ser `null` ou uma estimativa — use `has_more` como sinal de continuação.

---

## Projeção de campos (`fields`)

Endpoints que suportam `fields` retornam apenas o subconjunto solicitado do modelo canônico, reduzindo o tamanho do payload.

**Uso:**

```
GET /api/v2/pam/credentials/101?fields=credential.username,device.name,jit.credential_enabled
```

**Regras:**

- Use notação de ponto para referenciar campos aninhados (ex.: `credential.username`, `device.tags`).
- Solicite um objeto completo nomeando-o sem um caminho filho (ex.: `fields=device` retorna todos os campos não sensíveis de `device`).
- Quando `fields` é omitido, todos os campos públicos do modelo canônico são retornados, com `null` para campos não aplicáveis.
- Campos não presentes no modelo canônico retornam `422` com código `api.fields.invalid`.
- Campos sensíveis retornam `403` com código `api.fields.sensitive.not.allowed`. Veja [Campos sensíveis](/docs/pt/api-v2-conventions-and-shared-behaviors#campos-sensiveis).
- Campos fora do escopo da autorização vigente retornam `403`.

**Campos sensíveis — nunca retornados:**

Os campos a seguir são permanentemente excluídos de todas as respostas. Solicitá-los retorna `403`:

- `credential.password`
- `certificate.key_file`
- `certificate.key_password`
- `totp.secret_key`

---

## Ordenação (`sort_by`)

Endpoints de listagem que suportam ordenação aceitam o parâmetro de query `sort_by`.

**Uso:**

```
GET /api/v2/pam/credentials?sort_by=criticality:desc,credential.username
```

**Regras:**

| Regra | Detalhe |
| --- | --- |
| Formato | `campo` ou `campo:asc` ou `campo:desc` |
| Direção padrão | `asc` quando nenhum sufixo é informado |
| Múltiplos campos | Separados por vírgula, processados da esquerda para a direita |
| Campo inválido | Retorna `422` |
| Direção inválida | Retorna `422` |

---

## Filtros

Endpoints de listagem aceitam parâmetros de filtro como query strings. Todos os parâmetros de filtro são opcionais.

### Lógica AND e OR

| Padrão | Lógica | Exemplo |
| --- | --- | --- |
| Parâmetros diferentes | AND | `?device_id=123&credential.criticality=high` |
| Mesmo parâmetro repetido | AND (para arrays) | `?credential.tags=prod&credential.tags=finance` |
| Valores separados por vírgula | OR | `?credential.criticality=high,medium` |

> **Nota:** O caractere pipe (`|`) não é suportado como separador OR. Use valores separados por vírgula.

### Valores booleanos em filtros

Parâmetros booleanos aceitam apenas `true` ou `false` como valores de string. Os valores `0`, `1`, `yes` e `no` não são aceitos e retornam `422`.

### Validação

Todos os parâmetros de filtro inválidos retornam um erro explícito — a API nunca ignora silenciosamente um filtro não reconhecido.

| Condição | Resposta |
| --- | --- |
| Campo inexistente | `422 Unprocessable Content` |
| Campo sensível usado como filtro | `422 Unprocessable Content` |
| Valor de enum inválido | `422 Unprocessable Content` |
| Valor booleano inválido | `422 Unprocessable Content` |

### Exemplos

**Correspondência exata:**

```
GET /api/v2/pam/credentials?credential.username=svc-payments
```

**AND — múltiplos campos:**

```
GET /api/v2/pam/credentials?device_id=123&credential.criticality=high&jit.credential_enabled=true
```

**AND — mesmo campo (array):**

```
GET /api/v2/pam/credentials?credential.tags=prod&credential.tags=finance
```

**OR — valores separados por vírgula:**

```
GET /api/v2/pam/credentials?credential.criticality=high,medium
```

**Ordenação por múltiplos campos:**

```
GET /api/v2/pam/credentials?sort_by=criticality:desc,credential.username
```

---

## Convenções de nomenclatura

Todos os endpoints da API v2 seguem estas convenções de forma consistente.

| Convenção | Regra |
| --- | --- |
| Nomenclatura de path | `snake_case` para parâmetros de query e campos de resposta; `kebab-case` para segmentos de path compostos (ex.: `/group-sync`) |
| Collections | Substantivos no plural (ex.: `/credentials`, `/devices`) |
| Nomes de campos | `snake_case` em todos os payloads de requisição e resposta. `camelCase` não é utilizado. |
| Booleanos em query strings | Somente `true` / `false` |

---

## Erros de autenticação

Os erros de autenticação a seguir se aplicam a todos os endpoints v2.

| Mensagem | Causa possível | Solução |
| --- | --- | --- |
| `Client authentication failed.` | Falha na autenticação da aplicação com o servidor Segura™. | Verifique os parâmetros de autenticação (`Access Token URL`, `Client ID` e `Client secret`) e solicite um novo token de acesso. |
| `Invalid signature` | Falha no reconhecimento da URL da aplicação cliente. | Verifique a URL da aplicação cliente e reenvie a requisição. |
| `No route matched with those values.` | Header de autorização ausente na requisição da API. | Solicite um novo token de acesso. |
| `Request timed out.` | A requisição excedeu o limite de tempo. | Verifique a conectividade entre a origem da requisição e o servidor Segura™. |

---

## Documentos relacionados

- [GET | Listar todas as credenciais (v2)](/v4-2/docs/api-v2-get-list-all-credentials)
- [GET | Listar uma credencial por [id] (v2)](/v4-2/docs/api-v2-get-list-a-credential)
- [Sobre aplicações e autorizações no A2A](/v4-2/docs/a2a-about-applications-and-authorizations)