Objetivo

Utilizar para autênticações dos parceiro em vendas na forma de pagamento convênio.

No momento em que for solicitada a senha do convêniado, se estiver configurado para validar via integração externa, irá enviar ao parceiro informações para que ele valide ou não um código (token) do cliente para que ele digite e finalize a venda

Exemplos : Quando houve a necessidade de validar um token no pinpad.

Veja abaixo exemplo de configuração dos parâmetros : 

Lista de formas de pagamento : Iremos configurar uma lista de formas de pagamento que poderá ser validado e autenticado pelo parceiro.

Obter o valor no pinpad: A solicitação irá ser encaminhada para o cliente informar o valor no Pinpad.

URL :  Parceiro irá informar o caminho do seu servidor webservice para receber do PDV as solicitações e valores.

Formato dos arquivos JSON de Requisição e Resposta

Informações para Requisição (Request Information)

Parâmetros do Corpo (Body Parameters)

PARÂMETRO

TIPO

OBRIGATÓRIO

DESCRIÇÃO

AuthenticatorObject JsonSim

Grupo com os dados para autenticação

Authenticator.HeaderObject JsonSim

Grupo com os dados do cabeçalho

Authenticator.Header.DescriptionStringSim

Descrição da rotina a ser liberada

Authenticator.Header.IdStoreIntegerSim

Código da loja

Authenticator.Header.IdTerminalIntegerSim

Código do PDV

Authenticator.Header.IdUserIntegerSim

Código do usuário (operador de caixa)

Authenticator.Header.MethodStringSim

Rotina a ser liberada

Authenticator.Header.M

ethodStatus

StringSim

Status da liberação da rotina solicitada. Legenda:

arNone: envio da requisição (inicialização);

arPending: requisição pendente;

arAuthorized: requisição autorizada pelo fiscal de caixa;

arNotAuthorized: requisição negada pelo fiscal de caixa;

arCanceled: requisição cancelada (API fora do ar, timeout, usuário cancelou a solicitação, tempo limite atingido, etc).

Authenticator.Header.MethodTitleStringSim

Título da rotina a ser liberada

Authenticator.SaleObject JsonSim

Grupo com os dados da venda

Authenticator.Sale.AccountingDateDateSim

Data do documento ou, quando não existir, da transação

Authenticator.Sale.DateTimeIssueDateSim

Data e hora da requisição

Authenticator.Sale.IdDocumentIntegerSim

Código do documento

Authenticator.Sale.ItemsArray object JsonNão

Lista de produto(s) da venda

Authenticator.Sale.Items[0].DescriptionStringSim

Descrição do produto

Authenticator.Sale.Items[0].InternalCodeIntegerSim

Código interno do produto

Authenticator.Sale.Items[0].ItemNumberIntegerSim

Código de sequência do produto

Authenticator.Sale.CooDocumentIntegerNão

Código do documento da venda

Authenticator.Sale.DocumentIntegerNão

Códigos interno da venda (seqdocto)

Authenticator.Sale.IdentificationTypeStringNão

Tipo de identificação

Authenticator.Sale.DocumentTypeStringNão

CPF ou CNPJ do cliente informado

Authenticator.Sale.AgreementNumberIntegerNão

Nº do convênio/forma  de pagamento

Authenticator.Sale.AgreedNumberIntegerNão

Código do cliente (Seqpessoa)

Authenticator.Sale.TotalSaleDoubleNão

Total da venda

Authenticator.Sale.TotalPayDoubleNão

Valor do pagamento

EventStringSim

Tipo de evento da API

ExecutionStringSim

Status da execução

IDStringSim

ID da transação (que será consultando depois no evento GET)

OperationStringSim

Operação que está sendo enviada ("cotAuthenticador" para este evento POST)

ResponseStringNão

Valor retornado pelo PDV.

Este é o valor de retorno digitado lá no pdv pelo cliente

VersionIntegerSim

Número da versão

Formatos de Requisição (Request Formats)

application/json

Exemplo (Sample)

{
    "Authenticator": {
        "Header": {
            "Description": "Autenticacao",
            "IdStore": 1,
            "IdTerminal": 222,
            "IdUser": 2,
            "Method": "mtFinalizadoraConvenio",
            "MethodStatus": "arPending",
            "MethodTitle": "Autenticacao"
        },
        "Sale": {
            "AccountingDate": "2024-01-23T00:00:00",
            "AgreedNumber": 138789,
            "AgreementNumber": 252,
            "CooDocument": 27,
            "DateTimeIssue": "2024-01-23T14:34:01",
            "Document": "97107967000109",
            "DocumentType": "cdtCNPJ",
            "IdDocument": 11071962,
            "IdentificationType": "citReward",
            "Items": [
            ],
            "TotalPay": 1.0000000000000000E+001,
            "TotalSale": 1.0000000000000000E+001
        }
    },
    "Event": "cetAfter",
    "Execution": "cetContinue",
    "ID": "00122220240123143401",
    "Operation": "cotAuthenticator",
    "Response": "",
    "Version": 1
}


Formatos de Response(Response Formats) para obter valor, no caso do exemplo um Token

application/json

Exemplo (Sample)

{

    "version": 1,
    "sale": null,
    "pay": null,
    "return": {
        "code": 0
    },
    "execution": "cetContinue",
    "interpret": {
        "commandType": "cctGetValue",
        "messageCommand": null,
        "options": null,
        "value": {
            "title": "Cliente fidelidade",
            "subtitle": "Informe o Token",
            "dataType": "cvtToken",
            "size": 0,
            "documentTypes": [
            ]
        },
        "pay": null
    },
    "vouchersPrint": [
    ]
}

Exemplo da venda no convênio : 

1º - Passo :  

2º - Passo :  Informa o convêniado : 

Identifica o convêniado : 

Neste momento, iria ser apresentada a tela de senha para o cliente informar, mas se o parãmetro (Obter o valor no pinpad) tiver habilitado irá apresentar o retorno do parceiro para validar um token.


Se o parâmetro para obter no pinpad estiver ativo, mensagem irá para o PINPAD para solicitar a digitação.

Após digitar o valor e teclar ENTER, o sistema enviará para o parceiro o JSON com a resposta do que foi digitado pelo cliente.

Requisição do Exemplo (Request) com a resposta do que foi digitado :

{
    "Authenticator": {
        "Header": {
            "Description": "Autenticacao",
            "IdStore": 1,
            "IdTerminal": 222,
            "IdUser": 2,
            "Method": "mtFinalizadoraConvenio",
            "MethodStatus": "arPending",
            "MethodTitle": "Autenticacao"
        },
        "Sale": {
            "AccountingDate": "2024-01-23T00:00:00",
            "AgreedNumber": 138789,
            "AgreementNumber": 252,
            "CooDocument": 27,
            "DateTimeIssue": "2024-01-23T14:34:01",
            "Document": "97107967000109",
            "DocumentType": "cdtCNPJ",
            "IdDocument": 11071962,
            "IdentificationType": "citReward",
            "Items": [
            ],
            "TotalPay": 1.0000000000000000E+001,
            "TotalSale": 1.0000000000000000E+001
        }
    },
    "Event": "cetAfter",
    "Execution": "cetContinue",
    "ID": "00122220240123143401",
    "Operation": "cotAuthenticator",
    "Response": "151516",
    "Version": 1
}


Parceiro trata o retorno e finaliza com um response se estiver de acordo com a venda.

Response do Exemplo (Response) com a resposta cetCompleted:

{

    "version": 1,
    "sale": null,
    "pay": null,
    "return": {
        "code": 0,
        "messageText": "0"
    },
    "execution": "cetCompleted",
    "interpret": null,
    "vouchersPrint": [
    ]
}