From a5e273bafed64f39a0150a1f8eeebd327fff9716 Mon Sep 17 00:00:00 2001 From: javorosas Date: Thu, 11 Jul 2024 16:39:05 +0200 Subject: [PATCH 1/7] update "API reference" link --- website/docusaurus.config.js | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 5f743507..38c3270e 100644 --- a/website/docusaurus.config.js +++ b/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", From ad539dfe3e2886f9db6a446b1ed740c97ae55652 Mon Sep 17 00:00:00 2001 From: javorosas Date: Thu, 11 Jul 2024 16:39:14 +0200 Subject: [PATCH 2/7] fix typo --- website/docs/quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/quickstart.mdx b/website/docs/quickstart.mdx index 38780bc3..27e38002 100644 --- a/website/docs/quickstart.mdx +++ b/website/docs/quickstart.mdx @@ -40,7 +40,7 @@ composer require facturapi/facturapi-php -### 2. Crea tu primer factura +### 2. Crea tu primera factura From 162bbe38c59b75d57dffe652a0ff5cc6e4d278e9 Mon Sep 17 00:00:00 2001 From: javorosas Date: Thu, 11 Jul 2024 16:39:46 +0200 Subject: [PATCH 3/7] move "dates" article to "getting started" category --- website/docs/{advanced => getting-started}/dates.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename website/docs/{advanced => getting-started}/dates.mdx (99%) diff --git a/website/docs/advanced/dates.mdx b/website/docs/getting-started/dates.mdx similarity index 99% rename from website/docs/advanced/dates.mdx rename to website/docs/getting-started/dates.mdx index 6aeccd82..2c1a9ad1 100644 --- a/website/docs/advanced/dates.mdx +++ b/website/docs/getting-started/dates.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 4 --- # Formato de fechas From d5c27db1abe208546c4a4010a0ddf99c69213234 Mon Sep 17 00:00:00 2001 From: javorosas Date: Thu, 11 Jul 2024 16:40:16 +0200 Subject: [PATCH 4/7] expand invoices article --- website/docs/guides/invoices/index.mdx | 47 ++++++++++++++++++++------ 1 file changed, 36 insertions(+), 11 deletions(-) diff --git a/website/docs/guides/invoices/index.mdx b/website/docs/guides/invoices/index.mdx index fb957566..2495b160 100644 --- a/website/docs/guides/invoices/index.mdx +++ b/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.
* 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.
* 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.
* 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.
* 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.
* Una empresa importa productos y emite un CFDI al proveedor extranjero para informar al SAT y retener impuestos.
* 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) From 19496d3324c27f28599478b7e159d142fd67a04a Mon Sep 17 00:00:00 2001 From: javorosas Date: Thu, 11 Jul 2024 16:41:28 +0200 Subject: [PATCH 5/7] add drafts article --- website/docs/guides/drafts.mdx | 250 +++++++++++++++++++++++++++++++++ 1 file changed, 250 insertions(+) create mode 100644 website/docs/guides/drafts.mdx diff --git a/website/docs/guides/drafts.mdx b/website/docs/guides/drafts.mdx new file mode 100644 index 00000000..42b03c33 --- /dev/null +++ b/website/docs/guides/drafts.mdx @@ -0,0 +1,250 @@ +--- +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 +preeliminares 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. + +## 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`. + + + + +```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" +}); +``` + + + + +```csharp +var facturapi = new FacturapiClient("sk_test_API_KEY"); + +var invoice = await facturapi.Invoice.CreateAsync(new Dictionary +{ + ["status"] = "draft", // Guardar como borrador + ["customer"] = null, // Cuando guardas un borrador, todos los campos se vuelven opcionales + ["items"] = new Dictionary[] + { + new Dictionary + { + ["quantity"] = 2, + ["product"] = new Dictionary + { + ["description"] = "Ukelele", + ["product_key"] = "60131324", + ["price"] = 345.60, + ["taxes"] = new Dictionary[] + { + new Dictionary + { + ["type"] = "IVA", + ["rate"] = 0.16 + } + } + } + } + }, + ["use"] = "G01", + ["payment_form"] = "28" +}); +``` + + + + +```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" +]); +``` + + + + +```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" + }' +``` + + + + +## 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. + + + + +```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' + } + } +}); +``` + + + + +```csharp +var facturapi = new FacturapiClient("sk_test_API_KEY"); + +var invoice = await facturapi.Invoice.UpdateDraft(new Dictionary +{ + ["customer"] = new Dictionary + { + ["legal_name"] = "Dunder Mifflin", + ["email"] = "email@example.com", + ["tax_id"] = "ABC101010111", + ["tax_system"] = "601", + ["address"] = new Dictionary + { + ["zip"] = "85900" + } + } +}); +``` + + + + +```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" + ] + ] +]); +``` + + + + +```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" + } + } + }' +``` + + + + +## 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. \ No newline at end of file From e6d10e58e2eac52802b7992b3def36998dda3def Mon Sep 17 00:00:00 2001 From: javorosas Date: Thu, 11 Jul 2024 17:32:31 +0200 Subject: [PATCH 6/7] fix typo --- website/docs/guides/drafts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/drafts.mdx b/website/docs/guides/drafts.mdx index 42b03c33..ff4a1088 100644 --- a/website/docs/guides/drafts.mdx +++ b/website/docs/guides/drafts.mdx @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem'; # Borradores de facturas Los borradores de facturas te permiten guardar una factura con datos -preeliminares o incompletos, para que puedas enviarla a tu cliente para su +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. From 7cd8785e5be403d894904a80a13f164e6c01c5a9 Mon Sep 17 00:00:00 2001 From: javorosas Date: Thu, 11 Jul 2024 17:37:20 +0200 Subject: [PATCH 7/7] indicate required plan for drafts --- website/docs/guides/drafts.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/website/docs/guides/drafts.mdx b/website/docs/guides/drafts.mdx index ff4a1088..9b8f3a82 100644 --- a/website/docs/guides/drafts.mdx +++ b/website/docs/guides/drafts.mdx @@ -13,6 +13,12 @@ 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