Ir al contenido
CierreListoCierreListoCierreListo Developers

Listar facturas

GET
/v1/taxpayers/{taxpayer_id}/invoices
curl --request GET \
  --url 'https://sandbox.api.cierrelisto.com/v1/taxpayers/340f4500-e627-4f37-aaa8-9ad5baff8209/invoices?external_id=erp-venta-2026-000184&status=queued&limit=25' \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Request-Id: req_6a07a2bfa55e4e1ebf5a9f27482f09f1'

Requiere el alcance invoices.read. Los resultados usan cursor estable y pueden filtrarse por identificador externo o estado público.

Authorizations

Sección titulada «Authorizations»

Parameters

Sección titulada «Parameters»

Path Parameters

Sección titulada «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

Sección titulada «Header Parameters»
X-Request-Id
string
/^req_[0-9a-f]{32}$/

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

Example
req_6a07a2bfa55e4e1ebf5a9f27482f09f1

Query Parameters

Sección titulada «Query Parameters»
external_id
string
>= 1 characters <= 200 characters

Identificador estable de la factura en el sistema integrador.

Example
erp-venta-2026-000184
status
string
Allowed values: queued validation_failed submitted processing accepted accepted_conditional rejected outcome_unknown delivered
cursor
string
>= 1 characters <= 500 characters
limit
integer
default: 25 >= 1 <= 100

Responses

Sección titulada «Responses»

200

Sección titulada «200»

Lista paginada de facturas.

Media typeapplication/json
object
data
required
Array<object>
object
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)$/
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 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
/^(?:(?:\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)))$/
key
additional properties
meta
required
object
request_id
required
string
/^req_[0-9a-f]{32}$/
next_cursor
required
Any of:
string
>= 1 characters
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",
    "next_cursor": null
  }
}

Headers

Sección titulada «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
70
RateLimit-Remaining
integer

Solicitudes disponibles antes de agotar la ventana actual.

Example
69
RateLimit-Reset
integer

Instante de reinicio de la ventana expresado como Unix time.

Example
1785337200

400

Sección titulada «400»

Solicitud o JSON inválido.

Media typeapplication/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

Sección titulada «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
70
RateLimit-Remaining
integer

Solicitudes disponibles antes de agotar la ventana actual.

Example
69
RateLimit-Reset
integer

Instante de reinicio de la ventana expresado como Unix time.

Example
1785337200

401

Sección titulada «401»

Credencial ausente o inválida.

Media typeapplication/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": "unauthorized",
    "message": "La credencial no es válida.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

Sección titulada «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
70
RateLimit-Remaining
integer

Solicitudes disponibles antes de agotar la ventana actual.

Example
69
RateLimit-Reset
integer

Instante de reinicio de la ventana expresado como Unix time.

Example
1785337200

403

Sección titulada «403»

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

Media typeapplication/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": "forbidden",
    "message": "La credencial no tiene el alcance requerido.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

Sección titulada «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
70
RateLimit-Remaining
integer

Solicitudes disponibles antes de agotar la ventana actual.

Example
69
RateLimit-Reset
integer

Instante de reinicio de la ventana expresado como Unix time.

Example
1785337200

429

Sección titulada «429»

Se excedió el límite temporal de solicitudes.

Media typeapplication/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": "rate_limited",
    "message": "Espera antes de volver a intentarlo.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

Sección titulada «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
70
RateLimit-Remaining
integer

Solicitudes disponibles antes de agotar la ventana actual.

Example
69
RateLimit-Reset
integer

Instante de reinicio de la ventana expresado como Unix time.

Example
1785337200

500

Sección titulada «500»

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

Media typeapplication/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": "internal_error",
    "message": "No pudimos completar la operación. Conserva el request_id para soporte.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

Sección titulada «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
70
RateLimit-Remaining
integer

Solicitudes disponibles antes de agotar la ventana actual.

Example
69
RateLimit-Reset
integer

Instante de reinicio de la ventana expresado como Unix time.

Example
1785337200

503

Sección titulada «503»

El servicio no puede completar temporalmente la operación.

Media typeapplication/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": "service_unavailable",
    "message": "El servicio no está disponible temporalmente.",
    "request_id": "req_6a07a2bfa55e4e1ebf5a9f27482f09f1"
  }
}

Headers

Sección titulada «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
70
RateLimit-Remaining
integer

Solicitudes disponibles antes de agotar la ventana actual.

Example
69
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.

Example
1