Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.
Expandir
titleAutenticação

As APIs disponibilizadas funcionam com duas autenticações, Basic ou Token Bearer, nos dois casos é necessário um usuário e senha do RM previamente disponibilizado

Deck of Cards
idAutenticacaoAPI
Card
idBasic
labelBasic

Authorization - Basic Auth

Username <USUARIO RM>

Password <SENHA RM>


Card
idBearer
labelBearer

Abaixo estão as instruções de como buscar um bearer token, tanto com base em um certificado embutido automaticamente na aplicação quanto um inserido manualmente.

Exemplo de utilização - Sucesso:

  1. Realize uma requisição POST ao endpoint http(s)://{dominio}:{porta}/api/connect/token/ via Postman, SoapUi, ou outro programa que realize requisições HTTP REST.
  2. No corpo da requisição envie um JSON explicitando usuário e senha do RM para qual a autenticação está sendo direcionada:

 username
• password 

A requisição deve parecer com a abaixo

Image Added


Bloco de código
languagejs
themeMidnight
titleJSON de requisição de token
{
 "username": "USUARIO RM",
 "password": "SENHA RM"
}


O token de segurança será gerado e já poderá ser utilizado no cabeçalho das requisições subsequentes às API's disponibilizadas pela TOTVS.

Exemplo de Token de Segurança gerado com sucesso e pronto para ser utilizado:

Image Added


Bloco de código
languagejs
themeMidnight
titleJSON de Retorno de Token
{
    "access_token": "eyJhbGciOiJSUzI1NiIsDKXI9RYRNIpq4zd2ZFTuKRAvvTLvytOW_yvYxUn-k-XM4stBcnzuo8Eg00A8mDePRH-Kcjy6AWZjOPGYuaiKnDZ5hWfVCO-mefV44wU1vAYSb3jWQuS-4SPgrmHHy3XurY1clVpwrHuIENsZdFSZxy-g0I_8VwCFZHIPGh4-s_uejDPTmkscCWoejc42nyE8zn8gkG1YYWQRQ",
    "expires_in": 300,
    "refresh_token": "eyJUb2tlbktleSI6ImROcU5pam9BbnZhaG1WMEZST1o1NjFYQlVZekIzSXplYldNdDZkcUFyVE0iLCJjb25uZWN0aW9uSWQiOiJDb3Jwb3JlUk0ifQ==",
    "token_type": "Bearer"
}


Utilize o token gerado incluindo-o no cabeçalho da requisição através da diretiva:

• Authorization: Bearer {token}

Inclusão do token no cabeçalho da requisição:

Image Added


Após a inclusão do cabeçalho de autorização, realize uma requisição HTTP em uma das API's disponibilizadas pela TOTVS e verifique o resultado.


Expandir
titleEtapas
HTML
<div class="get">GET</div>
<div class="endereco">/api/integracoes/v2/sesc/educacional/etapa</div>


Para buscar varias etapas no SGE, o filtro da busca deve ser passado via QueryString.

codColigada: Coligada da Turma/Disciplina no RM

idTurmaDisc: Id da Turma/Disciplina no RM

tipoEtapa: N para nota ou F para falta


Image Added


Bloco de código
languagejs
themeMidnight
titleExemplo
/api/integracoes/v2/sesc/educacional/etapa?codColigada=2&idTurmaDisc=4151&tipoEtapa=N
Bloco de código
languagejs
themeMidnight
titleExemplo de Resposta
collapsetrue
{
    "hasNext": false,
    "items": [
        {
            "codColigada": 2,
            "idTurmaDisc": 572,
            "codEtapa": 1,
            "dataInicio": "2024-01-01T00:00:00-03:00",
            "dataFim": "2024-01-31T00:00:00-03:00",
            "tipoEtapa": "N",
            "pontosDistribuidos": 100.0000,
            "media": 60.0000,
            "permiteDigitacaoNaEtapa": false,
            "etapaFinal": false,
            "etapaEncerrada": false
        },
        {
            "codColigada": 2,
            "idTurmaDisc": 572,
            "codEtapa": 2,
            "dataInicio": "2024-01-01T00:00:00-03:00",
            "dataFim": "2024-12-31T00:00:00-03:00",
            "tipoEtapa": "N",
            "pontosDistribuidos": 100.0000,
            "media": 60.0000,
            "permiteDigitacaoNaEtapa": false,
            "etapaFinal": false,
            "etapaEncerrada": false
        }
    ]
}


Também é possível buscar uma etapa especifica, para isso os dados da chave devem ser passados na URL separados por pipeline "|", devem ser passados o codColigada, idTurmaDisc, codEtapa e tipoEtapa.


Bloco de código
languagejs
themeMidnight
titleExemplo
/api/integracoes/v2/sesc/educacional/etapa/2|572|1|N
Bloco de código
languagejs
themeMidnight
titleRetorno
collapsetrue
{
    "codColigada": 2,
    "idTurmaDisc": 572,
    "codEtapa": 1,
    "dataInicio": "2024-01-01T00:00:00-03:00",
    "dataFim": "2024-01-31T00:00:00-03:00",
    "tipoEtapa": "N",
    "pontosDistribuidos": 100.0000,
    "media": 60.0000,
    "permiteDigitacaoNaEtapa": false,
    "etapaFinal": false,
    "etapaEncerrada": false
}
Expandir
titlePlano de Aula
HTML
<div class="get">GET</div>
<div class="endereco">/api/integracoes/v2/sesc/educacional/planodeaula</div>


Para buscar os planos de aula no SGE, o filtro da busca deve ser passado via QueryString.

codColigada: Coligada da Turma/Disciplina no RM

idTurmaDisc: Id da Turma/Disciplina no RM


Image Added


Bloco de código
languagejs
themeMidnight
titleExemplo
/api/integracoes/v2/sesc/educacional/planodeaula/?codColigada=2&idTurmadisc=572
Bloco de código
languagejs
themeMidnight
titleResposta
collapsetrue
{
    "hasNext": false,
    "items": [
        {
            "codColigada": 2,
            "idTurmaDisc": 572,
            "idPlanoAula": 23293,
            "numeroAula": 1,
            "dataPlanoAula": "2024-04-04T00:00:00-03:00",
            "confirmado": false,
            "aulaOnline": "http//:opopopoo",
            "conteudoPrevisto": "aula",
            "conteudoRealizado": "fez a aula",
            "dataEfetiva": "2025-04-04T00:00:00-03:00",
            "licaoDeCasa": "para casa via patch",
            "observacao": "via patch",
            "horaInicial": "07:00",
            "horaFinal": "07:50"
        },
        {
            "codColigada": 2,
            "idTurmaDisc": 572,
            "idPlanoAula": 23294,
            "numeroAula": 2,
            "dataPlanoAula": "2024-04-04T00:00:00-03:00",
            "confirmado": false,
            "aulaOnline": "",
            "conteudoPrevisto": "",
            "conteudoRealizado": "",
            "licaoDeCasa": "",
            "observacao": "",
            "horaInicial": "07:50",
            "horaFinal": "08:40"
        }
    ]
}
HTML
<div class="post">PATCH</div>
<div class="endereco">/api/integracoes/v2/sesc/educacional/planodeaula</div>


Para atualizar os dados de um plano de aula (importação de conteúdo realizado) os dados da chave do registro devem ser passados na URL separados por pipeline "|" e os campos a serem atualizados devem ser enviados no corpo da requisição.

Como chave do campo devem ser passados o codColigada, idTurmaDisc, idPlanoAula.


Bloco de código
languagejs
themeMidnight
titleExemplo URL requisição de atualização de plano de aula
/api/integracoes/v2/sesc/educacional/planodeaula/2|572|23293
Bloco de código
languagejs
themeMidnight
titleExemplo do copo da requisição de atualização de plano de aula
collapsetrue
{
    "numeroAula": 1,
    "dataPlanoAula": "2024-04-04T00:00:00-03:00",
    "dataEfetiva": "2025-04-04",
    "confirmado": false,
	"aulaOnline": "url da aula",
    "conteudoPrevisto": "conteudo previsto",
    "conteudoRealizado": "conteudo realizado",
    "licaoDeCasa": "para casa via patch",
    "observacao": "via patch"
}
Bloco de código
languagejs
themeMidnight
titleExemplo de retorno da atualização de plano de aula
collapsetrue
{
    "codColigada": 2,
    "idTurmaDisc": 572,
    "idPlanoAula": 23293,
    "numeroAula": 1,
    "dataPlanoAula": "2024-04-04T00:00:00-03:00",
    "confirmado": false,
    "dataEfetiva": "2025-04-04T00:00:00-03:00",
    "licaoDeCasa": "para casa via patch",
    "observacao": "via patch"
}



HTML
<style>
	.expand-control {
    	cursor: pointer;
    	text-decoration: none;
	    margin-bottom: 10px;
	    background-color: #ededed;
	    height: 20px;
	    font-size: 15px;
	    padding: 5px;
	}
	.expand-control-text {
    	vertical-align: top;
	    font-weight: bold;
		color: #242424;
	}
	.post {
    	background-color: #378000;
	    color: #ffffff;
	    display: inline-block;
	    padding: 5px;
	    border-radius: 5px;
		font-weight: bold;
	}
	.get {
    	background-color: #004fd6;
	    color: #ffffff;
	    display: inline-block;
	    padding: 5px;
	    border-radius: 5px;
		font-weight: bold;
	}
	.put {
    	background-color: #ffa200;
	    color: #ffffff;
	    display: inline-block;
	    padding: 5px;
	    border-radius: 5px;
		font-weight: bold;
	}
	.delete {
    	background-color: #cf0000;
	    color: #ffffff;
	    display: inline-block;
	    padding: 5px;
	    border-radius: 5px;
		font-weight: bold;
	}
	.endereco{
		display: inline-block;
		padding: 5px;
		font-weight: bold;
	}
</style>
<!-- 
EXEMPLO DE MARCAÇÃO PARA TIPO DE REQUEST:
<div class="post">POST</div>
<div class="get">GET</div>
<div class="put">PUT</div>
<div class="delete">DELETE</div>

O ENDEREÇO DEVE SER INSERIDO COM A SEGUINTE MARCAÇÃO:
<div class="endereco">/rm/api/TOTVSCustomizacao/CstIntegracaoProtheus/ItemContabil</div>
-->
HTML
{
	"openapi": "3.0.1",
	"servers": [
		{
			"description": "API para os parâmetros de sistemas do produtos TOTVS",
			"url": "{{host}}/api/framework/v1",
			"variables": {
				"serverUrl": {
					"default": "localhost"
				},
				"serverHttpPort": {
					"default": "8051"
				}
			}
		}
	],
	"info": {
		"description": "API para os parâmetros de sistemas do produtos TOTVS",
		"version": "1.000",
		"title": "Parametros de Sistema",
		"contact": {
			"name": "T-Talk",
			"url": "API.Totvs.com.br",
			"email": "[email protected]"
		},
		"x-totvs": {
			"messageDocumentation": {
				"name": "systemParameters",
				"description": "Parâmetros de Sistema",
				"segment": "Foundation"
			},
			"productInformation": [
				{
					"product": "Protheus",
					"contact": "[email protected]",
					"description": "Cadastro de parâmetros",
					"adapter": "",
					"helpUrl": "link aqui",
					"note": "Essa API exige que seja configurada a segurança no servidor (SECURITY=1)."
				}
			]
		}
	},
	"paths": {
		"/systemParameters": {
			"get": {
				"tags": [
					"System Parameters"
				],
				"summary": "Retorna todos os parâmetros do sistema",
				"x-totvs": {
					"productInformation": [
						{
							"product": "Protheus",
							"available": true,
							"note": "Este verbo esta disponivel com todos os parametros",
							"minimalVersion": "12.1.23"
						}
					]
				},
				"description": "Retorna todos os parâmetros do sistema",
				"operationId": "getSystemParameters",
				"parameters": [
					{
						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/Authorization"
					},
					{
						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/Order"
					},
					{
						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/Page"
					},
					{
						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/PageSize"
					},
					{
						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/Fields"
					},
					{
						"$ref": "#/components/parameters/Codes"
					},
					{
						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/AcceptLanguage"
					},
					{
						"$ref": "#/components/parameters/Description"
					}
				],
				"responses": {
					"200": {
						"description": "Operação realizada com sucesso",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/SystemParameter_1_000.json#/definitions/PagedParameters"
								}
							}
						}
					}
				}
			},
			"post": {
				"tags": [
					"System Parameters"
				],
				"summary": "Inclui o parâmetro passado na requisição",
				"description": "Inclui o parâmetro passado na requisição",
				"operationId": "postParameter",
				"x-totvs": {
					"productInformation": [
						{
							"product": "Protheus",
							"available": true,
							"note": "Este verbo esta disponivel com todos os parametros",
							"minimalVersion": "12.1.23"
						}
					]
				},
				"parameters": [
					{
						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/Authorization"
					}
				],
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/SystemParameter_1_000.json#/definitions/ParameterInfo"
							}
						}
					},
					"description": "Parâmetro para ser incluido"
				},
				"responses": {
					"200": {
						"description": "Operação realizada com sucesso",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/SystemParameter_1_000.json#/definitions/PagedParameters"
								}
							}
						}
					},
					"400": {
						"description": "erro no momento da Inclusão",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/definitions/ErrorModel"
								}
							}
						}
					}
				}
			}
		},
		"/systemParameters/{systemParameterId}": {
			"put": {
				"tags": [
					"System Parameters"
				],
				"summary": "Altera o parâmetro passado na requisição",
				"description": "Altera o parâmetro passado na requisição",
				"operationId": "postParameterId",
				"x-totvs": {
					"productInformation": [
						{
							"product": "Protheus",
							"available": true,
							"note": "Este verbo esta disponivel com todos os parametros",
							"minimalVersion": "12.1.23"
						}
					]
				},
				"parameters": [
					{
						"$ref": "#/components/parameters/ParameterId"
					},
					{
						"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/parameters/Authorization"
					}
				],
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/SystemParameter_1_000.json#/definitions/ParameterInfo"
							}
						}
					},
					"description": "Parâmetro para ser incluído"
				},
				"responses": {
					"200": {
						"description": "Operação realizada com sucesso",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/SystemParameter_1_000.json#/definitions/ParameterInfo"
								}
							}
						}
					},
					"400": {
						"description": "erro no momento da Inclusão",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/definitions/ErrorModel"
								}
							}
						}
					},
					"404": {
						"description": "Parâmetro não localizado na base",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/definitions/ErrorModel"
								}
							}
						}
					}
				}
			},
			"delete": {
				"tags": [
					"System Parameters"
				],
				"summary": "Exclusão de parâmetro da base",
				"description": "Exclusão de parâmetro da base",
				"operationId": "DeleteParameterId",
				"x-totvs": {
					"productInformation": [
						{
							"product": "Protheus",
							"available": true
						}
					]
				},
				"parameters": [
					{
						"$ref": "#/components/parameters/ParameterId"
					}
				],
				"responses": {
					"200": {
						"description": "Operação realizada com sucesso",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/SystemParameter_1_000.json#/definitions/ParameterInfo"
								}
							}
						}
					},
					"405": {
						"description": "Não disponivel",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/apis/types/totvsApiTypesBase.json#/definitions/ErrorModel"
								}
							}
						}
					}
				}
			}
		}
	},
	"components": {
		"parameters": {
			"ParameterId": {
				"name": "systemParameterId",
				"in": "path",
				"required": true,
				"description": "Identificador Único representando o parâmetro",
				"schema": {
					"type": "string"
				}
			},
			"Codes": {
				"name": "codes",
				"in": "query",
				"description": "Códigos de parâmetros retornados pelo get separado por vírgula (,) ",
				"required": false,
				"example": "param1,param2",
				"schema": {
					"type": "string"
				}
			},
			"Description": {
				"name": "description",
				"in": "query",
				"description": "Busca de descrição do paramêtro",
				"required": false,
				"example": "Parâmetro de busca",
				"schema": {
					"type": "string"
				}
			}
		}
	}
}