# FacturAPI

[![npm version](https://badge.fury.io/js/facturapi-es6.svg)](https://badge.fury.io/js/facturapi-es6)
[![js-semistandard-style](https://img.shields.io/badge/code%20style-semistandard-brightgreen.svg?style=flat-square)](https://github.com/Flet/semistandard)

This is the unofficial Node.js wrapper for https://www.facturapi.io

FacturAPI makes it easy for developers to generate valid Invoices in Mexico (known as Factura Electrónica or CFDI).

If you've ever used [Stripe](https://stripe.com) or [Conekta](https://conekta.io), you'll find FacturAPI very straightforward to understand and integrate in your server app.

## Install

```bash
npm install --save facturapi-es6
```

## Getting started

### Authenticate with your API Key

Make sure you have created your free account on [FacturAPI](https://www.facturapi.io) and that you have your **API Keys**.

```typescript
import { Facturapi } from "facturapi-es6";
const facturapi = new Facturapi("YOUR_API_KEY");
```

### Create a customer

```typescript
facturapi.customers
  .create({
    legal_name: "Walter White", // Razón social
    tax_id: "WIWA761018", // RFC
    email: "walterwhite@gmail.com", // Optional but useful to send invoice by email
    address: {
      street: "Av. de los Rosales",
      exterior: "123",
      neighborhood: "Tepito",
      zip: "06800"
      // city, municipality and state are filled automatically from the zip code
      // but if you want to, you can override their values
      // city: 'México',
      // municipality: 'Cuauhtémoc',
      // state: 'Ciudad de México'
    }
  })
  .then(customer => {
    // Remember to store the customer.id in your records.
    // You will need it to create an invoice for this customer.
  })
  .catch(err => console.log(err)); // Handle the error.
```

### Create a product

```typescript
facturapi.products
  .create({
    product_key: "4319150114", // Clave Producto/Servicio from SAT's catalog. Log in to FacturAPI and use our tool to look it up.
    description: "Apple iPhone 8",
    price: 20000 // price in MXN.
    // By default, taxes are calculated from the price with IVA 16%
    // But again, you can override that by explicitly providing a taxes array
    // taxes: [
    //   { type: Facturapi.TaxType.IVA, rate: 0.16 },
    //   { type: Facturapi.TaxType.ISR, rate: 0.03666, withholding: true }
    // ]
  })
  .then(product => {
    // Remember to store the product.id in your records.
    // You will need it to create an invoice for this product.
  })
  .catch(err => console.log(err)); // Handle the error.
```

### Create an invoice

```typescript
facturapi.invoices.create({
  customer: 'YOUR_CUSTOMER_ID',
  payment_form: Facturapi.PaymentForm.TRANSFERENCIA_ELECTRONICA, // Constant from SAT's catalog. Check out our documentation to learn more.
  items: [{
    quantity: 1, // Optional. Defaults to 1.
    product: 'YOUR_PRODUCT_ID' // You can also pass a product object instead
  }] // Add as many products as you want to include in your invoice
}).then(invoice => { ... });
```

#### Download your invoice

```typescript
// Once you have successfully created your invoice, you can...
const fs = require('fs');
facturapi.invoices.downloadZip(invoice.id) // or downloadPdf or downloadXml
  .then(zipStream => {
    // stream containing the PDF and XML as a ZIP file
    // Save your invoice to a folder
    const myZipFile = fs.createWriteStream('/path/to/destination/folder');
    zipStream.pipe(myZipFile);
    myZipFile.on('finish', () => {
      // Finished downloading, Yay!
    });
```

#### Send your invoice by email

```typescript
// Send the invoice to your customer's email (if any)
facturapi.invoices
  .sendByEmail(invioce.id) // Also returns a Promise
  .then(() => {
    // Successfully sent
  })
  .catch(err => console.log(err)); // Handle the error.
```

## Documentation

There's more you can do with this library: List, retrieve, update, and remove Customers, Products and Invoices.

Visit the full documentation at http://docs.facturapi.io.

## Help

### Found a bug?

Please report it on the Issue Tracker

### Want to contribute?

Send us your PR! We appreciate your help :)

### Contact us!

contacto@facturapi.io