Saltar al contenido principal

POST /api/v1/transactions/cancelDocument

Harald Krondorfer
  • Actualización

Mediante el método

  • función POST /api/v1/transactions/cancelDocument

se transmite al servicio fiscal la cancelación de una transacción, que queda almacenada allí. Se utiliza para abandonar una transacción antes de que se complete. Por ejemplo:

  • el cliente desea adquirir varios artículos en el punto de venta
  • el cajero comienza a escanear los artículos (el TPV envía PUT /api/v1/transactions/createDocument)
  • el cliente advierte que ha extraviado su cartera y no puede completar la compra
  • el cajero detiene la transacción y elimina todos los artículos escaneados (el TPV envía POST /api/v1/transactions/cancelDocument para cerrar la transacción que se abrió al utilizar PUT /api/v1/transactions/createDocument)

Resultado

Si el procesamiento se realiza con éxito (código 200), el cliente del servicio fiscal correspondiente responde con un «fiscalResponse» y registra la cancelación de la transacción.

Uso

  • Cada vez que se cierra un documento en el sistema de registro electrónico (caja registradora) mediante su cancelación.

Requisitos previos

Nota: Los documentos que no contengan datos de pago (por ejemplo, el informe X o Z, etc.) pueden transmitirse al punto final POST /api/v1/transactions/cancelDocument sin necesidad de una llamada previa a createDocument . No obstante, le recomendamos que siempre llame a createDocument como primer paso.

Proceso de transmisión

Tal y como se ha descrito, una llamada a `cancelDocument` requiere una llamada previa a `createDocument`. La respuesta `fiscalResponse` de `createDocument` contiene los siguientes campos:

"fiscalisationDocumentNumber": 0,
"fiscalisationDocumentRevision": 0,
"fiscalDocumentStartTime": 0,

La información de estos campos debe incluirse en la estructura JSON transmitida con «cancelDocument». Estos campos contienen valores generados por un dispositivo fiscal obligatorio (dispositivo técnico de seguridad «TSE» en Alemania) y se utilizan para el encadenamiento de transacciones.

Atención: Tenga en cuenta las siguientes características especiales:

La «fiscalResponse» de «createDocument» devuelve los campos «fiscalisationDocumentNumber» y «fiscalisationDocumentRevision». Sin embargo, en «cancelDocument», estos campos deben pasarse con

"fiscalDocumentNumber": 24,
"fiscalDocumentRevision": 1,

¡sin «isation»! Tenga en cuenta también lo siguiente: Si la transacción no se ha iniciado

Ejemplo:

El siguiente ejemplo muestra un recibo sencillo para Alemania (documentType = [0] = recibo), que se envía al punto final POST /api/v1/transactions/cancelDocument.

{
   "uniqueClientId": "c1062c55-57c4-4ed2-9c53-aff1762326a4",
   "documentGuid": "7d4a7761-e9e9-4759-8591-ed147a581da4",
   "documentId": "HAM01-00010329",
   "documentNumber": "00010329",
   "createDate": "2023-04-18T21:34:45",
   "bookDate": "2023-04-18T21:34:46",
   "cancellationDocument": false,
   "isTraining": false,
   "documentType": 0,
   "user": {
      "id": "1234",
      "caption": "1234"
   },
   "fiscalDocumentNumber": 2853,
   "fiscalDocumentStartTime": 1681803100,
   "fiscalDocumentRevision": 1,
   "Positions": [
      {
         "positionNumber": 0,
         "netValue": 10.66,
         "grossvalue": 12.90,
         "taxValue": 2.24,
         "quantity": 1,
         "itemId": "1101202930050",
         "itemCaption": "Pizza Margherita",
         "cancellationPosition": "false",
         "type": "0",
         "businessTransactionType": 0,
         "vatPercent": 19,
         "vatIdentification": 1,
      }
   ],
   "Payments": [
      {
         "Amount": 12.90,
         "paymentType": "cash",
         "uniqueReadablePaymentIdentifier": "Cash",
         "caption": "Bar+Euro",
         "currencyIsoCode": "EUR"
      }
   ]
}
Nota: El ejemplo anterior muestra un documento (sencillo) completo. Al invocar `cancelDocument`, no es necesario enviar un documento completo; basta con la información mínima que se muestra en el siguiente ejemplo.

Ejemplo de información mínima para «cancelDocument»:

{
   "uniqueClientId": "c1062c55-57c4-4ed2-9c53-aff1762326a4",
   "documentGuid": "{bdf8b5e9-5634-4c02-afad-543a7c480111}",
   "documentId": "100001",
   "documentNumber": "00002",
   "createDate": "2022-12-22T10:06:03",
   "bookDate": "2022-12-22T10:06:03",
   "user": {
      "id": "1234",
      "caption": "1234"
   },
   "fiscalDocumentNumber": 2938,
   "fiscalDocumentStartTime": "1671699962",
   "fiscalDocumentRevision": 1
   }
}

fiscalResponse

La fiscalResponse de un cancelDocument debe almacenarse en la base de datos del TPV a efectos de referencia.

La fiscalResponse contiene:

  • información genérica
  • información específica del país

Ejemplo de «fiscalResponse»:

{
   "fiscalCountry": "[0] = Germany",
   "fiscalisationDocumentNumber": 52,
   "fiscalisationDocumentRevision": 2,
   "fiscalDocumentStartTime": 1674819139,
   "processStartTime": 0,
   "errorDescription": null,
   "cashRegisterId": "00345-00345",
   "signature": "pCeGi98gNNhshcGJkbw0DwtSzuJkaawON8l5QwsFDEaDHOyYK2aNVO4ZAlpkYYnub7oxM/2R1/KB36UzmOQwew==",
   "userMessage": null,
   "printMessage": "***Test***",
   "requestTime": "2023-01-27T12:34:21.3088836+01:00",
   "requestCompletionTime": "2023-01-27T12:34:22.4379009+01:00",
   "AdditionalFields": {
      "QrCodeDataString": "V0;00345-00345;Kassenbeleg-V1;Beleg^13.90_0.00_0.00_0.00_0.00^13.90:Unbar;52;197;2023-01-27T11:32:19.000Z;2023-01-27T11:34:20.000Z;ecdsa-plain-SHA256;unixTime;pCeGi98gNNhshcGJkbw0DwtSzuJkaawON8l5QwsFDEaDHOyYK2aNVO4ZAlpkYYnub7oxM/2R1/KB36UzmOQwew==;BNHckCuXF2fEktIp8qwtnMLLgvpJDX6wEOqFENlHXZpekBHxHniQh9gbigjWS9UbCwZSrOTJTMK7WiV5owAfXkk=",
      "TransactionStartTime": 1674819139,
      "TransactionEndTime": 1674819260,
      "ProcessData": "Beleg^13.90_0.00_0.00_0.00_0.00^13.90:Unbar",
      "ProcessType": "Kassenbeleg-V1",
      "TseSerial": "e5f5836a57c50c526d4bed37f18823608f2f44e2c98cab73278a7676c5ea0885",
      "TseTimeFormat": "unixTime",
      "TseHashAlgorithm": "ecdsa-plain-SHA256",
      "TsePublicKey": "BNHckCuXF2fEktIp8qwtnMLLgvpJDX6wEOqFENlHXZpekBHxHniQh9gbigjWS9UbCwZSrOTJTMK7WiV5owAfXkk=",
      "TseSignatureCounter": 197,
      "TseCertificate": "MIIB0jCCAVmgAwIBAgIhAOX1g2pXxQxSbUvtN/GII2CPL0TiyYyrcyeKdnbF6giFMAoGCCqGSM49BAMDMDExFTATBgNVBAoTDGZpc2thbHkgR21iSDEYMBYGA1UEAxMPZmlza2FseSBUZXN0IENBMB4XDTIyMTAzMDEyMjgzMloXDTIzMTAzMDEyMjgzMlowMjEVMBMGA1UEChMMZmlza2FseSBHbWJIMRkwFwYDVQQDExBmaXNrYWx5IFRlc3QgVFNFMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0dyQK5cXZ8SS0inyrC2cwsuC+kkNfrAQ6oUQ2Uddml6QEfEeeJCH2BuKCNZL1RsLBlKs5MlMwrtaJXmjAB9eSaNBMD8wDgYDVR0PAQH/BAQDAgeAMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUlllBymQBup6ldKGojZVpZtWG5tQwCgYIKoZIzj0EAwMDZwAwZAIwEFsoSON9cIBqA5d9vsGI2jSjDlZxHokDvJ4yBmayvigrDbdhMYe3hw3HyQbO2B/FAjBXSVNbYR6Wg2TVzL9BhCla+tewRDGcs6vnetJ4i3VRtya1+ejt+vRjWnb/RUyo0Uw="
   }
}

Información genérica

Estos datos se encuentran en el header de la «fiscalResponse».

Tenga en cuenta lo siguiente:

  • El contenido del campo «fiscalisationDocumentNumber» debe figurar impreso en el documento (DE).
  • El contenido del campo «PrintMessage» debe figurar impreso en el recibo.

Información específica de cada país

La información específica de cada país se proporciona en el área «AdditionalFields» y contiene datos que deben imprimirse en el recibo (por ejemplo, el código QR o, alternativamente, los datos TSE en Alemania).

Consulte los ejemplos de documentos del país correspondiente.

Nota: Si se devuelve el valor «-1» en la fiscalResponse de la función «cancelDocument» en el campo

"fiscalDocumentNumber": -1,

el cliente ha identificado el documento correspondiente como no fiscal.

Respuesta

Respuestas posibles:

Código Descripción Ejemplo
200

El documento de cancelación se ha transmitido correctamente y sin errores, y se ha almacenado en el documentStore.

 fiscalResponse
404

Alemania: no se ha podido encontrar el fiscalDocumentNumber especificado. La transacción con el fiscalDocumentNumber especificado aún no se ha creado (iniciado).

Resolución de problemas:

 -
406

El tipo de documento transmitido no es compatible.

Solución de problemas:

  • Asignación del tipo de documento correcto
 -
422

El contenido del documento está vacío o es incorrecto

Resolución de problemas: 

  • Ejecute
    el método HTTP POST /api/v1/transactions/validateDocument o
    el método HTTP POST /api/v1/transactions/validateDocumentString
    para obtener un análisis más detallado del error.
 -

 

Este artículo ha sido traducido automáticamente.

Artículos relacionados

Comentarios

0 comentarios

Inicie sesión para dejar un comentario.

Tecnología de Zendesk