---
title: "Endpoint para anular una nómina electrónica"
method: POST
path: "/payrolls/{id}/cancel"
tags: ["Nóminas electrónicas"]
---

# Endpoint para anular una nómina electrónica

`POST /payrolls/{id}/cancel`

## Request

- Base URL: `https://sandbox-api.alegra.com/e-provider/col/v1`
- URL: `https://sandbox-api.alegra.com/e-provider/col/v1/payrolls/{id}/cancel`
- Auth: HTTP bearer

Este endpoint permite anular la nómina electrónica enviada como parámetro. Sólo se puede anular una nómina aceptada por la DIAN (`legalStatus` `ACCEPTED` o `ACCEPTED_WITH_OBSERVATIONS`): una nómina rechazada no se anula, se corrige y se envía de nuevo (`AEP2015`). Mientras otra anulación o reemplazo de la misma nómina esté en proceso, la solicitud se rechaza con `AEP2016`; una anulación o un reemplazo rechazado por la DIAN no bloquea un nuevo intento.

## Path parameters

- `id` string, required

## Parameters

- `#/paths/~1events/post/parameters/0` (unresolved $ref)

## Request body

- object
  - `prefix` string, required: Prefijo de la anulación de la nómina electrónica
  - `number` string, required: Número consecutivo de la anulación de la nómina electrónica

## Response `200`

Objeto que representa la respuesta cuando se anula una nómina electrónica en la DIAN

- object
  - `payroll` Emission (unresolved $ref)
  - `cancellation` Emission (unresolved $ref)

## Other responses

- `400`: Objeto que representa una respuesta de error por validaciones
- `404`: Objeto que representa una respuesta de error por qué no se ha encontrado el recurso al que se intenta acceder
- `409`: Objeto que representa una respuesta de error por un conflicto al anular o reemplazar una nómina. Código `AEP2017` cuando otra solicitud modificó la nómina mientras se procesaba esta anulación o reemplazo: consulta el estado actual de la nómina antes de reintentar. Código `IDEMPOTENCY_REQUEST_IN_PROGRESS` cuando una petición con la misma `Idempotency-Key` sigue en proceso: reintenta en unos segundos. Código `IDEMPOTENCY_OUTCOME_INDETERMINATE` cuando no fue posible establecer el resultado de la petición original: consulta el estado del documento con el endpoint `GET` o el webhook antes de reintentar con una llave nueva
- `422`: Objeto que representa una respuesta de error por reutilizar una `Idempotency-Key` con un cuerpo de petición diferente al de la petición original. Código `IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD`. La operación no se ejecuta: usa una llave nueva si realmente se trata de una operación distinta
- `500`: Objeto que representa una respuesta de error por qué ha ocurrido un error interno en el sistema

## Changes

- **2026-11-03** `2bc52ab55c2b`: 3 info
  - added the new optional `header` request parameter `Idempotency-Key`
  - added the non-success response with the status `409`
  - added the non-success response with the status `422`

[Operation history](https://skmtc.dev/alegra/apis/api-alegra-proveedor-electr-nico-colombia/changes/payrolls/:id/cancel/post.md)

---

[API](https://skmtc.dev/alegra/apis/api-alegra-proveedor-electr-nico-colombia.md) - [All operations](https://skmtc.dev/alegra/apis/api-alegra-proveedor-electr-nico-colombia/llms.txt) - [OpenAPI document](https://skmtc.dev/alegra/apis/api-alegra-proveedor-electr-nico-colombia/revisions/2bc52ab55c2b?raw)