Documentación de ecosistema presencial

guides/instore-api/create-and-manage-intent-point.en.md

@@ -0,0 +1,170 @@
+# Create and manage intents on Point devices
+
+Below, you can see how to create an intent on Point devices, how to check its status, and how to cancel it, as well as how to configure its notifications.
+
+## Create intent on Point devices
+
+To create an intent on your Point device, you have two options:
+ * You can make a POST call to the endpoint  ----[mla]---- [Create intent for a device associated with a point of sale](/developers/en/reference/instore_api_mla/_instore-api_integrationsintents_point_pos_external_id/post)------------ ----[mlb]---- [Create intent for a device associated with a point of sale](/developers/en/reference/instore_api_mlb/_instore-api_integrationsintents_point_pos_external_id/post)------------, replacing `external.id` with the value chosen when creating the point of sale.
+ * Alternatively, you can make a POST call to the endpoint ----[mla]---- [Create intent for a POS device](/developers/en/reference/instore_api_mla/_instore-api_integrationsintents_point_device_id/post)------------ ----[mlb]----[Create intent for a POS device](/developers/en/reference/instore_api_mlb/_instore-api_integrationsintents_point_device_id/post)------------, replacing `device.id` with the value obtained when querying the list of devices.
+
+You can choose the option that best suits your needs. The result will be the same, and you will have created an intent for the chosen Point device.
+
+
+----[mlb]----
+> Keep in mind that for the `amount` field, the minimum allowed amount for Point Pro 2 devices is 1.00, and the maximum is 70000.00.
+
+------------
+
+----[mla]----
+> Keep in mind that for the `amount` field, the minimum allowed amount for POS and SMART devices is 5.00, and the maximum is 4000000.00.
+
+------------
+
+## Check the status of an intent on Point devices
+
+To know the current status of an intent, make a GET call to the endpoint ----[mla]----[Get information about an intent](/developers/en/reference/instore_api_mla/_instore-api_integrationsintents_intent_id_point/get)------------ ----[mlb]----[Get information about an intent](/developers/en/reference/instore_api_mlb/_instore-api_integrationsintents_intent_id_point/get)------------, replacing `intent_id` with the value obtained in that field when creating it.
+
+Here's an example of a response when querying the status:
+
+``` json
+{
+    "description": "description",
+    "external_reference": "external_reference",
+    "status": "CLOSED",
+    "operations": [
+        {
+            "type": "PURCHASE",
+            ....
+            "results": [
+                {
+                    "id": 123456,
+                    "source": "PAYMENT"
+                }
+            ]
+            ...
+        }
+    ],
+    "enabler_configuration": {
+        "ticket_number": "Ticket001",
+         "device_payment_mode": "CARD",
+         "print_on_terminal": [
+             "SELLER_TICKET"
+         ]
+     }
+}
+```
+
+Within the `status` field, you can see the status of the intent. The only final states are `CANCELED`, `CLOSED`, `EXPIRED`, `ERROR`, and `CONFIRMATION_REQUIRED`.
+For more information about the possible states of an intent, refer to the [Glossary](/developers/en/docs/instore-api/glossary).
+
+Please note that for the final state `CLOSED`, you will see an additional `results` node in the response. This node contains payment information related to the results of the operation; that is, the list of transactions associated with it.
+
+This object is composed as follows:
+
+| Value | Description |
+|---|---|
+| `id` | It is the payment ID. With it, you can go to the [Payments API](/developers/en/reference/payments/_payments_id/get) and check the final status of the payment. |
+| `source` | Entity to which the `id` belongs. It will return the value `PAYMENT` when the payment flow has been created correctly. Go to the [Payments API](/developers/en/reference/payments/_payments_id/get) to check the final status of the payment with the received `id`. |
+
+## Cancel an intent on Point devices
+
+If the payment has not been made yet and you haven't loaded the intent on the device, you can cancel a payment intent and make that attempt no longer available for processing. 
+Make a DELETE call to the endpoint ----[mla]----[Cancel an intent](/developers/en/reference/instore_api_mla/_instore-api_integrationsintents_intent_id_point/delete)------------ ----[mlb]----[Cancel an intent](/developers/en/reference/instore_api_mlb/_instore-api_integrationsintents_intent_id_point/delete)------------, replacing `external.id` and `intent_id` with the values obtained when creating a cash register and the payment intent, respectively.
+
+> WARNING
+>
+> Important
+>
+> Please note that you can only cancel an intent using this method if its status is `OPENED`. If this is not the current state of the intent you are trying to cancel and instead it is `ON_TERMINAL`, you must do it from the Point device. For more information about the possible states of an intent, refer to the [Glossary](/developers/en/docs/instore-api/glossary).
+
+## Configure notifications
+
+We recommend **setting up your Webhook notifications**. These will facilitate receiving real-time information every time an intent reaches a final state.
+
+To configure your notifications, follow the instructions provided in the [Webhooks notifications documentation](/developers/en/docs/instore-api/additional-content/your-integrations/notifications/webhooks).
+
+> WARNING
+>
+> Important
+>
+> To set up notifications for InStore API, you must use the event **Instore Integration**, whose message will contain the `type` field with the value `topic_instore_integration_wh`. Through this event, you will receive notifications of final states of the intents, whether processed by Point or QR in integrated mode.
+
+Here's an example of a notification you can receive for a Point device when an intent reaches a final `status`. Keep in mind that the information notified within the `data` node will depend on the information used to create the intent.
+
+----[mla]----
+``` json
+{
+    "id": "1234567-12345-12345678-1234567890",
+    "action": "topic_instore_integration_wh.application.authorized",
+    "api_version": "v1",
+    "data": {
+        "enabler_configuration": {
+            "ticket_number": "Ticket001",
+            "device_payment_mode": "CARD",
+            "print_on_terminal": [
+                "SELLER_TICKET"
+            ]
+        },
+        "external_reference": "123132342341",
+        "description": "abc",
+        "id": "1234567-12345-12345678-1234567890",
+        "operations": [
+            {
+                "amount": "10.14",
+                "type": "PURCHASE"
+            }
+        ],
+        "status": "CANCELED",
+        "url": "https://api.mercadopago.com/instore-api/integrations/v1/intents/1234567-12345-12345678-1234567890/point"
+    },
+    "date_created": "2023-07-27 20:24:21.776642198-0400",
+    "live_mode": true,
+    "type": "topic_instore_integration_wh",
+    "user_id": 12345667
+}
+
+```
+------------
+----[mlb]----
+``` json
+{
+    "id": "1234567-12345-12345678-1234567890",
+    "action": "topic_instore_integration_wh.application.authorized",
+    "api_version": "v1",
+    "data": {
+        "enabler_configuration": {
+            "device_payment_mode": "CARD",
+            "print_on_terminal": [
+                "SELLER_TICKET"
+            ]
+        },
+        "external_reference": "123132342341",
+        "description": "abc",
+        "id": "1234567-12345-12345678-1234567890",
+        "operations": [
+            {
+                "amount": "10.14",
+                "type": "PURCHASE"
+            }
+        ],
+        "status": "CANCELED",
+        "url": "https://api.mercadopago.com/instore-api/integrations/v1/intents/1234567-12345-12345678-1234567890/point"
+    },
+    "date_created": "2023-07-27 20:24:21.776642198-0400",
+    "live_mode": true,
+    "type": "topic_instore_integration_wh",
+    "user_id": 12345667
+}
+
+```
+------------
+
+## Refunding a payment 
+
+If, once the payment has been made, you need to refund that received money, we recomend to [Create a refund](/developers/en/reference/chargebacks/_payments_id_refunds/post) by making a POST request to our API.  
+
+If you want to refund the money manually, you can follow the steps below: 
+1. On your Point device, press the **Menu** button. 
+2. Go to the "Last payments" option and select the payment you want to refund. 
+3. Click on "Refund charge" option, and confirm the refund.

guides/instore-api/create-and-manage-intent-point.es.md

@@ -0,0 +1,169 @@
+# Crear y administrar intents en dispositivos Point
+
+A continuación, puedes ver cómo crear un intent en dispositivos Point, cómo consultar su estado, y cómo cancelarlo, así como la vía para configurar sus notificaciones.
+
+## Crear intent en dispositivos Point
+
+Para crear un intent en tu dispositivo Point, tienes dos posibilidades:
+
+* Puedes realiza una llamada POST al endpoint ----[mla]----[Crear intent para un dispositivo asociado a una caja](/developers/es/reference/instore_api_mla/_instore-api_integrationsintents_point_pos_external_id/post)------------ ----[mlb]---- [Crear intent para un dispositivo asociado a una caja](/developers/es/reference/instore_api_mlb/_instore-api_integrationsintents_point_pos_external_id/post)------------, reemplazando `external.id` por el valor escogido al crear la caja.
+* O bien, puedes realizar una llamada POST al endpoint ----[mla]----[Crear intent para un dispositivo PDV](/developers/es/reference/instore_api_mla/_instore-api_integrationsintents_point_device_id/post)------------ ----[mlb]----[Crear intent para un dispositivo PDV](/developers/es/reference/instore_api_mlb/_instore-api_integrationsintents_point_device_id/post)------------, reemplazando `device.id` por el valor obtenido al consultar el listado de dispositivos. 
+
+Puedes elegir la opción que mejor se adapte a tus necesidades. El resultado será el mismo y habrás creado un intent para el dispositivo Point elegido.
+
+----[mlb]----
+> Ten en cuenta que para el campo `amount`, el monto mínimo permitido para dispositivos Point Pro 2 es 1.00, y el máximo 70000.00. 
+------------
+
+----[mla]----
+> Ten en cuenta que para el campo `amount`, el monto mínimo permitido para dispositivos POS y SMART es 5.00, y el máximo 4000000.00.
+------------
+
+## Consultar el estado de un intent en dispositivos Point
+
+Para conocer el estado actual de un intent, realiza una llamada GET al endpoint ----[mla]----[Obtener información de un intent](/developers/es/reference/instore_api_mla/_instore-api_integrationsintents_intent_id_point/get)------------ ----[mlb]----[Obtener información de un intent](/developers/es/reference/instore_api_mlb/_instore-api_integrationsintents_intent_id_point/get)------------, reemplazando `intent_id` por el valor obtenido en ese campo al momento de crearlo. 
+
+A continuación, te mostramos un ejemplo de respuesta a la consulta de un estado:
+
+``` json
+{
+    "description": "description",
+    "external_reference": "external_reference",
+    "status": "CLOSED",
+    "operations": [
+        {
+            "type": "PURCHASE",
+            ....
+            "results": [
+                {
+                    "id": 123456,
+                    "source": "PAYMENT"
+                }
+            ]
+            ...
+        }
+    ],
+    "enabler_configuration": {
+        "ticket_number": "Ticket001",
+         "device_payment_mode": "CARD",
+         "print_on_terminal": [
+             "SELLER_TICKET"
+         ]
+     }
+}
+```
+
+Dentro del campo `status` podrás ver el estado del intent. Los únicos estados finales son `CANCELED`, `CLOSED`, `EXPIRED` , `ERROR` y  `CONFIRMATION_REQUIRED`.  
+Para obtener más información sobre los estados posibles de un intent, dirígete al [Glosario](/developers/es/docs/instore-api/glossary).
+
+Ten en cuenta que, para el estado final `CLOSED`,  verás en la respuesta el nodo adicional `results`. Este nodo contiene la información del pago relacionada a los resultados de la operación; es decir, el listado de transacciones asociadas a la misma. 
+
+Este objeto se compone de la siguiente manera: 
+
+| Valor | Descripción |
+|---|---|
+| `id` | Es la identificación del pago. Con ella, puedes dirigirte a [Payments API](/developers/es/reference/payments/_payments_id/get) y consultar el estado final del pago. |
+| `source` | Entidad a la que pertenece el `id`.  Arrojará el valor `PAYMENT` cuando el flujo del pago se haya creado correctamente. Dirígete a [Payments API](/developers/es/reference/payments/_payments_id/get) para verificar el estado final del pago con el `id` recibido. |
+
+## Cancelar un intent en dispositivos Point
+
+Si todavía no se ha realizado el pago y no has cargado el intent en el dispositivo, puedes cancelar una intención de pago y hacer que ese intento ya no esté disponible para su procesamiento. 
+Realiza una llamada DELETE al endpoint ----[mla]----[Cancelar un intent](/developers/es/reference/instore_api_mla/_instore-api_integrationsintents_intent_id_point/delete)------------ ----[mlb]----[Cancelar un intent](/developers/es/reference/instore_api_mlb/_instore-api_integrationsintents_intent_id_point/delete)------------, reemplazando `external.id` e `intent_id` por los valores obtenidos al crear una caja y el intento de pago, respectivamente.
+
+> WARNING
+>
+> Importante
+>
+> Ten en cuenta que sólo se permite la cancelación de un intent por este método si su estado es `OPENED`. En caso de que este no sea el estado actual del intent que estás queriendo cancelar y, en cambio, sea `ON_TERMINAL`, deberás hacerlo desde el dispositivo Point. Para más información sobre los posibles estados de un intent, dirígete al [Glosario](/developers/es/docs/instore-api/glossary).
+
+## Configurar notificaciones
+
+Recomendamos **configurar tus notificaciones Webhook**. Estas facilitarán que recibas información en tiempo real cada vez que un intent llega a un estado final. 
+
+Para configurar tus notificaciones, sigue las instrucciones proporcionadas en la [documentación de notificaciones Webhooks](/developers/es/docs/instore-api/additional-content/your-integrations/notifications/webhooks).
+
+> WARNING
+>
+> Importante
+>
+> Para configurar las notificaciones de InStore API, deberás utilizar el evento **Integraciones Presenciales**, cuyo mensaje contendrá el campo `type` con el valor  `topic_instore_integration_wh`. Por medio de este evento recibirás las notificaciones de estados finales de los intent, ya sean procesados por Point o QR en modo integrado.  
+
+A continuación, te mostramos un ejemplo de notificación que puedes recibir para un dispositivo Point cuando un intent llega a un estado (`status`) final. Ten en cuenta que la información que se notifica dentro del nodo `data` va a depender de la información con la que se cree el intent.
+
+----[mla]----
+``` json
+{
+    "id": "1234567-12345-12345678-1234567890",
+    "action": "topic_instore_integration_wh.application.authorized",
+    "api_version": "v1",
+    "data": {
+        "enabler_configuration": {
+            "ticket_number": "Ticket001",
+            "device_payment_mode": "CARD",
+            "print_on_terminal": [
+                "SELLER_TICKET"
+            ]
+        },
+        "external_reference": "123132342341",
+        "description": "abc",
+        "id": "1234567-12345-12345678-1234567890",
+        "operations": [
+            {
+                "amount": "10.14",
+                "type": "PURCHASE"
+            }
+        ],
+        "status": "CANCELED",
+        "url": "https://api.mercadopago.com/instore-api/integrations/v1/intents/1234567-12345-12345678-1234567890/point"
+    },
+    "date_created": "2023-07-27 20:24:21.776642198-0400",
+    "live_mode": true,
+    "type": "topic_instore_integration_wh",
+    "user_id": 12345667
+}
+
+```
+------------
+----[mlb]----
+``` json
+{
+    "id": "1234567-12345-12345678-1234567890",
+    "action": "topic_instore_integration_wh.application.authorized",
+    "api_version": "v1",
+    "data": {
+        "enabler_configuration": {
+            "device_payment_mode": "CARD",
+            "print_on_terminal": [
+                "SELLER_TICKET"
+            ]
+        },
+        "external_reference": "123132342341",
+        "description": "abc",
+        "id": "1234567-12345-12345678-1234567890",
+        "operations": [
+            {
+                "amount": "10.14",
+                "type": "PURCHASE"
+            }
+        ],
+        "status": "CANCELED",
+        "url": "https://api.mercadopago.com/instore-api/integrations/v1/intents/1234567-12345-12345678-1234567890/point"
+    },
+    "date_created": "2023-07-27 20:24:21.776642198-0400",
+    "live_mode": true,
+    "type": "topic_instore_integration_wh",
+    "user_id": 12345667
+}
+
+```
+------------
+
+## Devolver un pago
+
+Si, una vez que el pago fue realizado, necesitas realizar una devolución de ese dinero percibido, recomendamos [crear un reembolso](/developers/es/reference/chargebacks/_payments_id_refunds/post) realizando una llamada POST a la API. 
+
+Si, en cambio, quieres hacer un reembolso manual, sigue los pasos a continuación:
+
+1. En tu dispositivo Point, presiona el botón **Menú**.
+2. Dirígete a la opción “Últimos pagos” y selecciona el pago que deseas devolver.
+3. Presiona la opción “Devolver cobro”, y confirma esa devolución.