Skip to content

Commit 16c3f7c

Browse files
javorosasjavorosas
committed
Añadir sección de cancelaciones
1 parent 38c4e74 commit 16c3f7c

6 files changed

Lines changed: 142 additions & 2 deletions

File tree

‎website/docs/guides/invoices/cancelaciones.mdx‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
sidebar_position: 10
3+
title: Cancelaciones
4+
---
5+
6+
# Cancelaciones de CFDI
7+
8+
Esta guía explica cómo funciona la cancelación de facturas en Facturapi, qué significa cada estado y qué debes esperar después de solicitar la cancelación.
9+
10+
## Requisitos y reglas
11+
12+
- Solo puedes cancelar facturas con `status: "valid"`.
13+
- Si la factura está en `draft`, el método de cancelar la elimina.
14+
- Si la factura ya está `canceled` o tiene una cancelación en curso (`cancellation_status: "pending"` o `"verifying"`), el método regresará error.
15+
16+
## Motivos de cancelación (SAT) y sustitución
17+
18+
El SAT define **Motivos de cancelación** y Facturapi los expone con el parámetro `motive`. La cancelación usa el **nuevo esquema de cancelación del SAT (vigente desde 2022)**.
19+
20+
- `01`: **Comprobante emitido con errores con relación**. Requiere `substitution` con el UUID (o ID de Facturapi) de la factura que sustituye a la anterior.
21+
- `02`: **Comprobante emitido con errores sin relación**.
22+
- `03`: **No se llevó a cabo la operación**.
23+
- `04`: **Operación nominativa relacionada en una factura global**.
24+
25+
El SAT exige que el motivo sea coherente con el caso de uso; si no, la cancelación puede fallar.
26+
27+
Notas:
28+
29+
- Si eliges el Motivo `01`, debes enviar `substitution` y esa factura debe existir.
30+
- Si el SAT considera que tu CFDI no es cancelable (por su estatus o relaciones), la solicitud será rechazada aunque el Motivo sea válido.
31+
32+
## Flujo de cancelación y estados
33+
34+
Después de llamar a `cancelInvoice`, puede ocurrir:
35+
36+
- Respuesta exitosa con `status: "canceled"` y `cancellation_status: "accepted"` (cancelación finalizada).
37+
- Respuesta exitosa con `status: "valid"` y `cancellation_status: "pending"` (requiere aceptación del receptor).
38+
- Respuesta exitosa con `status: "valid"` y `cancellation_status: "verifying"` (el SAT recibió la solicitud y la está validando).
39+
- Error con la explicación de por qué no se pudo cancelar.
40+
41+
Significado de `cancellation_status`:
42+
43+
| Estado | Significado | Qué hacer |
44+
|:--|:--|:--|
45+
| `none` | No hay solicitud registrada por el SAT. | Puedes solicitar la cancelación si aplica. |
46+
| `verifying` | El SAT recibió la solicitud y la está validando. | Espera la actualización automática o consulta el invoice. |
47+
| `pending` | Requiere aceptación del receptor. | Espera aceptación/rechazo o expiración. |
48+
| `accepted` | La cancelación fue aceptada. | La factura queda en `status: "canceled"`. |
49+
| `rejected` | La cancelación fue rechazada. | Revisa el motivo y vuelve a intentar si aplica. |
50+
| `expired` | El receptor no respondió a tiempo. | Puedes intentar cancelar de nuevo si aplica. |
51+
52+
## Actualización automática del estado
53+
54+
Facturapi consulta periódicamente el SAT y actualiza `cancellation_status`. Puedes:
55+
56+
- Consultar la factura con [Obtener Factura](/api/#tag/invoice/operation/getInvoice).
57+
- Suscribirte al webhook `invoice.cancellation_status_updated` para recibir cambios cuando el estado deje de estar `pending` o `verifying`.
58+
59+
## Acuse de cancelación y verificación
60+
61+
Cuando la cancelación es aceptada, puedes descargar el acuse en XML o PDF desde el endpoint de [Cancellation receipt](/api/#tag/invoice/operation/downloadCancellationReceiptXml). También puedes validar el CFDI con `verification_url`.
62+
63+
## Errores comunes
64+
65+
- `409 Conflict`: la factura no está en `valid` o ya tiene una cancelación en curso.
66+
- `400 Bad Request`: motivo inválido o falta `substitution` cuando el SAT lo requiere.
67+
- `404 Not Found`: el folio o UUID no existe en el SAT.

‎website/docs/guides/invoices/index.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,6 @@ para indicar que el pago se realizó a una factura de venta a crédito.
4040

4141
Puedes leer más sobre documentos relacionados en la [sección de documentos relacionados](/docs/guides/invoices/relacionados).
4242

43+
## Cancelaciones
44+
45+
El SAT requiere motivos específicos y, en ciertos casos, la aceptación del receptor. Consulta el flujo completo, estados y recomendaciones en la [guía de cancelaciones](/docs/guides/invoices/cancelaciones).

‎website/i18n/en/docusaurus-plugin-content-docs/current/guides/invoices/cancelaciones.mdx‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
sidebar_position: 10
3+
title: Cancellations (Cancelaciones)
4+
---
5+
6+
# CFDI cancellations
7+
8+
This guide explains how invoice cancellations work in Facturapi, what each status means, and what to expect after requesting a cancellation.
9+
10+
## Requirements and rules
11+
12+
- You can only cancel invoices with `status: "valid"`.
13+
- If the invoice is `draft`, the cancel method deletes it.
14+
- If the invoice is already `canceled` or has a cancellation in progress (`cancellation_status: "pending"` or `"verifying"`), the method will return an error.
15+
16+
## Cancellation motives (SAT) and substitution
17+
18+
The SAT defines **cancellation motives**, and Facturapi exposes them via the `motive` parameter. Cancellations use the **SAT's new cancellation scheme (effective since 2022)**.
19+
20+
- `01`: **Invoice issued with errors with relation**. Requires `substitution` with the UUID (or Facturapi ID) of the replacing invoice.
21+
- `02`: **Invoice issued with errors without relation**.
22+
- `03`: **Operation not carried out**.
23+
- `04`: **Nominative operation related to a global invoice**.
24+
25+
The SAT expects the motive to match the use case; otherwise the cancellation may fail.
26+
27+
Notes:
28+
29+
- If you choose motive `01`, you must send `substitution`, and the replacement invoice must exist.
30+
- If the SAT considers your CFDI non-cancellable (by status or relationships), the request will be rejected even if the motive is valid.
31+
32+
## Cancellation flow and statuses
33+
34+
After calling `cancelInvoice`, you may get:
35+
36+
- Success with `status: "canceled"` and `cancellation_status: "accepted"` (finalized).
37+
- Success with `status: "valid"` and `cancellation_status: "pending"` (requires receiver approval).
38+
- Success with `status: "valid"` and `cancellation_status: "verifying"` (SAT received the request and is validating it).
39+
- An error explaining why the cancellation could not be completed.
40+
41+
Meaning of `cancellation_status`:
42+
43+
| Status | Meaning | What to do |
44+
|:--|:--|:--|
45+
| `none` | No request registered by the SAT. | You can request cancellation if needed. |
46+
| `verifying` | SAT received the request and is validating it. | Wait for automatic updates or fetch the invoice. |
47+
| `pending` | Receiver approval is required. | Wait for acceptance/rejection or expiration. |
48+
| `accepted` | Cancellation was accepted. | Invoice moves to `status: "canceled"`. |
49+
| `rejected` | Cancellation was rejected. | Review the motive and retry if applicable. |
50+
| `expired` | Receiver did not respond in time. | You may retry cancellation if applicable. |
51+
52+
## Automatic status updates
53+
54+
Facturapi periodically checks the SAT and updates `cancellation_status`. You can:
55+
56+
- Fetch the invoice using [Get Invoice](/api/#tag/invoice/operation/getInvoice).
57+
- Subscribe to the `invoice.cancellation_status_updated` webhook to receive changes when the status leaves `pending` or `verifying`.
58+
59+
## Cancellation receipt and verification
60+
61+
When the cancellation is accepted, you can download the cancellation receipt in XML or PDF from the [Cancellation receipt](/api/#tag/invoice/operation/downloadCancellationReceiptXml) endpoint. You can also validate the CFDI using `verification_url`.
62+
63+
## Common errors
64+
65+
- `409 Conflict`: the invoice is not `valid` or already has a cancellation in progress.
66+
- `400 Bad Request`: invalid motive or missing `substitution` when required by SAT rules.
67+
- `404 Not Found`: the folio or UUID does not exist in the SAT.

‎website/i18n/en/docusaurus-plugin-content-docs/current/guides/invoices/index.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,6 @@ para indicar que el pago se realizó a una factura de venta a crédito.
4040

4141
Puedes leer más sobre documentos relacionados en la [sección de documentos relacionados](/docs/guides/invoices/relacionados).
4242

43+
## Cancelaciones
44+
45+
El SAT requiere motivos específicos y, en ciertos casos, la aceptación del receptor. Consulta el flujo completo, estados y recomendaciones en la [guía de cancelaciones](/docs/guides/invoices/cancelaciones).

‎website/openapi_v1.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1517,7 +1517,7 @@ paths:
15171517
- invoice
15181518
summary: Cancelar factura
15191519
description: |
1520-
Realiza una solicitud de cancelación de factura ante el SAT, soportando el esquema de cancelación 2022.
1520+
Realiza una solicitud de cancelación de factura ante el SAT, soportando el **nuevo esquema de cancelación del SAT (vigente desde 2022)**.
15211521
15221522
Al usar este método pueden ocurrir los siguientes resultados:
15231523

‎website/openapi_v2.en.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3116,7 +3116,7 @@ paths:
31163116
- invoice
31173117
summary: Cancel invoice
31183118
description: |
3119-
Creates a cancellation request to the SAT for the specified invoice.
3119+
Creates a cancellation request to the SAT for the specified invoice, using the **SAT's new cancellation scheme (effective since 2022)**.
31203120
31213121
When using this method, the following results can occur:
31223122

0 commit comments

Comments
 (0)