API v2: anular, reprocesar, reenviar, borrar y sincronizar comprobantes sin duplicados

Antes de empezar

La API v2 usa una credencial con permisos (cabecera X-Api-Key), que el dueño de la cuenta crea en tu nombre → Credenciales API. Las rutas empiezan por /plataforma/api/v2/ y el recurso es el tipo en plural (facturas, creditos, debitos, guias, retenciones, liquidaciones).

Ciclo de vida de un comprobante

• GET {recurso}/{id}/estado: estado del comprobante. Con ?sri=1 consulta además al SRI.
• POST {recurso}/{id}/anular: solo comprobantes autorizados. Antes debes presentar la solicitud en el SRI (ver abajo).
• POST {recurso}/{id}/reprocesar: vuelve a enviar uno rechazado o en proceso. Solo funciona con la fecha de hoy.
• POST {recurso}/{id}/correo: reenvía el comprobante por correo.
• DELETE {recurso}/{id}: solo borradores y rechazados (estados 5, 6 y 7). Un autorizado no se borra: se anula.

Anular y reprocesar requieren el permiso Enviar al SRI y anular; borrar, el de crear y editar borradores.

Cómo anular por la API

1. Entra a SRI en línea: Facturación Electrónica → Producción → Anulación → Solicitud de Anulación y presenta la solicitud.
2. En retenciones, notas de crédito y notas de débito, el receptor debe aceptar la anulación (tiene 5 días hábiles).
3. Llama a POST {recurso}/{id}/anular.

Respuestas posibles:

• anulacion_no_solicitada: «El SRI no tiene registrada la solicitud de anulación de este comprobante…». Presenta la solicitud y vuelve a llamar.
• anulacion_fuera_de_plazo: pasó el plazo (hasta el día 7 del mes siguiente a la emisión). Corrige con una nota de crédito.
• sri_no_disponible: el SRI no contestó. Reintenta en unos minutos.
• En notas de crédito, débito y retenciones la respuesta puede traer pendiente_en_sri = true: está dado de baja en el sistema, pero falta completar la anulación en el SRI.

Evitar duplicados: cabecera Idempotency-Key

Al guardar, enviar, anular, reprocesar, cobrar o crear productos y sucursales, envía la cabecera Idempotency-Key con un valor único por operación (por ejemplo, el número de tu pedido).

• Si la misma petición se repite (corte de red, reintento), el sistema devuelve la respuesta original durante 24 horas en vez de crear otro comprobante.
• Si llega mientras la primera aún se procesa, responde 429: «Esa misma … se está procesando ahora mismo». Espera y consulta.

Sincronizar con tu ERP

Los listados /facturas, /comprobantes y /recibidos aceptan:

• modificado_desde (aaaa-mm-dd, con guiones): solo lo creado o cambiado desde esa fecha.
• cursor: para pasar de página sin repetir ni saltar documentos, aunque se modifiquen mientras lees.

Así tu sistema trae solo lo nuevo en cada sincronización. Requiere el permiso Consultar comprobantes.

Qué ve cada credencial

• La credencial queda atada a un punto de emisión: lista y factura solo desde su establecimiento y en su ambiente.
• Clientes, proveedores y transportistas son de toda la empresa.
• Si usas un producto de otro establecimiento, la API lo rechaza con un mensaje que lo indica.
• Una sesión de usuario de punto de venta solo puede vender y consultar sus propias ventas.