Aceptar o rechazar un documento recibido

POST

/v1/received-documents/{receivedDocumentId}/commercial-response

curl --request POST \
  --url https://api.timbro.do/v1/received-documents/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/commercial-response \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "decision": "accepted" }'

• API de Timbro

Registra la decisión comercial sobre un documento recibido de un suplidor. Si lo rechazas, indica el motivo. Esta decisión no registra una cuenta por pagar.

Autenticación

• secretKey
• integrationToken
  invoices:test
• integrationToken
  invoices:live

Parámetros

Parámetros de ruta

receivedDocumentId

obligatorio

string format: uuid

Cuerpo de la solicitud^obligatorio

Media typeapplication/json

discriminator: decision

object

DGII Estado 1: e-CF aceptado.

object

decision

obligatorio

string

Valores permitidos: accepted

object

DGII Estado 2: e-CF rechazado.

object

decision

obligatorio

string

Valores permitidos: rejected

motive

obligatorio

DetalleMotivoRechazo es obligatorio y no puede estar vacío cuando Estado es 2.

string

Respuestas

200

200

Respuesta predeterminada

Media typeapplication/json

Campos y códigos de la respuesta

object

buyerTaxId

obligatorio

string

commercialResponse

obligatorio

discriminator: status

object

El documento no está en estado received, por lo que no hay nada que revisar.

object

status

obligatorio

string

Valores permitidos: notReviewable

PendingStatus

Recibido y pendiente de revisión por una persona administradora.

object

status

obligatorio

string

Valores permitidos: pending

object

object

recordedAt

obligatorio

string format: date-time

status

obligatorio

string

Valores permitidos: accepted

submissionState

obligatorio

Estado informativo del envío saliente del ACECF, mostrado como contexto en Portal Timbro.

string

Valores permitidos: pending inFlight submitted dgiiRejected submissionRefused signingRefused constructionRefused authenticationFailed unavailable outcomeUnknown attemptsExhausted

object

object

motive

obligatorio

string

<= 250 characters

recordedAt

obligatorio

string format: date-time

status

obligatorio

string

Valores permitidos: rejected

submissionState

obligatorio

Estado informativo del envío saliente del ACECF, mostrado como contexto en Portal Timbro.

string

Valores permitidos: pending inFlight submitted dgiiRejected submissionRefused signingRefused constructionRefused authenticationFailed unavailable outcomeUnknown attemptsExhausted

eNcf

obligatorio

string

environment

obligatorio

Ambiente de ejecución de la DGII elegido antes de admitir el ciclo de vida.

string

Valores permitidos: sandbox certification production

id

obligatorio

string format: uuid

issuerLegalName

obligatorio

La RazonSocialEmisor del emisor tal como figura en el e-CF recibido, o null cuando la entrega no traía un nombre legible.

string | null

>= 1 characters <= 150 characters /\S/

issuerTaxId

obligatorio

string

notReceivedReason

obligatorio

null

null

ReceivedDocumentNotReceivedReasonResource

string

Valores permitidos: schemaError signatureError duplicateSubmission buyerRncMismatch

receivedAt

obligatorio

string format: date-time

receivedXmlSha256

obligatorio

string

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

state

obligatorio

string

Valores permitidos: received notReceived

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_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: parameter_missing parameter_invalid request_body_malformed custody_certificate_malformed custody_signature_algorithm_unsupported custody_certificate_trust_profile_unsupported custody_certificate_chain_untrusted custody_certificate_purpose_unsupported source_provider_installation_request_invalid missing_idempotency_key invalid_idempotency_key malformed_json invalid_request invoice_original_invalid invalid_collection_query invalid_collection_cursor invalid_replay_scope webhook_destination_not_allowed commercial_response_motive_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 integration_token_invalid checkout_token_invalid checkout_token_expired unauthenticated invalid_login invalid_credential credential_revoked

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": "route_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: route_not_found webhook_endpoint_not_found webhook_event_not_found organization_not_found legal_issuer_not_found invitation_invalid certificate_custody_binding_not_found integration_not_found source_provider_authorization_not_found certification_test_run_document_not_found fiscal_operation_not_found invoice_not_found fiscal_artifact_not_found invoice_receipt_not_found fiscal_delivery_not_found received_document_not_found receiving_issuer_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.

409

409

La solicitud entra en conflicto con el estado actual del recurso o con una solicitud anterior que usó la misma clave de idempotencia (Idempotency-Key).

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La solicitud entra en conflicto con el estado actual del recurso o con una solicitud anterior que usó la misma clave de idempotencia (`Idempotency-Key`).",
  "status": 409,
  "code": "webhook_endpoint_deleted",
  "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: webhook_endpoint_deleted webhook_endpoint_suspended email_already_registered organization_slug_taken hosted_tenant_conflict legal_issuer_already_registered onboarding_legal_issuer_identity_conflict legal_issuer_profile_incomplete already_a_member certificate_custody_binding_conflict certificate_custody_certificate_not_active certificate_custody_certificate_version_not_active integration_not_connected source_provider_authorization_required source_provider_installation_disabled source_provider_installation_removed source_provider_scope_insufficient source_provider_target_access_removed source_provider_authorization_conflict source_provider_installation_callback_replayed integration_creation_conflict integration_activation_conflict integration_activation_verification_rejected certification_environment_required certification_test_set_required certification_test_run_in_progress idempotency_key_conflict fiscal_number_already_used sequence_changed sequence_source_record_conflict source_version_stale source_predecessor_conflict source_history_requires_reconciliation source_content_conflict source_action_conflict source_command_conflict invoice_reference_conflict invoice_totals_mismatch printed_representation_profile_conflict source_record_already_fiscalized source_operation_pending source_outcome_unknown authority_rejected_replacement fiscal_operation_not_in_intervention intervention_not_resumable intervention_not_closable correction_target_unsettled correction_target_closed invoice_receipt_not_ready fiscal_delivery_outcome_conflict webhook_endpoint_registration_conflict commercial_response_decision_conflict receiving_issuer_held_elsewhere production_reception_certificate_required production_reception_integration_required production_reception_already_filed

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 409

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.

413

413

El cuerpo de la solicitud es más grande de lo que acepta este endpoint.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "El cuerpo de la solicitud es más grande de lo que acepta este endpoint.",
  "status": 413,
  "code": "request_body_too_large",
  "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: request_body_too_large request_too_large

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 413

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.

415

415

El cuerpo de la solicitud tiene un tipo de contenido que este endpoint no acepta.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "El cuerpo de la solicitud tiene un tipo de contenido que este endpoint no acepta.",
  "status": 415,
  "code": "unsupported_media_type",
  "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: unsupported_media_type

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 415

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 fiscal_artifact_unverified

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.

503

503

Un servicio requerido no está disponible temporalmente. Inténtalo de nuevo con la misma referencia o la misma clave de idempotencia.

Media typeapplication/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "Un servicio requerido no está disponible temporalmente. Inténtalo de nuevo con la misma referencia o la misma clave de idempotencia.",
  "status": 503,
  "code": "integration_authorization_unavailable",
  "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: integration_authorization_unavailable

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 503

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.

Retry-After

string

/^[0-9]+$/

Segundos que debes esperar antes de repetir esta solicitud o volver a consultar el recurso.