Getnet DocsGetnet Docs

Métodos e parâmetros

Esta referência lista os métodos do POS Integrado e seus parâmetros. É uma consulta rápida para desenvolvedores; para fluxos passo a passo, use o guia de Início rápido e os guias de pagamento ou operacionais.

O que são esses métodos

O POS Integrado expõe métodos de gerenciamento da conexão (CreateHttp, CreateUsb, CreateCloud, Polling, GetInfo, Close) e métodos de operação do dispositivo (Sale, Refund, PreAuth, GetReports, Shift, GetLastVoucher etc.). Todas as operações do dispositivo são invocadas em uma instância de Connector retornada por um dos métodos Create. Somente uma operação por vez pode estar em andamento por Connector. Os nomes e os tipos dos parâmetros podem variar um pouco conforme o SDK (.NET, Kotlin, JavaScript/TypeScript).

Somente uma operação do dispositivo pode estar em andamento por Connector a cada momento. Aguarde a resposta (ou o erro) antes de enviar o próximo comando. Consulte Connector e fluxos de comunicação.

Métodos de criação do Connector

As tabelas a seguir descrevem os métodos de criação do Connector:

CreateHttp

Cria um Connector usando HTTP (Wi-Fi ou Ethernet).

ParâmetroTipoObrigatórioDescrição
hostnameStringSimNome de host, IPv4 ou IPv6 do dispositivo POS.
portintNãoPorta remota (8080 por padrão).
setupParamsHashMap<String, String>NãoConfiguração do terminal. Se usar, consulte o comportamento de reconexão.

CreateUsb

Cria um Connector usando USB (serial).

ParâmetroTipoObrigatórioDescriçãoDisponibilidade
addressStringSimEndereço da porta serial (por exemplo, COM3, /dev/ttyACM0)..NET
usbDeviceUsbDeviceSimObjeto de dispositivo USB do Android.Kotlin
setupParamsHashMap<String, String>NãoConfiguração do terminal. Se usar, consulte o comportamento de reconexão.Kotlin

É obrigatório exatamente um entre address (.NET) e usbDevice (Kotlin), conforme a plataforma. Se usar setupParams, consulte a seção do fluxo de reconexão para mais detalhes.

CreateCloud

Cria um Connector que alcança um terminal remoto pela nuvem da Getnet. Não é necessário informar nome de host nem porta; a nuvem roteia cada comando para o terminal registrado.

ParâmetroTipoObrigatórioDescrição
setupParamsHashMap<String, String>NãoConfiguração do terminal. Se usar, consulte o comportamento de reconexão.

CreateCloud está disponível nas bibliotecas Kotlin e JavaScript/TypeScript. Se usar setupParams, consulte a seção do fluxo de reconexão para mais detalhes.

Close

Libera todos os recursos em memória. Depois de chamar essa função, você não consegue reutilizar o objeto connector. Nenhum parâmetro é esperado.

Gerenciamento da conexão

As tabelas a seguir descrevem os métodos de gerenciamento da conexão:

Polling

Valida a conectividade e se o terminal está pronto. Você deve chamá-lo antes das operações do dispositivo.

Parâmetros: nenhum.

Retorno:

ParâmetroTipoDescrição
CodeIntCódigo de resposta; 0 indica sucesso.
MessageStringMensagem de resultado (por exemplo, “APPROVED”).
ConnectedBoolIndica se o terminal está conectado e responde.

GetInfo

Recupera informações do dispositivo e do comércio no POS (modelo, série, rede, identificadores do comércio). É útil para validação ou diagnóstico.

Parâmetros: nenhum.

Retorno:

ParâmetroTipoDescrição
CodeIntCódigo de resposta; 0 indica sucesso.
MessageStringMensagem de resultado (por exemplo, “APPROVED”).
LegalNameStringRazão social do comércio.
CommerceCuitStringIdentificação do comércio (CUIT, CNPJ ou Rut).
CommerceNumberStringIdentificação do vendedor (sellerCode).
BranchNumberStringCódigo da filial (número de identificação).
BranchNameStringRazão social da filial.
LittleBranchNameStringNome abreviado da filial.
BranchAddressStringEndereço completo do comércio.
BranchDistrictStringCidade ou distrito do comércio.
TerminalIdStringIdentificação lógica do terminal (terminalCode).
SerialNumberStringNúmero de série físico do terminal.
TerminalModelStringNome do modelo do terminal.
OSStringVersão do Android ou do SDK do terminal.
EmvModuleStringVersão do módulo EMV.
AppVersionNameStringVersão da aplicação de pagamento.
CommunicationUrlStringEndereço de comunicação dos terminais.
PrimaryIPStringNúmero de IP atual do terminal.
CompanyStringNome da operadora de rede móvel (se usar SIM).
ApnStringNome do ponto de acesso (APN) do SIM.
SimIdStringIdentificador do SIM (ICCID).
CommunicationTypeStringTipo de conexão de rede (por exemplo, Wi-Fi, USB, HTTP).
WifiStringNome da rede Wi-Fi conectada.
CertificateStatusBooleanTrue se o certificado do SDK é válido.
TipEnabledBooleanTrue se a digitação de gorjeta está habilitada.
ReceiptBooleanTrue se a impressão ou o conteúdo do recibo está habilitado.
SalespersonBooleanTrue se a digitação do código de vendedor está habilitada.
InstallmentsCommerceBooleanTrue se os planos de parcelamento do comércio estão habilitados.
IssuerInstallmentsBooleanTrue se os planos de parcelamento do emissor estão habilitados.

Operações do dispositivo

As tabelas a seguir descrevem as operações do dispositivo:

Sale

Executa um pagamento (em passo único, parcelado ou com QR Code).

ParâmetroTipoObrigatórioDescrição
AmountLongNãoValor da transação (os 2 últimos dígitos são decimais).
SaleTypeEnumNãoCard, QrCode.
PrintOnPosBoolNãoImprime o recibo no POS.
EmployeeIdIntNãoID do garçom.
TipLongNãoValor da gorjeta. Não suportado para QR.
InstallmentsIntNãoNúmero de parcelas.
SkipReceiptBoolNãoIgnora o recibo do cliente.
SkipConfirmationBoolNãoIgnora a tela de confirmação.
PlanIdStringNãoPlano de parcelamento.
InterestEnumNãoOnPosSelection, Interest, NoInterest.
OperationModeEnumNãoCalculatedGetnet (o terminal calcula) ou CalculatedISV (sua aplicação calcula). Se omitido, o valor padrão é CalculatedGetnet.
CallerIdStringNãoID gerado pelo sistema de automação (máx. 100 caracteres), necessário para consultar a transação depois com o Check Status. Não são permitidos caracteres especiais nem Unicode.

Retorno:

CampoTipoDescrição
CodeIntCódigo de resposta; 0 indica sucesso.
MessageStringMensagem de resultado (por exemplo, “APPROVED”).
CommerceCodeStringCódigo único de filial aprovado pela Getnet.
TerminalIdStringIdentificação lógica do terminal.
AuthorizationCodeStringCódigo de autorização da transação.
AmountLongValor final cobrado na moeda local.
Last4DigitsStringOs quatro últimos dígitos do cartão do cliente.
CardTypeStringTipo de cartão usado.
AccountingDateStringData e hora da transação em GMT (pode retornar valores padrão se for nula).
CardBrandStringBandeira do cartão usada na transação.
RealDateDateData e hora da transação no horário local (pode retornar valores padrão se for nula).
EmployeeIdIntID do garçom ou funcionário.
TipLongValor da gorjeta incluído na venda.
SaleTypeEnumCard ou QR Code.
ReceiptContentDictDados padronizados do recibo se PrintOnPos for false. Consulte Objeto ReceiptContent.
PlanIdStringO plano de parcelamento selecionado (presente quando aplicável).
InterestEnumIndica se houve aplicação de juros (presente quando aplicável).
OperationModeEnumCalculatedGetnet ou CalculatedISV. Pode ser omitido ou assumir o valor padrão se não for enviado.
OriginalAmountLongValor inicial antes dos ajustes (presente quando aplicável).
InstallmentsIntNúmero de parcelas usado (presente quando aplicável).
CallerIdStringID gerado pelo sistema de automação (máx. 100 caracteres).
CardBinStringOs oito primeiros dígitos do cartão do cliente (máx. 8).

Refund

Executa um reembolso (cancelamento).

ParâmetroTipoObrigatórioDescrição
AuthorizationCodeStringNãoCódigo de autorização da transação original (6 dígitos).
OriginTransDateDateNãoData da transação original, no formato ISO8601 com fuso horário. Não pode ser posterior à data atual.
AmountLongNãoValor do reembolso (reembolsos parciais são suportados).
SkipConfirmationBoolNãoIgnora a tela de confirmação.
SkipReceiptBoolNãoNão imprime o recibo do cliente.
PrintOnPosBoolNãoImprime no POS ou retorna o conteúdo na resposta.
RefundTypeEnumNãoEspecifica qual parte de uma venda é reembolsada: SaleWithdrawal, Sale ou Withdrawal.

Retorno:

CampoTipoDescrição
CodeIntCódigo de resposta; 0 indica sucesso.
MessageStringMensagem de resultado (por exemplo, “APPROVED”).
CommerceCodeStringCódigo único de estabelecimento aprovado pela Getnet.
TerminalIdStringIdentificação lógica do terminal.
AuthorizationCodeStringCódigo de autorização da operação de reembolso.
NsuLastSuccessfulMessageStringNSU da última mensagem bem-sucedida.
ReceiptContentDictObjetos de dados padronizados do recibo; fornecidos se PrintOnPos for false. Consulte Objeto ReceiptContent.

GetLastVoucher

Recupera ou reimprime o comprovante da última transação.

ParâmetroTipoObrigatórioDescrição
PrintOnPosBooleanNãoImprime no POS ou retorna o conteúdo.
SkipReceiptBooleanNãoSe PrintOnPos for true: não imprime o recibo do cliente. Por padrão é false.

Retorno:

CampoTipoDescrição
CodeIntCódigo de resposta; 0 indica sucesso.
MessageStringMensagem de resultado (por exemplo, “APPROVED”).
ReceiptContentDictObjetos de dados padronizados do recibo se PrintOnPos for false. Consulte Objeto ReceiptContent.

Se a última operação foi do tipo Relatório (Totals, Detailed, Shift), não há comprovante disponível para reimpressão. Uma mensagem indicando esse cenário é retornada.

GetReports

Recupera o relatório Totals, Detailed ou Shift.

ParâmetroTipoObrigatórioDescrição
TypeEnumSimTotals, Detailed ou Shift.
PrintOnPosBooleanNãoImprime no POS ou retorna o conteúdo na resposta.

Retorno:

CampoTipoDescrição
CodeIntCódigo de resposta; 0 indica sucesso.
MessageStringMensagem de resultado (por exemplo, “APPROVED”).
ReportDetailsDictDados estruturados fornecidos se PrintOnPos for false. O conteúdo varia conforme o Type.

ReportDetails (Totals)

Uma visão resumida de todas as operações, agrupada em objetos por tipo de operação mais um objeto global operationTotals.

Objetos por operação — debitOperation, creditOperation, qrcodeCreditOperation, qrcodeDebitOperation, qrcodePrePaidOperation, devolutionOperation, prePaidOperation e qrcodeOperation. Cada um contém:

CampoTipoDescrição
quantityStringNúmero de transações.
amountStringValor total.
amountSalesDiscountedStringValor total das vendas com desconto.
refundsAmountStringValor total dos reembolsos.
salesCancelledQuantityStringNúmero de vendas canceladas.
listOperationStringLista de objetos Operation (consulte ReportDetails (Detailed)).

Objeto operationTotals — totais globais de todas as operações:

CampoTipoDescrição
salesAmountStringValor total das vendas.
salesQuantityStringNúmero de vendas.
refundsAmountStringValor total dos reembolsos.
refundsQuantityStringNúmero de reembolsos.
tipAmountStringValor total das gorjetas.
tipQuantityStringNúmero de gorjetas.
qrPctAmountStringValor total dos QR Codes.
qrPctQuantityStringNúmero de QR Codes.
totalCreditStringValor total das vendas no crédito.
totalDebitStringValor total das vendas no débito.
totalPrepaidStringValor total das vendas no pré-pago.

ReportDetails (Detailed)

Uma lista de operações individuais.

CampoTipoDescrição
authorizationCodeStringCódigo de autorização da transação.
paymentIdStringIdentificador único interno do pagamento.
opReasonMessageStatusStringMensagem de status da operação.
timestampDateData e hora da transação (ISO8601).
brandTypeStringBandeira do cartão usada.
cardLastNumberStringÚltimos 4 dígitos do cartão.
operationValueLongValor da operação.
operationEnumTipo de operação: crédito, débito, voucher, QR Code, cancelamento ou reembolso.

Solicite os relatórios ao menos 2 minutos após a última venda ou troca de turno para garantir a sincronização dos dados.

Shift

Configuração de turnos, troca de turno ou consulta do total de turnos.

ParâmetroTipoObrigatórioDescrição
ShiftOperationEnumSimConfiguration (configuração), Change ou GetShifts.
NumberOfShiftsIntCondicionalObrigatório somente para Configuration, para definir o total de turnos (máx. 2 dígitos).
SkipConfirmationBooleanNãoIgnora a tela de confirmação da troca de turno.
PrintOnPosBooleanNãoImprime os dados do turno no terminal.

Retorno:

CampoTipoDescrição
CodeIntCódigo de resposta; 0 indica sucesso.
MessageStringMensagem de resultado (por exemplo, “APPROVED”).
TotalOfShiftsIntTotal de turnos atual.
ReportDetailsStringFornecido somente se PrintOnPos for false e ShiftOperation for Change.

PreAuth

Gerencia o ciclo de vida da pré-autorização (Create, Modify, Remove, Confirm, Retrieve).

Parâmetros:

ParâmetroTipoObrigatórioDescrição
OperationEnumSimCreate, Modify, Remove, Confirm, Retrieve.
ReservationCodeStringNãoNecessário para Modify, Remove ou Confirm (máx. 5 caracteres). É opcional, mas deve ser único se você o enviar; o sistema de automação é responsável pela unicidade. Chama-se reservationId no SDK.
AuthorizationCodeStringCondicionalÉ exigido um código válido para identificar a transação que você vai modificar (6 dígitos).
OriginalTransactionDateDateCondicionalObrigatório para identificar a pré-autorização em Modify, Remove ou Confirm. No formato ISO8601 com fuso horário.
AmountLongNãoValor na moeda local, com os 2 últimos dígitos como decimais (máx. 9 dígitos).
PlanIdStringNãoID do plano de parcelamento (Argentina).
InstallmentsIntNãoNúmero de parcelas.
FiltersObjectNãoCritérios de busca (somente para Retrieve). Consulte Filtros de PreAuth.
PrintOnPosBoolNãoImprime o recibo no POS ou o retorna na resposta.
SkipReceiptBoolNãoNão imprime o recibo do cliente.
SkipConfirmationBoolNãoIgnora a tela de confirmação.
CallerIdStringNãoID gerado pelo sistema de automação (máx. 100 caracteres). É necessário para consultar depois uma transação Create com o Check Status. Não são permitidos caracteres especiais nem Unicode.

Filtros de PreAuth

Usado somente quando Operation é Retrieve.

CampoTipoDescrição
InitialDateDateLimite inicial para recuperar pré-autorizações pendentes, no formato ISO8601 com fuso horário (padrão: a data atual). Não pode ser posterior à data atual nem a FinalDate.
FinalDateDateLimite final, no formato ISO8601 com fuso horário (padrão: a data atual). Não pode ser posterior à data atual nem anterior a InitialDate.
AuthorizationCodeStringFiltra por um código de autorização específico (6 dígitos).
ReservationCodeStringFiltra por um código de reserva específico (máx. 5 caracteres).
Last4CardDigitsStringFiltra pelos últimos 4 dígitos do cartão.
CardBrandIntFiltra por bandeira do cartão: 0 = ALL (padrão), 1 = Visa, 2 = MasterCard, 3 = Amex.

Retorno:

CampoTipoDescrição
CodeIntCódigo de resposta; 0 indica sucesso.
MessageStringMensagem de resultado (por exemplo, “APPROVED”).
AuthorizationCodeStringCódigo de autorização da transação.
AmountLongValor final na moeda local.
OriginalAmountLongValor antes de qualquer ajuste.
PlanIdStringO plano de parcelamento selecionado.
InstallmentsIntNúmero de parcelas.
Last4DigitsStringÚltimos quatro dígitos do cartão do cliente.
CardTypeStringTipo de cartão.
AccountingDateDateData e hora da transação (GMT).
CardBrandStringBandeira do cartão usada.
RealDateDateData e hora da transação (local).
ReceiptContentDictDados padronizados do recibo se PrintOnPos for false. Consulte Objeto ReceiptContent.
ReservationIdStringIdentificador do código de reserva.
CommerceCodeStringCódigo único de estabelecimento.
TerminalIdStringCódigo do terminal POS.
PendingPreAuthorizationsListLista de elementos (somente para Retrieve). Consulte Elemento da lista PendingPreAuthorizations.
CardBinStringOs oito primeiros dígitos do cartão do cliente (máx. 8).
CallerIdStringID gerado pelo sistema de automação (máx. 100 caracteres).

Elemento da lista PendingPreAuthorizations

Estrutura dos objetos dentro da lista PendingPreAuthorizations.

CampoTipoDescrição
TransactionDateDateData e hora em que foi processada.
AmountLongValor da transação na moeda local.
AuthorizationCodeStringCódigo de autorização da transação.
Last4DigitsStringÚltimos quatro dígitos do cartão usado.
EntryModeEnumCHIP, MAGSTRIPE, CONTACTLESS.
CommerceCodeStringCódigo único de filial.
TerminalIdStringCódigo do terminal POS.
DateLimitDateData de vencimento da pré-autorização.
ReceiptCodeStringCódigo de identificação impresso no recibo.
ReservationIdStringIdentificador da transação informado pelo usuário quando a pré-autorização é criada ou atualizada.

Cancel

Cancela um comando em andamento e devolve o terminal à tela POS Connected.

Parâmetros: nenhum.

Retorno:

CampoTipoDescrição
CodeIntCódigo de resposta; 6 indica que a operação Cancel foi executada com sucesso.
MessageStringMensagem de resultado.

Somente Sale (Card/QR), Refund e Pre-authorization aceitam cancelamento. Cancelar um comando não cancelável retorna “The operation isn’t cancellable”; cancelar sem uma operação ativa retorna “There’s no active operation to cancel”. Quando um comando é cancelado com sucesso, esse comando cancelado também retorna Code 2 (cancelado).

Check Status

Busca o status de uma transação específica processada nas últimas 72 horas, identificada pelo CallerId.

Parâmetros:

ParâmetroTipoObrigatórioDescrição
CallerIdStringSimID gerado pelo sistema de automação para a transação original (máx. 100 caracteres). Não são permitidos caracteres especiais nem Unicode. Deve coincidir com o CallerId enviado na transação original; caso contrário, você pode receber um status incorreto. Para consultar um Refund, use o mesmo CallerId enviado no Sale original.

Retorno:

CampoTipoObrigatórioDescrição
CodeIntSimCódigo de status da transação (0–6). Consulte a tabela a seguir.
MessageStringSimMensagem de texto que representa o resultado da operação.
CallerIdStringSimID gerado pelo sistema de automação.
StatusEnumSimStatus atual da transação: APPROVED, AUTHORIZED, REFUNDED, CANCELED, REVERSED, NOT_FOUND ou UNKNOWN.
AuthorizationCodeStringNãoCódigo de autorização da transação (6 dígitos). Pode ser null se nenhuma transação for encontrada para o CallerId.

Códigos de status da transação:

CódigoStatusDescrição
0APPROVEDTransação capturada (aprovada). Usado em vendas com cartão padrão e em QR Code com cartão.
1AUTHORIZEDTransação autorizada (pré-autorização ou QR PCT). Exclusivo dos pagamentos com QR Code PCT.
2REFUNDEDTransação reembolsada (D+1).
3CANCELEDTransação cancelada (D+0).
4REVERSEDTransação revertida (desfeita).
5NOT_FOUNDNenhuma transação foi encontrada para o CallerId informado.
6UNKNOWNStatus desconhecido ou não mapeado.

Comportamento do QR Code: Uma transação QR PCT (Point of Capture) sempre retorna AUTHORIZED (código 1), nunca APPROVED. Um QR Code com cartão segue o comportamento padrão de cartão e retorna APPROVED (código 0) após a captura.

Uma transação pode levar um instante para ser processada por completo na plataforma da Getnet. Se você consultá-la logo após a captura, pode receber NOT_FOUND; nesse caso, use Recuperar o último comprovante.

Se várias transações compartilham o mesmo CallerId, o sistema usa a mais recente para determinar o status. Aguarde ao menos 2 minutos após um reembolso para obter o status mais atualizado. O Check Status permite consultar somente a operação de pré-autorização Create.

SwitchToNormalPos

Desativa o modo POS Integrado de forma correta e permite o uso manual do terminal.

Parâmetros: nenhum.

Retorno:

CampoTipoDescrição
CodeIntCódigo de resposta; 0 indica sucesso.
MessageStringMensagem de resultado.

Setup

Define a configuração do terminal, como um nome amigável personalizado para identificá-lo.

ParâmetroTipoObrigatórioDescrição
SetupParamsDict/MapSimChaves e valores de identificação (por exemplo, friendly_name).

Configurações disponíveis:

ChaveTipoDescrição
friendly_nameStringNome personalizado associado a cada transação de pagamento, reembolso e pré-autorização; a Getnet o usa internamente para identificar a origem. Somente caracteres alfanuméricos e espaços são permitidos, sem caracteres especiais (por exemplo, ISV Name2 é válido; I.S.V ? N@m!2 não é). O valor padrão é ConectorApp.

Se você usa um friendly_name personalizado, envie-o em cada conexão (CreateUsb, CreateHttp ou CreateCloud), porque a reconexão restaura a configuração do terminal.

Retorno:

CampoTipoDescrição
CodeIntCódigo de resposta; 0 indica sucesso.
MessageStringMensagem de resultado.

Objeto ReceiptContent

Quando PrintOnPos é false, as operações que geram recibo (Sale, Refund, GetLastVoucher, PreAuth) retornam um objeto ReceiptContent: uma string em formato JSON com os campos do recibo. Assim o sistema de automação pode imprimir ou armazenar o recibo. Se o sistema de automação assume a impressão, ele deve imprimir ao menos o recibo do estabelecimento; o recibo do cliente é opcional.

CampoTipoDescrição
getnetLogoStringLogo da Getnet codificado como string base64.
sellerNameStringNome do estabelecimento.
sellerAddressStringEndereço do estabelecimento.
cuitStringCódigo único de documento.
comStringCódigo de vendedor do estabelecimento.
aidStringCódigo AID do terminal.
termStringCódigo do terminal.
authorizationCodeStringCódigo de autorização deste recibo.
letterTypeTransactionStringIndica a tecnologia de leitura do cartão.
dateTimeStringData e hora do recibo em ISO8601 (UTC).
cardLastDigitsStringÚltimos 4 dígitos do cartão.
brandStringBandeira do cartão.
receiptCodeStringCódigo de identificação impresso no recibo.
amountStringValor da transação mais a gorjeta (se aplicada), na moeda local.
tipStringValor da gorjeta.
operationTypeStringTipo de operação.
errorMessageStringMensagem de erro.
cardholderValidationMethodStringMétodo de validação usado na transação.

Recursos relacionados