Contrato do backend
Os três endpoints que o SDK SoftPOS consome do backend Eagle, e como substituir o cliente HTTP por uma implementação própria
Em construção
O SDK conversa com o backend Eagle por três chamadas. Você não precisa implementá-las —
HttpEagleBackend já faz isso — mas conhecer o contrato ajuda a diagnosticar falhas e é
obrigatório se você for fornecer a sua própria implementação.
Autenticação
Todas as chamadas levam a apiKey do tenant:
Authorization: Bearer <apiKey>Credencial ausente ou inválida responde 401, que o SDK converte em
EagleError.Backend(401, ...).
POST /v1/sellers/activate
Ativa o vendedor no modelo federado: o backend valida a credencial do tenant, valida o
sellerToken emitido pelo backend da empresa e provisiona o PDV.
Request
{ "sellerToken": "token-emitido-pelo-backend-da-empresa" }Response · 200
{
"sellerId": "seller-9f31ac",
"posId": "POS-9F31AC12",
"subEstablishmentRef": "SUB-POS-9F31AC12",
"tlsRegistered": true
}| Status | Significado |
|---|---|
200 | Vendedor ativado |
401 | Credencial de tenant ausente ou inválida |
422 | Erro de negócio (token inválido, vendedor recusado) |
GET /v1/transactions/config
Resolve a configuração da transação para um PDV, imediatamente antes da venda.
| Parâmetro | Em | Obrigatório | Descrição |
|---|---|---|---|
posId | query | sim | PDV devolvido na ativação |
Response · 200
{
"empresaSitef": "00000001",
"enderecoSitef": "sitef.exemplo.com.br:20036",
"cnpjCpf": "12345678000199",
"comExterna": "4",
"tokenRegistroTls": "…",
"cnpjAutomacao": "99999999000199",
"cnpjFacilitador": "88888888000199",
"branding": {
"logoUrl": "https://…/logo.png",
"primaryColor": "#22C55E",
"secondaryColor": "#0EA5E9"
}
}Esta resposta é de curta duração e não deve ser cacheada no aparelho. O SDK a usa para montar a Intent e a descarta ao fim da venda.
POST /v1/transactions
Relata o resultado da venda para histórico e observabilidade. O SDK envia essa chamada depois de interpretar o retorno do m-SiTef.
Request
{
"posId": "POS-9F31AC12",
"approved": true,
"codResp": 0,
"nsuSitef": "000123",
"nsuHost": "889977",
"cardBrand": "VISA",
"acquirerNetwork": "FISERV",
"authorizationCode": "A1B2C3",
"installments": 3,
"amountInCents": 5000,
"occurredAt": "2026-09-17T14:32:05.120Z"
}amountInCents e occurredAt não vêm do m-SiTef: o valor é decisão do app e o horário é o
da captura. Sem eles o backend receberia uma venda sem quantia.
| Status | Significado |
|---|---|
202 | Aceito para processamento |
401 | Credencial de tenant ausente ou inválida |
O relato é best-effort: se ele falhar, o SDK registra o erro no logger e ainda assim
devolve o SaleResult ao app — a venda já aconteceu no m-SiTef, e perder o relato não
pode significar perder o comprovante do portador. A verdade financeira vem da conciliação
server-side, não desta chamada.
Erros de negócio
{ "code": 422, "message": "sellerToken inválido" }O SDK transforma isso em EagleError.Backend(statusCode, detail).
Implementação própria
Se o seu app precisa falar com o backend por outro transporte (proxy corporativo,
autenticação adicional, mTLS), implemente EagleBackend e passe-o em EagleConfig:
interface EagleBackend {
suspend fun activateSeller(sellerToken: String): ActivationResult
suspend fun fetchTransactionConfig(posId: String): TransactionConfig
suspend fun reportTransaction(report: TransactionReport)
}Eagle.initialize(
context = applicationContext,
config = EagleConfig(
apiKey = apiKey,
environment = EagleEnvironment.PRODUCTION,
backend = MeuBackendCorporativo(),
),
)O fluxo de venda não muda: o SDK continua resolvendo config, disparando a Intent, interpretando o retorno e relatando. Só o transporte é seu.
Esse mesmo ponto de extensão é o que torna a venda testável sem aparelho: um backend falso em memória cobre o fluxo inteiro em teste unitário.