GuidesSuporteAPI Reference

NFe.io

Suggest Edits

A nossa integração do APP NFe.io conecta a sua solução de pagamento Pagar.me com uma solução de emissão de notas fiscais.
Com essa integração completamos ainda mais o fluxo transacional de um pedido em sua loja, qualquer pedido e pagamento gerado em sua loja da pagar.me irá passar pela emissão de nota fiscal no nosso APP, te ajudando a manter o controle desta etapa fiscal e automatizando o processo até o NFe.io.

Pré requisitos para a instalação
Para utilizar o Nfe.io com a Pagar.me é necessário que alguns pré-requisitos sejam atendidos. Dentre eles os mais importantes são:

  • Conta Pagar.me integrada na versão mais atual da nossa API (V5). Caso deseje criar uma conta no Pagar.me, cadastre-se clicando aqui;
  • Conta ativa no Nfe.io.
    Caso queira saber mais sobre o NFe.io você pode acessar o site aqui!
  • Atualmente o aplicativo do NFe.io disponibilizado pela Pagar.me gera apenas Nota Fiscal de Serviço (NFS-e), você deverá ter uma empresa cadastrada para esse produto. Em qualquer outro produto a integração não é suportada.

Etapas da Integração

Configurações no NFe.io

O primeiro passo para realizar esta integração com sucesso é ter uma conta com o NFe.io, ela pode ser criada aqui.

Após estar conectado ao NFe.io é necessário recolher algumas informações importantes para que o Hub consiga se integrar a solução, iremos te mostrar como é fácil e rápido recolher todas as informações necessárias e já utilizar a sua integração!

A primeira informação que iremos pegar no NFe.io será a API KEY da sua conta;
Para isso basta entrar em "Empresa" e no modelo de Nota Fiscal escolhido.

Dentro das empresas você deve escolher a empresa desejada e clicar em "Alterar".

Basta 'rolar' a página até as informações de Chaves de Acesso e copiar a sua "Chave de Acesso", essa será a sua API KEY.

A segunda informação que iremos precisar é o Código de Serviço.

Dentro das configurações da Empresa é possível chegar até essa informação, e basta clicar na pesquisa que você será redirecionado até a Lista de Serviços cadastradas no endereço da sua conta.
A informação que desejamos é o código numérico abaixo do Código de Serviço.

A última informação que precisamos é a Empresa ID.
Ainda nas configurações da empresa é possível pegar a informação da Empresa ID nas informações de Chaves de Acesso e copiar a sua "Empresa ID".

E com essas três informações conseguimos realizar a nossa integração com o Hub!

Integração com o Hub

Agora para efetivarmos a nossa integração da Pagar.me com o NFe.io basta entrar no nosso Hub de aplicativos com a sua conta, clicar no APP NFe.io da categoria 'Financeiro' e clicar em "Integrar com Pagar.me".

Então seremos redirecionados para a configuração da nossa Integração;

Nesta etapa iremos utilizar as três informações que recolhemos no NFe.io, a API KEY, Código de Serviço e Empresa ID.
Ainda assim nas configurações temos alguns campos extras que você deve configurar e iremos explicá-los abaixo.

Vale citar que é possível criar uma lista de empresas em sua instalação e identificá-las, para que você possa definir por qual empresa emitir a Nota Fiscal, caso seja necessário emitir por mais de um CNPJ conforme demanda. Sendo a interação feita via metadata.
Mas a primeira empresa definida na instalação será sempre considerada como empresa default para emissão.

Permissões

Temos uma lista de Ações e Eventos no NFe.io, temos duas ações obrigatórias e cinco opcionais e temos três eventos opcionais, você pode alterá-los caso não queira algum evento ou ação opcional em sua integração.
Mas se você remover permissões de eventos, os recursos associados a eles não serão permitidos.
Por exemplo, se a permissão de Fatura Paga não for habilitada, a emissão de nota fiscal para assinatura não funcionará.

Vale ressaltar que no caso das permissões de Eventos, caso seja assinalado o campo "Cobrança criada" E "Cobrança paga" será criado DUAS notas fiscais, você deve escolher um OU outro, caso queira que a sua nota fiscal seja criada no momento que a cobrança for criada ou no momento que a cobrança for paga.

Campos

  • API Key: Chave de autenticação que será usada para comunicação com a API da Nfe.io;
  • Código de serviço na cidade: Código específico do serviço para seu município que está habilitado em sua inscrição municipal (CCM). Consulte seu contador para saber qual código deve usar;
  • Empresa ID: Identificação da empresa no sistema da NFe.io;
  • Identificador: Identificação da empresa na Pagar.me (a sua escolha), para cenários que você possua mais de uma empresa no ambiente do NFe.io, você poderá criar uma lista de empresas identificá-las;
  • Sempre emitir nota fiscal: Habilita emissão automática após um pedido/fatura paga. Caso esteja desabilitado, será necessário enviar o metadata "nfeio_issuance_enabled: true" para que a notificação seja enviada;
  • Sempre cancelar nota fiscal: Habilita cancelamento automático da nota fiscal após um pedido/fatura cancelada. Caso esteja desabilitado, será necessário enviar o metadata "nfeio_cancellation_enabled: true" para que o cancelamento da cobrança na Pagar.me reflita na nota fiscal;
  • Sempre cancelar cobrança: Habilita cancelamento automático da cobrança na Pagar.me após uma nota fiscal ser cancelada pela plataforma do NFe.io. Caso esteja desabilitado, será necessário enviar o metadata "charge_cancellation_enabled: true" para que o cancelamento da nota fiscal reflita na cobrança na Pagar.me;
  • Sempre cancelar cobrança com nota fiscal com erro: Habilita cancelamento automático da cobrança na Pagar.me após uma nota fiscal não ter sido criada corretamente pela plataforma do NFe.io. Este caso geralmente acontece ao criar uma nota com algum dado inválido, como um CEP que não existe. Caso esteja desabilitado, será necessário enviar o metadata "charge_failed_cancellation_enabled: true" para que o erro da nota fiscal reflita na cobrança na Pagar.me;
  • Sempre criar nota fiscal com CPF/CNPJ inválido: Habilita criação automática da nota fiscal mesmo que o documento (CPF ou CNPJ) do cliente estiver errado. Nessa caso, as notas fiscais serão criadas sem nenhum documento nela.
  • Descrição da Nota Fiscal: Descrição do serviço que será exibida na nota fiscal, você poderá utilizar variáveis na descrição das Notas;
  • CEP padrão: O CEP padrão é usando quando não encontramos o código do IBGE do CEP passado no pedido. Nesse caso, criaremos a nota fiscal com o CEP que você digitou nesse campo. Caso você deixe vazio, os pedidos com CEP sem código do IBGE não criarão nota fiscal. Normalmente esse problema acontece com CEPs que foram alterados recentemente e ainda não foram atualizados no Correios.

Após preenchido todos os campos e configurações basta clicar em "Autorizar" para efetivar a integração!

Variáveis na Descrição da Nota Fiscal

Você pode utilizar variáveis para personalizar a descrição da sua Nota Fiscal com dados específicos do seu pedido ou fatura.
Para isso basta utilizar os campos abaixo como parte do texto da sua descrição e no momento da emissão da Nota iremos substituir pelo informação correta.
  1. {name} : Nome do comprador;
  2. {code} : Código do pedido ou da assinatura;
  3. {items} : Exibe os itens do pedido, 1 item por linha;
  4. {cycle_start} : Período inicial do ciclo de cobrança da assinatura;
  5. {cycle_end} : Período final do ciclo de cobrança da assinatura;

Metadata e NFe.io

Interagindo via Metadata (você poderá adicionar algumas parametrizações!)

Para alguns modelos de negócio mais complexos, pode ser necessário manipular mais informações durante a emissão de uma Nota Fiscal, como tornar o valor da Nota Fiscal diferente do total do pedido.
A sua integração com a Pagar.me pode enviar alguns Metadatas para sinalizar algumas ações, como:
  1. nfeio_increase_flat : Adiciona um valor específico ao valor final da Nota Fiscal, podendo ser um acréscimo ou desconto (para aplicar um desconto envie um valor negativo). O valor deve ser informado em centavos. Exemplo: -1050 aplica um desconto de R$ 10,50;
  2. nfeio_increase_percent : Adiciona um valor proporcional ao valor do pedido em % ao valor final da Nota Fiscal, podendo ser um acréscimo ou desconto (para aplicar um desconto envie um valor negativo). Exemplo: -2.6 aplica um desconto de 2.6% em relação ao valor do pedido;
  3. nfeio_issuance_enabled : Habilita (true) ou desabilita (false) a criação automática da Nota Fiscal para a assinatura/pedido criado; Quando passado, esse metadata sobreescreve o campo "Sempre emitir nota fiscal";
  4. nfeio_cancellation_enabled : Habilita (true) ou desabilita (false) o cancelamento automático da Nota Fiscal para a assinatura/pedido criado; Quando passado, esse metadata sobreescreve o campo "Sempre cancelar nota fiscal";
  5. charge_cancellation_enabled : Habilita (true) ou desabilita (false) o cancelamento automático de uma cobrança caso a Nota Fiscal referente seja cancelada. Quando passado, esse metadata sobreescreve o campo "Sempre cancelar cobrança";
  6. charge_failed_cancellation_enabled : Habilita (true) ou desabilita (false) o cancelamento automático de uma cobrança caso ocorra algum erro ao criar a Nota Fiscal referente.
  7. nfeio_description : Altera a descrição da NFS-e. Caso não enviado e a emissão for baseada em um pedido ou fatura, será inserido os items como descrição. Caso seja baseado apenas em uma cobrança avulsa (sem carrinho de compras) será usado o nome da loja.
  8. nfeio_discover_real_amount_percent : caso um NFe tenha um acréscimo percentual no seu valor original, esta propriedade permite que esta informação seja recebida para que o valor original da nota possa ser trabalhado posteriormente.
  9. nfeio_company_identification : Para casos em que seja necessário emitir NFe em empresas diferentes dentro do NFe.io, deve ser passado o Indentificador da Pagar.me neste campo, para que repassemos os dados deste caso específico para a emissão avulsa.

Metadatas informativos

Quando a pagar.me interage com uma cobrança, pedido ou fatura, podemos adicionar dados ao metadata dependendo de algum fluxo e permissões específicas.
As permissões necessárias são:
  1. Atualizar Metadata de Cobrança
  2. Atualizar Metadata de Pedido
  3. Atualizar Metadata da Fatura
Os possíveis metadatas são:
  1. nfeio_issuance_error_message : Caso ocorra algum erro no momento de criação da Nota, este campo será preenchido com o motivo do erro;
  2. nfeio_cancellation_error_message : Caso ocorra algum erro no momento de cancelamento da nota, este campo será preenchido com o motivo do erro;
  3. nfeio_invoice_id : Identificador da Nota Fiscal pra a NFe.io ;
  4. nfeio_invoice_number : Número da RPS (Recibo Provisório de Serviços);
  5. nfeio_invoice_provider_number : Número da Nota Fiscal;
  6. nfeio_invoice_status : Status de processamento. Possíveis valores: CancelFailed, IssueFailed, Issued, Cancelled, PullFromCityHall, WaitingCalculateTaxes, WaitingDefineRpsNumber, WaitingSend, WaitingSendCancel, WaitingReturn, WaitingDownload;
  7. nfeio_issue_date : Data de emissão da Nota Fiscal;
  8. nfeio_provider_legal_name : Razão social da sua empresa;
  9. nfeio_invoice_services_amount : Valor cobrado na Nota Fiscal;
  10. nfeio_invoice_iss_amount : Valor do ISS (Imposto Sobre Serviços);
  11. nfeio_pdf_url : Link para PDF da Nota Fiscal;
  12. nfeio_cancel_date : Data de cancelamento da Nota Fiscal;

Integrei, e agora?

Após realizar a sua integração você poderá acessa-la na página do APP ou em "Minhas integrações".
Podendo editá-la ou excluí-la caso desejar.

Vendendo e gerando Notas Fiscais

Após integrado o APP do NFe.io já irá começar a gerar Notas Fiscais para as Vendas realizadas nas lojas integradas a ele!
Ao cair um pedido ou cobrança na Pagar.me poderemos ver a Nota Fiscal gerada no NFe.io.

E assim todos os seus pedidos na Pagar.me estão integrados a uma Nota Fiscal da NFe.io, algumas ações podem ser realizadas com a Nota dentro do Nfe.io, como por exemplo enviar Visualiza-la ou envia-la por e-mail!

Dúvidas

Eai, ficou alguma dúvida sobre a nossa Integração com a solução de Notas Fiscais NFe.io?

Se você tiver dúvidas pode entrar em contato com o nosso suporte pelo e-mail.
Nosso time ficará feliz em te ajudar com a instalação desse APP!

Updated 6 months ago