Pasos para implementar una venta.
Ahora que has podido autorizar tu aplicación y obtener un access_token, el siguiente paso es realizar una transacción de prueba.
Recuerda que debes conectar a internet la terminal, configurar la aplicación para poder realizar una venta y configurar el servicio de respuesta como se indica en la sección de Introducción.
5.1 Estructura de una petición.
POST https://api-154.api-netpay.com/integration-service/transactions/sale
Headers
Los siguientes headers deben ser enviados en la petición
- Content-Type: application/json
- Authorization: Bearer {{access_token}}
| Nombre | Descripción | Tipo | Valor | Requerido |
|---|---|---|---|---|
| Content-Type | Identificador de dos partes para formatos de archivo transmitidos por Internet. | string | application/json | true |
| Authorization | Esquema de autenticación HTTP. | string | Bearer {access_token} | true |
Nota
- La terminal debe tener acceso a internet en todo momento sin restricciones al dominio y subdominios que involucren a *.netpay.com.mx para recibir y enviar solicitudes.
- Debe estar encendida la pantalla de la terminal y estar en primer plano la pantalla principal de la aplicación.
5.2 Estructura de un JSON de venta.
Para poder generar una transacción es necesario formar un JSON con la siguiente información.
| Parámetro | Descripción |
|---|---|
| traceability | Objeto JSON para enviar información relevante para el comercio. |
| serialNumber | Número de serie. Cadena numérica a 10 dígitos ubicada en la parte posterior de la terminal (S/N). |
| storeId | Número identificador de comercio asignado por terminal. |
| msi | Número que identifica la promoción a MSI que se desea integrar Ej: 3, 6, 9, 12 o 18 msi ( esta promoción no aplica para tarjetas Amex) (Este dato no es obligatorio, solo si el cliente lo requiere). |
| folioNumber | Número de folio que se mostrará en el ticket. |
| access_token | Token de acceso necesario para consumir el servicio. Ver sección Generar Token. |
| disablePrintAnimation | Bandera de control con valor por default false. Al enviarla en true, se omitirá el ticket oficial de NetPay. (Opcional.) |
Body
En la petición, se debe mandar un objeto JSON con los datos según se requieran. Los 5 valores mínimos requeridos son serialNumber, amount, storeId, traceability y folionumber.
{
"serialNumber": "{serialNumber}",
"amount": "{{amount}}",
"storeId": "{storeId}",
"folioNumber":"{folioNumber}",
"msi":"{msi}",
"traceability": {}
}
Ejemplo:
{
"traceability": {
"idProducto": "123456",
"idTienda": 0987
},
"serialNumber": "1400000000",
"amount":0.01,
"folioNumber":"123",
"storeId": "9194",
"msi":"03",
"disablePrintAnimation": true
}
Tabla de parámetros mandatorios y opcionales a enviar en una petición de Venta.
| Nombre campo | Descripción | Tipo de dato | |
|---|---|---|---|
| serialNumber | Número de serie del dispositivo al que se requiere enviar la petición. | String (Máximo hasta 20 caracteres) | Mandatorio |
| amount | Monto total de la transacción. | Double(15,2) | Mandatorio |
| storeId | Identificador de la tienda asignada al dispositivo. | String (Máximo hasta 38 caracteres) | Mandatorio |
| folioNumber | Número identificador de transacción que puede ser enviado en la solicitud de venta. | String (Máximo hasta 250 caracteres) | Recomendable |
| traceability | Objeto JSON para enviar información relevante para el comercio (puede ser algún id de la transacción que posteriormente les servirá para hacer “match” dentro de su sistema. | Object. | Mandatorio |
| msi | Número que identifica la promoción a MSI que se desea integrar Ej: 03, 06, 09, 12 o 18 msi (esta promoción no aplica para tarjetas Amex) | String (Máximo 2 carateres). | Opcional |
| tip | Campo que hace referencia al envío de propina (Predeterminadamente tiene un límite del 25%) | String | Opcional |
| disablePrintAnimation | Bandera de control con valor default falso, cambiarlo a true desactiva la impresión del ticket oficial de NetPay. Este campo debe enviarse sólo si el comercio cuenta con una impresora propia. | Bool | Opcional |
Nota.
Si se requiere el uso de la propina y si el monto debe ser mayor al 25%, el comercio se puede comunicar con su comercial asignado correspondiente para que se coordine con el equipo de operaciones y ese límite sea aumentado al porcentaje que sea necesario. Este aumento de límite ya se realizaría en producción después de terminar con la integración y de realizar la certificación exitosamente como lo indica la sección de 10. Certificación y pasos a seguir de esta documentación.
5.3 Ejemplo de solicitud / respuesta.
A continuación, se muestran ejemplos en diferentes lenguajes de programación para realizar una petición y solicitar una venta con los diferentes mensajes de respuesta.