Merge pull request #167 from FacturAPI/FAC-1224/async-invoices

Add tutorial for async invoices

Author: javorosas

website/docs/guides/_category_.json

@@ -1,4 +1,5 @@
 {
   "label": "Guías",
-  "position": 4
+  "position": 4,
+  "collapsed": false
 }

website/docs/guides/invoices/_category_.json

@@ -1,3 +1,4 @@
 {
-  "position": 3
+  "position": 3,
+  "collapsed": false
 }

website/docs/guides/invoices/async-invoices.mdx

@@ -0,0 +1,223 @@
+---
+sidebar_position: 9
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Facturación asíncrona
+
+Cuando el tamaño de tus facturas es muy grande, o necesitas facturar muchas facturas al mismo tiempo, es recomendable (y en algunos casos requerido) utilizar la facturación asíncrona. Esto te permite registrar una factura en Facturapi
+y recibir una respuesta inmediata con el objeto Invoice y su ID, pero sin timbrar todavía. El timbrado de la factura se realiza en segundo plano, y puedes consultar el estado de la factura en cualquier momento
+por medio del método de obtener factura.
+
+## Crear una factura asíncrona
+
+Una factura se creará de manera asíncrona en cualquiera de estos 2 casos:
+
+- Si se envía el parámetro `async` con el valor `true` al crear la factura.
+- Si el tamaño de la información enviada excede los 2MB (CFDIs con alrededor de 5,000 elementos o con un complemento de carta porte muy extenso).
+
+En cualquiera de los 2 casos recibirás el objeto invoice como respuesta, con el campo `status` en `pending`. Esto significa que la factura se está procesando en segundo plano. Mientras esto ocurre, es importante
+señalar que los campos `stamp` y `uuid` serán null. Una vez timbrada la factura, el campo `status` cambiará a `valid` y se llenarán los campos `stamp` y `uuid` con la información del timbrado.
+
+### Petición
+
+<Tabs groupId="codeExamples">
+<TabItem value="js" label="Node.js" default>
+
+```javascript
+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: 2,
+    product: {
+      description: 'Ukelele',
+      product_key: '60131324', // ClaveProdServ del SAT
+      price: 345.60,
+      taxes: [
+        {
+          type: 'IVA',
+          rate: 0.16
+        }
+      ]
+    }
+  }],
+  use: 'G01',
+  payment_form: "28" // "Tarjeta de débito"
+}, { async: true });
+```
+
+</TabItem>
+<TabItem value="cs" label="C#">
+
+```csharp
+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 List<Dictionary<string, object>>
+  {
+    new Dictionary<string, object>
+    {
+      ["quantity"] = 2,
+      ["product"] = new Dictionary<string, object>
+      {
+        ["description"] = "Ukelele",
+        ["product_key"] = "60131324",
+        ["price"] = 345.60,
+        ["taxes"] = new List<Dictionary<string, object>>
+        {
+          new Dictionary<string, object>
+          {
+            ["type"] = "IVA",
+            ["rate"] = 0.16
+          }
+        }
+      }
+    }
+  },
+  ["use"] = "G01",
+  ["payment_form"] = "28" // "Tarjeta de débito"
+}, new Dictionary<string, object>
+{
+  ["async"] = true
+});
+```
+
+</TabItem>
+<TabItem value="php" label="PHP">
+
+```php
+$invoice = $facturapi->Invoices->create([
+  "customer" => [
+    "legal_name" => "Dunder Mifflin",
+    "email" => "email@example.com",
+    "tax_id" => "ABC101010111",
+    "tax_system" => "601",
+    "address" => [
+      "zip" => "85900"
+    ]
+  ],
+  "items" => [
+    [
+      "quantity" => 2,
+      "product" => [
+        "description" => "Ukelele",
+        "product_key" => "60131324",
+        "price" => 345.60,
+        "taxes" => [
+          [
+            "type" => "IVA",
+            "rate" => 0.16
+          ]
+        ]
+      ]
+    ]
+  ],
+  "use" => "G01",
+  "payment_form" => "28" // "Tarjeta de débito"
+], [
+  "async" => true
+]);
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl https://www.facturapi.io/v2/invoices \
+  -H "
+  Authorization Bearer sk_test_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "customer": {
+      "legal_name": "Dunder Mifflin",
+      "email": "email@example.com",
+      "tax_id": "ABC101010111",
+      "tax_system": "601",
+      "address": {
+        "zip": "85900"
+      }
+    },
+    "items": [
+      {
+        "quantity": 2,
+        "product": {
+          "description": "Ukelele",
+          "product_key": "60131324",
+          "price": 345.60,
+          "taxes": [
+            {
+              "type": "IVA",
+              "rate": 0.16
+            }
+          ]
+        }
+      }
+    ],
+    "use": "G01",
+    "payment_form": "28" // "Tarjeta de débito"
+  }'
+```
+
+</TabItem>
+</Tabs>
+
+### Response
+
+```json
+{
+  "id": "5f4b1b4b4b4b4b4b4b4b4b4a",
+  "created_at": "2020-08-29T00:00:00.000Z",
+  "status": "pending",
+  "customer": {
+    "id": "5f4b1b4b4b4b4b4b4b4b4b4b",
+    "legal_name": "Dunder Mifflin",
+    "email": "email@example.com",
+    "tax_id": "ABC101010111",
+    "tax_system": "601",
+    "address": {
+      "country": "MEX",
+      "zip": "85900"
+    }
+  },
+  "items": [
+    {
+      "quantity": 2,
+      "product": {
+        "description": "Ukelele",
+        "product_key": "60131324",
+        "price": 345.60,
+        "taxes": [
+          {
+            "type": "IVA",
+            "rate": 0.16
+          }
+        ]
+      }
+    }
+  ],
+  "use": "G01",
+  "payment_form": "28",
+  "stamp": null,
+  "uuid": null
+}
+```