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

# Visão geral da API

> API com chave de serviço para análises de ACU, gerenciamento de grupos e limites de ACU em implantações federais.

<Info>
  Esta documentação é destinada às implantações federais do Devin. [Voltar para a documentação do Devin](/pt-BR/get-started/devin-intro)
</Info>

Administradores do Enterprise federal podem consultar programaticamente o consumo de ACU e gerenciar [grupos](/pt-BR/federal/groups), [disponibilidade de modelos](/pt-BR/federal/model-provisioning) e [limites de ACU](/pt-BR/federal/acu-limits) usando uma API com chave de serviço. Um [SDK Python](/pt-BR/federal/api/python-sdk) encapsula todos os endpoints descritos nesta seção.

Os endpoints de gerenciamento de grupos e de limite de ACU estão disponíveis somente em implantações federais auto-hospedadas e multi-tenant. Eles não são disponibilizados em implantações comerciais. Os endpoints de análises (`/Analytics`, `/UserPageAnalytics` e `/CascadeAnalytics`) também verificam o nível de acesso a análises da implantação; uma equipe sem acesso a análises recebe `permission_denied`.

***

<div id="base-url">
  ## URL base
</div>

Todas as requisições são do tipo JSON `POST` e direcionadas ao servidor de API da sua implantação:

```
https://<your-server>/api/v1/<Method>
```

Substitua `<your-server>` pelo domínio da API da sua implantação federal.

<div id="authentication">
  ## Autenticação
</div>

Todas as requisições são autenticadas com uma **chave de serviço** incluída no corpo da requisição:

```json theme={null}
{
  "service_key": "your_service_key_here"
}
```

Para criar uma chave de serviço, faça login no portal federal como administrador da equipe e acesse **Configurações → Chaves de serviço**. Em seguida, crie uma chave com as permissões exigidas pelos endpoints que você pretende chamar.

<Warning>Mantenha as chaves de serviço seguras. Nunca as exponha em código do lado do cliente nem faça commit delas em repositórios.</Warning>

<div id="required-permissions">
  ### Permissões necessárias
</div>

| Endpoint                                                                                                                    | Permissão necessária |
| --------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| [Relatório de uso legado](/pt-BR/federal/api/python-sdk#per-user-usage-report) (`/UserPageAnalytics` e `/CascadeAnalytics`) | Teams Read-Only      |
| [Consumo de ACU](/pt-BR/federal/api/acu-consumption) (`/Analytics`)                                                         | Analytics Read       |
| [Listar grupos](/pt-BR/federal/api/group-management#list-groups) (`/ListGroups`)                                            | Teams Read-Only      |
| [Obter grupo](/pt-BR/federal/api/group-management#get-group) (`/GetGroup`)                                                  | Teams Read-Only      |
| [Criar grupo](/pt-BR/federal/api/group-management#create-group) (`/CreateGroup`)                                            | Teams Update         |
| [Atualizar grupo](/pt-BR/federal/api/group-management#update-group) (`/UpdateGroup`)                                        | Teams Update         |
| [Excluir grupo](/pt-BR/federal/api/group-management#delete-group) (`/DeleteGroup`)                                          | Teams Update         |
| [Listar membros do grupo](/pt-BR/federal/api/group-management#list-group-members) (`/ListGroupMembers`)                     | Teams Read-Only      |
| [Adicionar membros ao grupo](/pt-BR/federal/api/group-management#add-group-members) (`/AddGroupMembers`)                    | Teams Update         |
| [Remover membros do grupo](/pt-BR/federal/api/group-management#remove-group-members) (`/RemoveGroupMembers`)                | Teams Update         |
| [Obter o limite de ACU de um usuário](/pt-BR/federal/api/acu-caps#get-a-users-acu-cap) (`/GetUserAcuCap`)                   | Teams Read-Only      |
| [Atualizar o limite de ACU de um usuário](/pt-BR/federal/api/acu-caps#set-or-clear-a-users-acu-cap) (`/UpdateUserAcuCap`)   | Teams Update         |

<div id="team-scoped-and-group-scoped-keys">
  ### Chaves com escopo de equipe e grupo
</div>

As chaves de serviço recebem um escopo no momento da criação:

* As **chaves com escopo de equipe** podem consultar dados de toda a equipe e gerenciar todos os grupos da equipe.
* As **chaves com escopo de grupo** são limitadas ao grupo atribuído. Elas podem ler o total agregado de ACUs do grupo e as linhas de usuários, listar e ler somente esse grupo e ler ou atualizar limites de ACU apenas para os membros atuais desse grupo. Elas não podem ler os totais de toda a equipe nem as linhas de usuários, visualizar outros grupos ou criar grupos.

<div id="pagination">
  ## Paginação
</div>

As listas de grupos, de membros de grupos e de linhas de ACU por usuário são paginadas:

* `page_size` — opcional; o padrão é 100 e o máximo é 1.000. Omiti-lo ou informar `0` usa o valor padrão.
* `next_page_token` — retornado quando houver mais resultados. Envie-o novamente como `page_token` em uma requisição idêntica em todos os demais aspectos (incluindo o mesmo `page_size`) para buscar a próxima página.

Os tokens de página são opacos e criptografados. Eles expiram após 24 horas. Os tokens de consumo de ACU são vinculados ao endpoint, à equipe, ao escopo, ao período, à seleção de grupos e ao tamanho da página. Os tokens das listas de grupos e de membros são vinculados ao endpoint, à equipe, ao escopo e ao tamanho da página. Alterar um valor vinculado entre páginas retorna um erro `invalid_argument`.

<div id="errors">
  ## Erros
</div>

Os erros são retornados em JSON com um código e uma mensagem:

```json theme={null}
{
  "code": "permission_denied",
  "message": "service key role is missing the required permission"
}
```

| Código                | Significado                                                                                                                                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unauthenticated`     | A chave de serviço está ausente, é inválida ou expirou.                                                                                                                                                                   |
| `permission_denied`   | A função da chave de serviço não tem a permissão necessária.                                                                                                                                                              |
| `invalid_argument`    | A requisição está malformada — por exemplo, contém um período inválido, uma consulta do Custom Analytics que mistura tipos e campos personalizados, uma atualização vazia ou um token de página obsoleto ou incompatível. |
| `not_found`           | O recurso não existe, pertence a outra equipe ou está fora do escopo da chave de serviço. Recursos de outras equipes ou fora do escopo são indistinguíveis de recursos ausentes.                                          |
| `failed_precondition` | A requisição é válida, mas não pode ser concluída no estado atual, como ao definir um limite de ACU para uma equipe que não usa cobrança por ACU ou ao selecionar um e-mail de usuário ambíguo.                           |
| `already_exists`      | O nome de grupo solicitado já está em uso pela equipe.                                                                                                                                                                    |
| `internal`            | O serviço não conseguiu concluir a requisição.                                                                                                                                                                            |