Documento de API

Produto:	Datasul
Ocorrência:	Documentação de API
Nome Físico	prgfin/acr/acr540za

Considerações Gerais

Objetivo

Realizar a integração com leitora de cartão para vendas via TEF - Transferência Eletrônica de Fundos, na modalidade crédito à vista ou parcelado e/ou débito à vista.

Funcionamento

A API funciona em conjunto com o Aplicativo externo “Cliente Modular Sitef”, conforme parceria firmada com a Empresa Software Express para fornecimento da solução. A troca de informações se dá através de troca de arquivos seguindo padrões definidos pela empresa parceira (documentações disponíveis no site da empresa).

Na forma padrão, realiza-se a chamada através de um comando RUN persistent, passando-se parâmetros e uma temp-table para controle de erros durante o processo de transação.

A sintaxe para executar a API em modo persistente é:

run prgfin/acr/acr540za.py persistent set h-handle (input param...,

output param...,

output table...).

A variável denominada h-handle irá receber o “handle” do programa, permitindo o acesso aos “métodos” internos da API.

Tabelas Temporárias

Nos atributos das tabelas temporárias de entrada e saída:

tt_log_erro					Entrada/Saída
Tabela temporária para retorno de erros na execução da transação TEF					Saída
Atributo	Tipo	Formato	Descrição	Obrigatório	Evolução
ttv_num_cod_erro	integer	">>>>,>>9"	Código do erro	Sim
ttv_des_msg_ajuda	character	"x(40)"	Mensagem de ajuda.	Sim
ttv_des_msg_erro	character	"x(60)"	Mensagem de erro.	Sim

Método Básico

Quando a API for executada em modo persistente, os seguintes métodos estarão disponíveis para execução:

pi_envia_req_vda_tef
Requisito	REQ 1376 - Controle de caixa - Integração com leitora de cartão
Sintaxe	run pi_envia_req_vda_tef in h-handle (input param p_cod_empresa_tef , input param p_cod_operac_admdra , input param p_cod_usuar, input param p_cdn_tip_parcto, input param p_idi_forma_pag, input param p_num_parc_pag, input param p_val_trans_tef, output param p_cdd_trans_seq, output param p_nom_mensagem_tef, output param p_nom_arquivo_retorno, output param table for tt_log_erro).
Descrição		Requisição de venda via leitora de cartão – Tecnologia TEF (Transferência Eletrônica de Fundos)
		Parâmetros	Descrição
		p_cod_empresa_tef	Código da empresa corrente.
		p_cod_operac_admdra	Tipo de operação, de acordo com manual do Aplicativo. Ex.: (CRT).
		p_cod_usuar	Código do usuário do módulo.
		p_cdn_tip_parcto	Tipo de parcelamento, de acordo com manual do Aplicativo. Ex.: 0 = Estab.
		p_idi_forma_pag	Forma de Pagto TEF. Crédito ou Débito de acordo com a transação.
		p_num_parc_pag	Número de parcelas da transação TEF.
		p_val_trans_tef	Valor da transação TEF.
		p_cdd_trans_seq	Número sequencial gerado para a transação.
		p_nom_mensagem_tef	Mensagem para o Operador.
		p_nom_arquivo_retorno	Caminho e nome do arquivo gerado com a imagem do cupom.
		table for tt_log_erro	Tabela temporária com retorno de erros da API.
Retorno		A API irá retornar o número da transação, que será gerado no parâmetro “p_cdd_trans_tef”, o qual será utilizado na chamada do método “pi_envia_cnf_ncn_vda_tef” para confirmação da venda; O campo “p_nom_mensagem_tef” é somente orientativo, para que o Operador possa saber que a transação teve sucesso; Está API gera o recibo de transação em diretório específico, portanto devolve o caminho e o nome do arquivo gerado no parâmetro “p_nom_arquivo_retorno”; Os motivos para a rejeição da solicitação de venda são especificados na temp-table tt_erro_log. As mensagens possíveis para esse método são:
		21.368 - Transações TEF não autorizadas.
		21.369 - Usuário(a) sem permissão para transações TEF.
		21.372 - Diretório de integração não foi localizado.
		21.376 - Falta parâmetros para este procedimento.
		21.379 - Arquivo de transação não foi gerado.
		21.380 - Houve erro no tratamento do arquivo gerado.
		21.381 - Sistema não respondeu a solicitação de transação TEF.
		21.382 - Arquivo de Confirmação foi gerado com erro.
		21.383 - Arquivo de resposta foi gerado com erro.
		21.384 - Mensagem TEF: &1 = ex: Cartão não autorizado.
		21.396 - Parâmetros do TEF não foi localizado.
		21.397 - Usuário do Controle de Caixa não localizado.
		21.400 - Registro &1 = (nome da tabela) não foi localizado.

pi_envia_cnf_ncn_vda_tef
Requisito	REQ 1376 - Controle de caixa - Integração com leitora de cartão
Sintaxe	run pi_envia_cnf_ncn_vda_tef in h-handle (input param p_cod_empresa_tef , input param p_cod_operac_admdra , input param p_cdd_trans_seq, input param p_cod_usuar, output param p_nom_mensagem_tef, output param table for tt_log_erro).
Descrição	Confirmação ou desfazimento de transação realizada via leitora de cartão.
Parâmetros	Descrição
p_cod_empresa_tef	Código da empresa corrente.
p_cod_operac_admdra	Tipo de operação, de acordo com manual do Aplicativo. Ex.: (CNF,NCN).
p_cod_usuar	Código do usuário do módulo.
p_cdd_trans_seq	Número sequencial gerado para a transação.
p_nom_mensagem_tef	Mensagem para o Operador.
table for tt_log_erro	Tabela temporária com retorno de erros da API.
Retorno		A API irá retornar o campo “p_nom_mensagem_tef” preenchido apenas quando o tipo de operação for desfazimento para que o Operador possa saber que a transação teve sucesso; Para o tipo confirmação não haverá retorno de informações.Os motivos para a rejeição da solicitação de confirmação ou desfazimento da venda são especificados na temp-table tt_erro_log. As mensagens possíveis para esse método são:
		21.368 - Transações TEF não autorizadas.
		21.369 - Usuário(a) sem permissão para transações TEF.
		21.372 - Diretório de integração não foi localizado.
		21.376 - Falta parâmetros para este procedimento.
		21.379 - Arquivo de transação não foi gerado.
		21.380 - Houve erro no tratamento do arquivo gerado.
		21.381 - Sistema não respondeu a solicitação de transação TEF.
		21.382 - Arquivo de Confirmação foi gerado com erro.
		21.383 - Arquivo de resposta foi gerado com erro.
		21.384 - Mensagem TEF: &1 = ex: Cartão não autorizado.
		21.396 - Parâmetros do TEF não foi localizado.
		21.397 - Usuário do Controle de Caixa não localizado.
		21.400 - Registro &1 = (nome da tabela) não foi localizado.

pi_envia_req_cnc_vda_tef
Requisito	REQ 1376 - Controle de caixa - Integração com leitora de cartão
Sintaxe	run pi_envia_req_cnc_vda_tef in h-handle (input param p_cod_empresa_tef , input param p_cod_operac_admdra , input param p_cod_usuar, Input param p_rec_cancel_vda_tef, output param p_cdd_trans_seq, output param p_nom_mensagem_tef, output param p_nom_arquivo_retorno, output param table for tt_log_erro).
Descrição	Estorno de transações confirmadas no mesmo dia do pedido de cancelamento, via leitora de cartão.
Parâmetros	Descrição
p_cod_empresa_tef	Código da empresa corrente.
p_cod_operac_admdra	Tipo de operação, de acordo com manual do Aplicativo. Ex.: (CNC).
p_cod_usuar	Código do usuário do módulo.
p_rec_cancel_vda_tef	Recid do regisro que será cancelado. (tabela: process_negoc_cx_cart).
p_cdd_trans_seq	Número sequencial gerado para a transação.
p_nom_mensagem_tef	Mensagem para o Operador.
p_nom_arquivo_retorno	Caminho e nome do arquivo gerado com a imagem do cupom.
table for tt_log_erro	Tabela temporária com retorno de erros da API.
Retorno		A API irá retornar o número da transação, que será gerado no parâmetro “p_cdd_trans_tef”, o qual pode vir a ser utilizado na chamada do método “pi_envia_cnf_ncn_vda_tef” para confirmação do cancelamento da venda; Atualmente o processo de cancelamento não exige a geração de confirmação do cancelamento; O campo “p_nom_mensagem_tef” é somente orientativo, para que o Operador possa saber que a transação teve sucesso; Está API gera o recibo de transação em diretório específico, portanto devolve o caminho e o nome do arquivo gerado no parâmetro “p_nom_arquivo_retorno”; Os motivos para a rejeição da solicitação de cancelamento da venda são especificados na temp-table tt_erro_log. As mensagens possíveis para esse método são:
		21.368 - Transações TEF não autorizadas.
		21.369 - Usuário(a) sem permissão para transações TEF.
		21.372 - Diretório de integração não foi localizado.
		21.376 - Falta parâmetros para este procedimento.
		21.379 - Arquivo de transação não foi gerado.
		21.380 - Houve erro no tratamento do arquivo gerado.
		21.381 - Sistema não respondeu a solicitação de transação TEF.
		21.382 - Arquivo de Confirmação foi gerado com erro.
		21.383 - Arquivo de resposta foi gerado com erro.
		21.384 - Mensagem TEF: &1 = ex: Cartão não autorizado.
		21.387 - Operação TEF não pode ser cancelada por &1 = ex.: nome do usuário.
		21.395 - Cancelamento não permitido.
		21.396 - Parâmetros do TEF não foi localizado.
		21.397 - Usuário do Controle de Caixa não localizado.
		21.400 - Registro &1 = (nome da tabela) não foi localizado.

pi_envia_req_md_adm_tef
Requisito	REQ 1376 - Controle de caixa - Integração com leitora de cartão
Sintaxe	run pi_envia_req_md_adm_tef in h-handle (input param p_cod_empresa_tef , input param p_cod_operac_admdra , input param p_cod_usuar, output param p_nom_mensagem_tef, output param p_nom_arquivo_retorno).
Descrição	Requisição acesso ao administrador SITEF – Tecnologia TEF (Transferência Eletrônica de Fundos)
	Parâmetros	Descrição
	p_cod_empresa_tef	Código da empresa corrente.
	p_cod_operac_admdra	Tipo de operação, de acordo com manual do Aplicativo. Ex.: (CRT).
	p_cod_usuar	Código do usuário do módulo.
	p_nom_mensagem_tef	Mensagem para o Operador.
	p_nom_arquivo_retorno	Caminho e nome do arquivo gerado com a imagem do cupom.
Retorno	A API irá retornar o campo “p_nom_mensagem_tef” o qual retornará a última ação executado no administrador. Serve também para informar ao operador do caixa que o retorno do controle voltou para a Automação (Controle de Caixa); Se o operador solicitar reimpressão ou fazer algum cancelamento pelo administrador, a API fará a geração do cupom o qual será impresso automaticamente pelo Controle de Caixa, através do parâmetro p_nom_arquivo_retorno que retorna com o caminho completo onde foi gerado o arquivo que contem a imagem do cupom; Caso esteja em branco, houve erro ou o acesso ao administrador não gerou nenhuma saída de impressão. As mensagens possíveis para esse método são:
	21.368 - Transações TEF não autorizadas.
	21.369 - Usuário(a) sem permissão para transações TEF.
	21.372 - Diretório de integração não foi localizado.
	21.376 - Falta parâmetros para este procedimento.
	21.379 - Arquivo de transação não foi gerado.
	21.380 - Houve erro no tratamento do arquivo gerado.
	21.381 - Sistema não respondeu a solicitação de transação TEF.
	21.382 - Arquivo de Confirmação foi gerado com erro.
	21.383 - Arquivo de resposta foi gerado com erro.
	21.384 - Mensagem TEF: &1 = ex: Cartão não autorizado.
	21.396 - Parâmetros do TEF não foi localizado.
	21.397 - Usuário do Controle de Caixa não localizado.
	21.400 - Registro &1 = (nome da tabela) não foi localizado.

Método Negócio

pi_valid_amb_tef
Requisito	REQ 1376 - Controle de caixa - Integração com leitora de cartão
Sintaxe	run pi_valid_amb_tef (input p_cod_empresa_tef, input p_cod_usuar)
Descrição	Faz a verificação dos parâmetros do TEF e carrega as variáveis de diretórios e arquivos que serão utilizados durante o processamento. Em caso de erro grava-o em tt_log_erro.
	Parâmetros	Descrição
	p_cod_empresa_tef	Código da empresa corrente.
	p_cod_usuar	Código do usuário do módulo.
Retorno	Não há retorno de informações. Em caso de erro, apenas grava o mesmo na tabela de erros. Os erros são tratados na procedure ‘pai”.

pi_grava_erro_tef
Requisito	REQ 1376 - Controle de caixa - Integração com leitora de cartão
Sintaxe	run pi_grava_erro_tef (input p_num_erro_tef, input p_nom_mensagem_tef)
Descrição	Executa a gravação de erros na tabela temporária tt_log_erro.
	Parâmetros	Descrição
	p_num_erro_tef	Código do erro, de acordo com a mensagem de erro.
	p_nom_mensagem_tef	Mensagem por parâmetro, para se substituída em tempo de execução.
Retorno	Sem retorno de informações.

pi_gera_arq_tef
Requisito	REQ 1376 - Controle de caixa - Integração com leitora de cartão
Sintaxe	run pi_gera_arq_tef (input p_cod_operac_admdra)
Descrição	De acordo com o tipo de operação, faz a geração do arquivo de requisição da transação no diretório correspondente. Em caso de erro faz a gravação na tabela temporária tt_log_erro.
	Parâmetros	Descrição
	p_cod_operac_admdra	Tipo de operação para requisição da transação TEF.
Retorno	Sem retorno de informações.

pi_interp_arq_retorno
Requisito	REQ 1376 - Controle de caixa - Integração com leitora de cartão
Sintaxe	run pi_interp_arq_retorno (input p_cod_operac_admdra)
Descrição	De acordo com o tipo de operação, faz a importação do arquivo retorno da transação TEF em diretório específico, faz a consistência das informações, segundo o manual de padrões, fornecido pelo empresa parceira da solução. Cria o registro na tabela wt_process_negoc_cx_cart (tabela temporária física), grava mensagem para o Operador se for o caso. Em caso de erros faz a gravação na tabela temporária tt_log_erro.
	Parâmetros	Descrição
	p_cod_operac_admdra	Tipo de operação para requisição da transação TEF.
Retorno	Sem retorno de informações.

pi_interp_arq_ret_adm
Requisito	REQ 1376 - Controle de caixa - Integração com leitora de cartão
Sintaxe	run pi_interp_arq_ret_adm (output p_des_cupom_trans)
Descrição	Faz a escuta do diretório de transação até que seja gerado um arquivo retorno da transação TEF, faz a consistência das informações, se houve ação de impressão ou reimpressão através do administrador, será gravado no parâmetro de saída p_des_cupom_trans a imagem do cupom para ser impresso pela pi chamadora.
	Parâmetros	Descrição
	p_des_cupom_trans	Vai receber a imagem do cupom para ser gerado o arquivo de impressão TEF.
Retorno	Sem retorno de informações.

pi_trata_arq_trans
Requisito	REQ 1376 - Controle de caixa - Integração com leitora de cartão
Sintaxe	run pi_trata_arq_trans (input p_nom_tip_acao)
Descrição	De acordo com o tipo de ação, esta procedure executa a limpeza dos diretórios de trabalho, renomeia arquivos de requisição ou elimina arquivos de resposta ou confirmação durante o processo de venda. Em caso de erros faz a gravação na tabela temporária tt_log_erro.
	Parâmetros	Descrição
	p_nom_tip_acao	Tipo de ação para andamento da transação TEF.
Retorno	Sem retorno de informações.

pi_verif_trans_tef
Requisito	REQ 1376 - Controle de caixa - Integração com leitora de cartão
Sintaxe	run pi_verif_trans_tef (input p_idi_tempo_tef, input p_cod_operac_admdra)
Descrição	De acordo com o tipo de operação, este método faz a escuta dos diretórios de trabalho para saber se o arquivo de requisição ou resposta foram capturados ou gerados respectivamente neste ordem. O tempo de ação é determinado pelo parâmetro “p_idi_temp_tef” que lido na tabela de parâmetros TEF. Em caso de erros faz a gravação na tabela temporária tt_log_erro.
	Parâmetros	Descrição
	p_idi_tempo_tef	Tempo em segundos que o ERP irá aguardar pela resposta da transação TEF, enquanto o controle estiver com o Aplicativo Sitef.
	p_cod_operac_admdra	Tipo de operação para requisição da transação TEF.
Retorno	Sem retorno de informações.

pi_imprime_comprov_tef
Requisito	REQ 1376 - Controle de caixa - Integração com leitora de cartão
Sintaxe	run pi_imprime_comprov_tef (input p_des_cupom_trans_tef, output p_nom_arquivo_retorno_tef)
Descrição	Este método faz a impressão do cupom de venda direcionada para arquivo em diretório específico, retorna o nome e o local da geração no parâmetro “p_nom_arquivo_retorno_tef”.
	Parâmetros	Descrição
	p_des_cupom_trans_tef	Contém a imagem do cupom da transação TEF.
	p_nom_arquivo_retorno_tef	Contém o nome e caminho completo da gravação do comprovante de impressão.
Retorno	Retorna o nome do arquivo e local da gravação do comprovante de impressão.