Minha experiência com APIs e integração de POS

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...