API PosPinpad

Referência da interface PosPinpad (com.tupifintech.apossdk.sdk.api) — a porta de entrada do SDK.

Visão Geral

A interface concentra todas as operações de alto nível: configuração, registro/inicialização, captura de cartão/PIN, pagamentos, PIX, estorno, pré-autorização, consultas, impressão, tela secundária e usuários locais.

Tipo	Como chamar	Resultado
suspend	Dentro de uma coroutine	Retorno direto da função
Fluxos de pagamento	createPayment e createPixPayment são suspend; os fluxos start* são @RunAsync e executam em segundo plano	Eventos em PosPinpadCallback
Síncronos	De qualquer thread	Retorno direto, sem rede

As operações financeiras e cancelPayment() exigem o terminal inicializado. Sem terminalInitialization(), todas disparam onAppError(SdkErrorCode.TERMINAL_NOT_INITIALIZED, ...). Em createPayment e createPixPayment, a chamada também lança IllegalStateException; nos fluxos start* e em cancelPayment, que executam em segundo plano, só o onAppError é emitido.

Interface completa

interface PosPinpad {

    // Ativação e inicialização
    suspend fun getTerminalConfig(slug: String): TerminalConfigResponse
    suspend fun register(fields: Map<String, String>, partnerSlug: String): RegistrationResult
    suspend fun authenticate(request: AuthenticationRequest): AuthenticationResponse
    suspend fun terminalInitialization(request: TerminalInitializationRequest): TerminalInitializationResponse
    fun isTerminalInitialized(): Boolean
    suspend fun logout()

    // Informações do terminal
    fun getDeviceInfo(): DeviceInfo
    fun getTablesInfo(): TablesInfo?
    fun getTerminalTid(): String?
    fun getTransactionLimits(transactionType: TransactionType, paymentMethod: PaymentMethod, installments: Int = 1): TransactionLimits?
    fun getAvailableProducts(paymentMethod: PaymentMethod): List<ProductInfo>
    fun getConfiguredAcquirers(): List<String>
    fun hasAcquirerKeys(acquirerName: String): Boolean
    fun hasDukptKey(index: Int): Boolean
    @Deprecated fun hasPagSeguroKeys(): Boolean
    suspend fun getSimInfo(): SimInfo?
    suspend fun checkInternetConnection(): HealthCheckResult

    // Pagamentos
    suspend fun createPayment(
        type: TransactionType,
        amount: Long,
        paymentMethod: PaymentMethod?,
        installments: Int,
        installmentsInterest: Boolean? = false,
        metadata: TransactionMetadata = TransactionMetadata.EMPTY
    )
    suspend fun createPixPayment(amount: Long, metadata: TransactionMetadata = TransactionMetadata.EMPTY)
    fun cancelPayment()

    // Estorno e pré-autorização
    fun startRefundFlow(operatorTaxId: String? = null, paymentMethod: PaymentMethod? = null, metadata: TransactionMetadata = TransactionMetadata.EMPTY)
    fun startPixRefundFlow(transactionId: String, amount: Long, operatorTaxId: String? = null)
    fun startPixRefundListFlow(operatorTaxId: String? = null)
    fun startPreAuthFlow(preAuthId: String? = null, metadata: TransactionMetadata = TransactionMetadata.EMPTY)

    // Consultas
    suspend fun getTransactionSummaries(filters: QueryFilterBuilder): TransactionSummaryResponse
    suspend fun getTransactionSummary(id: String): TransactionSummary
    suspend fun getTransactionStats(filters: QueryFilterBuilder): TransactionStats
    suspend fun getTransactionCycles(filters: QueryFilterBuilder): TransactionCycleListResponse

    // Transações pendentes
    suspend fun getPendingTransactionsCount(): Int
    fun resolvePendingTransactions()
    fun cancelPendingTransactionsWorker()

    // Cartão
    suspend fun waitForCard(waitContact: Boolean, waitMagneticStripe: Boolean, waitContactless: Boolean, timeoutSeconds: Int): CardReadType?
    suspend fun removeCard()

    // Impressão
    fun print(text: String)
    fun printText(text: String, attributes: PrintAttributes, notifyComplete: Boolean = true)
    fun printColumns(texts: List<String>, attributes: List<PrintAttributes>, notifyComplete: Boolean = true)
    fun printImage(source: Any, width: Int, height: Int)
    fun printImage(source: Any, width: Int, height: Int, attributes: PrintAttributes, notifyComplete: Boolean = true)
    fun printBitmap(bitmap: Bitmap, notifyComplete: Boolean = true)
    fun printQrCode(payload: String, align: Align = Align.CENTER, sizePx: Int = 200, notifyComplete: Boolean = true)
    fun feedPaper(lines: Int, notifyComplete: Boolean = true)
    fun feedStep(steps: Int, notifyComplete: Boolean = true)

    // Tela secundária (OCTA 400)
    fun hasSecondaryDisplay(): Boolean
    fun getSecondaryDisplayResolution(): IntArray
    fun initSecondaryDisplay()
    fun setSecondaryDisplayPower(on: Boolean): Boolean
    fun setSecondaryDisplayBrightness(percent: Int): Boolean
    fun showOnSecondaryDisplay(source: Any)
    fun showMessageOnSecondaryDisplay(message: String)
    fun showQrCodeOnSecondaryDisplay(bitmap: Bitmap)
    fun showVideoOnSecondaryDisplay(filePath: String): Boolean
    fun showViewOnSecondaryDisplay(view: View)
    fun clearSecondaryDisplay()
    fun releaseSecondaryDisplay()

    // Usuários locais
    val localUsers: LocalUserManager

    companion object {
        fun create(context: Context, posPinpadCallback: PosPinpadCallback, mtlsCertificate: MtlsCertificate? = null): PosPinpad
    }
}

// Extensões (pacote com.tupifintech.apossdk.sdk.api)
fun PosPinpad.setCardReadTimeouts(timeouts: CardReadTimeouts)
fun PosPinpad.setEndpointProvider(endpointProvider: EndpointProvider)
fun PosPinpad.Companion.createFake(context: Context, posPinpadCallback: PosPinpadCallback): PosPinpad // só no artefato debug-staging

Criação da instância

companion object {
    fun create(context: Context, posPinpadCallback: PosPinpadCallback, mtlsCertificate: MtlsCertificate? = null): PosPinpad
}

Inicializa o HttpClient (mTLS) e retorna a instância pronta. Sempre use este método e mantenha uma única instância por processo.

val posPinpad = PosPinpad.create(context, callback)

Parâmetro	Descrição
context	Contexto do app
posPinpadCallback	Implementação de PosPinpadCallback
mtlsCertificate	Opcional. Sobrescreve o certificado mTLS embutido no SDK. Veja Configuração

PosPinpad.createFake(context, callback), disponível apenas no artefato apossdk-debug-staging, cria um POS simulado para testes sem hardware. É uma extensão: importe com.tupifintech.apossdk.sdk.api.createFake. Veja Exemplos.

Configuração e Inicialização

Os métodos de configuração e inicialização (getTerminalConfig, register, authenticate, terminalInitialization, logout, isTerminalInitialized, getTablesInfo) estão documentados na seção de Configuração:

• Personalização do Parceiro — getTerminalConfig()
• Registro do Terminal — register(), authenticate(), logout()
• Inicialização do Terminal — terminalInitialization(), isTerminalInitialized(), getTablesInfo()

Tempo de espera do cartão (setCardReadTimeouts), endpoints, usuários locais (localUsers) e metadados estão em Configuração.

Dispositivo, Chaves e Diagnóstico

fun getDeviceInfo(): DeviceInfo                 // lança IllegalStateException enquanto o pinpad não conectou
fun getTerminalTid(): String?                   // TID do adquirente, o mesmo impresso no comprovante
fun getConfiguredAcquirers(): List<String>      // o primeiro é o padrão; vazio sem inicialização
fun hasAcquirerKeys(acquirerName: String): Boolean // nome como a carga declara, sem diferenciar maiúsculas
fun hasDukptKey(index: Int): Boolean            // true se getDUKPT(index) e getDUKPTData(index) OK
@Deprecated fun hasPagSeguroKeys(): Boolean     // use hasAcquirerKeys("pagseguro")
suspend fun getSimInfo(): SimInfo?              // ICCID, operadora e transporte ativo; null se o serviço não responder
suspend fun checkInternetConnection(): HealthCheckResult

Transações Pendentes

Confirmações e desfazimentos não entregues ficam numa fila e são reenviados automaticamente.

suspend fun getPendingTransactionsCount(): Int // zero é o normal
fun resolvePendingTransactions()               // reenvia imediatamente
fun cancelPendingTransactionsWorker()          // suspende o reenvio automático (diagnóstico)

Veja Configuração — Transações Pendentes.