Run a certification workbook

POST

/v1/business/certification/test-runs

curl --request POST \
  --url https://api.timbro.do/v1/business/certification/test-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: example' \
  --data '{ "kind": "ecf", "testSetId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "confirmation": { "statementVersion": "2026-10-21", "language": "es" } }'

• Production

Signs each case of the retained workbook (kind ecf for DGII step 2, acecf for step 3) with the business’s signing certificate in Timbro’s custody and sends it to DGII, in workbook order, stopping at the first rejection. Call it only while the business certification lists the run_test_set action; otherwise it answers business_certification_unavailable. It needs the representative’s confirmation of the statement, recorded with the actor, time, and statement hash before Timbro is asked; only a person or an admin key can confirm, not an agent. A retained workbook of that kind must exist, or it answers business_certification_test_set_required. A retry with the same Idempotency-Key and body returns the same run; a new run needs a new confirmation and key. A run is evidence for the business and the team, not a DGII decision: it never changes a step’s status. Read the outcome with retrieveBusinessCertificationTestRun.

Authentication

• adminKey

Parameters

Header parameters

idempotency-key

required

string

>= 1 characters <= 255 characters /^[\x20-\x7e]+$/

Request body^required

Media typeapplication/json

object

kind

required

Any of:

string

string

Allowed value: ecf

string

string

Allowed value: acecf

testSetId

required

The id of the retained workbook the representative saw. If a newer workbook of that kind has replaced it, the operation answers business_certification_test_set_changed and runs nothing.

string format: uuid

confirmation

required

The statement the representative read and accepted for this workbook. {business} is the business’s legal name. Send a new Idempotency-Key for each confirmation. 2026-10-21, es: “Autorizo a Timbro a firmar con el certificado digital de {business} y a enviar a la DGII los casos de prueba de este archivo.” 2026-10-21, en: “I authorize Timbro to sign with {business}’s digital certificate and send the test cases in this file to DGII.”

object

statementVersion

required

Any of:

string

string

Allowed value: 2026-10-21

language

required

Any of:

string

string

Allowed value: es

string

string

Allowed value: en

Responses

200

200

One run of a retained DGII test workbook. Timbro signs each case with the business’s custodied certificate and sends it to DGII in workbook order, and stops at the first rejection. refused means the workbook could not be built into documents and nothing was sent; refusal names the sheet, row, and column, never the cell text. consumerInvoices lists the signed consumer invoices (E32) to upload in DGII’s portal box for step 2, and is empty for acecf. A run is evidence, not a DGII decision: it never changes a step’s status.

Media typeapplication/json

Response fields and codes

One run of a retained DGII test workbook. Timbro signs each case with the business’s custodied certificate and sends it to DGII in workbook order, and stops at the first rejection. refused means the workbook could not be built into documents and nothing was sent; refusal names the sheet, row, and column, never the cell text. consumerInvoices lists the signed consumer invoices (E32) to upload in DGII’s portal box for step 2, and is empty for acecf. A run is evidence, not a DGII decision: it never changes a step’s status.

object

object

required

string

Allowed value: certification_test_run

id

required

string format: uuid

attemptReference

required

string

>= 1 characters

kind

required

Any of:

string

string

Allowed value: ecf

string

string

Allowed value: acecf

testSetId

required

string format: uuid

status

required

Any of:

string

string

Allowed value: running

string

string

Allowed value: accepted

string

string

Allowed value: rejected

string

string

Allowed value: failed

string

string

Allowed value: refused

failureMessage

required

Any of:

string

string

null

null

createdAt

required

string format: date-time

completedAt

required

Any of:

string

string format: date-time

null

null

counts

required

Array<object>

object

documentType

required

An e-CF type from 31 to 47, RFCE, or ACECF.

string

total

required

integer

accepted

required

integer

rejected

required

integer

cases

required

Array<object>

object

sourceRow

required

The workbook row the case came from.

integer

>= 1

caseLabel

required

Any of:

string

string

null

null

documentType

required

string

eNcf

required

string

status

required

Any of:

string

string

Allowed value: pending

string

string

Allowed value: sent

string

string

Allowed value: accepted

string

string

Allowed value: rejected

string

string

Allowed value: unknown

dgiiMessage

required

Any of:

string

string

null

DGII’s text for a rejected case; null otherwise.

null

refusal

required

Any of:

object

object

code

required

string

sheet

required

Any of:

string

string

null

null

row

required

Any of:

integer

integer

>= 1

null

null

column

required

Any of:

integer

integer

>= 1

null

null

null

null

consumerInvoices

required

Array<object>

object

eNcf

required

string

sourceRow

required

integer

>= 1

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

Idempotent-Replayed

string

Allowed value: true

true when this response replays the stored result of an earlier request with the same Idempotency-Key.

201

201

One run of a retained DGII test workbook. Timbro signs each case with the business’s custodied certificate and sends it to DGII in workbook order, and stops at the first rejection. refused means the workbook could not be built into documents and nothing was sent; refusal names the sheet, row, and column, never the cell text. consumerInvoices lists the signed consumer invoices (E32) to upload in DGII’s portal box for step 2, and is empty for acecf. A run is evidence, not a DGII decision: it never changes a step’s status.

Media typeapplication/json

Response fields and codes

One run of a retained DGII test workbook. Timbro signs each case with the business’s custodied certificate and sends it to DGII in workbook order, and stops at the first rejection. refused means the workbook could not be built into documents and nothing was sent; refusal names the sheet, row, and column, never the cell text. consumerInvoices lists the signed consumer invoices (E32) to upload in DGII’s portal box for step 2, and is empty for acecf. A run is evidence, not a DGII decision: it never changes a step’s status.

object

object

required

string

Allowed value: certification_test_run

id

required

string format: uuid

attemptReference

required

string

>= 1 characters

kind

required

Any of:

string

string

Allowed value: ecf

string

string

Allowed value: acecf

testSetId

required

string format: uuid

status

required

Any of:

string

string

Allowed value: running

string

string

Allowed value: accepted

string

string

Allowed value: rejected

string

string

Allowed value: failed

string

string

Allowed value: refused

failureMessage

required

Any of:

string

string

null

null

createdAt

required

string format: date-time

completedAt

required

Any of:

string

string format: date-time

null

null

counts

required

Array<object>

object

documentType

required

An e-CF type from 31 to 47, RFCE, or ACECF.

string

total

required

integer

accepted

required

integer

rejected

required

integer

cases

required

Array<object>

object

sourceRow

required

The workbook row the case came from.

integer

>= 1

caseLabel

required

Any of:

string

string

null

null

documentType

required

string

eNcf

required

string

status

required

Any of:

string

string

Allowed value: pending

string

string

Allowed value: sent

string

string

Allowed value: accepted

string

string

Allowed value: rejected

string

string

Allowed value: unknown

dgiiMessage

required

Any of:

string

string

null

DGII’s text for a rejected case; null otherwise.

null

refusal

required

Any of:

object

object

code

required

string

sheet

required

Any of:

string

string

null

null

row

required

Any of:

integer

integer

>= 1

null

null

column

required

Any of:

integer

integer

>= 1

null

null

null

null

consumerInvoices

required

Array<object>

object

eNcf

required

string

sourceRow

required

integer

>= 1

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

Idempotent-Replayed

string

Allowed value: true

true when this response replays the stored result of an earlier request with the same Idempotency-Key.

400

400

The request could not be understood.

Media typeapplication/problem+json

Example

{
  "type": "about:blank",
  "title": "The request could not be understood.",
  "status": 400,
  "code": "parameter_missing",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: parameter_missing parameter_invalid request_body_malformed

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 400

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

Allowed values: 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

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

401

401

The credential is missing, malformed, or no longer valid.

Media typeapplication/problem+json

Example

{
  "type": "about:blank",
  "title": "The credential is missing, malformed, or no longer valid.",
  "status": 401,
  "code": "person_session_missing",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: person_session_missing api_key_missing api_key_invalid checkout_token_invalid checkout_token_expired

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 401

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

Allowed values: 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

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

403

403

The credential is valid but not permitted to perform this operation.

Media typeapplication/problem+json

Example

{
  "type": "about:blank",
  "title": "The credential is valid but not permitted to perform this operation.",
  "status": 403,
  "code": "operation_not_permitted",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: operation_not_permitted

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 403

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

Allowed values: 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

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

404

404

No endpoint serves this method and path, or no resource with this identifier exists within the caller’s scope.

Media typeapplication/problem+json

Example

{
  "type": "about:blank",
  "title": "No endpoint serves this method and path, or no resource with this identifier exists within the caller's scope.",
  "status": 404,
  "code": "business_not_found",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: business_not_found

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 404

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

Allowed values: 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

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

409

409

The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.

Media typeapplication/problem+json

Example

{
  "type": "about:blank",
  "title": "The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.",
  "status": 409,
  "code": "business_certification_requirements_unmet",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: business_certification_requirements_unmet business_certification_test_set_required business_certification_test_set_changed business_certification_test_run_in_progress idempotency_key_reused certification_environment_required idempotency_key_conflict

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 409

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

Allowed values: 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

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

413

413

The request body is larger than this endpoint accepts.

Media typeapplication/problem+json

Example

{
  "type": "about:blank",
  "title": "The request body is larger than this endpoint accepts.",
  "status": 413,
  "code": "request_body_too_large",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: request_body_too_large

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 413

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

Allowed values: 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

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

415

415

The request body carries a content type this endpoint does not accept.

Media typeapplication/problem+json

Example

{
  "type": "about:blank",
  "title": "The request body carries a content type this endpoint does not accept.",
  "status": 415,
  "code": "unsupported_media_type",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: unsupported_media_type

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 415

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

Allowed values: 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

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

500

500

The request could not complete. Recover by the retained resource reference or retry with the same command identity.

Media typeapplication/problem+json

Example

{
  "type": "about:blank",
  "title": "The request could not complete. Recover by the retained resource reference or retry with the same command identity.",
  "status": 500,
  "code": "internal_error",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: internal_error

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 500

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

Allowed values: 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

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

503

503

A required service is temporarily unavailable. Retry with the same reference or command identity.

Media typeapplication/problem+json

Example

{
  "type": "about:blank",
  "title": "A required service is temporarily unavailable. Retry with the same reference or command identity.",
  "status": 503,
  "code": "business_certification_unavailable",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

Stable machine-readable code. Branch on this, never on title.

string

Allowed values: business_certification_unavailable

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 503

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

Allowed values: 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

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.