Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentación de ecosistema presencial #2114

Open
wants to merge 45 commits into
base: development
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 39 commits
Commits
Show all changes
45 commits
Select commit Hold shift + click to select a range
eff1133
documentación de ecosistema presencial
pcanosa Jul 31, 2023
c6b7c4b
fixes de contenido y código
pcanosa Aug 1, 2023
44e9722
fixes en iniciar sesión, activar pdv e intents para QR
pcanosa Aug 2, 2023
f966e10
Fixes
pcanosa Aug 2, 2023
24b92cd
incorporación de archivos YAML provisorios para API Ref
pcanosa Aug 2, 2023
32eefa4
fixes traducciones en endpoints point
pcanosa Aug 3, 2023
54e9e48
se suma glosario en español
pcanosa Aug 3, 2023
d0d185a
traducciones a los endpoint de qr y dispositivos
pcanosa Aug 3, 2023
9855e49
landing en es
pcanosa Aug 4, 2023
5a4ff95
fixes landing es
pcanosa Aug 4, 2023
6fb2f92
fix landing
pcanosa Aug 4, 2023
855333a
fixes en varios archivos y agregado de flujo de prueba de integración
pcanosa Aug 4, 2023
cd947a4
fix landing
pcanosa Aug 4, 2023
62f680a
heits
hgaldino Aug 4, 2023
f92ac1d
heits2
hgaldino Aug 4, 2023
daca81d
heits3
hgaldino Aug 4, 2023
47fa3d2
heits4
hgaldino Aug 4, 2023
ecc4fe6
heits5
hgaldino Aug 4, 2023
9b42db9
fixes
pcanosa Aug 4, 2023
df143d0
fix links a api ref
pcanosa Aug 4, 2023
0832ab3
agregado de archivos en pt
pcanosa Aug 7, 2023
917c79c
incorporación de archivos en pt
pcanosa Aug 7, 2023
95d0a88
fixed identation issues
rwaetemann Aug 7, 2023
89f1c55
fixes
pcanosa Aug 7, 2023
1f05191
agregado de archivos en EN
pcanosa Aug 7, 2023
4c0569d
agregado de archivos en EN
pcanosa Aug 8, 2023
908695b
add landing EN
pcanosa Aug 8, 2023
a9c2302
fixes
pcanosa Aug 8, 2023
592cc2e
fixes nombre de la API en inglés
pcanosa Aug 9, 2023
c5f6415
fix error
bacarvalho Aug 14, 2023
5bd8eb5
Fixed all file
bacarvalho Aug 14, 2023
72357d6
fixes identation mla
pcanosa Aug 15, 2023
666f3b1
prueba de respuesta exitosa
pcanosa Aug 16, 2023
c330da7
fixes en la beta
pcanosa Aug 16, 2023
809cc17
fix endpoints docu
pcanosa Aug 16, 2023
4f36f6e
fixes
pcanosa Aug 16, 2023
0105233
fixes
pcanosa Aug 16, 2023
6febb63
fixes
pcanosa Aug 17, 2023
26b741a
fixes endpoints
pcanosa Aug 17, 2023
e0e328a
Fixes yaml mla
pcanosa Aug 18, 2023
bd3c432
Fixes mlb
pcanosa Aug 18, 2023
c316ef1
eliminación de error 409 y de extra cash y cash out para qr
pcanosa Aug 18, 2023
ea0338a
eliminación de cashout de los json
pcanosa Aug 18, 2023
1614148
renaming
pcanosa Sep 6, 2023
9decdf6
fixes
pcanosa Sep 7, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 170 additions & 0 deletions guides/ecosistema-presencial/create-and-manage-intent-point.en.md
Original file line number Diff line number Diff line change
@@ -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/ecosistema-presencial/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/ecosistema-presencial/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/ecosistema-presencial/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.
169 changes: 169 additions & 0 deletions guides/ecosistema-presencial/create-and-manage-intent-point.es.md
Original file line number Diff line number Diff line change
@@ -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/ecosistema-presencial/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/ecosistema-presencial/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/ecosistema-presencial/additional-content/your-integrations/notifications/webhooks).

> WARNING
>
> Importante
>
> Para configurar las notificaciones de Ecosistema Presencial, 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.
Loading