Emisión de factura

Objetivo

Permitir que un sistema externo de emisión fiscal utilice los datos de la EVO API para emitir facturas basadas en:

la Venta (Sales)

el Cobro efectivo (Receivables)

Como EVO no realiza la emisión de facturas directamente, la API permite que sistemas externos obtengan toda la información necesaria para generar la factura a partir de ventas (sales) o cobros (receivables).

Endpoints Utilizados

Consultar venta con recibibles vinculados

GET /api/v2/sales

Consultar datos del miembro

GET /api/v2/members

Consultar recibibles directamente (opcional)

GET /api/v1/receivables

Flujo Técnico

1. Capturar el Evento de Venta

La estrategia recomendada es utilizar el webhook:

NewSale – se dispara cuando se registra una nueva venta

RecurrentSale – se dispara en ventas recurrentes

Este evento puede utilizarse como disparador para iniciar el proceso de emisión fiscal.

Ejemplo de payload recibido vía webhook:

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

¿Quieres aprender más sobre webhooks y cómo utilizarlos?
Más información aquí

1.2 Alternativa: Consultar ventas por período

Además del uso de webhooks, también es posible consultar directamente el endpoint de ventas para obtener registros ya realizados dentro de un intervalo de fechas.

Esta estrategia es útil para:

sincronizaciones periódicas

reprocesamiento de facturas

recuperación de eventos perdidos

conciliación entre sistemas

Ejemplo de solicitud:

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

Parámetros importantes:

Parámetro	Descripción
`dateSaleStart`	Fecha inicial para filtrar ventas (`yyyy-mm-dd`)
`dateSaleEnd`	Fecha final para filtrar ventas (`yyyy-mm-dd`)
`showReceivables`	Devuelve los recibibles vinculados a la venta

Este método permite obtener una lista de ventas registradas en el período, incluyendo:

ítems de la venta

valores

recibibles vinculados

estado de los pagos

Después de obtener los registros, el integrador puede seguir el mismo flujo descrito en los siguientes pasos para verificar el estado de los recibibles y realizar la emisión de la factura.

2. Consultar los Datos de la Venta

Después de recibir el evento o identificar la venta en la consulta por período, consulte los datos completos de la venta utilizando:

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

El parámetro showReceivables=true permite retornar también los recibibles vinculados a la venta.

Esta información incluye:

ítems vendidos

valores

centro de ingresos

códigos fiscales

cuotas

estado de los recibibles

3. Verificar el Estado del Recibible

Dentro de la respuesta de la venta existe el objeto receivables, que contiene las cuotas asociadas a la venta.

Ejemplo:

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

El campo status.id indica el estado del recibible.

ID	Name
1	Abierto
2	Recibido
3	Cancelado
4	Atrasado

Cuando status.id = 2, significa que el pago fue realizado y los datos pueden utilizarse para la emisión de la factura.

4. Consultar los Datos del Cliente

Para obtener la información del receptor de la factura, consulte el miembro asociado a la venta.

GET /api/v2/members/{idMember}

Información relevante para la factura:

nombre

CPF o CNPJ

correo electrónico

teléfono

dirección (cuando esté disponible)

5. Emitir la Factura en el Servicio Externo

Con la información recopilada:

datos del miembro

ítems de la venta

valores

impuestos

fecha del pago o de la venta

el integrador debe enviar estos datos al servicio externo de emisión fiscal.

🚧 La emisión de la factura ocurre fuera de EVO.

Escenario Adicional: Pago de Débito Después del Vencimiento

En situaciones donde un recibible entra en atraso y posteriormente es pagado.

Cuando esta deuda es liquidada, puede utilizarse el siguiente webhook:

ClearedDebt

Este evento indica que una deuda previamente registrada fue pagada.

Ejemplo de payload:

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

Después de recibir este evento, se recomienda consultar los datos de la venta:

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

y continuar con los pasos siguientes descritos en el flujo técnico anterior.

Preguntas Frecuentes

1. ¿EVO emite facturas automáticamente?

No. EVO proporciona los datos necesarios para que un sistema externo de emisión fiscal genere la factura.

2. ¿La emisión debe basarse en la venta o en el pago?

Depende de la regla fiscal del cliente.

Algunos escenarios requieren emisión en el momento de la venta, mientras que otros requieren emisión solo después de la confirmación del pago.

3. ¿Puedo utilizar solo webhooks para emitir facturas?

Los webhooks deben utilizarse como disparadores del proceso.

La confirmación de los datos siempre debe realizarse consultando los endpoints de la API (se recomienda realizar consultas más masivas fuera del horario comercial).

4. ¿El webhook ClearedDebt cubre todos los pagos?

No necesariamente. Este webhook se dispara específicamente cuando una deuda previamente registrada es liquidada.

Para garantizar un mayor control del proceso, se recomienda validar el estado del recibible dentro de la venta.

Resultado Esperado

Después de implementar este flujo:

Las facturas se emitirán automáticamente después de la venta o del pago

Los datos fiscales estarán basados en la información oficial registrada en EVO

El proceso de emisión podrá ser totalmente automatizado mediante integración

Objetivo#

Endpoints Utilizados#

Consultar venta con recibibles vinculados#

Consultar datos del miembro#

Consultar recibibles directamente (opcional)#

Flujo Técnico#

1. Capturar el Evento de Venta#

1.2 Alternativa: Consultar ventas por período#

2. Consultar los Datos de la Venta#

3. Verificar el Estado del Recibible#

4. Consultar los Datos del Cliente#

5. Emitir la Factura en el Servicio Externo#

Escenario Adicional: Pago de Débito Después del Vencimiento#

Preguntas Frecuentes#

1. ¿EVO emite facturas automáticamente?#

2. ¿La emisión debe basarse en la venta o en el pago?#

3. ¿Puedo utilizar solo webhooks para emitir facturas?#

4. ¿El webhook ClearedDebt cubre todos los pagos?#

Resultado Esperado#

Objetivo

Endpoints Utilizados

Consultar venta con recibibles vinculados

Consultar datos del miembro

Consultar recibibles directamente (opcional)

Flujo Técnico

1. Capturar el Evento de Venta

1.2 Alternativa: Consultar ventas por período

2. Consultar los Datos de la Venta

3. Verificar el Estado del Recibible

4. Consultar los Datos del Cliente

5. Emitir la Factura en el Servicio Externo

Escenario Adicional: Pago de Débito Después del Vencimiento

Preguntas Frecuentes

1. ¿EVO emite facturas automáticamente?

2. ¿La emisión debe basarse en la venta o en el pago?

3. ¿Puedo utilizar solo webhooks para emitir facturas?

4. ¿El webhook ClearedDebt cubre todos los pagos?

Resultado Esperado