Documento de API
Produto: | Datasul |
Ocorrência: | Documentação de API |
Nome físico: | prgfin/bgc/bgc705za |
Objetivo
Possibilitar através da passagem de informações que retorne o valor orçado, empenhado e realizado.
Funcionamento
A execução na forma persistente padrão para essa API é a execução persistente.
A sintaxe para executar a API/BO em modo persistente é:
A variável denominada h-handle irá receber o “handle” do programa, permitindo o acesso aos “métodos” internos da API.
Tabela Temporária
Aqui iremos dividir a tabela temporária em Entrada, Entrada/Saída e Saída para organizar e categorizar os dados conforme o seu papel e fluxo na execução da API.
O programa que irá executar a API deverá conter e criar a seguinte tabela temporária:
1. Entrada
Esses atributos são usados para fornecer informações à API. Eles são necessários para definir o contexto e os parâmetros de execução da API.
| Tabela Temporária | Descrição | Entrada/Saída |
|---|---|---|
tt_integr_retorna_sdo_orcto | Entrada |
| Atributo | Tipo | Formato | Descrição | Obrigatório | Evolução |
|---|---|---|---|---|---|
| ttv_cod_produt_dtsul | char | "x(8)" | Produto (EMS2 / EMS5) Observação: Quando o produto origem for EMS2, deverão ser informados somente os atributos externos (ttv_cod_matriz_trad_org_ext, ttv_cod_empresa_ext, ttv_cod_estab_ext, ttv_cod_cta_ctbl_ext, ttv_cod_sub_cta_ctbl_ext, ttv_cod_matriz_trad_finalid_ext, ttv_num_finalid_ext). A API fará as traduções necessárias para os atributos correspondentes do EMS5. | Sim | |
| tta_cod_empresa | char | "(3)" | Código da Empresa | Sim | |
| tta_cod_estab | char | "x(5) | Estabelecimento | Não | |
| tta_cod_plano_cta_ctbl | char | "x(8)" | Plano de Contas | Não | |
tta_cod_cta_ctbl | char | "x(20)" | Conta Contábil | Não | |
tta_cod_plano_ccusto | char | "x(8)" | Plano de Centro de Custo | Não | |
tta_cod_ccusto | char | "x(11)" | Centro de Custo | Não | |
ttv_cod_matriz_trad_org_ext | char | "x(8)" | Matriz de Tradução Observação: Quando não for informada, será buscado primeiro a matriz de tradução informada nos Parâmetros Gerais do BGC, caso não tenha matriz informada nos parâmetros, será buscada então a matriz de tradução dos parâmetros de integração do EMS (Contabilizações 2.00). | Não | |
ttv_cod_empresa_ext | char | "x(3)" | Empresa Externa | Não | |
ttv_cod_estab_ext | char | "x(3)" | Estabelecimento Externo | Não | |
ttv_cod_cta_ctbl_ext | char | "x(20)" | Conta Contábil Externa | Não | |
ttv_cod_sub_cta_ctbl_ext | char | "x(8)” | Sub-Conta Externa | Não | |
ttv_cod_matriz_trad_finalid_ext | char | "x(8)" | Matriz de Tradução Finalidade Externa | Não | |
ttv_num_finalid_ext | int | “>9” | Moeda Externa | Não | |
tta_cod_unid_negoc | char | "x(3)" | Unidade de Negócio Observação: Será obrigatório informar a Unidade de Negócio somente quando o produto for EMS5. | Sim (EMS5) | |
tta_cod_proj_financ | char | "x(20)" | Projeto | Não | |
tta_cod_finalid_econ | char | "x(10)" | Finalidade Econômica | Não | |
tta_cod_cenar_ctbl | char | "x(8)" | Cenário Contábil Observação: Quando não for informado o Cenário Contábil, será utilizado o cenário parametrizado como “Fiscal” no cadastro de Utilização do Cenário Contábil. | Não | |
tta_cod_exerc_ctbl | char | "9999" | Exercício | Sim | |
tta_num_period_ctbl | int | ">99" | Período | Sim | |
ttv_dat_movto | date | "99/99/9999" | Data Movimento | Não |
2. Entrada/Saída
Esses atributos podem atuar tanto como entrada quanto como saída. Isso significa que, além de fornecer informações iniciais para a API, eles podem ser atualizados pela API com novos valores baseados no processamento realizado.
| Tabela Temporária | Descrição | Entrada/Saída |
|---|---|---|
tt_integr_retorna_sdo_orcto | Entrada/Saída |
| Atributo | Tipo | Formato | Descrição | Obrigatório | Evolução |
|---|---|---|---|---|---|
tta_cod_cenar_orctario | char | "x(8)" | Cenário Orçamentário | Não | |
tta_cod_unid_orctaria | char | "x(8)" | Unidade Orçamentária | Não | |
tta_num_seq_orcto_ctbl | int | ">>>>>>>>9" | Sequencia do Orçamento | Não | |
tta_cod_vers_orcto_ctbl | char | "x(10)" | Versão do Orçamento | Não |
3. Saída
Esses atributos são utilizados para retornar os resultados do processamento da API. Eles contêm os valores calculados, informações de status e quaisquer mensagens de erro ou ajuda.
| Tabela Temporária | Descrição | Entrada/Saída |
|---|---|---|
tt_integr_retorna_sdo_orcto | Saída |
| Atributo | Tipo | Formato | Descrição | Obrigatório | Evolução |
|---|---|---|---|---|---|
ttv_val_tot_orcado | dec | "->>,>>>,>>>,>>9.99" | Valor Orçado | --- | |
ttv_val_movto_empenh | dec | "->>,>>>,>>>,>>9.99" | Valor Empenhado | --- | |
ttv_val_realiz | dec | "->>,>>>,>>>,>>9.99" | Valor Realizado | --- | |
ttv_log_utiliz_exec_orctaria | logical | Sim/Não | Indica se foi Utilizada a Execução Orçamentária | --- | |
ttv_cod_exerc_ctbl_ini | char | "9999" | Exercício Contábil Inicial | --- | |
ttv_cod_exerc_ctbl_fim | char | "9999" | Exercício Contábil Final | --- | |
ttv_num_period_ctbl_ini | int | ">99" | Período Inicial | --- | |
ttv_num_period_ctbl_fim | int | ">99" | Período Final | --- | |
tta_log_bloq_empres | logical | Sim/Não | Bloqueio por Empresa | --- | |
tta_log_bloq_estab | logical | Sim/Não | Bloqueio por Estabelecimento | --- | |
tta_log_bloq_unid_negoc | logical | Sim/Não | Bloqueio por Unidade de Negócio | --- | |
ttv_log_plano_cta_ctbl_bloq | logical | Sim/Não | Bloqueio por Plano de Contas | --- | |
tta_log_bloq_cta_ctbl | logical | Sim/Não | Bloqueio por Conta Contábil | --- | |
ttv_log_plano_ccusto_bloq | logical | Sim/Não | Bloqueio por Plano Centro de Custo | --- | |
tta_log_bloq_ccusto | logical | Sim/Não | Bloqueio por Centro de Custo | --- | |
tta_log_bloq_proj_financ | logical | Sim/Não | Bloqueio por Projeto | --- | |
ttv_num_cod_erro | int | ">>>>,>>9" | Número do Erro | --- | |
ttv_des_msg_erro | char | "x(60)" | Mensagem de Erro | --- | |
ttv_des_msg_ajuda | char | "x(40)" | Texto de Ajuda | --- |
def temp-table tt_integr_retorna_sdo_orcto no-undo
field ttv_cod_produt_dtsul as character format "x(8)" label "Produto" column-label "Produto"
field tta_cod_empresa as character format "x(3)" label "Empresa" column-label "Empresa"
field tta_cod_estab as Character format "x(5)" label "Estabelecimento" column-label "Estab"
field tta_cod_plano_cta_ctbl as character format "x(8)" label "Plano Contas" column-label "Plano Contas"
field tta_cod_cta_ctbl as character format "x(20)" label "Conta Contábil" column-label "Conta Contábil"
field tta_cod_plano_ccusto as character format "x(8)" label "Plano Centros Custo" column-label "Plano Centros Custo"
field tta_cod_ccusto as Character format "x(11)" label "Centro Custo" column-label "Centro Custo"
field ttv_cod_matriz_trad_org_ext as character format "x(8)" label "Matriz UO" column-label "Matriz UO"
field ttv_cod_empresa_ext as character format "x(3)" label "Código Empresa Ext" column-label "Cód Emp Ext"
field ttv_cod_estab_ext as character format "x(3)" label "Estabelecimento" column-label "Estabelecimento"
field ttv_cod_cta_ctbl_ext as character format "x(20)" column-label "Conta Cont bil"
field ttv_cod_sub_cta_ctbl_ext_2 as character format "x(8)"
field ttv_cod_matriz_trad_finalid_ext as character format "x(8)" label "Matriz Trad Finalid" column-label "Matriz Trad Finalid"
field ttv_num_finalid_ext as integer format ">9" label "Finalid Econ Externa" column-label "Finalid Econ Externa"
field tta_cod_unid_negoc as character format "x(3)" label "Unid Negócio" column-label "Un Neg"
field tta_cod_proj_financ as character format "x(20)" label "Projeto" column-label "Projeto"
field tta_cod_finalid_econ as character format "x(10)" label "Finalidade" column-label "Finalidade"
field tta_cod_cenar_ctbl as character format "x(8)" label "Cenário Contábil" column-label "Cen rio Cont bil"
field tta_cod_exerc_ctbl as character format "9999" label "Exerc¡cio Cont bil" column-label "Exercício Contábil"
field tta_num_period_ctbl as integer format ">99" initial 0 label "Período Contábil" column-label "Período"
field ttv_dat_movto as date format "99/99/9999" label "Data Movimento" column-label "Data Movimento"
field tta_cod_cenar_orctario as character format "x(8)" label "Cenário Orçament rio" column-label "Cen rio Orçamen"
field tta_cod_unid_orctaria as character format "x(8)" label "Unid Orçamentária" column-label "Unid Orçamentária"
field tta_num_seq_orcto_ctbl as integer format ">>>>>>>>9" initial 0 label "Seq Orcto Contábil" column-label "Seq Orcto Contábil"
field tta_cod_vers_orcto_ctbl as character format "x(10)" label "Versão Orçamento" column-label "Versão Orçamento"
field ttv_val_tot_orcado as decimal format "->>,>>>,>>>,>>9.99" decimals 2
field ttv_val_movto_empenh as decimal format "->>,>>>,>>>,>>9.99" decimals 9 initial 0 label "Movto Empenhado" column-label "Movto Empenhado"
field ttv_val_realiz as decimal format "->>,>>>,>>>,>>9.99" decimals 2
field ttv_log_utiliz_exec_orctaria as logical format "Sim/Não" initial no label "Utiliz Exec Orctaria" column-label "Utiliz Exec Orctaria"
field ttv_cod_exerc_ctbl_ini as character format "9999" label "Inicial" column-label "Inicial"
field ttv_cod_exerc_ctbl_fim as character format "9999" label "Final" column-label "Final"
field ttv_num_period_ctbl_ini as integer format ">99" initial 0 label "Período Inicial" column-label "Inicial"
field ttv_num_period_ctbl_fim as integer format ">99" initial 0 label "Período Final" column-label "Final"
field tta_log_bloq_empres as logical format "Sim/Não" initial no label "Bloqueio por Empresa" column-label "Bloqueio por Empresa"
field tta_log_bloq_estab as logical format "Sim/Não" initial no label "Bloq por Estabel" column-label "Bloq por Estabel"
field tta_log_bloq_cta_ctbl as logical format "Sim/Não" initial no label "Bloq por Cta Ctbl" column-label " Bloq por Cta Ctbl"
field ttv_log_plano_ccusto_bloq as logical format "Sim/Não" initial no
field tta_log_bloq_ccusto as logical format "Sim/Não" initial no label "Bloq por C.Custo" column-label "Bloq por C.Custo"
field tta_log_bloq_unid_negoc as logical format "Sim/Não" initial no label "Bloq por Un.Negócio" column-label "Bloq por Un.Negócio"
field ttv_log_plano_cta_ctbl_bloq as logical format "Sim/Não" initial no
field tta_log_bloq_proj_financ as logical format "Sim/Não" initial no label "Bloqueio por Projeto" column-label "Bloqueio por Projeto"
field ttv_num_cod_erro as integer format ">>>>,>>9" label "Número" column-label "Número"
field ttv_des_msg_erro as character format "x(60)" label "Mensagem Erro" column-label "Inconsistência"
field ttv_des_msg_ajuda as character format "x(40)" label "Mensagem Ajuda" column-label "Mensagem Ajuda"
.
Observações gerais:
a) Se a base estiver parametrizada para efetuar a execução orçamentária, a API irá retornar os valores de saldo utilizando as informações de Ordem de Busca e Parâmetros de Bloqueio cadastrados para a empresa. Nesse caso, além de retornar os valores Orçado, Empenhado e Realizado, serão retornados nesses campos também os dados do orçamento encontrado através dos parâmetros da execução orçamentária. Caso contrário, se a base NÃO estiver parametrizada para efetuar a execução orçamentária, a API tentará retornar os valores buscando diretamente no Saldo do Orçamento informado, e no Saldo da Conta Contábil informada, sem utilizar a execução orçamentária. Nesse caso será retornado somente o Valor Orçado e o Valor Realizado, sendo que o valor realizado poderá ser negativo, quando o valor dos movimentos a crédito for maior do que o valor dos movimentos a débito.
b) Além dos valores orçado, empenhado e realizado, serão retornados também a faixa de Exercício/Período e as informações do Parâmetro de Bloqueio utilizados para retornar os valores. Esses atributos serão atualizados somente quando for utilizada a execução orçamentária;
c) Ao primeiro erro ocorrido, a API irá interromper o processo de busca dos valores de saldo. As informações desse erro serão retornadas nos três últimos atributos da temp-table (ttv_num_cod_erro, ttv_des_msg_erro, ttv_des_msg_ajuda);
d) Se no momento da execução da API o extrato de versão estiver ativo, serão gerados dois arquivos no diretório temporário do sistema. Um contendo os dados de entrada recebidos pela API, e outro contendo as informações retornadas pela mesma.
Exemplo de utilização da API
Para a utilização da api é necessário realizar os seguintes passos:
1. Definição do Handle
Definição da variável h-handle para armazenar a referência ao programa externo.
def var h-handle as widget-handle no-undo. |
|---|
2. Definição da Tabela Temporária
Definição da tabela temporária tt_integr_retorna_sdo_orcto com seus respectivos campos.
def temp-table tt_integr_retorna_sdo_orcto no-undo |
|---|
3.Limpeza da Tabela Temporária
Após definirmos a tabela, no terceiro passo removemos todos os registros existentes na tabela temporária.
FOR EACH tt_integr_retorna_sdo_orcto: |
|---|
4. Criação de um Registro na Tabela Temporária
Com a limpeza da tabela temporária, criamos um novo registro na tabela tt_integr_retorna_sdo_orcto e atribui valores aos campos desse registro.
create tt_integr_retorna_sdo_orcto. |
|---|
5. Execução do Programa Externo
Aqui chamamos o programa externo bgc705za.r e define que ele será executado de forma persistente, armazenando a referência em h-handle. Em seguida, executamos a pi_main_retorna_dados_ctbl_01, passando a tabela temporária tt_integr_retorna_sdo_orcto como parâmetro de entrada e saída.
run prgfin/bgc/bgc705za.r persistent set h-handle. |
|---|
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas