Crear y someter una factura

POST

/v1/taxpayers/{taxpayer_id}/invoices

const url = 'https://sandbox.api.cierrelisto.com/v1/taxpayers/340f4500-e627-4f37-aaa8-9ad5baff8209/invoices';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'erp-venta-2026-000184-attempt-1',
    'X-Request-Id': 'req_6a07a2bfa55e4e1ebf5a9f27482f09f1',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"external_id":"erp-venta-2026-000184","ecf_type":"31","issue_date":"2026-07-29","due_date":"2026-08-28","currency":"DOP","language":"es","payment_type":"credit","buyer":{"legal_name":"CLIENTE DE PRUEBA SRL","tax_id":"131246796","email":"cuentas@cliente.example","address":{"line1":"Av. Abraham Lincoln 1001","city":"Santo Domingo de Guzmán","province_or_state":"Distrito Nacional","country_code":"DO"}},"lines":[{"line_id":"1","description":"Servicios profesionales de julio de 2026","sku":"SERV-CONT-001","unit":"servicio","item_kind":"service","billing_indicator":1,"unit_code":28,"quantity":"1","unit_price":"70000.00","discount":null,"taxes":[{"code":"ITBIS","label":"ITBIS 18%","rate_percent":"18"}]}],"declared_totals":{"subtotal":"70000.00","discount_total":"0.00","tax_total":"12600.00","total":"82600.00"},"payment_terms":"Pago por transferencia dentro de 30 días."}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://sandbox.api.cierrelisto.com/v1/taxpayers/340f4500-e627-4f37-aaa8-9ad5baff8209/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: erp-venta-2026-000184-attempt-1' \
  --header 'X-Request-Id: req_6a07a2bfa55e4e1ebf5a9f27482f09f1' \
  --data '{ "external_id": "erp-venta-2026-000184", "ecf_type": "31", "issue_date": "2026-07-29", "due_date": "2026-08-28", "currency": "DOP", "language": "es", "payment_type": "credit", "buyer": { "legal_name": "CLIENTE DE PRUEBA SRL", "tax_id": "131246796", "email": "cuentas@cliente.example", "address": { "line1": "Av. Abraham Lincoln 1001", "city": "Santo Domingo de Guzmán", "province_or_state": "Distrito Nacional", "country_code": "DO" } }, "lines": [ { "line_id": "1", "description": "Servicios profesionales de julio de 2026", "sku": "SERV-CONT-001", "unit": "servicio", "item_kind": "service", "billing_indicator": 1, "unit_code": 28, "quantity": "1", "unit_price": "70000.00", "discount": null, "taxes": [ { "code": "ITBIS", "label": "ITBIS 18%", "rate_percent": "18" } ] } ], "declared_totals": { "subtotal": "70000.00", "discount_total": "0.00", "tax_total": "12600.00", "total": "82600.00" }, "payment_terms": "Pago por transferencia dentro de 30 días." }'

Requiere los alcances invoices.write y ecf.submit. El cuerpo siempre contiene datos estructurados compatibles con el dominio de facturación; no se acepta XML. Idempotency-Key evita duplicados por reintentos.

Authorizations

BearerAuth

Parameters

Path Parameters

taxpayer_id

required

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

Contribuyente autorizado dentro de la cuenta CierreListo.

Example

340f4500-e627-4f37-aaa8-9ad5baff8209

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 200 characters

Clave única por intención de creación. Reutilizarla con un cuerpo diferente produce 409.

Example

erp-venta-2026-000184-attempt-1

X-Request-Id

string

/^req_[0-9a-f]{32}$/

Identificador opcional del cliente. Si no es válido, CierreListo genera uno.

Example

req_6a07a2bfa55e4e1ebf5a9f27482f09f1

Request Body^required

Cuerpo JSON estructurado. Tamaño máximo: 1 MiB (1048576 bytes).

application/json

object

external_id

required

string

>= 1 characters <= 200 characters

ecf_type

required

string

Allowed values: 31 32

issue_date

required

string

/^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/

due_date

Any of:

string
null

string

/^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/

currency

required

La API pública v1 emite únicamente facturas en pesos dominicanos (DOP).

string

Allowed value: DOP

language

string

Allowed values: es en

payment_type

required

Forma de pago pública: cash=TipoPago 1, credit=TipoPago 2, free_of_charge=TipoPago 3.

string

Allowed values: cash credit free_of_charge

buyer

required

object

legal_name

required

string

>= 1 characters <= 200 characters

tax_id

string

/^\d{9,11}$/

email

string format: email

<= 320 characters /^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$/

phone

string

>= 5 characters <= 40 characters

address

object

line1

required

string

>= 1 characters <= 200 characters

line2

string

>= 1 characters <= 200 characters

city

required

string

>= 1 characters <= 120 characters

province_or_state

string

>= 1 characters <= 120 characters

postal_code

string

>= 1 characters <= 20 characters

country_code

required

string

/^[A-Z]{2}$/

lines

required

Array<object>

>= 1 items <= 1000 items

object

line_id

required

string

>= 1 characters <= 100 characters

description

required

string

>= 1 characters <= 500 characters

sku

string

>= 1 characters <= 100 characters

unit

string

>= 1 characters <= 80 characters

item_kind

required

Naturaleza de la línea: product=IndicadorBienOServicio 1, service=2.

string

Allowed values: product service

billing_indicator

IndicadorFacturacion DGII explícito. Valores admitidos por el flujo comercial: 1-4.

number

Allowed values: 1 2 3 4

unit_code

Código UnidadMedida DGII explícito. Se usa cuando CierreListo no puede inferirlo.

number

Allowed values: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 60 61 62 63 64 65 66 67 68

quantity

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

unit_price

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

discount

required

Any of:

object
null

One of:

object
object

object

kind

required

string

Allowed value: percentage

value

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

taxes

required

Array<object>

<= 12 items

object

code

required

string

>= 1 characters <= 40 characters

label

required

string

>= 1 characters <= 120 characters

rate_percent

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

declared_totals

required

object

subtotal

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

discount_total

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

tax_total

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

total

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

purchase_order

string

>= 1 characters <= 120 characters

payment_terms

string

>= 1 characters <= 500 characters

notes

string

>= 1 characters <= 2000 characters

estimated_withholdings

object

income_tax_amount

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

income_tax_base_amount

Any of:

string
null

string

/^(0|[1-9]\d*)(\.\d+)?$/

income_tax_rate_percent

Any of:

string
null

string

/^(0|[1-9]\d*)(\.\d+)?$/

itbis_amount

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

itbis_base_amount

Any of:

string
null

string

/^(0|[1-9]\d*)(\.\d+)?$/

itbis_rate_percent

Any of:

string
null

string

/^(0|[1-9]\d*)(\.\d+)?$/

Example

{
  "external_id": "erp-venta-2026-000184",
  "ecf_type": "31",
  "issue_date": "2026-07-29",
  "due_date": "2026-08-28",
  "currency": "DOP",
  "language": "es",
  "payment_type": "credit",
  "buyer": {
    "legal_name": "CLIENTE DE PRUEBA SRL",
    "tax_id": "131246796",
    "email": "cuentas@cliente.example",
    "address": {
      "line1": "Av. Abraham Lincoln 1001",
      "city": "Santo Domingo de Guzmán",
      "province_or_state": "Distrito Nacional",
      "country_code": "DO"
    }
  },
  "lines": [
    {
      "line_id": "1",
      "description": "Servicios profesionales de julio de 2026",
      "sku": "SERV-CONT-001",
      "unit": "servicio",
      "item_kind": "service",
      "billing_indicator": 1,
      "unit_code": 28,
      "quantity": "1",
      "unit_price": "70000.00",
      "discount": null,
      "taxes": [
        {
          "code": "ITBIS",
          "label": "ITBIS 18%",
          "rate_percent": "18"
        }
      ]
    }
  ],
  "declared_totals": {
    "subtotal": "70000.00",
    "discount_total": "0.00",
    "tax_total": "12600.00",
    "total": "82600.00"
  },
  "payment_terms": "Pago por transferencia dentro de 30 días."
}

Responses

202

La factura fue aceptada para validación y procesamiento asíncrono.

application/json

object

data

required

object

required

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

taxpayer_id

required

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

external_id

required

string

>= 1 characters <= 200 characters

ecf_type

required

string

Allowed values: 31 32

status

required

string

Allowed values: queued validation_failed submitted processing accepted accepted_conditional rejected outcome_unknown delivered

fiscal_document_id

required

Any of:

string
null

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

currency

required

La API pública v1 emite únicamente facturas en pesos dominicanos (DOP).

string

Allowed value: DOP

issue_date

required

string

/^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/

totals

required

object

subtotal

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

discount_total

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

tax_total

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

total

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

paid

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

balance

required

string

/^(0|[1-9]\d*)(\.\d+)?$/

key

additional properties

created_at

required

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/

updated_at

required

string format: date-time

key

additional properties

meta

required

object

request_id

required

string

/^req_[0-9a-f]{32}$/

key

additional properties

key

additional properties

Example

{
  "data": {
    "id": "cc70a888-12db-48c5-8893-ef72046f57f1",
    "taxpayer_id": "340f4500-e627-4f37-aaa8-9ad5baff8209",
    "external_id": "erp-venta-2026-000184",
    "ecf_type": "31",
    "status": "queued",
    "fiscal_document_id": "261aa475-f462-4446-9f88-9525714ed925",
    "currency": "DOP",
    "issue_date": "2026-07-29",
    "totals": {
      "subtotal": "70000.00",
      "discount_total": "0.00",
      "tax_total": "12600.00",
      "total": "82600.00",
      "paid": "0.00",
      "balance": "82600.00"
    },
    "created_at": "2026-07-29T14:05:10.000-04:00",
    "updated_at": "2026-07-29T14:05:10.000-04:00"
  },
  "meta": {
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

X-Request-Id

string

/^req_[0-9a-f]{32}$/

Identificador de trazabilidad de la solicitud.

Example

req_6a07a2bfa55e4e1ebf5a9f27482f09f1

RateLimit-Limit

integer

>= 1

Máximo de solicitudes permitidas en la ventana actual.

Example

RateLimit-Remaining

integer

Solicitudes disponibles antes de agotar la ventana actual.

Example

RateLimit-Reset

integer

Instante de reinicio de la ventana expresado como Unix time.

Example

1785337200

Location

string format: uri-reference

Ruta canónica del recurso creado.

Example

/v1/taxpayers/340f4500-e627-4f37-aaa8-9ad5baff8209/invoices/cc70a888-12db-48c5-8893-ef72046f57f1

Idempotency-Replayed

string

Allowed values: true

Vale true cuando la respuesta fue recuperada de una solicitud idempotente anterior.

Example

true

400

Solicitud o JSON inválido.

application/json

object

error

required

object

code

required

string

Allowed values: bad_request invalid_json validation_error unauthorized forbidden not_found idempotency_mismatch external_id_conflict operational_readiness_failed artifact_not_ready rate_limited service_unavailable internal_error

message

required

string

>= 1 characters

request_id

required

string

/^req_[0-9a-f]{32}$/

details

Array<object>

object

field

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

key

additional properties

key

additional properties

Example

{
  "error": {
    "code": "bad_request",
    "message": "La solicitud no pudo interpretarse.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

X-Request-Id

string

/^req_[0-9a-f]{32}$/

Identificador de trazabilidad de la solicitud.

Example

req_6a07a2bfa55e4e1ebf5a9f27482f09f1

RateLimit-Limit

integer

>= 1

Máximo de solicitudes permitidas en la ventana actual.

Example

RateLimit-Remaining

integer

Solicitudes disponibles antes de agotar la ventana actual.

Example

RateLimit-Reset

integer

Instante de reinicio de la ventana expresado como Unix time.

Example

1785337200

401

Credencial ausente o inválida.

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

request_id

required

string

/^req_[0-9a-f]{32}$/

details

Array<object>

object

field

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

key

additional properties

key

additional properties

Example

{
  "error": {
    "code": "unauthorized",
    "message": "La credencial no es válida.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

X-Request-Id

string

/^req_[0-9a-f]{32}$/

Identificador de trazabilidad de la solicitud.

Example

req_6a07a2bfa55e4e1ebf5a9f27482f09f1

RateLimit-Limit

integer

>= 1

Máximo de solicitudes permitidas en la ventana actual.

Example

RateLimit-Remaining

integer

Solicitudes disponibles antes de agotar la ventana actual.

Example

RateLimit-Reset

integer

Instante de reinicio de la ventana expresado como Unix time.

Example

1785337200

403

La credencial no autoriza esta operación, integración o ambiente.

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

request_id

required

string

/^req_[0-9a-f]{32}$/

details

Array<object>

object

field

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

key

additional properties

key

additional properties

Example

{
  "error": {
    "code": "forbidden",
    "message": "La credencial no tiene el alcance requerido.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

X-Request-Id

string

/^req_[0-9a-f]{32}$/

Identificador de trazabilidad de la solicitud.

Example

req_6a07a2bfa55e4e1ebf5a9f27482f09f1

RateLimit-Limit

integer

>= 1

Máximo de solicitudes permitidas en la ventana actual.

Example

RateLimit-Remaining

integer

Solicitudes disponibles antes de agotar la ventana actual.

Example

RateLimit-Reset

integer

Instante de reinicio de la ventana expresado como Unix time.

Example

1785337200

409

Conflicto de idempotencia o identificador externo.

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

request_id

required

string

/^req_[0-9a-f]{32}$/

details

Array<object>

object

field

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

key

additional properties

key

additional properties

Example

{
  "error": {
    "code": "idempotency_mismatch",
    "message": "La clave de idempotencia ya fue utilizada con otro cuerpo.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

X-Request-Id

string

/^req_[0-9a-f]{32}$/

Identificador de trazabilidad de la solicitud.

Example

req_6a07a2bfa55e4e1ebf5a9f27482f09f1

RateLimit-Limit

integer

>= 1

Máximo de solicitudes permitidas en la ventana actual.

Example

RateLimit-Remaining

integer

Solicitudes disponibles antes de agotar la ventana actual.

Example

RateLimit-Reset

integer

Instante de reinicio de la ventana expresado como Unix time.

Example

1785337200

422

La factura estructurada no superó la validación.

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

request_id

required

string

/^req_[0-9a-f]{32}$/

details

Array<object>

object

field

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

key

additional properties

key

additional properties

Example

{
  "error": {
    "code": "validation_error",
    "message": "La factura contiene campos inválidos.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1",
    "details": [
      {
        "field": "lines.0.unit_price",
        "code": "invalid_decimal",
        "message": "Debe ser un decimal representado como string."
      }
    ]
  }
}

Headers

X-Request-Id

string

/^req_[0-9a-f]{32}$/

Identificador de trazabilidad de la solicitud.

Example

req_6a07a2bfa55e4e1ebf5a9f27482f09f1

RateLimit-Limit

integer

>= 1

Máximo de solicitudes permitidas en la ventana actual.

Example

RateLimit-Remaining

integer

Solicitudes disponibles antes de agotar la ventana actual.

Example

RateLimit-Reset

integer

Instante de reinicio de la ventana expresado como Unix time.

Example

1785337200

429

Se excedió el límite temporal de solicitudes.

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

request_id

required

string

/^req_[0-9a-f]{32}$/

details

Array<object>

object

field

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

key

additional properties

key

additional properties

Example

{
  "error": {
    "code": "rate_limited",
    "message": "Espera antes de volver a intentarlo.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

X-Request-Id

string

/^req_[0-9a-f]{32}$/

Identificador de trazabilidad de la solicitud.

Example

req_6a07a2bfa55e4e1ebf5a9f27482f09f1

RateLimit-Limit

integer

>= 1

Máximo de solicitudes permitidas en la ventana actual.

Example

RateLimit-Remaining

integer

Solicitudes disponibles antes de agotar la ventana actual.

Example

RateLimit-Reset

integer

Instante de reinicio de la ventana expresado como Unix time.

Example

1785337200

500

CierreListo no pudo completar la operación por un error interno.

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

request_id

required

string

/^req_[0-9a-f]{32}$/

details

Array<object>

object

field

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

key

additional properties

key

additional properties

Example

{
  "error": {
    "code": "internal_error",
    "message": "No pudimos completar la operación. Conserva el request_id para soporte.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

X-Request-Id

string

/^req_[0-9a-f]{32}$/

Identificador de trazabilidad de la solicitud.

Example

req_6a07a2bfa55e4e1ebf5a9f27482f09f1

RateLimit-Limit

integer

>= 1

Máximo de solicitudes permitidas en la ventana actual.

Example

RateLimit-Remaining

integer

Solicitudes disponibles antes de agotar la ventana actual.

Example

RateLimit-Reset

integer

Instante de reinicio de la ventana expresado como Unix time.

Example

1785337200

503

El servicio no puede completar temporalmente la operación.

application/json

object

error

required

object

code

required

string

message

required

string

>= 1 characters

request_id

required

string

/^req_[0-9a-f]{32}$/

details

Array<object>

object

field

required

string

>= 1 characters

code

required

string

>= 1 characters

message

required

string

>= 1 characters

key

additional properties

key

additional properties

key

additional properties

Example

{
  "error": {
    "code": "service_unavailable",
    "message": "El servicio no está disponible temporalmente.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

X-Request-Id

string

/^req_[0-9a-f]{32}$/

Identificador de trazabilidad de la solicitud.

Example

req_6a07a2bfa55e4e1ebf5a9f27482f09f1

RateLimit-Limit

integer

>= 1

Máximo de solicitudes permitidas en la ventana actual.

Example

RateLimit-Remaining

integer

Solicitudes disponibles antes de agotar la ventana actual.

Example

RateLimit-Reset

integer

Instante de reinicio de la ventana expresado como Unix time.

Example

1785337200

Retry-After

integer

>= 1

Segundos que debe esperar el cliente antes de reintentar una operación temporalmente ocupada.

Crear y someter una factura

Authorizations

Parameters

Path Parameters

Example

Header Parameters

Example

Example

Request Bodyrequired

Example

Responses

202

Example

Headers

Example

Example

Example

Example

Example

Example

400

Example

Headers

Example

Example

Example

Example

401

Example

Headers

Example

Example

Example

Example

403

Example

Headers

Example

Example

Example

Example

409

Example

Headers

Example

Example

Example

Example

422

Example

Headers

Example

Example

Example

Example

429

Example

Headers

Example

Example

Example

Example

500

Example

Headers

Example

Example

Example

Example

503

Example

Headers

Example

Example

Example

Example

Example

Request Body^required