<commit_before>---
layout: post
title: Visão geral sobre a integração web
categories: [integração, ecommerce]
tags: [web, ecommerce, stone]
fullview: true
---

## Integração web e e-commerce

O processo de compra em uma loja virtual começa sempre com o cliente consumidor escolhendo um ou mais produtos, adicionando-os ao carrinho, fazendo revisão, até chegar ao pagamento por aqueles produtos. O cliente consumidor é sempre o ponto de partida de qualquer integração web com sistemas de pagamento. Independentemente de ser um pagamento com recorrência, compra com um clique, autorização ou, até mesmo, uma captura futura, sempre haverá o participante cliente consumidor tomando a decisão por adquirir um produto ou serviço.

Uma vez tomada a decisão, por parte do cliente consumidor, por efetuar o pagamento através de cartão de crédito, débito, voucher, etc, dois novos participantes iniciam uma comunicação através de trocas de mensagens, para autorizar a transação e fazer sua captura.

1. Adquirente
2. Banco emissor do cartão

Adquirente é a empresa responsável por fazer a comunicação com o banco emissor. Cada banco emissor possui seu próprio fluxo, meio de comunicação, tecnologia de segurança, protocolo, etc. Quando uma loja virtual faz a integração através de um adquirente, está se beneficiando de todo um investimento em tecnologias e segurança, além de um mecanismo único para se comunicar com o banco emissor, independentemente da tecnologia utilizada pelo banco.

Se a loja virtual precisasse aceitar pagamentos através de três bandeiras de cartão de crédito diferentes, três processos de integração diferentes seriam necessários. Como o adquirente já fez esse investimento no processo de integração, o custo de integração través adquirente é muito menor para a loja, do que seria se a integração fosse feita diretamente com as bandeiras.

## Fluxo de comunicação

Toda a comunicação começa com o cliente consumidor, portador do cartão, optando por fazer o pagamento com um cartão aceito pela loja virtual. A loja virtual, por sua vez, envia uma mensagem para o adquirente, solicitando o processamento do pagamento. Assim como ocorre com pagamentos em maquinetas, o cliente precisará informar seus dados de autenticação e o pagamento poderá ser autorizado ou negado pelo adquirente, seja por informações incorretas, ou algum eventual problema.

![fluxo](/assets/media/fluxo.png)

## Protocolo

Durante o fluxo de comunicação, algumas mensagens serão enviadas a partir da loja online, para o Adquirente. Essas mensagens são enviadas no formato XML através do protocolo HTTP, utilizando a arquitetura REST. Essa arquitetura permite que representações da transação possam ser enviadas ou recebidas pela loja online, segundo seu estado atual.

Por exemplo, para criar uma autorização, a loja deverá enviar uma mensagem [AcceptorAuthorisationRequest](#) para o adquirente, que irá checar com o banco emissor se o cliente consumidor possui recursos para financiar o pagamento. Nessa mensagem, além dos dados de credenciamento da loja, a loja enviará os dados do dono do cartão e os dados da transação, como valor total, número de parcelas, etc.

## Mensagens

Todas as mensagens serão enviadas através do protocolo HTTP. Para o ambiente de produção, as mensagens deverão ser enviadas utilizando o método **POST** para [http://pos.stone.com.br:3989](http://pos.stone.com.br:3989). O endpoint de testes será liberado e definido de acordo com cada integrador.

### Mensagens de Autorização

É o processo de troca de mensagens entre o estabelecimento e o adquirente onde é verificado se portador do cartão possui ou não saldo suficiente para a realização de um pagamento. A diferença entre a mensagem de autorização com captura automática e com captura posterior, está no elemento `TxCaptr` que deve ser informado `true` para Autorização com Captura, ou `false` para Autorização com Captura posterior.

#### XML de requisição comentado

    <Document xmlns="urn:AcceptorAuthorisationRequestV02.1">
        <!-- A mensagem de AcceptorAuthorisationRequest é enviada pelo estabelecimento para o
             adquirente, para checar junto ao banco que a conta associada ao cartão possui
             recursos para financiar o pagamento. Este controle inclui a validação dos dados
             do cartão e todos os dados adicionais previstos. -->
        <AccptrAuthstnReq>
            <!-- Cabeçalho da requisição -->
            <Hdr>
                <!-- Identifica o tipo de processo em
                     que a mensagem se propõe.
                     Valor Fixo: “AUTQ” = AuthorisationRequest. -->
                <MsgFctn>AUTQ</MsgFctn>
                <!-- Versão do protocolo utilizado na mensagem. -->
                <PrtcolVrsn>2.0</PrtcolVrsn>
            </Hdr>
            <!-- Dados da requisição de autorização. -->
            <AuthstnReq>
                <!-- Ambiente da transação. -->
                <Envt>
                    <!-- Dados do estabelecimento. -->
                    <Mrchnt>
                        <!-- Identificação do estabelecimento. -->
                        <Id>
                            <!-- Identificação do estabelecimento comercial no adquirente.
                                 Também conhecido internamente como “SaleAffiliationKey”. -->
                            <Id>BFDB58AB9A8A48828C2647E18B7F1114</Id>
                        </Id>
                    </Mrchnt>
                    <!-- Dados do ponto de interação -->
                    <POI>
                        <!-- Identificação do ponto de interação -->
                        <Id>
                            <!-- Código de identificação do ponto de interação
                                 atribuído pelo estabelecimento. -->
                            <Id>2FB4C89A</Id>
                        </Id>
                        <!-- Capacidades do Ponto de interação. -->
                        <Cpblties>
                            <!-- Número máximo de colunas de cada linha a ser impressa
                                 no cupom. A quantidade mínima de colunas é de 38.
                                 Se o POI enviar menos do que 38, o Host Stone não irá
                                 retornar os dados do recibo. -->
                            <PrtLineWidth>50</PrtLineWidth>
                        </Cpblties>
                    </POI>
                    <!-- Dados do cartão utilizado na transação. -->
                    <Card>
                        <!-- Dados não criptografados do cartão utilizado na transação. -->
                        <PlainCardData>
                            <!-- Número do cartão. (Primary Account Number) -->
                            <PAN>4066559930861909</PAN>
                            <!-- Data de validade do cartão no formato “yyyy-MM”. -->
                            <XpryDt>2017-10</XpryDt>
                        </PlainCardData>
                    </Card>
                </Envt>
                <!-- Informações da transação a ser realizada. -->
                <Cntxt>
                    <!-- Informações sobre o pagamento. -->
                    <PmtCntxt>
                        <!-- Modo da entrada dos dados do cartão.
                             PHYS = Ecommerce ou Digitada; -->
                        <CardDataNtryMd>PHYS</CardDataNtryMd>
                        <!-- Tipo do canal de comunicação utilizado na transação.
                             ECOM = Ecommerce ou Digitada; -->
                        <TxChanl>ECOM</TxChanl>
                    </PmtCntxt>
                </Cntxt>
                <!-- Informações da transação. -->
                <Tx>
                    <!-- Identificação da transação definida pelo sistema que se
                         comunica com o Host Stone. -->
                    <InitrTxId>123123123</InitrTxId>
                    <!-- Indica se os dados da transação devem ser capturados (true)
                         ou não (false) imediatamente. -->
                    <TxCaptr>false</TxCaptr>
                    <!-- Dados de identificação da transação atribuída pelo
                         POI (Ponto de interação). -->
                    <TxId>
                        <!-- Data local e hora da transação atribuídas pelo
                             POI (ponto de interação). -->
                        <TxDtTm>2014-03-12T15:11:06</TxDtTm>
                        <!-- Identificação da transação definida pelo ponto de interação (POI,
                             estabelecimento, lojista, etc). O formato é livre contendo no
                             máximo 32 caracteres. -->
                        <TxRef>06064f516a50483da7f189243c95ccca</TxRef>
                    </TxId>
                    <!-- Detalhes da transação. -->
                    <TxDtls>
                        <!-- Moeda utilizada na transação em conformidade com a ISO 4217.
                             986 = BRL = Real Brasileiro
                             http://pt.wikipedia.org/wiki/ISO_4217 -->
                        <Ccy>986</Ccy>
                        <!-- Valor total da transação em centavos. -->
                        <TtlAmt>100</TtlAmt>
                        <!-- Modalidade do cartão utilizado na transação.
                             CHCK = Débito;
                             CRDT = Crédito. -->
                        <AcctTp>CRDT</AcctTp>
                        <!-- Os dados relativos à(s) parcela(s) ou a uma transação recorrente. -->
                        <RcrngTx>
                            <!-- Tipo de parcelamento.
                                 NONE = Nenhum,
                                 MCHT = Lojista -->
                            <InstlmtTp>NONE</InstlmtTp>
                            <!-- Número do total de parcelas. -->
                            <TtlNbOfPmts>0</TtlNbOfPmts>
                        </RcrngTx>
                    </TxDtls>
                </Tx>
            </AuthstnReq>
        </AccptrAuthstnReq>
    </Document>

#### Exemplo de resposta

    <Document xmlns="urn:AcceptorAuthorisationResponseV02.1">
        <!-- A mensagem AcceptorAuthorisationResponse é enviada pelo adquirente, para retornar
             o resultado da validação realizada pelo emissor sobre a operação de pagamento. -->
        <AccptrAuthstnRspn>
            <!-- Cabeçalho da mensagem -->
            <Hdr>
                <!-- Identifica o tipo de processo em que a mensagem se propõe.
                     AUTP = AuthorisationResponse. -->
                <MsgFctn>AUTP</MsgFctn>
                <!-- Versão do protocolo utilizado na mensagem. -->
                <PrtcolVrsn>2.0</PrtcolVrsn>
                <!-- Dados para rastreamento da mensagem. -->
                <Tracblt>
                    <!-- Data e hora da saída da mensagem no Host Stone. -->
                    <TracDtTmOut>2014-03-12T18:10:58</TracDtTmOut>
                </Tracblt>
            </Hdr>
            <!-- Informações relacionadas à resposta da autorização. -->
            <AuthstnRspn>
                <!-- Ambiente da transação. -->
                <Envt>
                    <!-- Dados do estabelecimento. -->
                    <MrchntId>
                        <!-- dentificação do estabelecimento comercial no adquirente. Também
                             conhecido internamente como “SaleAffiliationKey”. -->
                        <Id>BFDB58AB9A8A48828C2647E18B7F1114</Id>
                    </MrchntId><commit_msg>Ajustando título<commit_after>---
layout: post
title: Visão geral sobre a integração web
categories: [integração, ecommerce]
tags: [web, ecommerce, stone]
fullview: true
---

## Integração web e e-commerce

O processo de compra em uma loja virtual começa sempre com o cliente consumidor escolhendo um ou mais produtos, adicionando-os ao carrinho, fazendo revisão, até chegar ao pagamento por aqueles produtos. O cliente consumidor é sempre o ponto de partida de qualquer integração web com sistemas de pagamento. Independentemente de ser um pagamento com recorrência, compra com um clique, autorização ou, até mesmo, uma captura futura, sempre haverá o participante cliente consumidor tomando a decisão por adquirir um produto ou serviço.

Uma vez tomada a decisão, por parte do cliente consumidor, por efetuar o pagamento através de cartão de crédito, débito, voucher, etc, dois novos participantes iniciam uma comunicação através de trocas de mensagens, para autorizar a transação e fazer sua captura.

1. Adquirente
2. Banco emissor do cartão

Adquirente é a empresa responsável por fazer a comunicação com o banco emissor. Cada banco emissor possui seu próprio fluxo, meio de comunicação, tecnologia de segurança, protocolo, etc. Quando uma loja virtual faz a integração através de um adquirente, está se beneficiando de todo um investimento em tecnologias e segurança, além de um mecanismo único para se comunicar com o banco emissor, independentemente da tecnologia utilizada pelo banco.

Se a loja virtual precisasse aceitar pagamentos através de três bandeiras de cartão de crédito diferentes, três processos de integração diferentes seriam necessários. Como o adquirente já fez esse investimento no processo de integração, o custo de integração través adquirente é muito menor para a loja, do que seria se a integração fosse feita diretamente com as bandeiras.

## Fluxo de comunicação

Toda a comunicação começa com o cliente consumidor, portador do cartão, optando por fazer o pagamento com um cartão aceito pela loja virtual. A loja virtual, por sua vez, envia uma mensagem para o adquirente, solicitando o processamento do pagamento. Assim como ocorre com pagamentos em maquinetas, o cliente precisará informar seus dados de autenticação e o pagamento poderá ser autorizado ou negado pelo adquirente, seja por informações incorretas, ou algum eventual problema.

![fluxo](/assets/media/fluxo.png)

## Protocolo

Durante o fluxo de comunicação, algumas mensagens serão enviadas a partir da loja online, para o Adquirente. Essas mensagens são enviadas no formato XML através do protocolo HTTP, utilizando a arquitetura REST. Essa arquitetura permite que representações da transação possam ser enviadas ou recebidas pela loja online, segundo seu estado atual.

Por exemplo, para criar uma autorização, a loja deverá enviar uma mensagem [AcceptorAuthorisationRequest](#) para o adquirente, que irá checar com o banco emissor se o cliente consumidor possui recursos para financiar o pagamento. Nessa mensagem, além dos dados de credenciamento da loja, a loja enviará os dados do dono do cartão e os dados da transação, como valor total, número de parcelas, etc.

## Mensagens

Todas as mensagens serão enviadas através do protocolo HTTP. Para o ambiente de produção, as mensagens deverão ser enviadas utilizando o método **POST** para [http://pos.stone.com.br:3989](http://pos.stone.com.br:3989). O endpoint de testes será liberado e definido de acordo com cada integrador.

### Mensagens de Autorização

É o processo de troca de mensagens entre o estabelecimento e o adquirente onde é verificado se portador do cartão possui ou não saldo suficiente para a realização de um pagamento. A diferença entre a mensagem de autorização com captura automática e com captura posterior, está no elemento `TxCaptr` que deve ser informado `true` para Autorização com Captura, ou `false` para Autorização com Captura posterior.

#### XML de requisição comentado

    <Document xmlns="urn:AcceptorAuthorisationRequestV02.1">
        <!-- A mensagem de AcceptorAuthorisationRequest é enviada pelo estabelecimento para o
             adquirente, para checar junto ao banco que a conta associada ao cartão possui
             recursos para financiar o pagamento. Este controle inclui a validação dos dados
             do cartão e todos os dados adicionais previstos. -->
        <AccptrAuthstnReq>
            <!-- Cabeçalho da requisição -->
            <Hdr>
                <!-- Identifica o tipo de processo em
                     que a mensagem se propõe.
                     Valor Fixo: “AUTQ” = AuthorisationRequest. -->
                <MsgFctn>AUTQ</MsgFctn>
                <!-- Versão do protocolo utilizado na mensagem. -->
                <PrtcolVrsn>2.0</PrtcolVrsn>
            </Hdr>
            <!-- Dados da requisição de autorização. -->
            <AuthstnReq>
                <!-- Ambiente da transação. -->
                <Envt>
                    <!-- Dados do estabelecimento. -->
                    <Mrchnt>
                        <!-- Identificação do estabelecimento. -->
                        <Id>
                            <!-- Identificação do estabelecimento comercial no adquirente.
                                 Também conhecido internamente como “SaleAffiliationKey”. -->
                            <Id>BFDB58AB9A8A48828C2647E18B7F1114</Id>
                        </Id>
                    </Mrchnt>
                    <!-- Dados do ponto de interação -->
                    <POI>
                        <!-- Identificação do ponto de interação -->
                        <Id>
                            <!-- Código de identificação do ponto de interação
                                 atribuído pelo estabelecimento. -->
                            <Id>2FB4C89A</Id>
                        </Id>
                        <!-- Capacidades do Ponto de interação. -->
                        <Cpblties>
                            <!-- Número máximo de colunas de cada linha a ser impressa
                                 no cupom. A quantidade mínima de colunas é de 38.
                                 Se o POI enviar menos do que 38, o Host Stone não irá
                                 retornar os dados do recibo. -->
                            <PrtLineWidth>50</PrtLineWidth>
                        </Cpblties>
                    </POI>
                    <!-- Dados do cartão utilizado na transação. -->
                    <Card>
                        <!-- Dados não criptografados do cartão utilizado na transação. -->
                        <PlainCardData>
                            <!-- Número do cartão. (Primary Account Number) -->
                            <PAN>4066559930861909</PAN>
                            <!-- Data de validade do cartão no formato “yyyy-MM”. -->
                            <XpryDt>2017-10</XpryDt>
                        </PlainCardData>
                    </Card>
                </Envt>
                <!-- Informações da transação a ser realizada. -->
                <Cntxt>
                    <!-- Informações sobre o pagamento. -->
                    <PmtCntxt>
                        <!-- Modo da entrada dos dados do cartão.
                             PHYS = Ecommerce ou Digitada; -->
                        <CardDataNtryMd>PHYS</CardDataNtryMd>
                        <!-- Tipo do canal de comunicação utilizado na transação.
                             ECOM = Ecommerce ou Digitada; -->
                        <TxChanl>ECOM</TxChanl>
                    </PmtCntxt>
                </Cntxt>
                <!-- Informações da transação. -->
                <Tx>
                    <!-- Identificação da transação definida pelo sistema que se
                         comunica com o Host Stone. -->
                    <InitrTxId>123123123</InitrTxId>
                    <!-- Indica se os dados da transação devem ser capturados (true)
                         ou não (false) imediatamente. -->
                    <TxCaptr>false</TxCaptr>
                    <!-- Dados de identificação da transação atribuída pelo
                         POI (Ponto de interação). -->
                    <TxId>
                        <!-- Data local e hora da transação atribuídas pelo
                             POI (ponto de interação). -->
                        <TxDtTm>2014-03-12T15:11:06</TxDtTm>
                        <!-- Identificação da transação definida pelo ponto de interação (POI,
                             estabelecimento, lojista, etc). O formato é livre contendo no
                             máximo 32 caracteres. -->
                        <TxRef>06064f516a50483da7f189243c95ccca</TxRef>
                    </TxId>
                    <!-- Detalhes da transação. -->
                    <TxDtls>
                        <!-- Moeda utilizada na transação em conformidade com a ISO 4217.
                             986 = BRL = Real Brasileiro
                             http://pt.wikipedia.org/wiki/ISO_4217 -->
                        <Ccy>986</Ccy>
                        <!-- Valor total da transação em centavos. -->
                        <TtlAmt>100</TtlAmt>
                        <!-- Modalidade do cartão utilizado na transação.
                             CHCK = Débito;
                             CRDT = Crédito. -->
                        <AcctTp>CRDT</AcctTp>
                        <!-- Os dados relativos à(s) parcela(s) ou a uma transação recorrente. -->
                        <RcrngTx>
                            <!-- Tipo de parcelamento.
                                 NONE = Nenhum,
                                 MCHT = Lojista -->
                            <InstlmtTp>NONE</InstlmtTp>
                            <!-- Número do total de parcelas. -->
                            <TtlNbOfPmts>0</TtlNbOfPmts>
                        </RcrngTx>
                    </TxDtls>
                </Tx>
            </AuthstnReq>
        </AccptrAuthstnReq>
    </Document>

#### XML de resposta comentado

    <Document xmlns="urn:AcceptorAuthorisationResponseV02.1">
        <!-- A mensagem AcceptorAuthorisationResponse é enviada pelo adquirente, para retornar
             o resultado da validação realizada pelo emissor sobre a operação de pagamento. -->
        <AccptrAuthstnRspn>
            <!-- Cabeçalho da mensagem -->
            <Hdr>
                <!-- Identifica o tipo de processo em que a mensagem se propõe.
                     AUTP = AuthorisationResponse. -->
                <MsgFctn>AUTP</MsgFctn>
                <!-- Versão do protocolo utilizado na mensagem. -->
                <PrtcolVrsn>2.0</PrtcolVrsn>
                <!-- Dados para rastreamento da mensagem. -->
                <Tracblt>
                    <!-- Data e hora da saída da mensagem no Host Stone. -->
                    <TracDtTmOut>2014-03-12T18:10:58</TracDtTmOut>
                </Tracblt>
            </Hdr>
            <!-- Informações relacionadas à resposta da autorização. -->
            <AuthstnRspn>
                <!-- Ambiente da transação. -->
                <Envt>
                    <!-- Dados do estabelecimento. -->
                    <MrchntId>
                        <!-- dentificação do estabelecimento comercial no adquirente. Também
                             conhecido internamente como “SaleAffiliationKey”. -->
                        <Id>BFDB58AB9A8A48828C2647E18B7F1114</Id>
                    </MrchntId>
{'fraction_non_alphanumeric': 0.07102235728239635, 'fraction_numerical': 0.014846971999131755, 'mean_word_length': 1.57817571348629, 'pattern_counts': {'":': 0, '<': 273, '<?xml version=': 0, '>': 273, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 18, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2951810', 'n_tokens_mistral': 6678, 'n_tokens_neox': 6286, 'n_words': 2163}