Tezora

Correcciones

Caso Operación
Documento rechazado o no emitido POST /sales/{uuid}/document
Devolución, descuento o cargo sobre un CCF sellado POST /sales/{uuid}/adjustment-notes
Retiro de un documento sellado POST /sales/{uuid}/invalidation

Reintento del documento

Si Hacienda o el validador rechazan el documento, o no se puede emitir, la venta queda registrada con emission_failure (kind y message) y document nulo o rejected. Tras corregir el dato, POST /sales/{uuid}/document lo emite de nuevo; el cuerpo admite dte_type y customer. Lo que impide la emisión se informa en errors.document.

Un documento en contingencia no es una falla de emisión: emission_failure es nulo, document.status.value es pending_contingency y el documento se sella solo cuando Hacienda vuelve, sin reintento (ver Contingencia).

emission_failure.kind Significado
hacienda_unavailable Hacienda no respondió y el documento no se pudo emitir, ni siquiera en contingencia. POST /sales/{uuid}/document lo emite cuando Hacienda vuelva.
rejected_by_validator Se incumplió una regla del documento.
signing El documento no se pudo firmar.
credentials El certificado o las credenciales de Hacienda requieren atención.
rejected Hacienda rechazó el documento; message reúne sus observaciones.
unknown Otra causa.

El número de control de un documento corregido

Un documento rechazado que se corrige y se retransmite conserva su código de generación y recibe un número de control nuevo.

flowchart LR
  A["Documento rechazado<br/>número de control 41"] -->|corregir y emitir de nuevo<br/>mismo generation_code| B["Documento sellado<br/>el siguiente número libre"]
  B --> C["El 41 queda como salto<br/>en la numeración sellada"]

Notas de crédito y de débito

Una nota se emite sobre el CCF sellado de la venta, con Idempotency-Key. La de crédito devuelve unidades o descuenta un monto; la de débito agrega cargos.

flowchart LR
  A[CCF sellado] --> B[Nota de crédito 05]
  A --> C[Nota de débito 06]
  B -->|devuelve unidades o descuenta| D[Saldo del CCF]
  C -->|agrega cargos| D
  B --> E[Invalidar la nota antes que el CCF]
Nota Lleva Responde 422 validation_failed
Crédito 05 lines, discounts o ambos Sin ninguno de los dos, en lines
Débito 06 charges, al menos uno, y ninguna línea Sin charges, en charges; con lines, en lines
{
  "dte_type": "06",
  "reason": "Intereses por pago fuera de plazo",
  "charges": [{ "description": "Intereses de mora, 30 días", "amount": "11.30" }]
}

Una nota de débito sin charges responde:

{
  "message": "Una nota de débito agrega al documento un cargo que no traía, como un interés, un flete o una diferencia de precio: enviar en charges al menos uno, con su descripción y su monto.",
  "code": "validation_failed",
  "errors": {
    "charges": ["Una nota de débito agrega al documento un cargo que no traía, como un interés, un flete o una diferencia de precio: enviar en charges al menos uno, con su descripción y su monto."]
  }
}

Invalidación

La invalidación retira ante Hacienda un documento sellado y requiere el alcance documents:invalidate. Se resuelve antes de responder: con 200, el documento queda invalidated, invalidation trae el sello del evento y la existencia vuelve al estante. Un CCF con notas vigentes se invalida después de sus notas.

invalidation_type Motivo Requiere replacement_sale
1 Error en la información del documento Sí, salvo en una nota de crédito
2 Rescindir de la operación realizada No
3 Otro Sí, salvo en una nota de crédito

Con el tipo 1 o 3 la operación sigue en la venta de replacement_sale, y el pago con ella: la venta invalidada no queda por devolver, salvo lo que cobró de más sobre lo que lleva su reemplazo. invalidation.replacement nombra el documento que la corrige (generation_code y control_number) y su venta (uuid y reference, para leerla con GET /sales/{uuid}; nulos si esa venta no se hizo por la API). Del otro lado, la venta de reemplazo trae replaces con la venta invalidada (uuid y reference) y su documento (generation_code y control_number), nulo en cualquier otra venta. Con una llave atada a una sucursal, replacement_sale es una venta de esa sucursal: una de otra responde 403 sale_of_another_branch. Con el tipo 2 la operación se deshace y lo cobrado queda por devolver al cliente. owed_back de la venta dice cuánto queda por devolver en cada caso, la misma cifra que "Por devolver" en la pantalla.

Cada documento invalidado se corrige con su propio documento nuevo: el Manual Funcional (v2.0, página 10) pide "un evento por cada DTE/Evento que se requiera invalidar", y la Normativa de Cumplimiento (v2.0, página 127, campo 48) pide el "Código de Generación del nuevo DTE que reemplace al documento invalidado". Una replacement_sale ya nombrada en la invalidación de otra venta responde 422 replacement_already_used.

Después de una corrección con reemplazo, el pedido sigue facturado en la venta de reemplazo: la reference de la venta invalidada no queda libre, y otro POST /sales con ella responde 409 sale_reference_exists con el reemplazo en data. Solo la rescisión (tipo 2) libera la reference para facturar el pedido de nuevo. Ver Idempotencia.

Devolución parcial de una Factura

Una Factura (01) no admite nota de crédito. Cuando el cliente devuelve una parte, se crea con POST /sales la venta de reemplazo con lo que se queda, con su propia reference, y después se invalida la Factura original con el tipo 3 y esa venta en replacement_sale. El Manual Funcional del Sistema de Transmisión (v2.0, página 13, "Condiciones especiales") define el tipo 3 como "Otro (esta opción incluye el cambio de bienes /servicios)": la operación sigue con otros bienes. El tipo 1 es para un error en la información del documento, y el 2 para deshacer toda la operación, cuando el cliente devuelve todo.

La invalidación no lleva Idempotency-Key porque repetirla es seguro: un documento se invalida una sola vez. Ante una respuesta perdida se repite la misma petición.

flowchart TD
  A[POST invalidation] --> B{Respuesta}
  B -->|200| C[Invalidado]
  B -->|409 document_action_in_progress| D[Esperar Retry-After] --> A
  B -->|422 document_already_invalidated| E[Ya invalidado: leer la venta]
  B -->|503 hacienda_unavailable| F[Sin cambios] --> A
Respuesta al repetir Significado
200 La primera petición no llegó a Hacienda y esta invalidó el documento.
409 document_action_in_progress La primera sigue en curso; repetir tras Retry-After.
422 document_already_invalidated El documento ya está invalidado, por la primera petición o desde la pantalla de Tezora. GET /sales/{uuid} trae su invalidation.
503 hacienda_unavailable No se invalidó nada; repetir tras Retry-After.

Mientras una acción sobre una venta está en curso, otra sobre la misma venta responde 409 document_action_in_progress.