Criar loja e caixa
Após criar a aplicação e obter as credenciais, é necessário configurar a loja e caixa, que estarão associados às transações.
As lojas representam estabelecimentos físicos cadastrados no Mercado Pago e podem ter um ou mais caixas vinculados. Já os caixas correspondem aos pontos de venda (PDVs) e devem sempre estar associados a uma loja, garantindo a conciliação de pagamentos por Código QR em estabelecimentos físicos.
É possível criar lojas e caixas a partir do seu sistema através das nossas APIs para pagamentos presenciais. Para isso, siga os passos a seguir.
Criar loja
Para criar uma loja via API, envie um POST incluindo seu Access Token de testeChave privada da aplicação criada no Mercado Pago, utilizada no backend. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste. Durante o processo de integração, utilize o Access Token de teste. Ao concluir a integração, substitua-o pelo Access Token de produção caso seja uma integração própria, ou pelo Access Token obtido via OAuth em integrações para terceiros.Acessar as credenciais de teste ao endpoint Criar lojaAPI. Você deverá adicionar o user_id da conta de testeDurante o desenvolvimento da integração, utilize o User ID da sua conta de teste, disponível em Suas integrações > Detalhes da aplicação > Credenciais de teste > Dados das credenciais de teste. Ao subir em produção, substitua-o pelo User ID da conta real do Mercado Pago que receberá os pagamentos. no path da sua requisição e completar os parâmetros requeridos com os detalhes do negócio conforme se indica a seguir.
city_name, state_name, latitude e longitude). Dados incorretos podem causar erros nos cálculos de impostos, impactando diretamente o faturamento e a regularização fiscal da sua empresa.curl
curl -X POST \ 'https://api.mercadopago.com/users/USER_ID/stores'\ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "name": "Loja Instore", "business_hours": { "monday": [ { "open": "08:00", "close": "12:00" } ], "tuesday": [ { "open": "09:00", "close": "18:00" } ] }, "external_id": "LOJ001", "location": { "street_number": "0123", "street_name": "Nome da rua de exemplo.", "city_name": "Nome da cidade.", "state_name": "Nome do estado.", "latitude": 27.175193925922862, "longitude": 78.04213533235064, "reference": "Perto do Mercado Pago." } }'
| Parâmetro | Descrição e exemplos | Obrigatoriedade |
user_id | Identificador da conta do Mercado Pago que recebe o dinheiro pelas vendas realizadas na loja. Durante o desenvolvimento, utilize o user_id da conta de teste, disponível em Suas integrações > Detalhes da aplicação > Credenciais de teste > Dados das credenciais de teste.Ao subir em produção, substitua pelo user_id da conta real que receberá os pagamentos: Se você está realizando uma integração própriaIntegrações de QR Code ao seu sistema para uso próprio e configuradas a partir das credenciais da sua aplicação., encontrará este valor nos Detalhes da aplicação. Se, ao contrário, está realizando uma integração para terceirosIntegrações de QR Code ao seu sistema em nome de um vendedor e configuradas a partir de credenciais obtidas por meio do protocolo de segurança OAuth., obterá o valor na resposta à vinculação por meio de OAuthChave privada gerada mediante o protocolo de segurança OAuth, que permite gerenciar integrações em nome de terceiros. Para mais informações, dirija-se à documentação.OAuth. | Obrigatório |
name | Nome da loja criada. | Obrigatório |
business_hours | Horário comercial. Os horários de funcionamento são divididos por dia da semana e são permitidos até quatro horários de abertura e fechamento por dia. Informe esses dados para que sua loja seja exibida no aplicativo do Mercado Pago com o horário correto de funcionamento. | Opcional |
external_id | Identificador externo da loja para o sistema integrador. Pode conter qualquer valor alfanumérico de até 60 caracteres e deve ser único para cada loja. Por exemplo, LOJ001. | Obligatorio |
location | Este objeto deve conter todas as informações da localização da loja. É importante preencher tudo corretamente , especialmente os campos latitude e longitude com as coordenadas geográficas, usando o formato decimal simples e os dados reais do local. Por exemplo, "latitude": 27.175193925922862 e "longitude": 78.04213533235064, que correspondem à localização exata do Taj Mahal, na Índia. Ao inserir esses dados corretamente, a loja aparecerá no mapa na localização indicada. | Obrigatório |
Se a solicitação foi enviada corretamente, a resposta será como o exemplo a seguir:
json
{ "id": 1234567, "name": "Loja Instore", "date_created": "2019-08-08T19:29:45.019Z", "business_hours": { "monday": [ { "open": "08:00", "close": "12:00" } ], "tuesday": [ { "open": "09:00", "close": "18:00" } ] }, "location": { "address_line": "Nome da rua de exemplo, 0123, Nome da cidade, Nome do estado.", "latitude": 27.175193925922862, "longitude": 78.04213533235064, "reference": "Perto do Mercado Pago" }, "external_id": "LOJ001" }
Além dos dados enviados na solicitação, o endpoint retornará o identificador atribuído à loja pelo Mercado Pago sob o parâmetro id.
Criar caixa
Para habilitar vendas com Mercado Pago, é indispensável que cada loja registrada tenha pelo menos um caixa vinculado. Para criar um caixa e associá-lo à loja previamente criada, envie um POST incluindo seu Access Token de testeChave privada da aplicação criada no Mercado Pago, utilizada no backend. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste. Durante o processo de integração, utilize o Access Token de teste. Ao concluir a integração, substitua-o pelo Access Token de produção caso seja uma integração própria, ou pelo Access Token obtido via OAuth em integrações para terceiros.Acessar as credenciais de teste ao endpoint Criar caixaAPI como mostrado a seguir.
curl
curl -X POST \ 'https://api.mercadopago.com/pos'\ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "name": "First POS", "fixed_amount": true, "store_id": 1234567, "external_store_id": "LOJ001", "external_id": "LOJ001POS001", "category": 621102 }'
| Parâmetro | Descrição e exemplos | Obrigatoriedade |
name | Nome do caixa criado. | Obrigatório |
fixed_amount | Este campo determina se o cliente pode inserir o valor a pagar ou se já é predefinido pelo vendedor. Para modelos integrados, este valor deve ser igual a true. | Obrigatório |
store_id | Identificador da loja à qual pertence o caixa, atribuído a essa loja pelo Mercado Pago. É retornado na resposta à criação da loja sob o parâmetro id. | Obrigatório |
external_store_id | Identificador externo único da loja. Este valor é definido pelo integrador ao criar a loja, sob o parâmetro external_id. | Obrigatório |
external_id | Identificador único do caixa definido pelo sistema integrador. Deve ser um valor alfanumérico único para cada caixa e pode conter até 40 caracteres. | Obrigatório |
category | Código MCC que indica a categoria do ponto de venda. As únicas categorias possíveis são Gastronomia e Posto de gasolina, e o código varia segundo o país de operação. Se não for especificado, permanece como uma categoria genérica. Para mais informações sobre os códigos, consulte a Referência de APIAPI. | Opcional |
Se a solicitação foi enviada corretamente, a resposta será como o exemplo a seguir.
json
{ "id": 2711382, "qr": { "image": "https://www.mercadopago.com/instore/merchant/qr/2711382/0977011a027c4b4387e52069da4264deae2946af4dcc44ee98a8f1dbb376c8a1.png", "template_document": "https://www.mercadopago.com/instore/merchant/qr/2711382/template_0977011a027c4b4387e52069da4264deae2946af4dcc44ee98a8f1dbb376c8a1.pdf", "template_image": "https://www.mercadopago.com/instore/merchant/qr/2711382/template_0977011a027c4b4387e52069da4264deae2946af4dcc44ee98a8f1dbb376c8a1.png" }, "status": "active", "date_created": "2019-08-22T14:11:12.000Z", "date_last_updated": "2019-08-25T15:16:12.000Z", "uuid": "0977011a027c4b4387e52069da4264deae2946af4dcc44ee98a8f1dbb376c8a1", "user_id": 446566691, "name": "First POS", "fixed_amount": false, "category": 621102, "store_id": 1234567, "external_store_id": "SUC001", "external_id": "SUC001POS001" }
Veja na tabela abaixo a descrição de alguns dos parâmetros retornados que podem ser úteis para continuar com sua integração mais adiante.
| Parâmetro | Descrição |
id | ID de criação do ponto de venda. Ao registrar um ponto de venda, você receberá um ID correspondente. Esse ID pode ser utilizado para várias operações, incluindo consultar seus dados. |
qr | Código QR estático associado ao caixa criado automaticamente para processar as transações do ponto de venda. Este código QR é necessário quando as orders são criadas em modo estático (static) ou híbrido (hybrid). O objeto qr contém os seguintes atributos: image: URL da imagem do código QR a ser utilizado para realizar as transações. template_document: URL do arquivo (em formato PDF) do template com o código QR a ser utilizado para realizar as transações. template_image: URL do arquivo (em formato de imagem) do template com o código QR a ser utilizado para processar as transações. |
status | Status de criação do ponto de venda. |
uuid | O UUID (Universally Unique Identifier - Identificador Universalmente Único) é um número de 128 bits utilizado para identificar informações. Neste caso, é o número de identificação do Código QR em questão. |
user_id | Identificador da conta do Mercado Pago que recebe o dinheiro pelas vendas realizadas no caixa. |
name | Nome atribuído ao caixa no momento da sua criação. |
store_id | Identificador da loja à qual pertence o ponto de venda. |
external_store_id | Identificador externo da loja, que foi atribuído pelo sistema integrador no momento da sua criação sob o parâmetro external_id. |
external_id | Identificador único do caixa definido pelo sistema integrador. |
Se ambas as solicitações foram bem-sucedidas, você terá criado e configurado a loja e o caixa necessários para a integração com Código QR.
Com a loja e o caixa criados, você poderá integrar o processamento de pagamentos.