O PlugStorage foi desenvolvido para simplificar o armazenamento de arquivos XML e facilitar o compartilhamento dessas informações entre o cliente, a Software House (parceiro) e o contador.
Com o PlugStorage, você pode:
- Armazenar notas fiscais enviadas;
- Armazenar notas fiscais recebidas por e-mail e notas destinadas (desde que utilize um Certificado A1);
- Registrar inutilizações;
- Manifestar notas destinadas.
Neste artigo, explicaremos os primeiros passos para começar a usar a API e detalharemos o fluxo principal para aproveitar ao máximo o PlugStorage.
Neste artigo, você encontrará:
- Interfaces Disponíveis
- Criando a conta de parceiro
- Obtendo o token de autenticação
- Personalizando o PlugStorage
- Cadastrando o Cliente
- Personalizando o Cliente
- Configurando certificado digital para busca de destinadas e manifesto de notas
- Vinculando o contador do cliente
- Integrando via API
- Montando uma Requisição
Interfaces Disponíveis
O PlugStorage oferece três interfaces principais: Parceiro, Cliente e Contador. Cada uma delas foi desenvolvida para atender a necessidades específicas de gestão e acesso às informações. Confira abaixo os detalhes de cada interface:
Parceiro
A interface do Parceiro é o painel principal de gestão, permitindo:
- Acesso a todos os clientes vinculados;
- Visualização de todas as notas enviadas pelos clientes;
- Configuração de White Label e do próprio servidor de e-mail;
- Gerenciamento completo das configurações disponíveis.
Para mais detalhes, consulte nossa documentação sobre o Portal Web.
Cliente
A interface do Cliente oferece funcionalidades simplificadas e práticas, incluindo:
- Acesso às configurações de conta;
- Consulta às notas enviadas ou emitidas contra o seu CNPJ (notas destinadas);
- Opção para upload de arquivos SPED, possibilitando o envio ao contador.
Contador
A interface do Contador é bem mais reduzida, com foco em:
- Acesso às configurações da própria conta;
- Visualização das notas fiscais dos clientes que cadastrarem seu e-mail como contador;
- Download dos arquivos SPED desses clientes.
Essas interfaces garantem um fluxo organizado e eficiente para atender as necessidades de cada tipo de usuário.
Criando a conta de parceiro
Para realizar seu cadastro como parceiro no PlugStorage, você precisa criar a sua conta em nossa página de login e clicar em "CRIAR UMA CONTA"
Na tela seguinte, você precisa preencher as informações solicitadas
Após concluir o cadastro, é necessário acessar o e-mail informado e ativar a conta clicando no link enviado.
Observação: Se a conta for criada utilizando um CNPJ sem contrato ativo conosco, será gerada uma conta trial. Nesse caso:
- O acesso do parceiro será desativado após 30 dias;
- Os acessos dos clientes vinculados à Software House também serão desativados.
Ao tentar acessar o painel do Parceiro ou do Cliente após o período de teste, serão exibidas as seguintes mensagens:
Token de Integração
Para utilizar as rotas da API, é imprescindível obter o token de integração, que será usado para autenticar todas as requisições no PlugStorage.
Para visualizar o token:
- Acesse a interface de Parceiro;
- Navegue até Configurações > Dados da Conta;
- Localize o campo “Token de Integração”.
Esse token é essencial para o funcionamento da integração com a API.
Personalizando o PlugStorage
No PlugStorage existem diversas configurações, algumas delas estão diretamente relacionadas ao visual e configurações de e-mail, como o White Label e as configurações de SMTP. Com essas configurações você pode deixar o PlugStorage com a cara da sua empresa e passar ao seu cliente a sensação de não sair do seu meio.
White Label
Com o White Label da TecnoSpeed, você pode:
- Alterar o link de acesso dos seus clientes;
- Personalizar as logos exibidas nas páginas e nos e-mails.
Para instruções detalhadas sobre como realizar essas configurações, consulte nosso post sobre as configurações da Software House.
Servidor SMTP
As configurações de SMTP permitem que os e-mails enviados pelo PlugStorage sejam exibidos como enviados diretamente por sua empresa. Basta configurar seu e-mail na interface, e todas as mensagens terão o endereço configurado como remetente.
Mais informações sobre a configuração do Servidor SMTP estão disponíveis em nosso post sobre as configurações da Software House.
Essas funcionalidades ajudam a reforçar a identidade da sua marca e a melhorar a experiência do cliente.
Cadastrando o Cliente
Para iniciar o envio de XMLs ao PlugStorage e garantir que seus clientes tenham acesso a esses arquivos posteriormente, é necessário cadastrá-los na plataforma. Após o cadastro, o cliente também terá acesso a uma interface web, onde poderá realizar configurações e personalizar sua conta.
Formas de Cadastro
O cadastro dos clientes pode ser realizado de duas maneiras:
- Pela interface do Parceiro: Uma opção prática e intuitiva para gerenciar diretamente os cadastros.
- Pela API: Ideal para integrações automatizadas, permitindo que o processo de cadastro seja incorporado ao seu sistema.
Escolha a opção que melhor atende às suas necessidades e comece a integrar seus clientes ao PlugStorage.
Cadastrando através da interface
Para realizar o cadastro pela interface de parceiro, você precisa acessar o menu “Clientes” e clicar em “Novo Cliente”, após isso será mostrada a tela abaixo:
Na tela de cadastro, basta preencher as informações solicitadas.
Abaixo, destacamos duas opções importantes:
-
Permitir acesso caso encerrado:
Se ativada, essa opção permite que o cliente continue acessando a interface para consultar notas fiscais mesmo após o encerramento do contrato. No entanto, ele não poderá enviar novas notas. -
Confirmação de e-mail:
Quando marcada, será enviado um e-mail ao endereço cadastrado para confirmar a criação da conta. Nesse e-mail, o cliente também poderá definir uma senha para acessar a interface.
Certifique-se de preencher os campos corretamente e configurar essas opções de acordo com as necessidades do cliente.
Cadastrando por API
Também é possível cadastrar o cliente via API, onde você irá utilizar uma requisição do tipo Post para enviar todas as informações necessárias para nós. É possível verificar mais detalhes dessa requisição em nossa documentação sobre o cadastro de cliente por API.
Personalizando o Cliente
Na interface do cliente ele pode realizar algumas personalizações que permitem alterar a logo das impressões da DANFE e da DANFCE além de poder alterar os e-mail enviados aos clientes e contadores. Para acessar ambas as configurações, é necessário acessar o menu “Configurações” e depois ir em “Gerais”.
Personalizar DANFE
Tanto para a DANFE quanto para a DANFCE existe um tamanho recomendado da logo, o qual está explícito no portal, basta incluir a nova logo através da opção disponibilizada que será possível ver as impressões das notas com o novo logotipo.
Configurar envio de e-mail
Nas configurações de envio de e-mail é possível escolher o template utilizado no e-mail para informar o recebimento de notas e eventos pelo PlugStorage, também é possível escolher se esse e-mail será enviado automaticamente ao destinatário da nota ou não.
Existem algumas variáveis nesse ambiente que podem ser utilizadas com informações da nota e/ou evento recebido pelo Plug Storage, elas estão listadas ao final da página de personalização.
Configurando certificado digital para busca de destinadas e manifesto de notas
No PlugStorage é possível realizar o cadastro de um certificado do tipo A para que o mesmo possa ser utilizado na busca das notas destinadas do modelo NFe e CTe, e também para manifesto de notas.
Para isso você deve acessar o menu Configurações > Destinadas - DFe (No portal do cliente) ou em Clientes > Configurações DFe (No portal do parceiro), após isto basta preencher os dados solicitados.
A verificação automática é utilizada para constantemente fazer a consulta das destinadas na sefaz de acordo com o tempo escolhido na opção, dessa forma, o cliente irá receber e-mails informando que as destinadas foram consultadas, caso o cliente não queira receber notificação por e-mail, é necessário desmarcar a opção de permitir notificação por e-mail.
A opção “Tipos de Documentos” é utilizada para especificar quais documentos devem ser buscados no sefaz, podendo selecionar NFe, CTe ou Ambos.
Vinculando o contador do cliente
Pensando em facilitar a transferência de dados entre clientes e contador é possível vincular um e-mail de contador no cliente através do menu Configurações > Contador (no painel do cliente) ou Clientes > Vincular Contador (no painel do parceiro), para isto basta cadastrar o e-mail do contador como na imagem:
É possível também escolher a forma de envio das notas para o contador. Existem dois tipos de envio, o Singular, Recorrente e Não enviar e-mail.
No envio singular, uma vez por mês, na data que você selecionar será enviado para o contador todos os XMLs do mês anterior.
No envio recorrente, você escolhe a cada quantos dias você deseja que o e-mail seja enviado.
Integrando via API
Todos os exemplos da utilização da API foram produzidos e testados através do Postman, uma ferramenta que permite realizar requisições de uma forma mais visível, facilitando assim o entendimento das rotinas.
Instalando o Postman
O Postman pode ser baixado e instalado como uma aplicação desktop ou adicionado como uma aplicação do Google Chrome.
Importar a coleção de requisições
Após abrir o aplicativo, para importar uma coleção de requisições, basta clicar no botão "Import", no canto esquerdo da barra superior.
Em anexo, temos um arquivo com as rotas disponíveis. (arquivo disponivel no final da pagina https://atendimento.tecnospeed.com.br/hc/pt-br/articles/4414137187095-Guia-Geral-PlugStorage)
Converter a requisição em código
O Postman possui uma funcionalidade que permite visualizar uma requisição em algumas linguagens. Com a requisição aberta, basta clicar no botão "Code", no canto direito da tela, conforme é mostrado na imagem abaixo.
Após isso, será aberta uma janela com um trecho de código correspondente àquela requisição. Para alterar a linguagem, basta clicar na seta apontada para baixo, no canto superior esquerdo da janela, e selecionar a linguagem desejada.
Montando uma Requisição
Na API do PlugStorage, vamos utilizar 3 tipos de requisições, as do tipo POST, as do tipo GET e as do tipo PUT.
As requisições do tipo POST servem, nesse caso, para o envio das informações para nossa api, para que possamos realizar os tratamentos necessários e inclusão de notas, clientes, contadores e etc.
As requisições do tipo GET servem, nesse caso, para a consulta de informações, que no nosso caso será referente as notas e manifestos.
Já as requisições do tipo PUT servem, nesse caso, para a alteração de registros já existentes em nossa base, como a alteração dos dados de um usuário já cadastrado.
Montando a URL
A URL sempre será no padrão UrlRaiz + rota + parâmetros, sem contar com o cabeçalho da requisição (Headers) e o Body (quando necessário).
A URL raiz do Plug Storage é: https://app.plugstorage.com.br/api/ e as documentações de cada rotas estão disponíveis nos links abaixo:
As rotas V2 são rotas usadas com mais frequência e que passaram por melhorias nos fluxos.
Comentários
0 comentário
Por favor, entre para comentar.