> ## 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 faça a gestão das 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 todos os pedidos de recursos relacionados |
| `name`                  | string       | Nome de apresentação                                                                  |
| `legal_name`            | string       | Nome oficial da entidade legal                                                        |
| `tax_id`                | string       | Número de registo fiscal (ex.: CNPJ)                                                  |
| `country`               | string       | País de registo                                                                       |
| `website`               | string       | Sítio web 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á ativa                                         |
| `badge_image_uuid`      | string\|null | UUID do ficheiro de imagem do badge (obrigatório se badges estiver ativo)             |

***

## Listar instituições

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

**Parâmetros de consulta:** Consulte [Filtragem, Ordenação e Paginação](/pt/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 apresentação (máx. 255 caracteres)    |
| `country`               | string  | Sim         | País de registo                               |
| `legal_name`            | string  | Não         | Nome oficial da entidade legal                |
| `tax_id`                | string  | Não         | Número de registo fiscal                      |
| `website`               | string  | Não         | URL do sítio web 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         | Ativar 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 pretende alterar. `PATCH` realiza uma atualização parcial.

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

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

***

## Eliminar uma instituição

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

Devolve `204 No Content` em caso de sucesso. Trata-se de uma **eliminação lógica** — o registo não é removido permanentemente.

<Warning>
  Eliminar uma instituição não elimina os cursos, módulos ou certificados a ela associados. Esses registos permanecerão, mas farão referência a uma instituição eliminada.
</Warning>

***

## Eliminaçã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 eliminar |

```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
```

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