Integración de Pre-Órdenes con QR

Introducción

Este documento describe los endpoints de la API de TotalCoin para gestionar pre-órdenes con generación y procesamiento de códigos QR.

Autenticación

El control de acceso a la API se realiza mediante OAuth 2.0 con Tokens Bearer.

Endpoint

POST api/auth/login

Solicitud

{
    "username": "",
    "password": ""
}

Campo	Tipo	Descripción	Requerido
username	String	Nombre de usuario	Sí
password	String	Contraseña	Sí

Respuesta (HTTP 200)

{
    "token": "",
    "expires_in": 3600
}

Campo	Tipo	Descripción
token	String	Token de autenticación
expires_in	Number	Validez del token en segundos

Posibles Errores

Código	Descripción
401	Credenciales inválidas o no existentes
403	Sin permisos para acceder a la API

Credenciales: Deben solicitarse al departamento técnico.

Crear Pre-Orden

Crea una nueva pre-orden y genera un código QR para el pago.

Endpoint

POST https://apicobranzastest.totalcoin.com/api/iep/pre-order

Solicitud

        {
            "concept": "test-jpgq",
            "expirationDate": "2025-03-26T17:23:14.099Z",
            "businessUnit": 348,
            "externalReference": "JPGQ_PAYMENT_001",
            "qrAmountType": "closed",
            "amount":10,
            "qrType": "static",
            "resetOnPayment": true,
            "operationId": "ca8964d1-b90b-4583-98da-bfc7f757d6e7",
            "dni": "27594189",
            "companyReferenceToConciliate": "OP:000001110001"
        }

Campo	Tipo	Descripción	Requerido
concept	Strint	A description or identifier for the payment	Sí
expirationDate	String	When the QR code will expire and no longer be valid for payment	Sí
businessUnit	String	Identifier for the business unit receiving the payment	Sí
externalReference	String	External reference ID for tracking/reconciliation	Sí
qrAmountType	Object	Whether amount is fixed ("closed") or variable ("open")	Sí
amount	String	The payment amount in the default currency	Sí
qrType	String	"static" for fixed QR codes, "dynamic" for one-time use	Sí
resetOnPayment	String	If true, QR code can be reused after successful payment	Sí
operationId	String	Merchant Transaction Reference, this is a value provided by Arbet System and indicates the id of this payment in your system	Sí
dni	String	Document number of the payer	Sí
companyReferenceToConciliate	String	Reference used for payment reconciliation	Sí

Respuesta (HTTP 201)

                    {
                        "id": 13010,
                        "qrCode": "00020101021143510033com.totalcoin.integracionesqrtest0210000001301050150011307180924815126002200002228000000000577235204490053030325802AR5905ARBET6012Buenos Aires62200116JPGQ_PAYMENT_0016304584D",
                        "expirationDate": "2025-03-26T17:23:14.099Z",
                        "amount": 10.0,
                        "concept": "test-jpgq", 
                        "businessUnitName": "ARBET",
                        "cashier": "ARBET ",
                        "externalReference": "JPGQ_PAYMENT_001",
                        "isEnabled": true
                    }

Campo	Tipo	Descripción
id	String	Unique identifier assigned to the preorder
qrCode	String	The generated QR code string that can be rendered for payment
expirationDate	String	When the QR code will expire and become invalid
amount	String	The payment amount in the default currency
concept	String	Description or identifier for the payment
businessUnitName	String	Name of the business unit receiving payment
cashier	String	Name of the cashier/point of sale
externalReference	String	External reference ID for tracking
isEnabled	String	Whether the QR code is currently active and usable

Posibles Errores

Código	Descripción
400	Parámetros de solicitud inválidos
401	No autorizado - Token inválido o faltante
403	Prohibido - Permisos insuficientes

Notificaciones Webhook

El webhook de notificaciones se llama cuando ingresa un pago ya sea por una transferencia,un pago de QR o pago con tarjeta.

O tambien cuaando se realiza la conciliacion automatica de la pre-orden.

Payload del Webhook

                    {
                        "Concepto": "1234567890",
                        "Referencia": "0000004053",
                        "Monto": 1000,
                        "MontoNeto": 937.2,
                        "Tarifas": 51.9,
                        "Impuestos": 10.9,
                        "FechaCreacion": "11/19/2020 16:40:20",
                        "FechaConfirmacion": "11/19/2020 16:40:23",
                        "FechaAcreditacion": "04/21/2021 14:34:53", 
                        "Estado": "APROBADO",
                        "MetodoPago": "TARJETA", 
                        "Operacion": "COBRANZA TARJETA",
                        "NombreCompletoEmisor": "TOTAL COIN", 
                        "EmailEmisor":"@totalcoin.com", 
                        "NombreCompletoReceptor": "TOTAL COIN", 
                        "EmailReceptor": "@totalcoin.com", 
                        "CuilCuitEmisor": "11111111",
                        "CuilCuitReceptor": "11111111", 
                        "BarCode": null,
                        "CbuOrigen": "", 
                        "CvuOrigen": null, 
                        "Tarjeta": "VISA",
                        "Cuotas": "02", 
                        "ReferenciaMerchant": null
                    }

Los campos mas importantes de ese body son:

Campo	Descripción
Referencia	Numero de referencia interno y unico de la transaccion de Totalcoin
Monto	Monto
Estado	Ultimo estado de la operacion
ReferenciaMerchant	IdOperacion del merchant

Configuración de Webhook: Contacte al departamento técnico para configurar los endpoints de webhook y definir la seguridad de los mismos.