Emitir una nota de débito (E33)

Emite una nota de débito que modifica la factura {id} (cargos o intereses no facturados). Se emite por líneas (items) o por monto (amount), no con ambos. La respuesta suele llegar con status: pending; el estado se actualiza solo: recíbelo con un webhook o consúltalo con GET /v1/notes/{id}.

Límite mensual: si alcanzaste el límite mensual de este tipo de e-CF responde 429 sin Retry-After (el 429 por exceso de solicitudes sí lo trae); consulta tu consumo con GET /v1/limits. Consultar, descargar y anular siguen funcionando, y reintentar un documento ya emitido no vuelve a contar. Ese 429 no se guarda: cuando se amplíe el límite puedes reintentar con la misma Idempotency-Key.

POST /v1/invoices/{id}/debit-notes

Emitir una nota de débito (E33)

cURL

curl --request POST \
  --url https://e-cf.acpay.do/sandbox/v1/invoices/{id}/debit-notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "modificationCode": 3,
  "reason": "Cargo por entrega no facturado",
  "items": [
    {
      "description": "Entrega a domicilio",
      "quantity": 1,
      "unitPrice": 500
    }
  ]
}
'

201

Example

{
  "id": "3f1c2b9e-8a4d-4f6e-9c1a-2b7d5e8f0a13",
  "status": "accepted",
  "statusMessage": null,
  "securityCode": "a1B2c3",
  "stampUrl": "https://ecf.dgii.gov.do/testecf/ConsultaTimbre?RncEmisor=101000000&RncComprador=131793916&ENCF=E310000000001&FechaEmision=27-09-2026&MontoTotal=3541.18&FechaFirma=27-09-2026%2010:15:00&CodigoSeguridad=a1B2c3",
  "signedAt": "2026-09-27T14:15:00.000Z",
  "issuedAt": "2026-09-27T14:14:58.000Z",
  "environment": "test",
  "currency": "DOP",
  "subtotal": 3001,
  "itbis": 540.18,
  "total": 3541.18,
  "encf": "E340000000003",
  "ecfType": 34,
  "invoiceId": "3f1c2b9e-8a4d-4f6e-9c1a-2b7d5e8f0a13",
  "invoiceEncf": "E310000000001",
  "modificationCode": 3,
  "reason": "Devolución parcial de mercancía",
  "items": [
    {
      "description": "Servicio de mantenimiento mensual",
      "quantity": 2,
      "unitPrice": 1500.5,
      "itbisRate": 18,
      "subtotal": 3001
    }
  ]
}

Autorizaciones

Authorization · string · header · requerido

Llave de API de AC-PAY del ambiente de esta URL.

Encabezados

Idempotency-Key · string · requerido

Identificador único que generas por operación (p. ej. un UUID), de 1 a 255 caracteres ASCII imprimibles. Si repites la solicitud con la misma llave en las siguientes 24 h recibes la respuesta original (con Idempotent-Replayed: true) sin ejecutarla de nuevo.

Ejemplo:

"5b0f7c1e-2f7a-4d8e-9d3c-7f1e2a9b4c60"

Parámetros de ruta

id · string<uuid> · requerido

Identificador del documento (UUID).

Ejemplo:

"3f1c2b9e-8a4d-4f6e-9c1a-2b7d5e8f0a13"

Cuerpo

application/json

modificationCode · enum<number> · requerido

Código de modificación: 1 anulación total, 2 corrige textos, 3 corrige montos, 4 reemplazo de un comprobante emitido en contingencia.

Opciones disponibles: 1, 2, 3, 4

Ejemplo:

3

reason · string · requerido

Motivo de la nota.

Maximum string length: 500

Ejemplo:

"Devolución parcial de mercancía"

items · object[]

Líneas de la nota (1 a 500). Envía items o amount, no ambos.

Show child attributes

amount · number

Monto total de la nota en RD$, con ITBIS (máximo 2 decimales). Envía items o amount, no ambos.

Rango requerido: 0 < x <= 99999999.99

Ejemplo:

1180

itbis · number · predeterminado: 0

ITBIS incluido en amount (máximo 2 decimales, no mayor que amount). Solo junto con amount.

Rango requerido: 0 <= x <= 99999999.99

Ejemplo:

180

Respuesta

201

application/json

Nota creada y enviada a la DGII.

id · string<uuid> · requerido

Ejemplo:

"3f1c2b9e-8a4d-4f6e-9c1a-2b7d5e8f0a13"

status · enum<string> · requerido

pending: enviado, esperando a la DGII (se actualiza solo en segundo plano, y también al consultar). accepted / accepted_with_observations: válido. rejected: la DGII lo rechazó (ver statusMessage). cancelled: anulado. error: no se pudo procesar (se puede reintentar).

Opciones disponibles: pending, accepted, accepted_with_observations, rejected, cancelled, error

Ejemplo:

"accepted"

statusMessage · string | null · requerido

Detalle del estado (motivo de rechazo u observaciones).

Ejemplo:

null

securityCode · string | null · requerido

Código de seguridad del e-CF (va impreso en la representación impresa).

Ejemplo:

"a1B2c3"

stampUrl · string | null · requerido

URL de consulta de la DGII (contenido del código QR).

Ejemplo:

"https://ecf.dgii.gov.do/testecf/ConsultaTimbre?RncEmisor=101000000&RncComprador=131793916&ENCF=E310000000001&FechaEmision=27-09-2026&MontoTotal=3541.18&FechaFirma=27-09-2026%2010:15:00&CodigoSeguridad=a1B2c3"

signedAt · string<date-time> | null · requerido

Ejemplo:

"2026-09-27T14:15:00.000Z"

issuedAt · string<date-time> · requerido

Ejemplo:

"2026-09-27T14:14:58.000Z"

environment · enum<string> · requerido

Opciones disponibles: test, live

Ejemplo:

"test"

currency · enum<string> · requerido

Opciones disponibles: DOP

Ejemplo:

"DOP"

subtotal · number · requerido

Monto sin ITBIS.

Ejemplo:

3001

itbis · number · requerido

ITBIS total.

Ejemplo:

540.18

total · number · requerido

Total con ITBIS.

Ejemplo:

3541.18

encf · string | null · requerido

e-NCF de la nota. null mientras no se haya asignado.

Ejemplo:

"E340000000003"

ecfType · enum<number> · requerido

33 nota de débito, 34 nota de crédito.

Opciones disponibles: 33, 34

Ejemplo:

34

invoiceId · string<uuid> · requerido

Factura que modifica la nota.

Ejemplo:

"3f1c2b9e-8a4d-4f6e-9c1a-2b7d5e8f0a13"

invoiceEncf · string | null · requerido

e-NCF de la factura modificada.

Ejemplo:

"E310000000001"

modificationCode · enum<number> · requerido

1 anulación total, 2 corrige textos, 3 corrige montos, 4 reemplazo de un comprobante en contingencia.

Opciones disponibles: 1, 2, 3, 4

Ejemplo:

3

reason · string · requerido

Ejemplo:

"Devolución parcial de mercancía"

items · object[] · requerido

Show child attributes