Emissão de Nota Fiscal

Objetivo

Permitir que um sistema terceiro de emissão fiscal utilize os dados da EVO API para emitir notas fiscais com base:

Na Venda (Sales)

No Recebimento efetivo (Receivables)

Como a EVO não realiza a emissão de notas fiscais diretamente, a API permite que sistemas terceiros obtenham todas as informações necessárias para gerar a nota fiscal a partir de vendas (sales) ou recebimentos (receivables).

Endpoints Utilizados

Consultar venda com recebíveis vinculados

GET /api/v2/sales

Consultar dados do membro

GET /api/v2/members

Consultar recebíveis diretamente (opcional)

GET /api/v1/receivables

Fluxo Técnico

1. Capturar o Evento de Venda

A estratégia recomendada é utilizar o webhook:

NewSale – disparado quando uma nova venda é registrada

RecurrentSale – disparado em vendas recorrentes

Esse evento pode ser utilizado como gatilho para iniciar o processo de emissão fiscal.

Exemplo de payload recebido via webhook:

{
  "IdW12": 123,
  "IdBranch": 1,
  "IdRecord": 123,
  "EventType": "NewSale",
  "ApiCallback": "https://evo-integracao-api.w12app.com.br/api/v1/sales/123"
}

Quer aprender mais sobre webhook e como utilizá-lo? Saiba mais aqui.

1.2 Alternativa: Consultar vendas por período

Além do uso de webhooks, também é possível consultar diretamente o endpoint de vendas para buscar registros já realizados dentro de um intervalo de datas.

Essa estratégia é útil para:

sincronizações periódicas

reprocessamento de notas fiscais

recuperação de eventos perdidos

conciliação entre sistemas

Exemplo de requisição:

GET /api/v2/sales?dateSaleStart=2024-06-01&dateSaleEnd=2024-06-30&showReceivables=true

Parâmetros importantes:

Parâmetro	Descrição
`dateSaleStart`	Data inicial para filtro de vendas (`yyyy-mm-dd`)
`dateSaleEnd`	Data final para filtro de vendas (`yyyy-mm-dd`)
`showReceivables`	Retorna os recebíveis vinculados à venda

Esse método permite obter uma lista de vendas registradas no período, incluindo:

itens da venda

valores

recebíveis vinculados

status dos pagamentos

Após obter os registros, o integrador pode seguir o mesmo fluxo descrito nos próximos passos para verificar o status dos recebíveis e realizar a emissão da nota fiscal.

2. Consultar os Dados da Venda

Após receber o evento ou identificar a venda na consulta por período, consulte os dados completos da venda utilizando:

GET /api/v2/sales?idSale=12345&showReceivables=true

O parâmetro showReceivables=true permite retornar também os recebíveis vinculados à venda.

Essas informações incluem:

itens vendidos

valores

centro de receita

códigos fiscais

parcelas

status dos recebíveis

3. Verificar o Status do Recebível

Dentro da resposta da venda existe o objeto receivables, que contém as parcelas associadas à venda.

Exemplo:

"receivables": [
  {
    "idReceivable": 9876,
    "status": {
      "id": 2,
      "name": "Recebido"
    },
    "receivingDate": "2024-06-12",
    "ammountPaid": 150.00
  }
]

O campo status.id indica o estado do recebível.

ID	Name
1	Em aberto
2	Recebido
3	Cancelado
4	Atrasado

Quando status.id = 2, significa que o pagamento foi realizado e os dados podem ser utilizados para emissão da nota fiscal.

4. Consultar os Dados do Cliente

Para obter as informações do tomador da nota, consulte o membro associado à venda.

GET /api/v2/members/{idMember}

Informações relevantes para a nota fiscal:

nome

CPF ou CNPJ

telefone

endereço (quando disponível)

5. Emitir a Nota Fiscal no Serviço Externo

Com as informações coletadas:

dados do membro

itens da venda

valores

impostos

data do pagamento ou da venda

o integrador deve enviar essas informações para o serviço externo de emissão fiscal.

🚧 A emissão da nota ocorre fora do EVO.

Cenário Adicional: Pagamento de Débito Após Vencimento

Em situações onde um recebível entra em atraso e posteriormente é pago.

Quando esse débito é quitado, o webhook abaixo pode ser utilizado:

ClearedDebt

Esse evento indica que um débito anteriormente registrado foi pago.

Exemplo de payload:

{
  "IdW12": 123,
  "IdBranch": 1,
  "IdRecord": 12345,
  "EventType": "ClearedDebt",
  "ApiCallback": "https://evo-integracao-api.w12app.com.br/api/v2/sales/123"
}

Após receber esse evento, recomenda-se consultar os dados da venda:

GET /api/v2/sales?idSale=12345&showReceivables=true

e prosseguir com as etapas seguintes informadas no fluxo técnico acima.

Perguntas Frequentes

1. A EVO emite nota fiscal automaticamente?

Não. A EVO fornece os dados necessários para que um sistema externo de emissão fiscal realize a geração da nota.

2. A emissão deve ser baseada na venda ou no pagamento?

Isso depende da regra fiscal do cliente.

Alguns cenários exigem emissão na venda, enquanto outros exigem emissão somente após confirmação do pagamento.

3. Posso utilizar apenas webhooks para emitir notas?

Os webhooks devem ser utilizados como gatilhos do processo.
A confirmação dos dados deve sempre ser feita consultando os endpoints da API (recomendamos fazer essa consulta mais massiva fora do horário comercial).

4. O webhook ClearedDebt cobre todos os pagamentos?

Não necessariamente. Esse webhook é disparado especificamente quando um débito previamente registrado é quitado.

Para garantir maior controle do processo, recomenda-se validar o status do recebível dentro da venda.

Resultado Esperado

Após implementar esse fluxo:

As notas fiscais serão emitidas automaticamente após venda ou pagamento

Os dados fiscais serão baseados nas informações oficiais registradas no EVO

O processo de emissão poderá ser totalmente automatizado via integração

Emissão de Nota Fiscal

Objetivo#

Endpoints Utilizados#

Consultar venda com recebíveis vinculados#

Consultar dados do membro#

Consultar recebíveis diretamente (opcional)#

Fluxo Técnico#

1. Capturar o Evento de Venda#

1.2 Alternativa: Consultar vendas por período#

2. Consultar os Dados da Venda#

3. Verificar o Status do Recebível#

4. Consultar os Dados do Cliente#

5. Emitir a Nota Fiscal no Serviço Externo#

Cenário Adicional: Pagamento de Débito Após Vencimento#

Perguntas Frequentes#

1. A EVO emite nota fiscal automaticamente?#

2. A emissão deve ser baseada na venda ou no pagamento?#

3. Posso utilizar apenas webhooks para emitir notas?#

4. O webhook ClearedDebt cobre todos os pagamentos?#

Resultado Esperado#

Objetivo

Endpoints Utilizados

Consultar venda com recebíveis vinculados

Consultar dados do membro

Consultar recebíveis diretamente (opcional)

Fluxo Técnico

1. Capturar o Evento de Venda

1.2 Alternativa: Consultar vendas por período

2. Consultar os Dados da Venda

3. Verificar o Status do Recebível

4. Consultar os Dados do Cliente

5. Emitir a Nota Fiscal no Serviço Externo

Cenário Adicional: Pagamento de Débito Após Vencimento

Perguntas Frequentes

1. A EVO emite nota fiscal automaticamente?

2. A emissão deve ser baseada na venda ou no pagamento?

3. Posso utilizar apenas webhooks para emitir notas?

4. O webhook ClearedDebt cobre todos os pagamentos?

Resultado Esperado