Pular para o conteúdo
Docs

Gatilho Asaas: pagamento recebido emite a NFS-e

Atualizado em

Nesta página

Se você cobra os seus clientes pelo Asaas, a Emitra pode emitir a NFS-e assim que o pagamento entrar. Você define a regra uma vez; cada pagamento gera no máximo uma nota.

Pré-requisitos#

  • Permissões connectors:manage (owner e admin) e nfse:emit.
  • Certificado A1 ativo e configuração fiscal completa.
  • Uma chave de API do Asaas da sua conta, do ambiente que você vai usar (sandbox ou produção).
  • Um item de serviço cadastrado para usar como padrão da nota.

1. Crie o conector#

  1. No painel, abra Conectores e escolha Asaas.
  2. Informe a chave de API do Asaas e o ambiente. A chave é guardada criptografada e nunca é mostrada de novo, nem para você.
  3. Salve. A Emitra gera:
    • uma URL de webhook exclusiva do conector, no formato https://emitra.com.br/api/v1/webhooks/connectors/asaas/{connector_id};
    • um token de autenticação.

2. Configure o webhook no Asaas#

No painel do Asaas, cadastre um webhook para eventos de cobrança apontando para a URL gerada e informe o token. O Asaas envia esse token no header asaas-access-token, e a Emitra recusa qualquer chamada sem ele.

3. Crie a regra de emissão#

Campo Opções
Gatilho PAYMENT_RECEIVED (pagamento recebido) ou PAYMENT_CONFIRMED (pagamento confirmado)
Modelo da nota Item de serviço padrão, tributação, série e descrição
Valor da nota Valor bruto ou líquido do pagamento
Tomador não encontrado Criar o tomador automaticamente ou pular com motivo
Modo Emitir direto ou gerar rascunho para a fila de aprovação

A descrição da nota aceita variáveis do pagamento:

Variável Conteúdo
{{pagamento.descricao}} Descrição da cobrança no Asaas
{{pagamento.valor}} Valor do pagamento
{{pagamento.data}} Data do pagamento
Exemplo de descrição
Mensalidade de suporte - {{pagamento.descricao}} - pago em {{pagamento.data}}

Como o tomador é encontrado#

Quando chega um pagamento, a Emitra consulta o cliente da cobrança na sua conta Asaas (com a sua chave) e procura um tomador com o mesmo CPF ou CNPJ no seu cadastro. Se não encontrar, cria o tomador ou pula o pagamento, conforme a regra.

Sem nota duplicada#

O Asaas entrega webhooks "pelo menos uma vez", então o mesmo evento pode chegar repetido. A Emitra protege em duas camadas:

  1. cada evento do Asaas é registrado uma única vez por conector;
  2. a emissão usa a chave de idempotência asaas:{payment_id}, de modo que um pagamento gera no máximo uma nota, mesmo que os eventos PAYMENT_RECEIVED e PAYMENT_CONFIRMED cheguem os dois.

Estornos#

Um estorno (PAYMENT_REFUNDED) não cancela a nota sozinho. Cancelamento fiscal tem prazo e regras do município, então a Emitra cria uma tarefa "cancelar nota?" e avisa você. Para cancelar, siga Cancelar e substituir.

Acompanhar os eventos#

A tela do conector lista cada evento recebido com o status (received, processed, skipped, failed, needs_action), o motivo e a nota gerada. Eventos com falha podem ser reprocessados. Os eventos são guardados por 90 dias.

A emissão pelo conector respeita a cota do plano, o bloqueio por inadimplência e as permissões, como qualquer outra emissão.

Próximos passos#

Esta página foi útil?