Avançar para o conteúdo principal

Interface do sistema de ficheiros

DEVELOPMENT
  • Atualizado

Este artigo descreve como utilizar a interface de ficheiros do serviço fiscal.

Pré-requisitos

  • FiskalClient a partir da versão 1.2.11
  • FiscalClient como serviço (as implementações nuget não são suportadas)

Países suportados

Atualmente, apenas os países abaixo indicados são suportados através da interface de ficheiros:

  • Áustria
  • Dinamarca (a partir da versão 1.3)

Informações adicionais

A interface de ficheiros suporta apenas uma parte muito reduzida das funcionalidades do client fiscal para a transmissão dos dados necessários à fiscalização. Caso sejam necessários comandos mais específicos, o serviço pode ainda ser integrado com ferramentas como o CURL através da interface REST. No entanto, este aspeto não é abordado no presente artigo.

Ativação

A interface do sistema de ficheiros pode ser ativada da seguinte forma:

  • Definindo o caminho para a monitorização no ficheiro appsettings.json.
  • Criando um diretório em C:\ProgramData\RetailForce\Fiscal web service com o nome «fileSystemInterface».

Atenção: Para ativar o sistema, o serviço deve ser reiniciado após estas configurações.

appsettings.json

"AppSettings": {
  ...,
  "FileSystemInterfacePath": "c:/temp/filesysteminterface",
  ...
}

As entradas anteriores e posteriores não estão incluídas no exemplo. «c:\temp\filesysteminterface» é o caminho monitorizado.

Nota: A pasta monitorizada deve ser uma pasta local. As unidades de rede não são suportadas, uma vez que os sistemas de monitorização de ficheiros muitas vezes não funcionam de forma fiável neste contexto.

Como funciona

A interface de ficheiros do serviço fiscal monitoriza um diretório à procura de novos ficheiros com uma determinada estrutura de nomes. Assim que for criado neste diretório um novo ficheiro que corresponda às convenções de nomenclatura, este é processado.

Atenção: No caso de ficheiros de maior dimensão, é aconselhável gravar primeiro o ficheiro no diretório como um ficheiro temporário e, em seguida, renomeá-lo para o nome de ficheiro correto utilizando o comando RENAME.

Procedimento

O procedimento é o seguinte:

  1. O ficheiro é transferido para o diretório e reconhecido (*.request)
  2. O ficheiro está a ser processado
  3. O ficheiro *.response ou *.error é guardado no diretório «response» (subdiretório do diretório de importação) (com o mesmo nome de ficheiro antes da extensão).

Exemplo

  1. 20220308135010236.document.request é transferido
  2. O ficheiro está a ser processado
  3. O ficheiro response/20220308135010236.document.response foi guardado. 

ou, em caso de erro

  1. 20220308135010236.document.request foi transferido
  2. O ficheiro está a ser processado
  3. O ficheiro response/20220308135010236.document.error foi guardado. 

Responsabilidades

Os ficheiros de pedido processados são movidos para o subdiretório «processed» pela interface de ficheiros.

A interface de ficheiros nunca eliminará quaisquer ficheiros. No entanto, recomenda-se que os ficheiros mais antigos (reconhecíveis pela sua data) sejam arquivados após um determinado período de tempo.

Garantir a sequência correta

A sequência de processamento é garantida por um nome único e ordenável do ficheiro.

Estrutura do nome do ficheiro

AAAAMMDDHHNNSSZZZ.{tipo}.request

AAAA = Ano (2022), intervalo de valores: 2022-3000

MM = Mês (03 para março), intervalo de valores: 01-12

DD = Dia (02 para o dia 2 do mês), intervalo de valores: 01-31

HH = Hora no formato de 24 horas, intervalo de valores: 00-23

NN = Minutos (04 para 4 minutos), intervalo de valores: 00-59

SS = Segundos (05 para 5 segundos), intervalo de valores: 00-59

ZZZ = Milissegundos (010 para 10 milissegundos), intervalo de valores: 000-999

Tipo

{type} indica o tipo do pedido; existem os seguintes tipos:

  • document — para transmitir um recibo
  • validateDocument — para validar um recibo
  • command — para executar um comando

Documentação do tipo/modelo

Para mais informações sobre o modelo do documento e as respostas correspondentes, consulte a Documentação do Modelo de Objetos e a documentação swagger do Client Fiscal (http://localhost:7678/swagger/index.html).

O retorno de erro é o mesmo para todos os tipos: a exceção que foi lançada é devolvida no ficheiro de retorno (*.error).

Tipo «document» — transmissão de recibos

O conteúdo do ficheiro, neste caso, é um documento no formato de documento da RetailForce (Document).

O formato do documento pode ser consultado na Documentação do Modelo de Objetos ou na documentação swagger do serviço fiscal (http://localhost:7678/swagger/index.html).

Resposta

A fiscalResponse do respetivo país é transmitida no ficheiro de resposta.

Tipo «validateDocument» — validação de um recibo

O conteúdo do ficheiro, neste caso, é, tal como no tipo «document», um documento no formato de documento RetailForce.

Resposta

No ficheiro de resposta, é apresentada uma lista de possíveis erros (e avisos) resultantes da validação.

Tipo «createClient» — criação de um FiscalClient

O conteúdo do ficheiro, neste caso, é um FiscalClient no formato JSON (ver documentação).

Resposta

«OK» quando o pedido tiver sido processado com sucesso.

Tipo «createClientByCloud» — criação de um FiscalClient com dados da Cloud

O conteúdo do ficheiro é um documento JSON com a seguinte estrutura:

{
  "CompanyIdentification": 
  {
    "Type": 0, 
    "Identification": "UID"
  },
  "StoreNumber": "001",
  "TerminalNumber": "01",
  "ApiKey": "{ApiKey}",
  "ApiSecret": "{ApiSecret}"
}

Retornar

O uniqueClientId do cliente criado.

Tipo «restoreClientByCloud» — restauração de um FiscalClient com dados da Cloud

O conteúdo do ficheiro é um documento JSON com a seguinte estrutura:

{
  "CompanyIdentification": 
  {
    "Type": 0, 
    "Identification": "UID"
  },
  "StoreNumber": "001",
  "TerminalNumber": "01",
  "ApiKey": "{ApiKey}",
  "ApiSecret": "{ApiSecret}"
}

Resultado

O uniqueClientId do cliente restaurado.

Tipo «getClientId» — Pesquisar um client e obter o ID

Disponível a partir da versão: V1.2.12

O conteúdo do ficheiro é um documento JSON com a seguinte estrutura:

{
  "CompanyIdentification": 
  {
    "Type": 0, 
    "Identification": "UID"
  },
  "StoreNumber": "001",
  "TerminalNumber": "01"
}

Retorno

O uniqueClientId do cliente criado.

Digite «InitializeClient» — inicialização do FiscalClient

O conteúdo do ficheiro é um documento JSON com a seguinte estrutura:

{
  "UniqueClientId": "9607625f-1147-43a4-bf05-49319acbd9f6",
  "BookDate": "2022-03-10T08:52:33.3556282Z",
   "User": 
   {
     "Id": "1",
     "Caption": "Test",
     "LastName": "Test",
     "FirstName": "Test",
     "DateOfEntry": "2022-03-10T08:52:33.3556282Z"
  }
}

Os dados apresentados são dados de teste e devem ser substituídos pelos dados corretos.

Retorno

Vazio ou um objeto fiscalResponse do respetivo país.

Tipo «CloudConnect» — inicialização da ligação à nuvem

O conteúdo do ficheiro é um documento JSON com a seguinte estrutura:

{
  "UniqueClientId": "9607625f-1147-43a4-bf05-49319acbd9f6",
  "ApiKey": "{ApiKey}",
  "ApiSecret": "{ApiSecret}",
  "PersistDays": {days} // optional, days until credentials are stored 
}
Atenção: as credenciais são armazenadas encriptadas no disco. A persistência das credenciais constitui um potencial risco de segurança.

Retorno

«OK» quando o pedido tiver sido processado com sucesso.

Tipo «AuditLog» — transmissão de uma entrada no registo de auditoria

O conteúdo do ficheiro é um objeto JSON com a seguinte estrutura:

{
  "RecordDateTime": "2022-03-11T15:17:57.9859527",
  "UniqueClientId": "9607625f-1147-43a4-bf05-49319acbd9f6",
  "LogEntryType": 200,
  "Message": "OpenDrawer",
  "DocumentGuid": null,
  "User": null
}

Retornar

Em branco ou um objeto «fiscalResponse» do respetivo país (se exigido nesse país).

Tipo «digitalReceipt» — Transmissão de recibo digital

Este tipo de ficheiro pode ser utilizado para enviar um recibo digital. 

O conteúdo do ficheiro é um objeto JSON com a seguinte estrutura:

{
"UniqueClientId": "d5ecc344-e37a-40c6-bed4-a6b1e60e68c8",
"ReceiptMetaData": {
"DocumentType": 0,
"CustomDocumentType": null,
"DocumentGuid": "2394fef4-2339-459a-817e-e4cd86ce23f6",
"DocumentNumber": "1",
"DocumentId": "CS_01_01_1",
"BookDate": "2021-11-17T06:45:03.8203317",
"Amount": 141.0,
"Partner": null,
"Users": null,
"ProcessId": null,
"CancelledDocumentGuid": null,
"ItemIdArray": [
"1231",
"SW4471"
],
"ItemCodeArray": null
},
"PdfDataBase64": "JVBERi0xLjcKJeLjz9MKMSAwIG9iaiAKPDwKL0NvbG9yU3Bh..."
}

A propriedade «ReceiptMetaData» corresponde ao objeto ReceiptMetaData que também deve ser transmitido ao efetuar a chamada através da interface REST. 

No exemplo, o stream de dados PDF foi abreviado por ...

Retorno

No ficheiro de resposta, é devolvido um link de QrCode (na forma de string) para apresentação ao cliente.

Configuração

A interface do sistema de ficheiros pode ser ativada na configuração do client através de um valor no campo «FiscalClient.FileSystemInterfacePath». Se este campo estiver vazio (por predefinição), a interface de ficheiros não estará ativa.

Este artigo foi traduzido automaticamente.

Artigos relacionados

Comentários

0 comentários

iniciar sessão para comentar.

Powered by Zendesk