{"title":"Fundamentos da API de terminais","category":"default","creationDate":1560352500,"content":"<p>A API de terminais permite efetuar pagamentos, realizar reembolsos, coletar informa\u00e7\u00f5es do comprador e outras intera\u00e7\u00f5es cliente-terminal.<\/p>\n<div class=\"additional-info-block output-inline\">\n<div class=\"additional-info-block__body\"><p>Nossa API de terminais \u00e9 baseada no <a href=\"https:\/\/www.nexo-standards.org\/standards\/nexo-retailer-protocol\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">nexo Retailer Protocol<\/a>.<\/p><\/div><\/div>\n\n<p>Antes de efetuar qualquer pagamento no terminal, \u00e9 importante entender como nossa API de terminais funciona e como as solicita\u00e7\u00f5es e respostas s\u00e3o estruturadas.<\/p>\n<p>Aqui descreveremos:<\/p>\n<ul>\n<li>Os <a href=\"#endpoints-and-authentication\">endpoints e autentica\u00e7\u00e3o<\/a>.<\/li>\n<li>A <a href=\"#api-structure\">estrutura da API<\/a>.<\/li>\n<li>Como fazer <a href=\"#requests\">pedidos<\/a>.<\/li>\n<li>Como receber <a href=\"#responses\">respostas<\/a>.<\/li>\n<li>Como <a href=\"#notifications\">receber webhooks<\/a>.<\/li>\n<li>Como <a href=\"#handling-errors\">lidar com erros<\/a>.<\/li>\n<\/ul>\n<h2 id=\"endpoints-and-authentication\">Endpoints e autentica\u00e7\u00e3o<\/h2>\n<p>Os endpoits que voc\u00ea precisa usar e como voc\u00ea deve autenticar solicita\u00e7\u00f5es depende de como sua integra\u00e7\u00e3o se conecta \u00e0 plataforma de pagamentos Adyen:<\/p>\n<ul>\n<li><a href=\"#local\">Comunica\u00e7\u00f5es locais<\/a>.<\/li>\n<li><a href=\"#cloud\">Comunica\u00e7\u00f5es em nuvem<\/a>.<\/li>\n<\/ul>\n<h3 id=\"local\">Comunica\u00e7\u00f5es locais<\/h3>\n<p>Se sua integra\u00e7\u00e3o usa <a href=\"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\">comunica\u00e7\u00f5es locais<\/a>, <strong>todas<\/strong> as suas solicita\u00e7\u00f5es de API s\u00e3o feitas de uma caixa registradora diretamente no endere\u00e7o IP de um terminal. Como alternativa, se voc\u00ea atribuir um nome de host ao seu terminal, poder\u00e1 fazer solicita\u00e7\u00f5es ao nome do host terminal.<\/p>\n<p>O terminal recebe solicita\u00e7\u00f5es POST <code>\/nexo<\/code> na porta <strong>8443<\/strong>. Por exemplo, se o seu terminal tiver o endere\u00e7o IP <strong>198.51.100.1<\/strong> , voc\u00ea dever\u00e1 fazer solicita\u00e7\u00f5es de API para:  <code>https:\/\/198.51.100.1:8443\/nexo<\/code><\/p>\n<div class=\"notices yellow\">\n<p>Corrija o endere\u00e7o MAC de cada terminal para um endere\u00e7o IP est\u00e1tico. Isso ajuda a evitar problemas de conex\u00e3o quando o terminal ou sua rede \u00e9 reiniciada.<\/p>\n<\/div>\n<p>Para autenticar suas solicita\u00e7\u00f5es, voc\u00ea precisar\u00e1 <a href=\"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\/secure-local-communications\">adicionar o certificado da Adyen<\/a> \u00e0 sua caixa registradora e <a href=\"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\/secure-local-communications\">criptografar suas mensagens<\/a>.<\/p>\n<h3 id=\"cloud\">Comunica\u00e7\u00f5es na nuvem<\/h3>\n<p>Se sua integra\u00e7\u00e3o usa <a href=\"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/cloud\">comunica\u00e7\u00f5es em nuvem<\/a>, sua caixa registradora faz solicita\u00e7\u00f5es de API para a plataforma de pagamentos Adyen. Nossa plataforma encaminha a solicita\u00e7\u00e3o para o terminal.<\/p>\n<p>O terminal que voc\u00ea precisar\u00e1 usar depender\u00e1 de duas coisas:<\/p>\n<ul>\n<li>Se sua integra\u00e7\u00e3o receber\u00e1 resultados de transa\u00e7\u00e3o de forma s\u00edncrona ou ass\u00edncrona.<\/li>\n<li>Se voc\u00ea est\u00e1 fazendo transa\u00e7\u00f5es de teste ou transa\u00e7\u00f5es reais (live).<\/li>\n<\/ul>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\"><\/th>\n<th style=\"text-align: left;\">Test endpoints - para todas as transa\u00e7\u00f5es de teste<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">Resultado s\u00edncrono:<\/td>\n<td style=\"text-align: left;\"><code>https:\/\/terminal-api-test.adyen.com\/sync<\/code><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Resultado ass\u00edncrono:<\/td>\n<td style=\"text-align: left;\"><code>https:\/\/terminal-api-test.adyen.com\/async<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>Quando voc\u00ea estiver pronto para entrar no ar, precisar\u00e1 mudar para um endpoint de transa\u00e7\u00f5es reais (live) que esteja geograficamente mais pr\u00f3ximo do local da sua loja.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\"><\/th>\n<th style=\"text-align: left;\">Live endpoints  - Europa<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">Resultado s\u00edncrono:<\/td>\n<td style=\"text-align: left;\"><code>https:\/\/terminal-api-live.adyen.com\/sync<\/code><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Resultado ass\u00edncrono:<\/td>\n<td style=\"text-align: left;\"><code>https:\/\/terminal-api-live.adyen.com\/async<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\"><\/th>\n<th style=\"text-align: left;\">Live endpoints - Australia<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">Resultado s\u00edncrono:<\/td>\n<td style=\"text-align: left;\"><code>https:\/\/terminal-api-live-au.adyen.com\/sync<\/code><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Resultado ass\u00edncrono:<\/td>\n<td style=\"text-align: left;\"><code>https:\/\/terminal-api-live-au.adyen.com\/async<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\"><\/th>\n<th style=\"text-align: left;\">Live endpoints - USA<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">Resultado s\u00edncrono:<\/td>\n<td style=\"text-align: left;\"><code>https:\/\/terminal-api-live-us.adyen.com\/sync<\/code><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Resultado ass\u00edncrono:<\/td>\n<td style=\"text-align: left;\"><code>https:\/\/terminal-api-live-us.adyen.com\/async<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>Para autenticar suas solicita\u00e7\u00f5es, voc\u00ea precisar\u00e1 de uma chave da API da Adyen. Se voc\u00ea ainda n\u00e3o possuir uma chave de API, poder\u00e1 <a href=\"\/pt\/user-management\/how-to-get-the-api-key\/\">obt\u00ea-la aqui<\/a>. Voc\u00ea precisar\u00e1 incluir essa chave de API no cabe\u00e7alho de cada solicita\u00e7\u00e3o na API de terminais.<\/p>\n<div class=\"notices yellow\">\n<p>Adicione a chave da API ao cabe\u00e7alho usando: <strong>x-API-key<\/strong><\/p>\n<\/div>\n<h2>Estrutura da API<\/h2>\n<p>Nossa API de terminais se comunica com o terminal usando mensagens JSON. Todas as solicita\u00e7\u00f5es e respostas t\u00eam a seguinte estrutura de <strong>cabe\u00e7alho<\/strong>-<strong>corpo<\/strong>:<\/p>\n<ul>\n<li><strong>cabe\u00e7alho (header)<\/strong>: identifica o tipo de transa\u00e7\u00e3o, o terminal que est\u00e1 sendo usado e identificadores exclusivos de transa\u00e7\u00e3o.<\/li>\n<li><strong>corpo (body)<\/strong>: um objeto de solicita\u00e7\u00e3o ou resposta, dependendo do tipo de transa\u00e7\u00e3o. Por exemplo, quando voc\u00ea faz uma solicita\u00e7\u00e3o de pagamento, este \u00e9 um objeto <code>PaymentRequest<\/code> quando voc\u00ea recebe uma resposta de pagamento, \u00e9 um objeto <code>PaymentResponse<\/code>.<\/li>\n<\/ul>\n<p>O cabe\u00e7alho e o corpo das <a href=\"#api-responses\">respostas<\/a> e <a href=\"#api-requests\">solicita\u00e7\u00f5es<\/a> da API de terminais s\u00e3o descritos em mais detalhes abaixo.<\/p>\n<h2 id=\"requests\">Solicita\u00e7\u00f5es<\/h2>\n<p>Cada solicita\u00e7\u00e3o da API de terminais que voc\u00ea faz est\u00e1 contida em um objeto <code>SaletoPOIRequest<\/code> object. Neste, ser\u00e1 necess\u00e1rio fornecer um:<\/p>\n<ul>\n<li><a href=\"#request-message-header\">Objeto<code>MessageHeader<\/code><\/a>.<\/li>\n<li><a href=\"#request-body\">Objeto do corpo da solicita\u00e7\u00e3<\/a> correspondente ao tipo de transa\u00e7\u00e3o. Por exemplo, este \u00e9 um objeto <code>PaymentRequest<\/code> correspondente ao tipo de transa\u00e7\u00e3o. Por exemplo, este \u00e9 um objeto <code>InputRequest<\/code> quando est\u00e1 solicitando a entrada do comprador.<\/li>\n<\/ul>\n<h3 id=\"request-message-header\">Solicitar MessageHeader<\/h3>\n<p>Em cada solicita\u00e7\u00e3o <code>MessageHeader<\/code>, especifique o seguinte:<\/p>\n<table>\n<thead>\n<tr>\n<th>Nome<\/th>\n<th>Requerido<\/th>\n<th>Tipo<\/th>\n<th>Descri\u00e7\u00e3o<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>ProtocolVersion<\/code><\/td>\n<td>Sim<\/td>\n<td>String<\/td>\n<td><p>Vers\u00e3o da API do terminal da Adyen.<\/p> <p>A vers\u00e3o atual \u00e9 <strong>3.0<\/strong><\/p><\/td>\n<\/tr>\n<tr>\n<td><code>MessageClass<\/code><\/td>\n<td>Sim<\/td>\n<td>Enum<\/td>\n<td>Quase sempre \u00e9 <strong>Service<\/strong>, mas tamb\u00e9m pode ser <strong>Device<\/strong> ou <strong>Event<\/strong>. Vamos especificar qual <code>MessageClass<\/code> \u00e9 necess\u00e1rio ao longo da documenta\u00e7\u00e3o.<\/td>\n<\/tr>\n<tr>\n<td><code>MessageCategory<\/code><\/td>\n<td>Sim<\/td>\n<td>Enum<\/td>\n<td>O tipo de transa\u00e7\u00e3o. Por exemplo, <code>Payment<\/code> para uma solicita\u00e7\u00e3o de pagamento. Vamos especificar qual <code>MessageCategory<\/code> \u00e9 necess\u00e1rio ao longo da documenta\u00e7\u00e3o.<\/td>\n<\/tr>\n<tr>\n<td><code>MessageType<\/code><\/td>\n<td>Sim<\/td>\n<td>Enum<\/td>\n<td>Sempre \u00e9 <strong>Request<\/strong>.<\/td>\n<\/tr>\n<tr>\n<td><code>SaleID<\/code><\/td>\n<td>Sim<\/td>\n<td>String<\/td>\n<td>Seu ID exclusivo para sua caixa registradora.<\/td>\n<\/tr>\n<tr>\n<td><code>ServiceID<\/code><\/td>\n<td>Sim<\/td>\n<td>String<\/td>\n<td>Seu ID exclusivo para a tentativa de transa\u00e7\u00e3o, consistindo em 1 a 10 caracteres alfanum\u00e9ricos. Esse valor precisa ser exclusivo nas \u00faltimas 48 horas.<\/td>\n<\/tr>\n<tr>\n<td><code>POIID<\/code><\/td>\n<td>Sim<\/td>\n<td>String<\/td>\n<td><p>O ID exclusivo do terminal, no formato <em>[modelo do dispositivo]-[n\u00famero de s\u00e9rie]<\/em>. Por exemple, <strong>P400-123456789<\/strong>.<\/p><p>Voc\u00ea pode encontrar o <strong>modelo do dispositivo<\/strong> e o <strong>n\u00famero de s\u00e9rie<\/strong> de um terminal na sua <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>, em <strong>In-person payments<\/strong> &gt; <strong>Terminals<\/strong>. O <strong>n\u00famero de s\u00e9rie<\/strong> (ou <em>s\/n<\/em>) tamb\u00e9m \u00e9 impresso na parte inferior de cada terminal.<\/p><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>O exemplo abaixo mostra o cabe\u00e7alho que voc\u00ea forneceria se quisesse efetuar um pagamento.<\/p>\n<pre><code class=\"language-JSON\">{\n  \"SaleToPOIRequest\":{\n    \"MessageHeader\":{\n      \"ProtocolVersion\":\"3.0\",\n      \"MessageClass\":\"Service\",\n      \"MessageCategory\":\"Payment\",\n      \"MessageType\":\"Request\",\n      \"SaleID\":\"POSSystemID12345\",\n      \"ServiceID\":\"0207111104\",\n      \"POIID\":\"V400m-324688179\"\n    },\n    \"PaymentRequest\":{...}\n  }\n}<\/code><\/pre>\n<h3 id=\"request-body\">Corpo da solicita\u00e7\u00e3o<\/h3>\n<p>Os valores que voc\u00ea precisa incluir no corpo da solicita\u00e7\u00e3o dependem do tipo de transa\u00e7\u00e3o que voc\u00ea est\u00e1 fazendo. Fornecemos exemplos e informa\u00e7\u00f5es de refer\u00eancia para cada tipo de transa\u00e7\u00e3o em toda a documenta\u00e7\u00e3o dos terminais.<\/p>\n<h2 id=\"responses\">Respostas<\/h2>\n<p>Cada resposta da API do terminal que voc\u00ea recebe est\u00e1 contida em um objeto  <code>SaleToPOIResponse<\/code> e inclui um:<\/p>\n<ul>\n<li><a href=\"#response-message-header\">Objeto <code>MessageHeader<\/code><\/a>: reproduz os valores do <strong>MessageHeader<\/strong> que voc\u00ea forneceu na <a href=\"#request-message-header\">solicita\u00e7\u00e3o da API<\/a>.<\/li>\n<li><a href=\"#response-body\">Objeto do corpo da resposta<\/a>: corresponde ao tipo de solicita\u00e7\u00e3o de transa\u00e7\u00e3o que voc\u00ea fez.<br \/>\nPor exemplo, quando voc\u00ea faz um <code>PaymentRequest<\/code> voc\u00ea recebe um objeto <code>PaymentResponse<\/code>.<\/li>\n<\/ul>\n<div class=\"notices yellow\">\n<p>Se voc\u00ea estiver usando uma integra\u00e7\u00e3o em nuvem que receba resultados de forma ass\u00edncrona, voc\u00ea receber\u00e1 apenas uma resposta ok da API do terminal. O corpo e a resposta <code>MessageHeader<\/code> s\u00e3o enviados em uma <a href=\"#notifications\">notifica\u00e7\u00e3o de exibi\u00e7\u00e3o<\/a>.<\/p>\n<\/div>\n<h3 id=\"response-message-header\">Resposta MessageHeader<\/h3>\n<p>O <code>MessageHeader<\/code> que voc\u00ea recebe na resposta reproduzir\u00e1 os valores que voc\u00ea forneceu na solicita\u00e7\u00e3o. A \u00fanica exce\u00e7\u00e3o \u00e9 a <code>MessageType<\/code>, que ser\u00e1 uma <strong>Resposta<\/strong>.<\/p>\n<p>O exemplo a seguir mostra o cabe\u00e7alho que voc\u00ea receberia em resposta <a href=\"#request-message-header\">\u00e0 solicita\u00e7\u00e3o de pagamento do exemplo fornecido acima <\/a>.<\/p>\n<pre><code class=\"language-JSON\">{\n  \"SaleToPOIResponse\":{\n    \"MessageHeader\":{\n      \"ProtocolVersion\":\"3.0\",                  \/\/ Echoed from request\n      \"MessageClass\":\"Service\",                 \/\/ Echoed from request\n      \"MessageCategory\":\"Payment\",              \/\/ Echoed from request\n      \"MessageType\":\"Response\",                 \/\/ Response\n      \"SaleID\":\"POSSystemID12345\",              \/\/ Echoed from request\n      \"ServiceID\":\"0207111104\",                 \/\/ Echoed from request\n      \"POIID\":\"V400m-324688179\"                 \/\/ Echoed from request\n    },\n    \"PaymentResponse\":{...}                     \/\/ Response body object\n  }\n}<\/code><\/pre>\n<h3 id=\"response-body\">Corpo de resposta<\/h3>\n<p>Os valores que voc\u00ea recebe no corpo da resposta dependem do tipo de solicita\u00e7\u00e3o de transa\u00e7\u00e3o que voc\u00ea fez. Fornecemos exemplos e informa\u00e7\u00f5es de refer\u00eancia para cada tipo de transa\u00e7\u00e3o ao longo da documenta\u00e7\u00e3o dos terminais.<\/p>\n<p>O corpo da resposta geralmente inclui um <a href=\"#transaction-identifier\">identificador de transa\u00e7\u00e3o<\/a>, exclusivo e dados que voc\u00ea pode usar para <a href=\"#receipt-data\">gerar seus recibos<\/a>.<\/p>\n<h4 id=\"transaction-identifier\">Identificador de transa\u00e7\u00e3o<\/h4>\n<p>Toda solicita\u00e7\u00e3o de API que cria uma transa\u00e7\u00e3o ou interage com seu fluxo de dinheiro (como pagamento ou reembolso) retorna um identificador de transa\u00e7\u00e3o exclusivo no <code>POITransactionID.TransactionID<\/code>:<\/p>\n<p><img src=\"\/point-of-sale\/design-your-integration\/terminal-api\/ReferenceForOnline.png\" alt=\"\" \/><\/p>\n<p>Este identificador cont\u00e9m dois valores, separados por um ponto:<\/p>\n<ul>\n<li><strong>Refer\u00eancia tender<\/strong>: valor exclusivo gerado pelo terminal para a transa\u00e7\u00e3o.<\/li>\n<li><strong>Refer\u00eancia PSP<\/strong>: valor exclusivo gerado pela plataforma de pagamentos Adyen para a transa\u00e7\u00e3o.\n<div class=\"notices blue\">\n<p>Se voc\u00ea estiver usando a Adyen para <a href=\"\/pt\/online-payments\">pagamentos on-line<\/a> u com\u00e9rcio unificado, a <strong>Refer\u00eancia PSP<\/strong> ser\u00e1 o equivalente a <code>pspReference<\/code> que voc\u00ea recebe pelas transa\u00e7\u00f5es feitas on-line.<\/p>\n<\/div><\/li>\n<\/ul>\n<p>Voc\u00ea deve armazenar cada identificador de transa\u00e7\u00e3o que receber, voc\u00ea ir\u00e1 precisar deles para:<\/p>\n<ul>\n<li>Fazer um reembolso.<\/li>\n<li>Realizar um pagamento com os detalhes do cart\u00e3o adquirido.<\/li>\n<li>Identificar a transa\u00e7\u00e3o em sua <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>, ou nos <a href=\"\/pt\/reporting\">relat\u00f3rios<\/a> gerados pela Adyen.<\/li>\n<\/ul>\n<h4>Identificadores de transa\u00e7\u00e3o para pagamentos offline<\/h4>\n<p>Se sua integra\u00e7\u00e3o usar <a href=\"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/local\">comunica\u00e7\u00f5es locais<\/a>, seus terminais poder\u00e3o fazer transa\u00e7\u00f5es store-and-foward e EMV offline. Quando voc\u00ea tem um problema de rede, um pagamento <strong>Aprovado<\/strong> gera apenas um identificador de transa\u00e7\u00e3o com a refer\u00eancia Tender:<\/p>\n<p><img src=\"\/point-of-sale\/design-your-integration\/terminal-api\/ReferenceForOffline.png\" alt=\"\" \/><\/p>\n<p>Assim que o terminal puder se conectar \u00e0 Internet novamente, a plataforma de pagamentos da Adyen processar\u00e1 o pagamento e gerar\u00e1 uma refer\u00eancia PSP. A refer\u00eancia do PSP e a refer\u00eancia tender podem ser encontradas na sua <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>, e nos <a href=\"\/pt\/reporting\">relat\u00f3rios<\/a> gerados pela Adyen.<\/p>\n<h4 id=\"receipt-data\">Dados do recibo<\/h4>\n<p>Quando voc\u00ea faz uma transa\u00e7\u00e3o como um pagamento, o resultado do pagamento cont\u00e9m um objeto <code>PaymentReceipt<\/code>. Voc\u00ea pode adicionar os pares de valores-chave desse objeto ao recibo que voc\u00ea imprime, exibe em tela ou envia por e-mail ao seu cliente.<\/p>\n<p>Para mais informa\u00e7\u00f5es, consulte a nossa <a href=\"\/pt\/point-of-sale\/basic-tapi-integration\/generate-receipts\">documenta\u00e7\u00e3o de recibos<\/a>.<\/p>\n<h2 id=\"notifications\">Recebendo webhooks<\/h2>\n<p>\u00c0 medida que voc\u00ea realiza pagamentos e outras intera\u00e7\u00f5es com sua integra\u00e7\u00e3o, seu terminal gera notifica\u00e7\u00f5es. Estes s\u00e3o webhooks formatados em JSON que podem ser enviados para terminais em sua caixa registradora e usados para informar a equipe da loja sobre eventos importantes.<\/p>\n<p>Existem dois tipos de notifica\u00e7\u00f5es que podem ser enviadas para sua caixa registradora:<\/p>\n<ul>\n<li><a href=\"\/pt\/point-of-sale\/design-your-integration\/notifications\/display-notifications\">Notifica\u00e7\u00f5es em display <\/a>: informa a equipe da loja sobre eventos relacionados a uma transa\u00e7\u00e3o, como indicar se o comprador est\u00e1 interagindo com o terminal ou indicar o resultado do pagamento.\n<div class=\"notices yellow\">\n<p>Se sua integra\u00e7\u00e3o usar <a href=\"\/pt\/point-of-sale\/design-your-integration\/choose-your-architecture\/cloud#async\">comunica\u00e7\u00f5es em nuvem com um resultado ass\u00edncrono<\/a>, voc\u00ea precisar\u00e1 integrar notifica\u00e7\u00f5es em display para receber o resultado de suas transa\u00e7\u00f5es.<\/p>\n<\/div><\/li>\n<li><a href=\"\/pt\/point-of-sale\/design-your-integration\/notifications\/event-notifications\">Notifica\u00e7\u00f5es de evento<\/a>: informe a equipe da loja sobre a disponibilidade e o estado de um terminal, inclusive quando o terminal estiver iniciando a manuten\u00e7\u00e3o ou desligando.<\/li>\n<\/ul>\n<p>Al\u00e9m disso, a Adyen pode enviar <a href=\"\/pt\/development-resources\/notifications\">notifica\u00e7\u00f5es de plataforma<\/a> para o servidor de back office. Voc\u00ea pode us\u00e1-los para ajudar a automatizar processos de neg\u00f3cios, como relat\u00f3rios e reconcilia\u00e7\u00e3o, ou para manter o sistema de gerenciamento de pedidos (OMS) atualizado.<\/p>\n<h2 id=\"handling-errors\">Lidando com erros<\/h2>\n<p>\u00c0 medida que voc\u00ea se integra, voc\u00ea pode receber uma mensagem de erro na resposta da API. Para obter informa\u00e7\u00f5es sobre esses erros e como resolv\u00ea-los, consulte <a href=\"\/pt\/point-of-sale\/error-scenarios\">Cen\u00e1rios de erros<\/a>.<\/p>\n<p>Se voc\u00ea n\u00e3o receber uma resposta a uma solicita\u00e7\u00e3o de API, sua conex\u00e3o poder\u00e1 ter ca\u00eddo ap\u00f3s o envio da solicita\u00e7\u00e3o. Para obter mais informa\u00e7\u00f5es sobre como lidar com esse cen\u00e1rio, consulte a <a href=\"\/pt\/point-of-sale\/basic-tapi-integration\/verify-transaction-status\">verifica\u00e7\u00e3o do status de uma transa\u00e7\u00e3o<\/a>.<\/p>\n<hr \/>\n<p>Agora que voc\u00ea conhece os fundamentos da nossa API de terminais, voc\u00ea j\u00e1 pode come\u00e7ar a <a href=\"\/pt\/point-of-sale\/basic-tapi-integration\/make-a-payment\">realizar pagamentos<\/a>.<\/p>","url":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/design-your-integration\/terminal-api","articleFields":{"description":"Aprenda sobre a API de terminais, incluindo seus endpoints e a estrutura.","next_steps":[{"title":"Fa\u00e7a um pagamento","description":"Efetue um pagamento com cart\u00e3o com nossa API de terminais.","url":"\/point-of-sale\/basic-tapi-integration\/make-a-payment","required":true},{"title":"Gere recibos","description":"Aprenda a gerar recibos de suas transa\u00e7\u00f5es.","url":"\/point-of-sale\/basic-tapi-integration\/generate-receipts","required":false},{"title":"Exibir notifica\u00e7\u00f5es","description":"Mantenha sua equipe informada sobre as transa\u00e7\u00e3o.","url":"\/point-of-sale\/design-your-integration\/notifications\/display-notifications","required":false},{"title":"Notifica\u00e7\u00f5es de eventos","description":"Mantenha sua equipe informada sobre eventos fora do fluxo de pagamento.","url":"\/point-of-sale\/design-your-integration\/notifications\/event-notifications","required":false}],"last_edit_on":"01-06-2020 16:47"},"algolia":{"url":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/design-your-integration\/terminal-api","title":"Fundamentos da API de terminais","content":"A API de terminais permite efetuar pagamentos, realizar reembolsos, coletar informa\u00e7\u00f5es do comprador e outras intera\u00e7\u00f5es cliente-terminal.\n\nNossa API de terminais \u00e9 baseada no nexo Retailer Protocol.\n\nAntes de efetuar qualquer pagamento no terminal, \u00e9 importante entender como nossa API de terminais funciona e como as solicita\u00e7\u00f5es e respostas s\u00e3o estruturadas.\nAqui descreveremos:\n\nOs endpoints e autentica\u00e7\u00e3o.\nA estrutura da API.\nComo fazer pedidos.\nComo receber respostas.\nComo receber webhooks.\nComo lidar com erros.\n\nEndpoints e autentica\u00e7\u00e3o\nOs endpoits que voc\u00ea precisa usar e como voc\u00ea deve autenticar solicita\u00e7\u00f5es depende de como sua integra\u00e7\u00e3o se conecta \u00e0 plataforma de pagamentos Adyen:\n\nComunica\u00e7\u00f5es locais.\nComunica\u00e7\u00f5es em nuvem.\n\nComunica\u00e7\u00f5es locais\nSe sua integra\u00e7\u00e3o usa comunica\u00e7\u00f5es locais, todas as suas solicita\u00e7\u00f5es de API s\u00e3o feitas de uma caixa registradora diretamente no endere\u00e7o IP de um terminal. Como alternativa, se voc\u00ea atribuir um nome de host ao seu terminal, poder\u00e1 fazer solicita\u00e7\u00f5es ao nome do host terminal.\nO terminal recebe solicita\u00e7\u00f5es POST \/nexo na porta 8443. Por exemplo, se o seu terminal tiver o endere\u00e7o IP 198.51.100.1 , voc\u00ea dever\u00e1 fazer solicita\u00e7\u00f5es de API para:  https:\/\/198.51.100.1:8443\/nexo\n\nCorrija o endere\u00e7o MAC de cada terminal para um endere\u00e7o IP est\u00e1tico. Isso ajuda a evitar problemas de conex\u00e3o quando o terminal ou sua rede \u00e9 reiniciada.\n\nPara autenticar suas solicita\u00e7\u00f5es, voc\u00ea precisar\u00e1 adicionar o certificado da Adyen \u00e0 sua caixa registradora e criptografar suas mensagens.\nComunica\u00e7\u00f5es na nuvem\nSe sua integra\u00e7\u00e3o usa comunica\u00e7\u00f5es em nuvem, sua caixa registradora faz solicita\u00e7\u00f5es de API para a plataforma de pagamentos Adyen. Nossa plataforma encaminha a solicita\u00e7\u00e3o para o terminal.\nO terminal que voc\u00ea precisar\u00e1 usar depender\u00e1 de duas coisas:\n\nSe sua integra\u00e7\u00e3o receber\u00e1 resultados de transa\u00e7\u00e3o de forma s\u00edncrona ou ass\u00edncrona.\nSe voc\u00ea est\u00e1 fazendo transa\u00e7\u00f5es de teste ou transa\u00e7\u00f5es reais (live).\n\n\n\n\n\nTest endpoints - para todas as transa\u00e7\u00f5es de teste\n\n\n\n\nResultado s\u00edncrono:\nhttps:\/\/terminal-api-test.adyen.com\/sync\n\n\nResultado ass\u00edncrono:\nhttps:\/\/terminal-api-test.adyen.com\/async\n\n\n\nQuando voc\u00ea estiver pronto para entrar no ar, precisar\u00e1 mudar para um endpoint de transa\u00e7\u00f5es reais (live) que esteja geograficamente mais pr\u00f3ximo do local da sua loja.\n\n\n\n\nLive endpoints  - Europa\n\n\n\n\nResultado s\u00edncrono:\nhttps:\/\/terminal-api-live.adyen.com\/sync\n\n\nResultado ass\u00edncrono:\nhttps:\/\/terminal-api-live.adyen.com\/async\n\n\n\n\n\n\n\nLive endpoints - Australia\n\n\n\n\nResultado s\u00edncrono:\nhttps:\/\/terminal-api-live-au.adyen.com\/sync\n\n\nResultado ass\u00edncrono:\nhttps:\/\/terminal-api-live-au.adyen.com\/async\n\n\n\n\n\n\n\nLive endpoints - USA\n\n\n\n\nResultado s\u00edncrono:\nhttps:\/\/terminal-api-live-us.adyen.com\/sync\n\n\nResultado ass\u00edncrono:\nhttps:\/\/terminal-api-live-us.adyen.com\/async\n\n\n\nPara autenticar suas solicita\u00e7\u00f5es, voc\u00ea precisar\u00e1 de uma chave da API da Adyen. Se voc\u00ea ainda n\u00e3o possuir uma chave de API, poder\u00e1 obt\u00ea-la aqui. Voc\u00ea precisar\u00e1 incluir essa chave de API no cabe\u00e7alho de cada solicita\u00e7\u00e3o na API de terminais.\n\nAdicione a chave da API ao cabe\u00e7alho usando: x-API-key\n\nEstrutura da API\nNossa API de terminais se comunica com o terminal usando mensagens JSON. Todas as solicita\u00e7\u00f5es e respostas t\u00eam a seguinte estrutura de cabe\u00e7alho-corpo:\n\ncabe\u00e7alho (header): identifica o tipo de transa\u00e7\u00e3o, o terminal que est\u00e1 sendo usado e identificadores exclusivos de transa\u00e7\u00e3o.\ncorpo (body): um objeto de solicita\u00e7\u00e3o ou resposta, dependendo do tipo de transa\u00e7\u00e3o. Por exemplo, quando voc\u00ea faz uma solicita\u00e7\u00e3o de pagamento, este \u00e9 um objeto PaymentRequest quando voc\u00ea recebe uma resposta de pagamento, \u00e9 um objeto PaymentResponse.\n\nO cabe\u00e7alho e o corpo das respostas e solicita\u00e7\u00f5es da API de terminais s\u00e3o descritos em mais detalhes abaixo.\nSolicita\u00e7\u00f5es\nCada solicita\u00e7\u00e3o da API de terminais que voc\u00ea faz est\u00e1 contida em um objeto SaletoPOIRequest object. Neste, ser\u00e1 necess\u00e1rio fornecer um:\n\nObjetoMessageHeader.\nObjeto do corpo da solicita\u00e7\u00e3 correspondente ao tipo de transa\u00e7\u00e3o. Por exemplo, este \u00e9 um objeto PaymentRequest correspondente ao tipo de transa\u00e7\u00e3o. Por exemplo, este \u00e9 um objeto InputRequest quando est\u00e1 solicitando a entrada do comprador.\n\nSolicitar MessageHeader\nEm cada solicita\u00e7\u00e3o MessageHeader, especifique o seguinte:\n\n\n\nNome\nRequerido\nTipo\nDescri\u00e7\u00e3o\n\n\n\n\nProtocolVersion\nSim\nString\nVers\u00e3o da API do terminal da Adyen. A vers\u00e3o atual \u00e9 3.0\n\n\nMessageClass\nSim\nEnum\nQuase sempre \u00e9 Service, mas tamb\u00e9m pode ser Device ou Event. Vamos especificar qual MessageClass \u00e9 necess\u00e1rio ao longo da documenta\u00e7\u00e3o.\n\n\nMessageCategory\nSim\nEnum\nO tipo de transa\u00e7\u00e3o. Por exemplo, Payment para uma solicita\u00e7\u00e3o de pagamento. Vamos especificar qual MessageCategory \u00e9 necess\u00e1rio ao longo da documenta\u00e7\u00e3o.\n\n\nMessageType\nSim\nEnum\nSempre \u00e9 Request.\n\n\nSaleID\nSim\nString\nSeu ID exclusivo para sua caixa registradora.\n\n\nServiceID\nSim\nString\nSeu ID exclusivo para a tentativa de transa\u00e7\u00e3o, consistindo em 1 a 10 caracteres alfanum\u00e9ricos. Esse valor precisa ser exclusivo nas \u00faltimas 48 horas.\n\n\nPOIID\nSim\nString\nO ID exclusivo do terminal, no formato [modelo do dispositivo]-[n\u00famero de s\u00e9rie]. Por exemple, P400-123456789.Voc\u00ea pode encontrar o modelo do dispositivo e o n\u00famero de s\u00e9rie de um terminal na sua Customer Area, em In-person payments &gt; Terminals. O n\u00famero de s\u00e9rie (ou s\/n) tamb\u00e9m \u00e9 impresso na parte inferior de cada terminal.\n\n\n\nO exemplo abaixo mostra o cabe\u00e7alho que voc\u00ea forneceria se quisesse efetuar um pagamento.\n{\n  \"SaleToPOIRequest\":{\n    \"MessageHeader\":{\n      \"ProtocolVersion\":\"3.0\",\n      \"MessageClass\":\"Service\",\n      \"MessageCategory\":\"Payment\",\n      \"MessageType\":\"Request\",\n      \"SaleID\":\"POSSystemID12345\",\n      \"ServiceID\":\"0207111104\",\n      \"POIID\":\"V400m-324688179\"\n    },\n    \"PaymentRequest\":{...}\n  }\n}\nCorpo da solicita\u00e7\u00e3o\nOs valores que voc\u00ea precisa incluir no corpo da solicita\u00e7\u00e3o dependem do tipo de transa\u00e7\u00e3o que voc\u00ea est\u00e1 fazendo. Fornecemos exemplos e informa\u00e7\u00f5es de refer\u00eancia para cada tipo de transa\u00e7\u00e3o em toda a documenta\u00e7\u00e3o dos terminais.\nRespostas\nCada resposta da API do terminal que voc\u00ea recebe est\u00e1 contida em um objeto  SaleToPOIResponse e inclui um:\n\nObjeto MessageHeader: reproduz os valores do MessageHeader que voc\u00ea forneceu na solicita\u00e7\u00e3o da API.\nObjeto do corpo da resposta: corresponde ao tipo de solicita\u00e7\u00e3o de transa\u00e7\u00e3o que voc\u00ea fez.\nPor exemplo, quando voc\u00ea faz um PaymentRequest voc\u00ea recebe um objeto PaymentResponse.\n\n\nSe voc\u00ea estiver usando uma integra\u00e7\u00e3o em nuvem que receba resultados de forma ass\u00edncrona, voc\u00ea receber\u00e1 apenas uma resposta ok da API do terminal. O corpo e a resposta MessageHeader s\u00e3o enviados em uma notifica\u00e7\u00e3o de exibi\u00e7\u00e3o.\n\nResposta MessageHeader\nO MessageHeader que voc\u00ea recebe na resposta reproduzir\u00e1 os valores que voc\u00ea forneceu na solicita\u00e7\u00e3o. A \u00fanica exce\u00e7\u00e3o \u00e9 a MessageType, que ser\u00e1 uma Resposta.\nO exemplo a seguir mostra o cabe\u00e7alho que voc\u00ea receberia em resposta \u00e0 solicita\u00e7\u00e3o de pagamento do exemplo fornecido acima .\n{\n  \"SaleToPOIResponse\":{\n    \"MessageHeader\":{\n      \"ProtocolVersion\":\"3.0\",                  \/\/ Echoed from request\n      \"MessageClass\":\"Service\",                 \/\/ Echoed from request\n      \"MessageCategory\":\"Payment\",              \/\/ Echoed from request\n      \"MessageType\":\"Response\",                 \/\/ Response\n      \"SaleID\":\"POSSystemID12345\",              \/\/ Echoed from request\n      \"ServiceID\":\"0207111104\",                 \/\/ Echoed from request\n      \"POIID\":\"V400m-324688179\"                 \/\/ Echoed from request\n    },\n    \"PaymentResponse\":{...}                     \/\/ Response body object\n  }\n}\nCorpo de resposta\nOs valores que voc\u00ea recebe no corpo da resposta dependem do tipo de solicita\u00e7\u00e3o de transa\u00e7\u00e3o que voc\u00ea fez. Fornecemos exemplos e informa\u00e7\u00f5es de refer\u00eancia para cada tipo de transa\u00e7\u00e3o ao longo da documenta\u00e7\u00e3o dos terminais.\nO corpo da resposta geralmente inclui um identificador de transa\u00e7\u00e3o, exclusivo e dados que voc\u00ea pode usar para gerar seus recibos.\nIdentificador de transa\u00e7\u00e3o\nToda solicita\u00e7\u00e3o de API que cria uma transa\u00e7\u00e3o ou interage com seu fluxo de dinheiro (como pagamento ou reembolso) retorna um identificador de transa\u00e7\u00e3o exclusivo no POITransactionID.TransactionID:\n\nEste identificador cont\u00e9m dois valores, separados por um ponto:\n\nRefer\u00eancia tender: valor exclusivo gerado pelo terminal para a transa\u00e7\u00e3o.\nRefer\u00eancia PSP: valor exclusivo gerado pela plataforma de pagamentos Adyen para a transa\u00e7\u00e3o.\n\nSe voc\u00ea estiver usando a Adyen para pagamentos on-line u com\u00e9rcio unificado, a Refer\u00eancia PSP ser\u00e1 o equivalente a pspReference que voc\u00ea recebe pelas transa\u00e7\u00f5es feitas on-line.\n\n\nVoc\u00ea deve armazenar cada identificador de transa\u00e7\u00e3o que receber, voc\u00ea ir\u00e1 precisar deles para:\n\nFazer um reembolso.\nRealizar um pagamento com os detalhes do cart\u00e3o adquirido.\nIdentificar a transa\u00e7\u00e3o em sua Customer Area, ou nos relat\u00f3rios gerados pela Adyen.\n\nIdentificadores de transa\u00e7\u00e3o para pagamentos offline\nSe sua integra\u00e7\u00e3o usar comunica\u00e7\u00f5es locais, seus terminais poder\u00e3o fazer transa\u00e7\u00f5es store-and-foward e EMV offline. Quando voc\u00ea tem um problema de rede, um pagamento Aprovado gera apenas um identificador de transa\u00e7\u00e3o com a refer\u00eancia Tender:\n\nAssim que o terminal puder se conectar \u00e0 Internet novamente, a plataforma de pagamentos da Adyen processar\u00e1 o pagamento e gerar\u00e1 uma refer\u00eancia PSP. A refer\u00eancia do PSP e a refer\u00eancia tender podem ser encontradas na sua Customer Area, e nos relat\u00f3rios gerados pela Adyen.\nDados do recibo\nQuando voc\u00ea faz uma transa\u00e7\u00e3o como um pagamento, o resultado do pagamento cont\u00e9m um objeto PaymentReceipt. Voc\u00ea pode adicionar os pares de valores-chave desse objeto ao recibo que voc\u00ea imprime, exibe em tela ou envia por e-mail ao seu cliente.\nPara mais informa\u00e7\u00f5es, consulte a nossa documenta\u00e7\u00e3o de recibos.\nRecebendo webhooks\n\u00c0 medida que voc\u00ea realiza pagamentos e outras intera\u00e7\u00f5es com sua integra\u00e7\u00e3o, seu terminal gera notifica\u00e7\u00f5es. Estes s\u00e3o webhooks formatados em JSON que podem ser enviados para terminais em sua caixa registradora e usados para informar a equipe da loja sobre eventos importantes.\nExistem dois tipos de notifica\u00e7\u00f5es que podem ser enviadas para sua caixa registradora:\n\nNotifica\u00e7\u00f5es em display : informa a equipe da loja sobre eventos relacionados a uma transa\u00e7\u00e3o, como indicar se o comprador est\u00e1 interagindo com o terminal ou indicar o resultado do pagamento.\n\nSe sua integra\u00e7\u00e3o usar comunica\u00e7\u00f5es em nuvem com um resultado ass\u00edncrono, voc\u00ea precisar\u00e1 integrar notifica\u00e7\u00f5es em display para receber o resultado de suas transa\u00e7\u00f5es.\n\nNotifica\u00e7\u00f5es de evento: informe a equipe da loja sobre a disponibilidade e o estado de um terminal, inclusive quando o terminal estiver iniciando a manuten\u00e7\u00e3o ou desligando.\n\nAl\u00e9m disso, a Adyen pode enviar notifica\u00e7\u00f5es de plataforma para o servidor de back office. Voc\u00ea pode us\u00e1-los para ajudar a automatizar processos de neg\u00f3cios, como relat\u00f3rios e reconcilia\u00e7\u00e3o, ou para manter o sistema de gerenciamento de pedidos (OMS) atualizado.\nLidando com erros\n\u00c0 medida que voc\u00ea se integra, voc\u00ea pode receber uma mensagem de erro na resposta da API. Para obter informa\u00e7\u00f5es sobre esses erros e como resolv\u00ea-los, consulte Cen\u00e1rios de erros.\nSe voc\u00ea n\u00e3o receber uma resposta a uma solicita\u00e7\u00e3o de API, sua conex\u00e3o poder\u00e1 ter ca\u00eddo ap\u00f3s o envio da solicita\u00e7\u00e3o. Para obter mais informa\u00e7\u00f5es sobre como lidar com esse cen\u00e1rio, consulte a verifica\u00e7\u00e3o do status de uma transa\u00e7\u00e3o.\n\nAgora que voc\u00ea conhece os fundamentos da nossa API de terminais, voc\u00ea j\u00e1 pode come\u00e7ar a realizar pagamentos.","type":"page","locale":"pt","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Terminais","lvl2":"Design your integration","lvl3":"Fundamentos da API de terminais"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/pt","lvl1":"https:\/\/docs.adyen.com\/pt\/point-of-sale","lvl2":"https:\/\/docs.adyen.com\/pt\/point-of-sale\/design-your-integration","lvl3":"\/pt\/point-of-sale\/design-your-integration\/terminal-api"},"levels":4,"category":"In-person payments","category_color":"green","tags":["Fundamentos","terminais"]},"articleFiles":{"ReferenceForOnline.svg":"<img alt=\"\" src=\"https:\/\/docs.adyen.com\/user\/pages\/docs\/03.point-of-sale\/04.design-your-integration\/08.terminal-api\/ReferenceForOnline.svg\" \/>","ReferenceForOffline.svg":"<img alt=\"\" src=\"https:\/\/docs.adyen.com\/user\/pages\/docs\/03.point-of-sale\/04.design-your-integration\/08.terminal-api\/ReferenceForOffline.svg\" \/>"}}