Merge pull request #139 from FacturAPI/document/drafts

Document/drafts

website/docs/advanced/dates.mdx → website/docs/getting-started/dates.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 4
 ---
 
 # Formato de fechas

website/docs/guides/drafts.mdx

@@ -0,0 +1,256 @@
+---
+sidebar_position: 8
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Borradores de facturas
+
+Los borradores de facturas te permiten guardar una factura con datos
+preliminares o incompletos, para que puedas enviarla a tu cliente para su
+revisión antes de aplicar el timbrado y enviarla al SAT.
+
+Una vez guardada, puedes descargar el PDF, pero no el XML de un borrador.
+
+:::info
+Para crear borradores de facturas, tu organización emisora deberá
+tener contratado el plan **Advanced** o superior. Más información en
+nuestra [página de planes y precios](https://www.facturapi.io/pricing).
+:::
+
+## Crear un borrador
+
+Para crear un borrador de factura, simplemente crea una factura usando el
+método [`createInvoice`](/api/#tag/invoice/operation/createInvoice) enviando
+los datos que desees guardar y especificando el campo `status` como `draft`.
+
+<Tabs groupId="codeExamples">
+<TabItem value="js" label="Node.js" default>
+
+```javascript
+const Facturapi = require('facturapi');
+const facturapi = new Facturapi('sk_test_API_KEY');
+
+const invoice = await facturapi.invoices.create({
+  status: 'draft', // Guardar como borrador
+  customer: null, // Cuando guardas un borrador, todos los campos se vuelven opcionales
+  items: [{
+    quantity: 2,
+    product: {
+      description: 'Ukelele',
+      product_key: '60131324',
+      price: 345.60,
+      taxes: [
+        {
+          type: 'IVA',
+          rate: 0.16
+        }
+      ]
+    }
+  }],
+  use: 'G01',
+  payment_form: "28"
+});
+```
+
+</TabItem>
+<TabItem value="cs" label="C#">
+
+```csharp
+var facturapi = new FacturapiClient("sk_test_API_KEY");
+
+var invoice = await facturapi.Invoice.CreateAsync(new Dictionary<string, object>
+{
+  ["status"] = "draft", // Guardar como borrador
+  ["customer"] = null, // Cuando guardas un borrador, todos los campos se vuelven opcionales
+  ["items"] = new Dictionary<string, object>[]
+  {
+    new Dictionary<string, object>
+    {
+      ["quantity"] = 2,
+      ["product"] = new Dictionary<string, object>
+      {
+        ["description"] = "Ukelele",
+        ["product_key"] = "60131324",
+        ["price"] = 345.60,
+        ["taxes"] = new Dictionary<string, object>[]
+        {
+          new Dictionary<string, object>
+          {
+            ["type"] = "IVA",
+            ["rate"] = 0.16
+          }
+        }
+      }
+    }
+  },
+  ["use"] = "G01",
+  ["payment_form"] = "28"
+});
+```
+
+</TabItem>
+<TabItem value="php" label="PHP">
+
+```php
+$facturapi = new Facturapi( "sk_test_API_KEY" );
+
+$invoice = $facturapi->Invoices->create([
+  "status" => "draft", // Guardar como borrador
+  "customer" => null, // Cuando guardas un borrador, todos los campos se vuelven opcionales
+  "items" => [
+    [
+      "quantity" => 2,
+      "product" => [
+        "description" => "Ukelele",
+        "product_key" => "60131324",
+        "price" => 345.60,
+        "taxes" => [
+          [
+            "type" => "IVA",
+            "rate" => 0.16,
+          ]
+        ]
+      ]
+    ],
+  ],
+  "payment_form" => "28"
+]);
+```
+
+</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 '{
+    "status": "draft", // Guardar como borrador
+    "customer": null, // Cuando guardas un borrador, todos los campos se vuelven opcionales
+    "items": [{
+      "quantity": 2,
+      "product": {
+        "description": "Ukelele",
+        "product_key": "60131324",
+        "price": 345.60,
+        "taxes": [
+          {
+            "type": "IVA",
+            "rate": 0.16
+          }
+        ]
+      }
+    }],
+    "use": "G01",
+    "payment_form": "28"
+  }'
+```
+
+</TabItem>
+</Tabs>
+
+## Editar un borrador
+
+Para editar un borrador puedes usar el método
+[`updateDraftInvoice`](/api/#tag/invoice/operation/updateDraftInvoice) y
+actualizar la factura con los datos que desees cambiar.
+
+<Tabs groupId="codeExamples">
+<TabItem value="js" label="Node.js" default>
+
+```javascript
+const Facturapi = require('facturapi');
+const facturapi = new Facturapi('sk_test_API_KEY');
+
+const invoice = await facturapi.invoices.updateDraft('[INVOICE_ID]', {
+  customer: {
+    legal_name: 'Dunder Mifflin',
+    email: 'email@example.com',
+    tax_id: 'ABC101010111',
+    tax_system: '601',
+    address: {
+      zip: '85900'
+    }
+  }
+});
+```
+
+</TabItem>
+<TabItem value="cs" label="C#">
+
+```csharp
+var facturapi = new FacturapiClient("sk_test_API_KEY");
+
+var invoice = await facturapi.Invoice.UpdateDraft(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"
+    }
+  }
+});
+```
+
+</TabItem>
+<TabItem value="php" label="PHP">
+
+```php
+$facturapi = new Facturapi( "sk_test_API_KEY" );
+
+$invoice = $facturapi->Invoices->create([
+  "customer" => [
+    "legal_name" => "Dunder Mifflin",
+    "email" => "email@example.com",
+    "tax_id" => "ABC101010111",
+    "tax_system" => "601",
+    "address" => [
+      "zip" => "85900"
+    ]
+  ]
+]);
+```
+
+</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"
+      }
+    }
+  }'
+```
+
+</TabItem>
+</Tabs>
+
+## Cómo saber si un borrador está listo para timbrar
+
+Para saber si un borrador está listo para timbrar, puedes usar el método
+[`getInvoice`](/api/#tag/invoice/operation/getInvoice) y revisar el campo 
+`is_ready_to_stamp`, que tendrá el valor `true` cuando todos los campos
+requeridos estén completos.
+
+## Timbrar un borrador
+
+Para timbrar un borrador, utiliza el método
+[`stampDraftInvoice`](/api/#tag/invoice/operation/stampDraftInvoice)
+y especifica el ID de la factura. Si la factura no está lista para timbrar,
+recibirás un error como respuesta.

website/docs/guides/invoices/index.mdx

@@ -1,17 +1,42 @@
-# CFDI
+# Facturas / CFDI
+
+Un Comprobante Fiscal Digital por Internet (CFDI) es un documento electrónico
+que se utiliza para comprobar la realización de una transacción comercial entre dos partes.
+En México, los CFDI son emitidos por contribuyentes autorizados por el Servicio de Administración
+Tributaria (SAT) y deben cumplir con ciertos requisitos para ser válidos, como contar con la
+firma electrónica del emisor y el sello digital del SAT.
+
+Los comprobantes que emite Facturapi cumplen con dichos requisitos y son válidos ante el SAT.
 
-Existen 6 tipos de CFDI, pueden incluir complementos o relacionarse entre ellos:
 
 ## Tipos de comprobantes
 
-- [Comprobante de Ingreso](/docs/guides/invoices/ingreso)
-- [Comprobante de Egreso](/docs/guides/invoices/egreso)
-- [Comprobante de Pago](/docs/guides/invoices/pago)
-- [Comprobante de Nomina](/docs/guides/invoices/nomina)
-- [Comprobante de Traslado](/docs/guides/invoices/traslado)
-- [Comprobante de Retenciones](/docs/guides/invoices/retencion)
+Ya que los CFDI amparan operaciones comerciales, estos a su vez pueden ser de diferentes tipos,
+dependiendo de la naturaleza de la transacción que se está realizando.
+
+Existen 6 tipos de facturas o Comprobantes (CFDI):
+
+| Tipo de Comprobante | ¿Para qué se usa? | Ejemplos |
+|:------------------- |:----------------- |:-------- |
+| [Comprobante de Ingreso](/docs/guides/invoices/ingreso) | Registrar ingresos por venta de productos o por el cobro de servicios, ya sea de contado o a crédito. | * Una ferretería vende un martillo y recibe el pago en efectivo.<br/>* Una escuela recibe el pago de una colegiatura |
+| [Comprobante de Egreso](/docs/guides/invoices/egreso) | Registrar descuentos o devoluciones. | * Una ferretería recibe un martillo defectuoso y devuelve el dinero.<br/>* Una tienda de ropa aplica un descuento a un cliente por ser frecuente. |
+| [Comprobante de Pago](/docs/guides/invoices/pago) | Registrar pagos a una factura de ingreso en la que se registró una venta a crédito (Pago en Parcialidades o Diferido). | * Una empresa paga una factura de compra a un proveedor.<br/>* Un cliente paga una factura de venta a crédito. |
+| [Comprobante de Nomina](/docs/guides/invoices/nomina) | Registrar el pago de salarios a los empleados de una empresa. | * Una empresa paga el salario quincenal a sus empleados. |
+| [Comprobante de Traslado](/docs/guides/invoices/traslado) | Registrar el traslado de mercancías entre dos partes. | * Una empresa traslada mercancía de una sucursal a otra.<br/>* Una empresa de transporte traslada mercancía de un cliente a otro. |
+| [Comprobante de Retenciones](/docs/guides/invoices/retencion) | Registrar retenciones a proveedores e informar sobre pagos realizados a residentes en el extranjero. | * Una empresa contrata a un consultor independiente del extranjero y le emite un CFDI para informar al SAT y retener impuestos.<br/>* Una empresa importa productos y emite un CFDI al proveedor extranjero para informar al SAT y retener impuestos.<br/>* Una persona gana un premio en una lotería y el organizador le emite un CFDI para informar al SAT y retener impuestos. |
+
+## Complementos
+
+Los CFDI pueden incluir complementos, que son documentos electrónicos adicionales que se adjuntan
+al comprobante para proporcionar más información relacionada con la operación comercial.
+
+Puedes leer más sobre los complementos en la [sección de complementos](/docs/guides/invoices/complementos)
+
+## Relación entre comprobantes
+
+Los CFDI pueden estar relacionados entre sí, lo que significa que un comprobante puede hacer referencia
+a otro comprobante. Por ejemplo, una factura de pago puede estar relacionada con una factura de ingreso
+para indicar que el pago se realizó a una factura de venta a crédito.
 
-## Otros conceptos
+Puedes leer más sobre documentos relacionados en la [sección de documentos relacionados](/docs/guides/invoices/relacionados).
 
-- [Complementos](/docs/guides/invoices/complementos)
-- [Relacionados](/docs/guides/invoices/relacionados)

website/docs/quickstart.mdx

@@ -40,7 +40,7 @@ composer require facturapi/facturapi-php
 </TabItem>
 </Tabs>
 
-### 2. Crea tu primer factura
+### 2. Crea tu primera factura
 
 <Tabs groupId="codeExamples">
 <TabItem value="js" label="Node.js" default>

website/docusaurus.config.js

@@ -44,10 +44,6 @@ const darkCodeTheme = require("prism-react-renderer").themes.dracula;
               route: "/api",
               spec: 'openapi_v2.yaml',
             },
-            {
-              route: "/api_v1",
-              spec: "openapi_v1.yaml",
-            },
           ],
           theme: {
             primaryColor: "#4786FF",
@@ -77,12 +73,10 @@ const darkCodeTheme = require("prism-react-renderer").themes.dracula;
               label: "Documentación",
             },
             {
-              type: 'dropdown',
-              label: 'Referencia API',
-              items: [
-                { href: '/api', label: 'v2 (CFDI v4.0) ✅' }
-              ]
-            },
+              href: '/api', 
+              label: 'Referencia API'
+            }
+              ,
             {
               href: "https://github.com/facturapi",
               label: "GitHub",