POST /api/v1/transactions/storeDocument – RetailForce

Con el método

POST /api/v1/transactions/storeDocument

, se transmite un documento al servicio fiscal y se almacena allí.

Resultado

Si el procesamiento se realiza con éxito (200), el cliente del servicio fiscal correspondiente responde con un «fiscalResponse».

Uso

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

Requisitos previos

La llamada a storeDocument debe ir precedida de la llamada al punto final PUT /api/v1/transactions/createDocument
- Los datos de la respuesta de createDocument deben integrarse en la estructura JSON de storeDocument. Consulte la sección siguiente.

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/storeDocument sin necesidad de llamar previamente 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 `storeDocument` 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 figurar en la estructura JSON transmitida con `storeDocument`. Estos campos contienen valores generados por el hardware TSE fiscal obligatorio (en Alemania, «TSE») 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 «storeDocument», estos campos deben pasarse con

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

¡sin «isation»! Tenga en cuenta también lo siguiente: Transacción no iniciada

Ejemplo:

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

{
   "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"
      }
   ]
}

fiscalResponse

La fiscalResponse de una operación «storeDocument» 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 storeDocument 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 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: Se debe ejecutar «createDocument» antes de «storeDocument».	-
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 Solución de problemas: Ejecute POST /api/v1/transactions/validateDocument o POST /api/v1/transactions/validateDocumentString para obtener un análisis más detallado del error.	-

Este artículo ha sido traducido automáticamente.