Inicio rápido

1. Instala el paquete

Node.js
C#
Java
PHP
cURL

npm install facturapi

dotnet add package Facturapi

Usando Maven:

<dependency>
  <groupId>io.facturapi</groupId>
  <artifactId>facturapi-java</artifactId>
  <version>1.0.0</version>
</dependency>

Usando Gradle:

implementation("io.facturapi:facturapi-java:1.0.0")

composer require facturapi/facturapi-php

# No es necesario instalar nada

2. API Keys de Organización

Cambios en API keys

Estos cambios entrarán en vigor el 16 de junio de 2026.

Próximamente actualizaremos el manejo de API keys en Facturapi para mejorar la seguridad y el control de credenciales.

Con esta actualización, cada organización podrá generar como máximo:

5 API keys por hora
10 API keys por día

Este límite aplica tanto para test API keys como para live API keys.

Las API keys están diseñadas para usarse como credenciales persistentes en tus integraciones. Si tu integración genera una nueva API key por solicitud, te recomendamos mantener una API key estable para cada integración o entorno, guardarla de forma segura del lado de tu servidor y usar esa misma key para tus peticiones.

Si actualmente utilizas una API key estable almacenada del lado de tu servidor, no necesitas realizar ninguna acción.

Además, por motivos de seguridad, eliminaremos automáticamente las API keys que permanezcan sin uso por más de un año. Esto ayuda a reducir credenciales antiguas que podrían permanecer activas innecesariamente.

Si tienes dudas sobre este cambio, puedes contactar a nuestro equipo de soporte en soporte@facturapi.io o en el chat de nuestra página www.facturapi.io.

3. Crea tu primera factura

Node.js
C#
Java
PHP
cURL

// a) Importa el paquete
import Facturapi from 'facturapi'
// b) Crea una instancia del cliente, usando la llave secreta
//    de la organización emisora (https://dashboard.facturapi.io/integration/apikeys)
const facturapi = new Facturapi('sk_test_API_KEY');
// c) Crea una factura
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' // Tarjeta de crédito
});

// a) Importa el paquete
using Facturapi;
// b) Crea una instancia del cliente, usando la llave secreta
//    de la organización emisora (https://dashboard.facturapi.io/integration/apikeys)
var facturapi = new FacturapiClient("sk_test_API_KEY");
// c) Crea una factura
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" // Tarjeta de crédito
});

import io.facturapi.Facturapi;
import java.util.List;
import java.util.Map;

Facturapi facturapi = new Facturapi("sk_test_API_KEY");
var invoice = facturapi.invoices().create(Map.of(
  "customer", Map.of(
    "legal_name", "Dunder Mifflin",
    "email", "email@example.com",
    "tax_id", "ABC101010111",
    "tax_system", "601",
    "address", Map.of("zip", "85900")
  ),
  "items", List.of(Map.of(
    "quantity", 1,
    "product", Map.of(
      "description", "Ukelele",
      "product_key", "60131324",
      "price", 345.60
    )
  )),
  "use", "G01",
  "payment_form", "28"
));

// a) Importa el paquete
use Facturapi\Facturapi;
// b) Crea una instancia del cliente, usando la llave secreta
//    de la organización emisora (https://dashboard.facturapi.io/integration/apikeys)
$facturapi = new Facturapi("sk_test_API_KEY");
// c) Crea una factura
$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" // Tarjeta de crédito
]);

curl https://www.facturapi.io/v2/invoices \
  # a) Autentícate con la API Key de la organización emisora
  -H "Authorization: Bearer sk_test_API_KEY" \
  -H "Content-Type: application/json" \
  # b) Crea una factura
  -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" // Tarjeta de crédito
  }'

info

Por default se considera que el precio del producto tiene impuestos incluídos. Facturapi se encarga de desglosar los impuestos del producto (siendo 16% de IVA el default) y calcular el precio unitario. Si en lugar de eso requieres que el atributo price sea el precio unitario, debes enviar el parámetro tax_included con el valor false.

Respuesta: Objeto Invoice

{
  "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. Envía la factura por correo electrónico

Node.js
C#
Java
PHP
cURL

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

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

facturapi.invoices().sendByEmail(invoice.getId(), null);

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

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

4. Descarga de XML y PDF

Node.js
C#
Java
PHP
cURL

import fs from 'fs';

// Descarga PDF y XML comprimidos en archivo ZIP
const zipStream = await facturapi.invoices.downloadZip(invoice.id);
// Guarda la descarga en un archivo
const file = fs.createWriteStream('./factura.zip');
zipStream.pipe(file);
// O envíalo como respuesta a tu cliente (en ExpressJS)
zipStream.pipe(res);

// Descarga PDF y XML comprimidos en archivo ZIP
var zipStream = await facturapi.Invoice.DownloadZipAsync(invoice.Id);

// Guarda la descarga en un archivo
var file = new System.IO.FileStream("C:\\route\\to\\save\\invoice.zip", FileMode.Create);
zipStream.CopyTo(file);
file.Close();

import java.nio.file.Files;
import java.nio.file.Path;

byte[] zip = facturapi.invoices().downloadZip(invoice.getId());
Files.write(Path.of("./factura.zip"), zip);

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

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

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

## Descargar PDF y XML comprimidos en archivo ZIP
curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/zip \
  -H "Authorization: Bearer sk_test_API_KEY"

Siguientes pasos

Este fue un vistazo rápido del uso de Facturapi.

Te invitamos a consultar nuestra sección de ejemplos, así como ver la referencia completa de la API, donde podrás explorar todos los endpoints disponibles en Facturapi.

1. Instala el paquete​

2. API Keys de Organización​

3. Crea tu primera factura​

3. Envía la factura por correo electrónico​

4. Descarga de XML y PDF​

Siguientes pasos​