Create your first invoice
You create an invoice with a single API request. Fiscalapi validates it and stamps it (stamping: the certification by a SAT-authorized provider that makes a CFDI valid) with the SAT (Mexico's tax authority, Servicio de Administración Tributaria). Then it returns the finished CFDI (Mexico's electronic invoice). This tutorial covers what you need, how to choose the mode of operation, and what happens when you issue the invoice. The models, requests, and responses are in the invoices resource.
Before you start
- A tenant (the space in Fiscalapi that holds your issuers, recipients, credits, and data) in the test environment with a subscription and stamps (one credit each, used each time you stamp a CFDI). See how to activate them.
- Your tenant and an API key, which you send in the headers of every request. See how to get them.
- An issuer with its certificates, the CSD (Certificado de Sello Digital, the digital seal certificate used to sign CFDIs). For testing, use one of the test people (person: any individual or legal entity registered in your tenant) with its test certificates.
Choose the mode of operation
Fiscalapi creates invoices in two modes of operation, with the same endpoint and the same result. Only the way you send the data changes:
| Mode | What the invoice contains | What you need first |
|---|---|---|
| By reference (recommended) | The IDs of the issuer, the recipient, and the products. | Create your first person and your first product. |
| By value | All the issuer, recipient, and line item data, including the issuer's certificates. | Nothing. |
Issue the invoice
Send the invoice with Create an income invoice by reference or with Create an income invoice by value. The income invoice (type I) is the most common type and is usually called an invoice.
Besides the issuer, the recipient, and the line items, it includes the date, the currency, the form of payment (how the customer paid: cash, bank transfer, card; the FormaPago key), the payment method (whether the CFDI is paid in full when issued, PUE, or later or in installments, PPD; not how the customer pays), and the place of issue (the postal code where the CFDI is issued).
You can send the request with any HTTP client, the SDKs, or the Postman collection, which includes examples of every invoice type.
What happens when you issue it
- Fiscalapi validates the invoice: required fields, SAT catalogs and rules, text lengths, decimal places in amounts, and the password of the issuer's private key. If anything fails, it returns a 400 validation error without stamping the invoice or using a stamp.
- Fiscalapi stamps the invoice with the SAT and uses one stamp.
- Fiscalapi returns the stamped invoice, which includes its
idin Fiscalapi, the UUID (folio fiscal, the unique ID the PAC assigns when it stamps a CFDI), and the XML in base64.
In the test environment, invoices aren't valid for tax purposes. When your integration is ready, move to production by changing only the URL and your credentials.
After you issue it
With the invoice id, you can:
- Generate its PDF or email it to the recipient.
- Check its status with the SAT.
- Cancel it. The cancellation completes later at the SAT, and a webhook notifies you when it's confirmed or rejected.
The other invoice types use the same endpoint: credit note (an Egreso CFDI, type E), payment CFDI (type P), and payroll CFDI (the CFDI issued for each salary payment, type N).