Olá amigo! 😊 Como você está hoje?
Gostaria de compartilhar uma pequena parte dos meus aprendizados no meu primeiro projeto oficial: a integração de máquinas de POS/EDC com nosso sistema de faturamento. Foi um desafio empolgante onde tive experiência prática trabalhando com APIs e fornecedores.
Como uma máquina de pagamento realmente funciona?
É simples: comece iniciando/criando uma transação e, depois, recupere o status do pagamento dela.
Aqui, iniciar/criar refere-se ao método POST, e recuperar refere-se ao GET.
Fluxo de trabalho...
Vamos assumir que o fornecedor nos forneceu um documento com ambas as APIs (Criar e Buscar Status do Pagamento). Exemplos listados abaixo:
CRIAR TRANSAÇÃO:
url/endpoint: https://payvendor.com/create-transaction
method: POST
payload:
{
"reference_id": "2345678",
"pos_id": "PISC98765",
"date_time": "MMDDYYYYHHMMSS"
"amount": 100
}
response: [200]
{
"reference_id": "2345678",
"pos_id": "PISC98765",
"date_time": "MMDDYYYYHHMMSS"
"unn": "456789876546787656"
}
BUSCAR STATUS DO PAGAMENTO:
url/endpoint: https://payvendor.com/get-status
method: GET
payload: ?reference_id="2345678"
response: [200]
{
"reference_id": "2345678",
"pos_id": "PISC98765",
"date_time": "MMDDYYYYHHMMSS"
"unn": "456789876546787656"
"status": "paid"
"amount": 100
}
Como usamos essas APIs? Vamos descobrir... 🫡
Para consumir essas APIs no ObjectScript, temos um módulo ou classe para realizar requisições HTTP internamente: %Net.HttpRequest.
O básico:
- Criar uma instância de
%Net.HttpRequest. - Definir a URL e o método HTTP.
- Adicionar o cabeçalho (header) e o corpo (body). [se necessário]
- Enviar a requisição para o servidor.
- Tratar a resposta.
; --------- EXEMPLO DE REQUISIÇÃO POST ---------
Set req = ##class(%Net.HttpRequest).%New() ; cria uma instância desta classe
Set req.Server = "https://payvendor.com" ; o servidor
Set req.Location = "/create-transaction" ; o endpoint
Set req.Https = 1 ; 0 para http / 1 para https
Set req.ContentType = "application/json" ; Tipo de conteúdo
; ---- create the JSON body ----
Set obj = ##class(%DynamicObject).%New()
Set obj."reference_id" = "2345678" ; ID único
Set obj."pos_id" = "PISC98765" ; número do dispositivo
Set obj."date_time" = $ZSTRIP($ZDATETIME($HOROLOG,8), "*P")
Set obj."amount" = 100
; -------------------------------
; ---- enviar requisição ----
Do req.EntityBody.Write(obj.%ToJSON())
Do req.Post() ; .Post() irá disparar a chamada
; ----------------------
; ---- Resposta ----
Write req.HttpResponse.StatusCode,! ; CÓDIGO DE STATUS HTTP
Write req.HttpResponse.Data.Read(),! ; MENSAGEM DE STATUS HTTP
; ------------------
Após criar a transação, podemos manter uma tabela (preferível) ou um global para manter os logs de cada transação.
; --------- EXEMPLO DE REQUISIÇÃO GET ---------
Set req = ##class(%Net.HttpRequest).%New() ; cria uma instância desta classe
Set req.Server = "https://payvendor.com" ; o servidor
Set req.Location = "/get-status" ; o endpoint
Set req.Https = 1 ; 0 para http / 1 para https
; ---- Parâmetros de Consulta (Query) ----
Do req.SetParam("reference_id", "2345678")
; ---- enviar requisição ----
Do req.Get() ; .Get() irá disparar a chamada
; ---- Resposta ----
Set stsCode = req.HttpResponse.StatusCode,! ; CÓDIGO DE STATUS HTTP
If stsCode=200 {
Set objResponse = req.HttpResponse.Data.Read()
Set objData = ##class(%DynamicObject).%FromJSON(objResponse)
Set payStatus = objData.status ; status do pagamento
}
; ------------------
É assim que buscamos o status do pagamento. Depois de obter o status, podemos atualizá-lo no sistema de faturamento e também em nossos logs.
Este fluxo de trabalho é simples, mas à medida que programamos mais, podemos desenvolver frameworks e abordagens melhores. Ao longo da minha experiência, integrei com sucesso 5 fornecedores de POS e 3 gateways de pagamento com nosso sistema de faturamento. Se você tiver alguma dúvida ou precisar de orientação, sinta-se à vontade para entrar em contato!
Também estou aberto a feedbacks. :)
Obrigado...
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)

(1).jpg)