Entidades

Aqui se encontram os endpoints necessários para o gerenciamento da estrutura de entidades.

Criar uma entidade

POST /api/v2/partners/entities

Atributos

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim	Nome da entidade. Ex: `6o. Ano`
`entity_type`	enum	sim	Tipo da entidade: `network` (Rede), `school` (Escola) ou `class` (Turma)
`degree`	enum	sim	Série da entidade. Ver tabela em Estruturas Organizacionais
`inep`	string	não	Código INEP, usado apenas para `entity_type` com valor `school`. Ex: `123456`
`state`	string	não	Estado da entidade. Ex: `RS`
`city`	string	não	Cidade da entidade. Ex: `Caxias do Sul`
`reference_id`	string	sim	ID de referência do parceiro
`parent_reference_id`	string	sim	ID de referência da entidade de nível hierárquico superior

Request

POST /api/v2/partners/entities
Authorization: APIAuth access_key_id:signature
Content-Type: application/json

{
    "name": "Escola Exemplo",
    "entity_type": "school",
    "inep": "123456",
    "degree": "F",
    "state": "RS",
    "city": "Caxias do Sul",
    "reference_id": "707f3687-a2de-48f8-abfb-5804393de9cf",
    "parent_reference_id": "fajem-2x7io4zldu47jela98g16iyi-pmown"
}

Response

201 Created

{
    "data": {
        "city": "Caxias do Sul",
        "degree": "F",
        "entity_type": "school",
        "inep": "123456",
        "name": "Escola Exemplo",
        "parent_reference_id": "fajem-2x7io4zldu47jela98g16iyi-pmown",
        "reference_id": "707f3687-a2de-48f8-abfb-5804393de9cf",
        "state": "RS"
    },
    "errors": null,
    "pagination": null
}

422 Unprocessable Entity

{
    "errors": {
        "field_with_error": ["error_message"]
    }
}

Listagem de entidades

GET /api/v2/partners/entities

Atributos

Campo	Tipo	Obrigatório	Descrição
`after`	string	não	Cursor da próxima página
`before`	string	não	Cursor da página anterior
`entity_type`	enum	sim	Tipo da entidade: `network`, `school` ou `class`

Request

GET /api/v2/partners/entities?entity_type=class
Authorization: APIAuth access_key_id:signature

Response

200 OK

{
    "entries": [
        {
            "city": "Porto Alegre",
            "degree": "9",
            "entity_type": "class",
            "inep": null,
            "name": "9o. Ano",
            "reference_id": "cuy42r6je6lkv9u-y6g9rjoe-92zm2pdt-f6",
            "state": "RS"
        }
    ],
    "metadata": {
        "after": null,
        "before": null,
        "limit": 50
    }
}

Listagem de descendentes de uma entidade

GET /api/v2/partners/entities/{reference_id}/subtree

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`reference_id`	string	sim	ID de referência da entidade. Ex: `cuy42r6je6lkv9u-y6g9rjoe-92zm2pdt-f6`

Atributos

Campo	Tipo	Obrigatório	Descrição
`after`	string	não	Cursor da próxima página
`before`	string	não	Cursor da página anterior

Request

GET /api/v2/partners/entities/{reference_id}/subtree
Authorization: APIAuth access_key_id:signature

Response

200 OK

{
    "entries": [
        {
            "city": "Porto Alegre",
            "degree": "9",
            "entity_type": "class",
            "inep": null,
            "name": "9o. Ano",
            "reference_id": "cuy42r6je6lkv9u-y6g9rjoe-92zm2pdt-f6",
            "state": "RS"
        }
    ],
    "metadata": {
        "after": null,
        "before": null,
        "limit": 50
    }
}

Listagem de leitores de uma entidade

GET /api/v2/partners/entities/{entity_reference_id}/readers

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`entity_reference_id`	string	sim	ID de referência da entidade que retornará os leitores. Ex: `ejhb-uty94l129tbhc-r8kwt-u-xf7nw776t`

Atributos

Campo	Tipo	Obrigatório	Descrição
`after`	string	não	Cursor da próxima página
`before`	string	não	Cursor da página anterior

Request

GET /api/v2/partners/entities/{entity_reference_id}/readers
Authorization: APIAuth access_key_id:signature

Response

200 OK

{
    "entries": [
        {
            "access_token": "EDF4567",
            "entity_reference_id": "cuy42r6je6lkv9u-y6g9rjoe-92zm2pdt-f6",
            "name": "Richard Smith",
            "phone": "(00) 00000-0000",
            "reference_id": "ejhb-uty94l129tbhc-r8kwt-u-xf7nw776t",
            "active": true
        }
    ],
    "metadata": {
        "after": null,
        "before": null,
        "limit": 50
    }
}

Listagem de professores de uma entidade

GET /api/v2/partners/entities/{entity_reference_id}/teachers

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`entity_reference_id`	string	sim	ID de referência da entidade que retornará os professores. Ex: `ejhb-uty94l129tbhc-r8kwt-u-xf7nw776t`

Atributos

Campo	Tipo	Obrigatório	Descrição
`after`	string	não	Cursor da próxima página
`before`	string	não	Cursor da página anterior

Request

GET /api/v2/partners/entities/{entity_reference_id}/teachers
Authorization: APIAuth access_key_id:signature

Response

200 OK

{
    "entries": [
        {
            "access_token": "EDF4567",
            "entity_reference_id": "cuy42r6je6lkv9u-y6g9rjoe-92zm2pdt-f6",
            "name": "Richard Smith",
            "phone": "(00) 00000-0000",
            "reference_id": "ejhb-uty94l129tbhc-r8kwt-u-xf7nw776t",
            "active": true
        }
    ],
    "metadata": {
        "after": null,
        "before": null,
        "limit": 50
    }
}

Exibição de uma entidade

GET /api/v2/partners/entities/{reference_id}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`reference_id`	string	sim	ID de referência da entidade. Ex: `cuy42r6je6lkv9u-y6g9rjoe-92zm2pdt-f6`

Request

GET /api/v2/partners/entities/{reference_id}
Authorization: APIAuth access_key_id:signature

Response

200 OK

{
    "data": {
        "city": "Porto Alegre",
        "degree": "9",
        "entity_type": "class",
        "inep": null,
        "name": "9o. Ano",
        "parent_reference_id": "fajem-2x7io4zldu47jela98g16iyi-pmown",
        "reference_id": "cuy42r6je6lkv9u-y6g9rjoe-92zm2pdt-f6",
        "state": "RS"
    },
    "errors": null,
    "pagination": null
}

Edição de uma entidade

PUT /api/v2/partners/entities/{reference_id}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`reference_id`	string	sim	ID de referência da entidade. Ex: `cuy42r6je6lkv9u-y6g9rjoe-92zm2pdt-f6`

Request

PUT /api/v2/partners/entities/{reference_id}
Authorization: APIAuth access_key_id:signature
Content-Type: application/json

{
    "name": "8o. Ano",
    "degree": "8",
    "state": "SP",
    "city": "São Paulo"
}

Response

200 OK

{
    "data": {
        "city": "São Paulo",
        "degree": "8",
        "entity_type": "class",
        "inep": null,
        "name": "8o. Ano",
        "parent_reference_id": "fajem-2x7io4zldu47jela98g16iyi-pmown",
        "reference_id": "cuy42r6je6lkv9u-y6g9rjoe-92zm2pdt-f6",
        "state": "SP"
    },
    "errors": null,
    "pagination": null
}

422 Unprocessable Entity

{
    "errors": {
        "field_with_error": ["error_message"]
    }
}

Exclusão de uma entidade

DELETE /api/v2/partners/entities/{reference_id}

Remove uma entidade da estrutura organizacional. A entidade não pode ter filhos (subentidades). Ao deletar, os leitores e professores associados são desativados e as avaliações da entidade são removidas.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`reference_id`	string	sim	ID de referência da entidade. Ex: `cuy42r6je6lkv9u-y6g9rjoe-92zm2pdt-f6`

Request

DELETE /api/v2/partners/entities/{reference_id}
Authorization: APIAuth access_key_id:signature

Response

204 No Content — entidade removida com sucesso.

401 Unauthorized · 404 Not Found

422 Unprocessable Entity

{
    "errors": {
        "entity": ["has children, remove them first"]
    }
}