Crear un link de gestión para una suscripción

POST

/v1/subscriptions/{subscriptionId}/management

curl --request POST \
  --url https://api.timbro.do/v1/subscriptions/example/management \
  --header 'Authorization: Bearer <token>'

• API de Timbro

Autenticación

• secretKey

Parámetros

Parámetros de ruta

subscriptionId

obligatorio

string

/^sub_[0-9a-hjkmnp-tv-z]{24,}$/

Identidad de la suscripción

Respuestas

200

200

Respuesta predeterminada

Media typeapplication/json

Campos y códigos de la respuesta

object

id

obligatorio

Identidad de la suscripción

string

/^sub_[0-9a-hjkmnp-tv-z]{24,}$/

subscriptionReference

obligatorio

string

terms

obligatorio

object

version

obligatorio

string

text

obligatorio

string

locale

obligatorio

Cualquiera de:

string

string

Valor permitido: es

string

string

Valor permitido: en

translations

obligatorio

object

es

obligatorio

string

en

obligatorio

string

customer

obligatorio

object

customerReference

obligatorio

string

>= 1 characters <= 128 characters

name

obligatorio

string

>= 1 characters <= 150 characters

email

obligatorio

string format: email

<= 254 characters

status

obligatorio

string

Valores permitidos: pending active past_due deferred canceled expired

amount

obligatorio

Monto monetario decimal exacto.

object

currency

obligatorio

Ejemplo

DOP

string

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

value

obligatorio

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

interval

obligatorio

object

unit

obligatorio

string

Valor permitido: month

nextPaymentAt

obligatorio

Cualquiera de:

string

string format: date-time

null

null

setup

obligatorio

Cualquiera de:

SubscriptionSetupLink

object

url

obligatorio

Cualquiera de:

string

string format: uri

null

null

expiresAt

obligatorio

string format: date-time

null

null

management

obligatorio

Cualquiera de:

SubscriptionLink

object

url

obligatorio

string format: uri

null

null

managementLinkEmail

obligatorio

Cualquiera de:

SubscriptionManagementLinkEmail

object

status

obligatorio

Cualquiera de:

string

string

Valor permitido: pending

string

string

Valor permitido: accepted

string

string

Valor permitido: failed

string

string

Valor permitido: unknown

requestedAt

obligatorio

string format: date-time

null

null

deferralReason

obligatorio

Cualquiera de:

SubscriptionDeferralReason

string

Valores permitidos: merchant_account_not_ready recurring_account_required mandate_credential_unavailable business_fiscal_binding_unavailable business_fiscal_setup_unavailable subscription_invoicing_blocked card_enrollment_incomplete other

null

null

createdAt

obligatorio

string format: date-time

canceledAt

obligatorio

Cualquiera de:

string

string format: date-time

null

null

payments

obligatorio

Array<object>

<= 5 items

object

id

obligatorio

Identidad del pago

string

/^pay_[0-9a-hjkmnp-tv-z]{24,}$/

status

obligatorio

Solo succeeded, canceled y expired son terminales. Un intento rechazado devuelve el pago a requires_customer_action con lastDecline, así que el cliente puede intentarlo de nuevo hasta que el pago venza. partially_authorized significa que algunas partes tienen fondos retenidos, authorized que los fondos de todas las partes están retenidos y esperan que el organizador los capture, capturing que la captura está en curso y releasing que se están liberando los fondos retenidos. verifying es un estado real no terminal; no es un error ni un rechazo.

string

Valores permitidos: requires_customer_action processing partially_authorized authorized capturing partially_paid releasing verifying succeeded canceled expired

invoiceId

obligatorio

Cualquiera de:

string

string

null

null

customerCheckoutUrl

obligatorio

Cualquiera de:

string

string format: uri

null

null

periodStart

obligatorio

Cualquiera de:

string

string format: date-time

null

null

periodEnd

obligatorio

Cualquiera de:

string

string format: date-time

null

null

initiator

obligatorio

Cualquiera de:

string

string

Valor permitido: customer

string

string

Valor permitido: merchant

recoveryNotice

obligatorio

Cualquiera de:

SubscriptionRecoveryNotice

object

status

obligatorio

Cualquiera de:

string

string

Valor permitido: pending

string

string

Valor permitido: accepted

string

string

Valor permitido: failed

string

string

Valor permitido: unknown

deadline

obligatorio

Cualquiera de:

string

string format: date-time

null

null

problem

obligatorio

Cualquiera de:

SubscriptionRecoveryNoticeProblem

Por qué el aviso de pago pendiente necesita atención. notice_handoff_failed es un rechazo definitivo del proveedor; notice_handoff_unknown es una entrega al proveedor de resultado incierto, que se reintenta hasta que termina su ventana de deduplicación; notice_delivery_failed es un rebote o una queja después de la entrega; notice_unavailable significa que todavía no se pudo preparar el aviso.

string

Valores permitidos: notice_unavailable notice_handoff_failed notice_handoff_unknown notice_delivery_failed

null

null

null

null

invoicing

Cualquiera de:

PaymentInvoicing

Instrucciones de factura guardadas y selección del destinatario. El ciclo de vida de la factura y las credenciales de acceso se informan por separado.

object

mode

obligatorio

Cualquiera de:

string

string

Valor permitido: automatic

string

string

Valor permitido: merchant

string

string

Valor permitido: existing

type

obligatorio

string

Valores permitidos: E31 E32 E45

recipientEmail

obligatorio

Cualquiera de:

string

string format: email

<= 320 characters

null

null

issuanceProblem

Cuerpo de un problema RFC 9457 devuelto por la API /v1.

object

code

obligatorio

string

>= 1 characters

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

buyer

discriminator: kind

AnonymousBuyer

object

kind

obligatorio

string

Valores permitidos: anonymous

DomesticBuyer

object

kind

obligatorio

string

Valores permitidos: domestic

legalName

obligatorio

string

>= 1 characters <= 150 characters /^(?=.*[^\p{White_Space}])[\s\S]+$/

taxId

obligatorio

string

/^[0-9]{9}([0-9]{2})?$/

deliveryPhone

string

/^[0-9]{3}-[0-9]{3}-[0-9]{4}$/

ForeignBuyer

object

foreignId

obligatorio

string

>= 1 characters <= 20 characters /^(?=.*[^\p{White_Space}])[\s\S]+$/

kind

obligatorio

string

Valores permitidos: foreign

legalName

obligatorio

string

>= 1 characters <= 150 characters /^(?=.*[^\p{White_Space}])[\s\S]+$/

deliveryPhone

string

/^[0-9]{3}-[0-9]{3}-[0-9]{4}$/

governmentEligibility

Cualquiera de:

object

object

entityKind

obligatorio

string

Valor permitido: central_government

authorityReference

obligatorio

string

>= 1 characters <= 128 characters

object

object

entityKind

obligatorio

string

Valor permitido: decentralized_or_autonomous

authorityReference

obligatorio

string

>= 1 characters <= 128 characters

object

object

entityKind

obligatorio

string

Valor permitido: social_security

authorityReference

obligatorio

string

>= 1 characters <= 128 characters

object

object

entityKind

obligatorio

string

Valor permitido: other_noncommercial_government

authorityReference

obligatorio

string

>= 1 characters <= 128 characters

allowedTypes

Array<string>

Valores permitidos: E31 E32 E45

isTypeLocked

boolean

isBuyerLocked

boolean

revision

Aumenta cada vez que cambian el tipo de comprobante, el comprador o la elegibilidad gubernamental.

integer

>= 1

invoiceReference

string

>= 1 characters <= 128 characters

null

null

paymentsHasMore

obligatorio

boolean

paymentsNextCursor

obligatorio

Cualquiera de:

string

string

null

null

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

400

400

No se pudo entender la solicitud.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "No se pudo entender la solicitud.",
  "status": 400,
  "code": "parameter_invalid",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: parameter_invalid

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 400

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

401

401

La credencial falta, tiene un formato incorrecto o ya no es válida.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La credencial falta, tiene un formato incorrecto o ya no es válida.",
  "status": 401,
  "code": "api_key_missing",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: api_key_missing api_key_invalid checkout_token_invalid checkout_token_expired

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 401

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

403

403

La credencial es válida, pero no tiene permiso para realizar esta operación.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La credencial es válida, pero no tiene permiso para realizar esta operación.",
  "status": 403,
  "code": "operation_not_permitted",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: operation_not_permitted

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 403

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

404

404

Ningún endpoint sirve este método y ruta, o no existe un recurso con este identificador dentro del alcance del solicitante.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "Ningún endpoint sirve este método y ruta, o no existe un recurso con este identificador dentro del alcance del solicitante.",
  "status": 404,
  "code": "subscription_not_found",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: subscription_not_found

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 404

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.

500

500

La solicitud no pudo completarse. Recupera el resultado con la referencia guardada o repite la solicitud con la misma clave de idempotencia.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La solicitud no pudo completarse. Recupera el resultado con la referencia guardada o repite la solicitud con la misma clave de idempotencia.",
  "status": 500,
  "code": "internal_error",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: internal_error

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 500

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

detail

string

invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string

issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>

Valores permitidos: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch

problems

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object

code

obligatorio

string

message

obligatorio

string

path

obligatorio

string

Cabeceras

request-id

obligatorio

string

Identifica esta solicitud. Indícalo cuando contactes a soporte.