Quickstart

1. Install the package

Node.js

npm install facturapi

C#

dotnet add package Facturapi

PHP

composer require facturapi/facturapi-php

cURL

# cURL doesn't require installation

2. Create your first invoice

Node.js

// a) Import the package
const Facturapi = require('facturapi');
// b) Create an instance of the client, using the secret key
//    of the issuing organization (https://dashboard.facturapi.io/integration/apikeys)
const facturapi = new Facturapi('sk_test_API_KEY');
// c) Create an invoice
const invoice = await facturapi.invoices.create({
  customer: {
    legal_name: 'Dunder Mifflin',
    email: 'email@example.com',
    tax_id: 'ABC101010111',
    tax_system: '601',
    address: {
      zip: '85900'
    }
  },
  items: [{
    quantity: 1,
    product: {
      description: 'Ukelele',
      product_key: '60131324',
      price: 345.60
    }
  }],
  use: 'G01',
  payment_form: '28' // Credit card
});

C#

// a) Import the package
using Facturapi;
// b) Create an instance of the client, using the secret key
var facturapi = new FacturapiClient("sk_test_API_KEY");
// c) Create an invoice
var invoice = await facturapi.Invoice.CreateAsync(new Dictionary<string, object>
{
  ["customer"] = new Dictionary<string, object>
  {
    ["legal_name"] = "Dunder Mifflin",
    ["email"] = "email@example.com",
    ["tax_id"] = "ABC101010111",
    ["tax_system"] = "601",
    ["address"] = new Dictionary<string, object>
    {
      ["zip"] = "85900"
    }
  },
  ["items"] = new Dictionary<string, object>[]
  {
    new Dictionary<string, object>
    {
      ["quantity"] = 1,
      ["product"] = new Dictionary<string, object>
      {
        ["description"] = "Ukelele",
        ["product_key"] = "60131324",
        ["price"] = 345.60
      }
    }
  },
  ["use"] = "G01",
  ["payment_form"] = "28" // Credit card
});

PHP

// a) Import the package
use Facturapi\Facturapi;
//    of the issuing organization (https://dashboard.facturapi.io/integration/apikeys)
$facturapi = new Facturapi( "sk_test_API_KEY" );
// c) Create an invoice
$invoice = $facturapi->Invoices->create([
  "customer" => [
    "legal_name" => "Dunder Mifflin",
    "email" => "email@example.com",
    "tax_id" => "ABC101010111",
    "tax_system" => "601",
    "address" => [
      "zip" => "85900"
    ]
  ],
  "items" => [
    [
      "quantity" => 1,
      "product" => [
        "description" => "Ukelele",
        "product_key" => "60131324",
        "price" => 345.60
      ]
    ],
  ],
  "payment_form" => "28" // Credit card
]);

cURL

curl https://www.facturapi.io/v2/invoices \
  # a) Autenticate using the API Key of the issuing organization
  -H "Authorization: Bearer sk_test_API_KEY" \
  -H "Content-Type: application/json" \
  # b) Create an invoice
  -d '{
    "customer": {
      "legal_name": "Dunder Mifflin",
      "email": "email@example.com",
      "tax_id": "ABC101010111",
      "tax_system": "601",
      "address": {
        "zip": "85900"
      }
    },
    "items": [{
      "quantity": 1,
      "product": {
        "description": "Ukelele",
        "product_key": "60131324",
        "price": 345.60
      }
    }],
    "use": "G01",
    "payment_form": "28" // Credit card
  }'

info

By default, the product price is considered to have taxes included. Facturapi will break down the product taxes (16% VAT by default) and calculate the unit price. If you need the price attribute to be the unit price instead, you must send the tax_included parameter with the value false.

Response: Invoice object

{
  "id": "58e93bd8e86eb318b019743d",
  "created_at": "2017-01-01T14:00:08.000Z",
  "livemode": false,
  "status": "valid",
  "cancellation_status": "none",
  "verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
  "customer": {
    "id": "58e93bd8e86eb318b0197456",
    "legal_name": "Dunder Mifflin S.A. de C.V.",
    "tax_id": "ABC101010111",
    "tax_system": "601",
    "address": {
      "zip": "85900",
      "country": "MEX"
    }
  },
  "total": 345.60,
  "uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
  "folio_number": 914,
  "series": "A",
  "payment_form": "28",
  "related": [], 
  "currency": "MXN",
  "exchange": 1,
  "items": [{
    "quantity": 1,
    "discount": 0,
    "product": {
      "description": "Ukelele",
      "price": 345.60,
      "tax_included": true,
      "taxes": [
        {
          "type": "IVA",
          "rate": 0.16
        }
      ]
    }
  }],
  "stamp": {
    "signature": "ZGgQ126+lbo6XxVmeM0Kys1rAllqRaDmaK4yW20B3H5AaVShnItBwKATpxqJuGK1qPmLA2r16B8dAb4UFjR27Xc/+SsNPSwRBYRVKI0AB62jx2Z4uxooiVQBY9Bb6czlgzJb+ftgNvnGwSXzI6QZKpuWRe9LmJvACzqTB3ZdC9QoqaVICDNZ9oaT99txu9ahbJu3ftPhlykXi1SxVTBZ7uUTqsBkc6iEjbSTYpE85bsrhbMw4tDODR7o/PS917whChOFUU0sQenm5sJQMenPcKPyS9JoGQPO/a/4wzxJ2RyWCkw72LNFBbJTsPXcXdOZmEJ06Ixc2Iy24Biz8GEbJg==",
    "date": "2021-03-30T00:57:48",
    "sat_cert_number": "20001000000300022323",
    "sat_signature": "AzYwRdHfDp0BCBaTpT87gtAAE3Q="
  }
}

3. Send the invoice by email

Node.js

await facturapi.invoices.sendByEmail(invoice.id);

C#

await facturapi.Invoice.SendByEmailAsync(invoice.Id);

PHP

$facturapi->Invoices->send_by_email($invoice->id);

cURL

curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/email \
  -H "Authorization: Bearer sk_test_API_KEY"
  -X POST

4. Download the XML and PDF files

Node.js

const fs = require('fs');

// Download the PDF and XML files, bundled together in a ZIP file
const zipStream = await facturapi.invoices.downloadZip(invoice.id);
// Save the downloaded file to disk
const file = fs.createWriteStream('./factura.zip');
zipStream.pipe(file);
// Or send it as a response to your customer (ExpressJS syntax)
zipStream.pipe(res);

C#

// Download the PDF and XML files, bundled together in a ZIP file
var zipStream = await facturapi.Invoice.DownloadZipAsync(invoice.Id);

// Save the downloaded file to disk
var file = new System.IO.FileStream("C:\\route\\to\\save\\invoice.zip", FileMode.Create);
zipStream.CopyTo(file);
file.Close();

PHP

$zip = $facturapi->Invoices->download_zip($invoice->id) // stream containing the PDF and XML as a ZIP file or

$pdf = $facturapi->Invoices->download_pdf($invoice->id) // stream containing the PDF file or

$xml = $facturapi->Invoices->download_xml($invoice->id) // stream containing the XML file or

cURL

## Download the ZIP file containing the PDF and XML files
curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/zip \
  -H "Authorization: Bearer sk_test_API_KEY"

Next steps

This was a brief overview of using Facturapi.

We invite you to check our examples section, as well as the full API reference, where you can explore all the endpoints available in Facturapi.