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

# Instituições

> Crie e gerencie as instituições que emitem certificados.

# Instituições

Uma instituição é o órgão emissor — a universidade, escola ou organização que concede certificados. É a **entidade de nível mais alto** na hierarquia acadêmica e deve ser criada antes de cursos, módulos ou certificados.

***

## O objeto instituição

```json theme={null}
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Federal University of Technology",
  "legal_name": "Federal University of Technology Foundation",
  "tax_id": "00.000.000/0001-00",
  "country": "Brazil",
  "website": "https://fut.edu.br",
  "linkedin_organization": "federal-university-of-technology",
  "status": "active",
  "is_badges_enabled": false,
  "badge_image_uuid": null,
  "created_at": "2024-01-15T10:00:00.000000Z",
  "updated_at": "2024-01-15T10:00:00.000000Z"
}
```

| Campo                   | Tipo         | Descrição                                                                                 |
| ----------------------- | ------------ | ----------------------------------------------------------------------------------------- |
| `uuid`                  | string       | Identificador único — utilize este valor em todas as requisições de recursos relacionados |
| `name`                  | string       | Nome de exibição                                                                          |
| `legal_name`            | string       | Nome oficial da entidade legal                                                            |
| `tax_id`                | string       | Número de registro fiscal (ex.: CNPJ)                                                     |
| `country`               | string       | País de registro                                                                          |
| `website`               | string       | Site da instituição                                                                       |
| `linkedin_organization` | string       | Slug da organização no LinkedIn                                                           |
| `status`                | enum         | `active`, `inactive`, `suspended`                                                         |
| `is_badges_enabled`     | boolean      | Indica se a emissão de Open Badges está habilitada                                        |
| `badge_image_uuid`      | string\|null | UUID do arquivo de imagem do badge (obrigatório se badges estiver habilitado)             |

***

## Listar instituições

```http theme={null}
GET /institutions
```

**Parâmetros de consulta:** Consulte [Filtragem, Ordenação e Paginação](/pt-BR/core-concepts/filtering-sorting-pagination).

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.dokstamp.com/institutions \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "X-Tenant: {TENANT}"
  ```
</CodeGroup>

***

## Criar uma instituição

```http theme={null}
POST /institutions
```

| Parâmetro               | Tipo    | Obrigatório | Descrição                                     |
| ----------------------- | ------- | ----------- | --------------------------------------------- |
| `name`                  | string  | Sim         | Nome de exibição (máx. 255 caracteres)        |
| `country`               | string  | Sim         | País de registro                              |
| `legal_name`            | string  | Não         | Nome oficial da entidade legal                |
| `tax_id`                | string  | Não         | Número de registro fiscal                     |
| `website`               | string  | Não         | URL do site da instituição                    |
| `linkedin_organization` | string  | Não         | Identificador da organização no LinkedIn      |
| `status`                | enum    | Não         | `active` (padrão), `inactive`, `suspended`    |
| `is_badges_enabled`     | boolean | Não         | Habilitar emissão de Open Badges              |
| `badge_image_uuid`      | string  | Não\*       | Obrigatório se `is_badges_enabled` for `true` |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.dokstamp.com/institutions \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-Tenant: {TENANT}" \
    -d '{
      "name": "Federal University of Technology",
      "legal_name": "Federal University of Technology Foundation",
      "tax_id": "00.000.000/0001-00",
      "country": "Brazil",
      "website": "https://fut.edu.br",
      "status": "active"
    }'
  ```
</CodeGroup>

**Resposta `201`:**

```json theme={null}
{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Federal University of Technology",
    ...
  }
}
```

***

## Obter uma instituição

```http theme={null}
GET /institutions/{uuid}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.dokstamp.com/institutions/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "X-Tenant: {TENANT}"
  ```
</CodeGroup>

***

## Atualizar uma instituição

```http theme={null}
PATCH /institutions/{uuid}
```

Envie apenas os campos que deseja alterar. `PATCH` realiza uma atualização parcial.

```http theme={null}
PUT /institutions/{uuid}
```

`PUT` substitui o recurso inteiro — todos os campos devem ser fornecidos.

***

## Excluir uma instituição

```http theme={null}
DELETE /institutions/{uuid}
```

Retorna `204 No Content` em caso de sucesso. Esta é uma **exclusão lógica** — o registro não é removido permanentemente.

<Warning>
  Excluir uma instituição não exclui os cursos, módulos ou certificados vinculados a ela. Esses registros permanecerão, mas farão referência a uma instituição excluída.
</Warning>

***

## Exclusão em lote

```http theme={null}
DELETE /institutions/batch/destroy
```

| Parâmetro | Tipo  | Obrigatório | Descrição                                |
| --------- | ----- | ----------- | ---------------------------------------- |
| `uuids`   | array | Sim         | Array de UUIDs de instituições a excluir |

```json theme={null}
{ "uuids": ["uuid-1", "uuid-2", "uuid-3"] }
```

***

## Obter configuração de emissor de badges

```http theme={null}
GET /institutions/{uuid}/badges/issuers
```

Retorna o perfil de emissor de Open Badges da instituição. Utilizado na geração de asserções de badge.