Avançar para o conteúdo principal

POST /api/v1/transactions/cancelDocument

Harald Krondorfer
  • Atualizado

Com o

  • função POST /api/v1/transactions/cancelDocument

, o cancelamento de uma transação é transmitido ao serviço fiscal e aí armazenado. É utilizado para abortar uma transação antes da sua conclusão. Por exemplo:

  • o cliente pretende comprar alguns artigos na loja
  • o caixa começa a digitalizar os artigos (o POS envia PUT /api/v1/transactions/createDocument)
  • o cliente apercebe-se de que perdeu a carteira e não pode efetuar a compra
  • o caixa interrompe a transação e elimina todos os artigos digitalizados (o POS envia um POST /api/v1/transactions/cancelDocument para encerrar a transação que tinha sido iniciada com o PUT /api/v1/transactions/createDocument)

Resultado

Se o processamento for bem-sucedido (200), o respetivo client do serviço fiscal responde com uma «fiscalResponse» e regista o abandono da transação.

Utilização

  • Sempre que um documento for encerrado no sistema de registo eletrónico (caixa registadora) através do seu cancelamento.

Pré-requisitos

Nota: Os documentos que não contenham dados de pagamento (por exemplo, relatório X ou Z,...) podem ser transmitidos para o ponto de extremidade POST /api/v1/transactions/cancelDocument sem uma chamada prévia de createDocument . No entanto, recomendamos que chame sempre um createDocument como primeiro passo.

Processo de transmissão

Conforme descrito, um `cancelDocument` requer um `createDocument` prévio. A `fiscalResponse` do `createDocument` contém os seguintes campos:

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

A informação contida nestes campos deve constar na estrutura JSON transmitida com o `cancelDocument`. Estes campos contêm valores gerados por um hardware fiscal obrigatório (dispositivo técnico de segurança «TSE» na Alemanha) e são utilizados para o encadeamento de transações.

Atenção: Tenha em conta as seguintes características especiais:

A «fiscalResponse» do «createDocument» devolve os campos «fiscalisationDocumentNumber» e «fiscalisationDocumentRevision». No «cancelDocument», contudo, estes campos devem ser transmitidos com

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

sem «isation»! Tenha também em atenção: Transação não iniciada

Exemplo:

O exemplo seguinte mostra um recibo simples para a Alemanha (documentType = [0] = recibo), que é enviado para o ponto 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: O exemplo acima mostra um documento (simples) completo. Com um «cancelDocument», não é necessário passar um documento completo. As informações mínimas, tal como apresentadas no exemplo seguinte, são suficientes.

Exemplo de informações mínimas 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

A fiscalResponse para um cancelDocument deve ser armazenada na base de dados do POS para efeitos de referência.

A fiscalResponse contém:

  • informações genéricas
  • informações específicas do país

Exemplo 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="
   }
}

Informações genéricas

Estas podem ser encontradas na área do header da «fiscalResponse».

Nota:

  • O conteúdo do campo «fiscalisationDocumentNumber» deve ser impresso no documento (DE).
  • O conteúdo do campo «PrintMessage» deve ser impresso no recibo.

Informações específicas por país

As informações específicas por país são fornecidas na área «AdditionalFields» e contêm dados que devem ser impressos no recibo (por exemplo, código QR ou, em alternativa, dados TSE na Alemanha).

Consulte os exemplos de documentos do respetivo país.

Nota: Se for devolvido o valor «-1» na fiscalResponse do cancelDocument no campo

"fiscalDocumentNumber": -1,

the client recognized the corresponding document as non-fiscal.

Resposta

Respostas possíveis:

Código Descrição Exemplo
200

O documento de cancelamento foi transmitido com sucesso e sem erros e guardado no documentStore.

 fiscalResponse
404

Alemanha: não foi possível encontrar o fiscalDocumentNumber especificado. A transação com o fiscalDocumentNumber especificado ainda não foi criada (iniciada).

Resolução de problemas:

 -
406

O tipo de documento transmitido não é suportado

Resolução de problemas:

  • Atribuição do tipo de documento correto
 -
422

O conteúdo do documento está vazio ou incorreto

Resolução de problemas: 

  • Execute
    POST /api/v1/transactions/validateDocument ou
    POST /api/v1/transactions/validateDocumentString
    para uma análise mais detalhada do erro
 -

 

Este artigo foi traduzido automaticamente.

Artigos relacionados

Comentários

0 comentários

iniciar sessão para comentar.

Powered by Zendesk