Document global invoice automation

website/docs/getting-started/errors.mdx

@@ -195,6 +195,9 @@ Estos códigos describen errores de información fiscal validados por Facturapi.
 | `invoice_not_draft` | La factura no es un borrador. |
 | `invoice_not_found` | No se encontró la factura. |
 | `invoice_not_stamped` | La factura no ha sido timbrada. |
+| `zip_request_no_invoices` | No se encontraron facturas para generar el archivo ZIP. |
+| `zip_request_not_found` | No se encontró la solicitud del archivo ZIP. |
+| `zip_request_not_ready` | El archivo ZIP todavía no está listo para descargarse. |
 
 ### InvoiceDraftErrorCode
 
@@ -260,7 +263,7 @@ Estos códigos describen errores de información fiscal validados por Facturapi.
 
 | Código | Descripción |
 | --- | --- |
-| `global_invoice_too_many_items` | La factura global excede el máximo de 5,000 conceptos soportados. Genera varias facturas globales usando rangos de fechas más pequeños o subconjuntos de recibos. |
+| `global_invoice_too_many_items` | El periodo contiene más de 5,000 recibos abiertos. Envía `limit_to_max_receipts` para facturar hasta 5,000 por llamada o usa rangos de fechas o subconjuntos de recibos. |
 | `invalid_global_invoice_period` | El rango de fechas debe estar dentro del mismo periodo de facturación: `{period}`. |
 
 ### RetentionErrorCode
@@ -269,6 +272,7 @@ Estos códigos describen errores de información fiscal validados por Facturapi.
 | --- | --- |
 | `invalid_retention_complement` | El complemento de retención no es válido. |
 | `retention_not_found` | No se encontró la retención. |
+| `retention_not_draft` | La retención no es un borrador. |
 | `retention_not_stamped` | La retención no ha sido timbrada. |
 | `retention_not_cancelable` | La retención no puede cancelarse. |
 

website/docs/guides/receipts.mdx

@@ -189,6 +189,49 @@ factura global a `PUBLICO EN GENERAL`.
   Los recibos incluidos quedan asociados a ese cliente y cambian su `status` a
   `"invoiced_globally"`.
 
+### Facturas globales con más de 5,000 recibos
+
+El límite de una factura global se calcula sobre los recibos abiertos incluidos, no
+sobre los conceptos resultantes después de agruparlos.
+
+Si un periodo contiene más de 5,000 recibos, envía
+`limit_to_max_receipts: true`. La llamada generará una factura con hasta 5,000
+recibos y dejará el resto con `status = "open"`. Repite la misma solicitud,
+conservando el rango y la periodicidad originales, hasta que la API responda `null`.
+Así puedes dividir un mismo periodo entre varias facturas globales sin cambiar su
+información de periodicidad.
+
+Si omites esta opción, la API devuelve
+`global_invoice_too_many_items` y no genera una factura parcial.
+
+### Automatizar las facturas globales
+
+Las organizaciones que tienen contratado el feature de factura global pueden activar
+la automatización mediante
+[Editar configuración de recibos](/api/#tag/organization/operation/editOrganizationReceiptsSettings):
+
+```json
+{
+  "periodicity": "month",
+  "activate_global_invoice": true
+}
+```
+
+La automatización procesa cada periodo después de que termina, según la zona horaria
+de la organización. Puedes cambiar `periodicity` para reprogramar los periodos futuros
+o enviar `activate_global_invoice: false` para pausarla. Los periodos que transcurran
+mientras esté desactivada no se facturan automáticamente al reactivarla.
+
+Las tareas automáticas y programadas se pueden monitorear desde
+[Factura global automática](https://dashboard.facturapi.io/receipts/global-invoice-automation)
+en el Dashboard.
+
+### Agrupar conceptos al facturar recibos seleccionados
+
+La opción de configuración `grouped_items_invoice` agrupa conceptos
+equivalentes cuando se facturan varios recibos seleccionados, tanto desde la API como
+desde el portal de autofactura. No se utiliza para las facturas globales.
+
 ### Facturar un recibo
 
 Por medio del método [Facturar Recibo](/api/#tag/receipt/operation/invoiceReceipt) puedes convertir

website/docs/guides/self-invoice.mdx

@@ -60,7 +60,7 @@ abierto puede facturarse en cualquier momento por medio de la API, sin embargo,
 el portal de autofactura no permitirá facturar recibos después de su fecha de
 expiración (campo `expires_at`), la cual se calcula al momento de crear el
 recibo a partir de las [configuraciones de recibos](/docs/guides/receipts/) "Periodo de facturación"
-(`invoicing_period`) y "Días de vigencia para facturar" (`duration_days`).
+(`periodicity`) y "Días de vigencia para facturar" (`duration_days`).
 
 Por ejemplo, si tu periodo de facturación es mensual y tus días de vigencia
 para facturar son 7, el recibo expirará ya sea a los 7 días de su fecha de

website/i18n/en/docusaurus-plugin-content-docs/current/getting-started/errors.mdx

@@ -195,6 +195,9 @@ These codes describe tax-information errors validated by Facturapi. When a custo
 | `invoice_not_draft` | The invoice is not a draft. |
 | `invoice_not_found` | The invoice was not found. |
 | `invoice_not_stamped` | The invoice has not been stamped. |
+| `zip_request_no_invoices` | No invoices were found to generate the ZIP file. |
+| `zip_request_not_found` | The ZIP request was not found. |
+| `zip_request_not_ready` | The ZIP file is not ready to download yet. |
 
 ### InvoiceDraftErrorCode
 
@@ -260,7 +263,7 @@ These codes describe tax-information errors validated by Facturapi. When a custo
 
 | Code | Description |
 | --- | --- |
-| `global_invoice_too_many_items` | The global invoice exceeds the maximum of 5,000 supported items. Create multiple global invoices using smaller date ranges or receipt subsets. |
+| `global_invoice_too_many_items` | The period contains more than 5,000 open receipts. Send `limit_to_max_receipts` to invoice up to 5,000 per request, or use smaller date ranges or receipt subsets. |
 | `invalid_global_invoice_period` | The date range must be within the same billing period: `{period}`. |
 
 ### RetentionErrorCode
@@ -269,6 +272,7 @@ These codes describe tax-information errors validated by Facturapi. When a custo
 | --- | --- |
 | `invalid_retention_complement` | The retention complement is invalid. |
 | `retention_not_found` | The retention was not found. |
+| `retention_not_draft` | The retention is not a draft. |
 | `retention_not_stamped` | The retention has not been stamped. |
 | `retention_not_cancelable` | The retention cannot be canceled. |
 

website/i18n/en/docusaurus-plugin-content-docs/current/guides/receipts.mdx

@@ -190,6 +190,48 @@ to `PUBLICO EN GENERAL`.
   customer. Included receipts are associated with that customer and their `status`
   changes to `"invoiced_globally"`.
 
+### Global invoices with more than 5,000 receipts
+
+The global invoice limit is based on the number of included open receipts, not on
+the resulting items after they are grouped.
+
+If a period contains more than 5,000 receipts, send
+`limit_to_max_receipts: true`. The request creates an invoice with up to 5,000
+receipts and leaves the rest with `status = "open"`. Repeat the same request,
+keeping the original date range and periodicity, until the API responds with `null`.
+This lets you split one period across multiple global invoices without changing its
+periodicity information.
+
+If you omit this option, the API returns
+`global_invoice_too_many_items` and does not create a partial invoice.
+
+### Automate global invoices
+
+Organizations with the global invoice feature can enable automation through
+[Edit receipt settings](/api/#tag/organization/operation/editOrganizationReceiptsSettings):
+
+```json
+{
+  "periodicity": "month",
+  "activate_global_invoice": true
+}
+```
+
+The automation processes each period after it ends, using the organization's time
+zone. You can change `periodicity` to reschedule future periods or send
+`activate_global_invoice: false` to pause it. Periods elapsed while automation is
+disabled are not automatically invoiced when it is enabled again.
+
+Automatic and scheduled tasks can be monitored from
+[Automatic global invoice](https://dashboard.facturapi.io/receipts/global-invoice-automation)
+in the Dashboard.
+
+### Group items when invoicing selected receipts
+
+The `grouped_items_invoice` setting groups equivalent items when
+invoicing multiple selected receipts, both through the API and the self-invoice
+portal. It is not used for global invoices.
+
 ### Convert an e-receipt into an invoice
 
 With [Convert e-receipt to invoice](/api/#tag/receipt/operation/invoiceReceipt)

website/i18n/en/docusaurus-plugin-content-docs/current/guides/self-invoice.mdx

@@ -59,7 +59,7 @@ The receipt can only be invoiced while its `status` attribute has the value
 can be invoiced at any time through the API. However, the self-invoicing portal
 will not allow invoices to be generated for receipts after their expiration
 date (`expires_at` field), which is calculated at the time of creating the
-receipt based on the `invoicing_period` and `duration_days` fields from
+receipt based on the `periodicity` and `duration_days` fields from
 [receipt settings](/docs/guides/receipts/).
 
 For example, if your invoicing period is monthly and your duration days for

website/openapi_v2.en.yaml

@@ -6162,6 +6162,10 @@ paths:
         Global invoices are issued to the generic `PUBLICO EN GENERAL` customer.
         Included receipts are associated with that customer and their `status`
         changes to `"invoiced_globally"`.
+
+        A global invoice can include up to 5,000 open receipts. If the period contains
+        more, send `limit_to_max_receipts: true` and repeat the request with the same
+        period until the response is `null`.
       x-codeSamples:
         - lang: Bash
           label: cURL
@@ -6176,7 +6180,8 @@ paths:
                     "months": "01",
                     "year": 2021,
                     "folio_number": 1234,
-                    "series": "G"
+                    "series": "G",
+                    "limit_to_max_receipts": true
                 }'
         - lang: JavaScript
           label: Node.js
@@ -6189,9 +6194,10 @@ paths:
               to: '2020-12-31T04:59:59.999Z',
               periodicity: 'month',
               months: '01',
-              year: 2021
+              year: 2021,
               folio_number: 1234,
-              series: 'G'
+              series: 'G',
+              limit_to_max_receipts: true
             });
         - lang: csharp
           label: C#
@@ -6242,11 +6248,13 @@ paths:
         - "SecretTestKey": []
       responses:
         "200":
-          description: New `Invoice` object creaded
+          description: Created `Invoice` object, or `null` when the period has no open receipts
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/Invoice"
+                oneOf:
+                  - $ref: "#/components/schemas/Invoice"
+                  - type: "null"
         "400":
           $ref: "#/components/responses/BadRequest"
         "401":
@@ -8109,7 +8117,9 @@ paths:
         - organization
       summary: Edit receipts settings
       description: |
-        Update the organization's receipts settings.
+        Updates the supplied fields in the organization's receipt settings.
+        The organization must have the global invoice feature to enable automatic
+        global invoice generation.
       x-codeSamples:
         - lang: Bash
           label: cURL
@@ -8119,9 +8129,10 @@ paths:
               -H "Authorization: Bearer sk_user_API_KEY" \
               -H "Content-Type: application/json" \
               -d '{
-                    "invoicing_period": "month",
+                    "periodicity": "month",
                     "duration_days": 14,
-                    "next_folio_number": 100
+                    "next_folio_number": 100,
+                    "activate_global_invoice": true
                 }'
         - lang: JavaScript
           label: Node.js
@@ -8132,9 +8143,10 @@ paths:
             const organization = await facturapi.organizations.updateReceiptSettings(
               '5a2a307be93a2f00129ea035',
               {
-                invoicing_period: "month",
+                periodicity: "month",
                 duration_days: 14,
-                next_folio_number: 100
+                next_folio_number: 100,
+                activate_global_invoice: true
               }
             );
         - lang: csharp
@@ -8146,9 +8158,10 @@ paths:
               "5a2a307be93a2f00129ea035",
               new Dictionary<string, object>
               {
-                ["invoicing_period"] = "month",
+                ["periodicity"] = "month",
                 ["duration_days"] = 14,
-                ["next_folio_number"] = 100
+                ["next_folio_number"] = 100,
+                ["activate_global_invoice"] = true
               }
             );
         - lang: Java
@@ -8163,7 +8176,8 @@ paths:
             var organization = facturapi.organizations().updateReceiptSettings(
                 "org_123",
                 Map.of(
-                    "color", "#4786FF"
+                    "periodicity", "month",
+                    "activate_global_invoice", true
                 )
             );
         - lang: PHP
@@ -8173,9 +8187,10 @@ paths:
             $organization = $facturapi->Organizations->updateReceiptSettings(
               "5a2a307be93a2f00129ea035",
               [
-                "invoicing_period" => "month",
+                "periodicity" => "month",
                 "duration_days" => 14,
-                "next_folio_number" => 100
+                "next_folio_number" => 100,
+                "activate_global_invoice" => true
               ]
             );
       parameters:
@@ -17090,8 +17105,8 @@ components:
             - two_months
           description: |
             Periodicity that corresponds to the range of dates used.
-            If omitted, the organization's receipt configuration will be used.
-            If you omit sending the `from` and `to` fields, the default dates will depend on the value of `periodicity`.
+            If you omit the `from` and `to` fields, the default dates will depend
+            on the value of `periodicity`.
         months:
           type: string
           default: Month contained in the range of dates used.
@@ -17137,6 +17152,17 @@ components:
             maxLength: 24
             description: ID of a receipt previously registered in Facturapi.
             example: 614496b471d422de4b6cfcc4
+        limit_to_max_receipts:
+          type: boolean
+          default: false
+          description: |
+            Allows periods with more than 5,000 open receipts to be processed. When
+            `true`, the invoice includes at most 5,000 receipts and the remaining
+            receipts keep the `"open"` status. Repeat the request with the same period
+            until the response is `null`, which means no receipts remain to be invoiced.
+
+            When `false`, a period with more than 5,000 open receipts returns the
+            `global_invoice_too_many_items` error.
     ToInvoiceInput:
       type: object
       required:
@@ -17874,6 +17900,19 @@ components:
               description: |
                 Folio number that will be assigned to the next receipt in the Test environment.
                 It will be automatically incremented for each new receipt.
+            activate_global_invoice:
+              type: boolean
+              default: false
+              description: |
+                Indicates whether the organization automatically creates a global
+                invoice after each configured period closes. Requires the global
+                invoice feature.
+            grouped_items_invoice:
+              type: boolean
+              default: false
+              description: |
+                Groups equivalent items when invoicing multiple selected receipts,
+                including self-invoices. It does not affect global invoice generation.
         self_invoice:
           type: object
           description: |
@@ -18141,6 +18180,19 @@ components:
           type: integer
           description: |
             Folio number that will be assigned to the next receipt created in this organization in the Test environment.
+        activate_global_invoice:
+          type: boolean
+          default: false
+          description: |
+            Enables or disables automatic global invoice generation after each
+            configured period closes. The organization must have the global invoice
+            feature to enable it.
+        grouped_items_invoice:
+          type: boolean
+          default: false
+          description: |
+            When `true`, groups equivalent items when invoicing multiple selected
+            receipts, including self-invoices. It does not apply to global invoices.
     OrganizationSelfInvoiceInput:
       type: object
       properties: