Issuance of Invoice

Objective

Allow a third-party fiscal issuance system to use data from the EVO API to issue invoices based on:

Sales

Actual Receivables

Since EVO does not issue invoices directly, the API allows third-party systems to obtain all necessary information to generate the invoice from sales or receivables.

Used Endpoints

Consult Sale with Linked Receivables

GET /api/v2/sales

Consult Member Data

GET /api/v2/members

Consult Receivables Directly (optional)

GET /api/v1/receivables

Technical Flow

1. Capture the Sale Event

The recommended strategy is to use the webhook:

NewSale – triggered when a new sale is recorded

RecurrentSale – triggered for recurring sales

This event can be used as a trigger to start the fiscal issuance process.

Example of payload received via webhook:

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

Want to learn more about webhooks and how to use them? Learn more here.

1.2 Alternative: Consult Sales by Period

In addition to using webhooks, it is also possible to directly consult the sales endpoint to retrieve records already made within a date range.

This strategy is useful for:

periodic synchronizations

reprocessing invoices

recovering lost events

reconciliation between systems

Example of request:

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

Important parameters:

Parameter	Description
`dateSaleStart`	Start date for sales filter (`yyyy-mm-dd`)
`dateSaleEnd`	End date for sales filter (`yyyy-mm-dd`)
`showReceivables`	Returns the receivables linked to the sale

This method allows obtaining a list of sales recorded in the period, including:

sale items

amounts

linked receivables

payment statuses

After obtaining the records, the integrator can follow the same flow described in the next steps to check the status of the receivables and issue the invoice.

2. Consult Sale Data

After receiving the event or identifying the sale in the period consultation, consult the complete sale data using:

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

The parameter showReceivables=true allows returning the receivables linked to the sale as well.

This information includes:

sold items

amounts

revenue center

fiscal codes

installments

receivable statuses

3. Check the Status of the Receivable

Within the sale response, there is the receivables object, which contains the installments associated with the sale.

Example:

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

The status.id field indicates the state of the receivable.

ID	Name
1	Open
2	Received
3	Canceled
4	Overdue

When status.id = 2, it means that the payment has been made and the data can be used for issuing the invoice.

4. Consult Customer Data

To obtain the information of the invoice recipient, consult the member associated with the sale.

GET /api/v2/members/{idMember}

Relevant information for the invoice:

name

CPF or CNPJ

phone

address (when available)

5. Issue the Invoice in the External Service

With the collected information:

member data

sale items

amounts

taxes

payment or sale date

the integrator must send this information to the external fiscal issuance service.

🚧 The issuance of the invoice occurs outside of EVO.

Additional Scenario: Payment of Debt After Due Date

In situations where a receivable becomes overdue and is subsequently paid.

When this debt is settled, the webhook below can be used:

ClearedDebt

This event indicates that a previously recorded debt has been paid.

Example of payload:

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

After receiving this event, it is recommended to consult the sale data:

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

and proceed with the subsequent steps outlined in the technical flow above.

Frequently Asked Questions

1. Does EVO issue invoices automatically?

No. EVO provides the necessary data for an external fiscal issuance system to generate the invoice.

2. Should the issuance be based on the sale or the payment?

This depends on the client's fiscal rule.

Some scenarios require issuance at the sale, while others require issuance only after payment confirmation.

3. Can I use only webhooks to issue invoices?

Webhooks should be used as triggers for the process.
Data confirmation should always be done by consulting the API endpoints (we recommend doing this more extensively outside of business hours).

4. Does the ClearedDebt webhook cover all payments?

Not necessarily. This webhook is triggered specifically when a previously recorded debt is settled.

To ensure greater control of the process, it is recommended to validate the status of the receivable within the sale.

Expected Outcome

After implementing this flow:

Invoices will be issued automatically after sale or payment

Fiscal data will be based on the official information recorded in EVO

The issuance process can be fully automated via integration.

Objective#

Used Endpoints#

Consult Sale with Linked Receivables#

Consult Member Data#

Consult Receivables Directly (optional)#

Technical Flow#

1. Capture the Sale Event#

1.2 Alternative: Consult Sales by Period#

2. Consult Sale Data#

3. Check the Status of the Receivable#

4. Consult Customer Data#

5. Issue the Invoice in the External Service#

Additional Scenario: Payment of Debt After Due Date#

Frequently Asked Questions#

1. Does EVO issue invoices automatically?#

2. Should the issuance be based on the sale or the payment?#

3. Can I use only webhooks to issue invoices?#

4. Does the ClearedDebt webhook cover all payments?#

Expected Outcome#

Objective

Used Endpoints

Consult Sale with Linked Receivables

Consult Member Data

Consult Receivables Directly (optional)

Technical Flow

1. Capture the Sale Event

1.2 Alternative: Consult Sales by Period

2. Consult Sale Data

3. Check the Status of the Receivable

4. Consult Customer Data

5. Issue the Invoice in the External Service

Additional Scenario: Payment of Debt After Due Date

Frequently Asked Questions

1. Does EVO issue invoices automatically?

2. Should the issuance be based on the sale or the payment?

3. Can I use only webhooks to issue invoices?

4. Does the ClearedDebt webhook cover all payments?

Expected Outcome