Visão geral

Introdução

O PanamahSDK é dividido em três partes: PanamahStream, PanamahAdmin e os modelos de dados prefixados com Panamah, e. g.: PanamahLoja ou PanamahProduto.

• PanamahStream: API de manipulação dos dados. Permite o envio ou remoção de dados através dos métodos save e delete, também disponibilizando a leitura de documentos fiscais através dos métodos readNFe e readNFeDirectory. A leitura de documentos fiscais os transforma em modelos de dados, permitindo que o software apenas complemente propriedades que não são enviadas para SEFAZ, como por exemplo, o id da seção de um produto. Além disso, o Stream possui hooks que são úteis tanto na validação quanto na adição de informações.

• PanamahAdmin: API de gerenciamento administrativo. Permite a criação e leitura de assinantes.

• Modelos de dados: Os modelos de dados são utilizados pelas APIs para executar ações no servidor. Eles são a implementação da estrutura dos dados no Panamah, porém são validados localmente antes de serem salvos ou deletados, permitindo agilidade e evitando requisições desnecessárias.

Assinantes são os clientes que adquirem o software da empresa parceira.

Empresas parceiras consomem os serviços do Panamah.

Credenciais e tokens

Todos os parceiros recebem um par de tokens de autenticação chamados AuthorizationToken e Secret, que são usados para autorizar o uso das APIs do SDK. Esses tokens devem ser mantidos de forma segura, sob o risco de uso indevido por terceiros.

Execução contínua do PanamahStream

O fluxo de envio dos dados pelo PanamahStream se dá de forma contínua após a sua inicialização pelo método init que recebe os tokens de autenticação e o id do assinante. Esse fluxo é executado de forma assíncrona através de intervalos agendados continuamente. Operações de salvamento ou deleção são escritas no disco em lotes que tem limite de tempo (5 minutos) e tamanho (5 KB). Quando atingido qualquer limite, uma requisição contendo as operações é disparada para o servidor. Devido a natureza assíncrona do fluxo de envios, é essencial que o método flush seja chamado no fim da execução da aplicação, evitando que dados que foram salvos no lote corrente e ainda não atingiram um limite, sejam enviados apenas na próxima execução da aplicação.

Importante: os lotes são armazenados dentro do diretório .panamah. Este diretório é criado automaticamente, bem como a sua estrutura, não sendo recomendável a remoção ou alteração de seu conteúdo, sob o risco de perda de dados.

Hooks e eventos

O PanamahStream extende o EventEmitter para emitir os seguintes eventos:

• before_save: Executado antes da validação que precede o salvamento do modelo. Pode ser usado para complementar o modelo com dados novos caso a chamada do save aconteça em um loop simples de leitura, ou depois de salvar uma lista de documentos fiscais. Também é possível cancelar a operação de forma segura.
• before_delete: Executado antes da validação que precede a deleção do modelo. Também é possível cancelar a operação de forma segura.
• error: Executado quando qualquer exceção acontece no processamento assíncrono do PanamahStream.

Tratando recursos pendentes

O PanamahStream dispõe do método de getPendingResources que retorna uma lista de modelos cujos dados completos não foram enviados para o Panamah, porém foram referenciados por modelos enviados anteriormente. Por exemplo: um produto Coca-Cola (id: 111) pertence a seção Bebidas (id: 999). Este produto foi salvo utilizando o modelo PanamahProduto com a devida propriedade secaoId preenchida com 999, por motivo indeterminado, o serviço do parceiro não enviou a seção Bebidas (999) usando o modelo PanamahSecao. Executando o método getPendingResources, uma lista contendo apenas um modelo PanamahSecao seria retornada com somente a propriedade id preenchida com 999. Caberia ao software do parceiro percorrer a lista, preencher o restante dos dados e salvar os modelos com o PanamahStream.

Importante: A pendência do recurso leva até 5 minutos para ser resolvida após o envio dos dados corretos.