Declare the DGII step a business certification is on

POST

/v1/business/certification/progress

curl --request POST \
  --url https://api.timbro.do/v1/business/certification/progress \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: example' \
  --data '{ "expectedRevision": 1, "dgiiStep": 1, "postulationSoftware": { "kind": "timbro", "name": "example" } }'

• Production

Records the step the business’s DGII certification portal shows, for a business that started certification elsewhere or that DGII sent back to an earlier step. Earlier steps then count as done for sequencing and stay user-reported. The declaration is not evidence, verifies no step, and never grants Live access. Only a person can read DGII’s portal; an agent passes the step that person reports.

Authentication

• adminKey

Parameters

Header parameters

idempotency-key

required

string

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

Request body^required

Media typeapplication/json

The step the business’s DGII certification portal shows. A lower step than the last declaration reports a DGII reset. Omitting postulationSoftware keeps the software last declared.

object

expectedRevision

required

integer

>= 1

dgiiStep

required

Any of:

number

number

Allowed value: 1

number

number

Allowed value: 2

number

number

Allowed value: 3

number

number

Allowed value: 4

number

number

Allowed value: 5

number

number

Allowed value: 6

number

number

Allowed value: 7

number

number

Allowed value: 8

number

number

Allowed value: 9

number

number

Allowed value: 10

number

number

Allowed value: 11

number

number

Allowed value: 12

number

number

Allowed value: 13

number

number

Allowed value: 14

number

number

Allowed value: 15

Optional fields

postulationSoftware

The software the business named in its DGII postulation. name is accepted only with kind other.

object

kind

required

Any of:

string

string

Allowed value: timbro

string

string

Allowed value: other

string

string

Allowed value: unknown

name

string

>= 1 characters <= 80 characters /^[^\p{C}]*$/

Responses

200

200

Durable certification preparation and user-reported DGII progress for the authenticated business. Nothing in it grants Live access.

Media typeapplication/json

Response fields and codes

discriminator: status

BusinessCertificationNotStarted

object

object

required

string

Allowed value: business_certification

status

required

string

Allowed value: not_started

requirements

required

Array<object>

What stands in the way, who resolves it, and which steps wait for it. From step 12, Timbro files the business’s live deliveries in production; a production_reception requirement blocks step 12 until it does. Recording or declaring step 12 again retries when an owner or an admin key does it; one the operator owns waits for Timbro’s team.

object

code

required

Any of:

string

string

Allowed value: invoices_not_requested

string

string

Allowed value: fiscal_details_incomplete

string

string

Allowed value: certification_binding_required

string

string

Allowed value: certification_certificate_required

string

string

Allowed value: provider_eligibility_unverified

string

string

Allowed value: certification_test_set_processing_unavailable

string

string

Allowed value: certification_provider_acceptance_pending

string

string

Allowed value: production_reception_certificate_required

string

string

Allowed value: production_reception_integration_required

string

string

Allowed value: production_reception_held_elsewhere

string

string

Allowed value: production_reception_not_started

string

string

Allowed value: production_reception_owner_required

string

string

Allowed value: production_reception_receiver_missing

string

string

Allowed value: production_reception_operator_review

string

string

Allowed value: production_reception_already_filed

owner

required

Any of:

string

string

Allowed value: merchant

string

string

Allowed value: dgii

string

string

Allowed value: timbro

string

string

Allowed value: operator

blocks

required

Array

<= 4 items

field

string

availablePaths

required

Array

>= 1 items

recommendedPath

required

Any of:

string

string

Allowed value: own_software

string

string

Allowed value: external_software

actions

required

Array

<= 1 items

BusinessCertificationInProgress

object

object

required

string

Allowed value: business_certification

id

required

string

/^cert_[a-z0-9]{24,}$/

revision

required

integer

>= 1

status

required

string

Allowed value: in_progress

path

required

Any of:

string

string

Allowed value: own_software

string

string

Allowed value: external_software

software

required

object

name

required

string

>= 1 characters <= 128 characters

version

required

string

>= 1 characters <= 64 characters

dgiiProvider

required

Any of:

object

object

rnc

required

string

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

name

required

string

>= 1 characters <= 128 characters

null

null

phase

required

Any of:

string

string

Allowed value: preparation

string

string

Allowed value: application

string

string

Allowed value: tests

string

string

Allowed value: authorization

receiver

required

The one address DGII and other issuers reach the business at, in certification and in production.

object

host

required

Timbro’s receiver address, written as DGII’s boxes take it, for example ecf.timbro.do. The business enters it in Recepción, Aprobación comercial, and Autenticación, in the postulation and at steps 7 and 12.

string

>= 1 characters

requirements

required

Array<object>

What stands in the way, who resolves it, and which steps wait for it. From step 12, Timbro files the business’s live deliveries in production; a production_reception requirement blocks step 12 until it does. Recording or declaring step 12 again retries when an owner or an admin key does it; one the operator owns waits for Timbro’s team.

object

code

required

Any of:

string

string

Allowed value: invoices_not_requested

string

string

Allowed value: fiscal_details_incomplete

string

string

Allowed value: certification_binding_required

string

string

Allowed value: certification_certificate_required

string

string

Allowed value: provider_eligibility_unverified

string

string

Allowed value: certification_test_set_processing_unavailable

string

string

Allowed value: certification_provider_acceptance_pending

string

string

Allowed value: production_reception_certificate_required

string

string

Allowed value: production_reception_integration_required

string

string

Allowed value: production_reception_held_elsewhere

string

string

Allowed value: production_reception_not_started

string

string

Allowed value: production_reception_owner_required

string

string

Allowed value: production_reception_receiver_missing

string

string

Allowed value: production_reception_operator_review

string

string

Allowed value: production_reception_already_filed

owner

required

Any of:

string

string

Allowed value: merchant

string

string

Allowed value: dgii

string

string

Allowed value: timbro

string

string

Allowed value: operator

blocks

required

Array

<= 4 items

field

string

actions

required

What the caller can do now. start_production_reception appears when recording step 12 can ask Timbro to receive the business’s documents in production: for an owner or an admin key, since that creates the production binding. sign_portal_document appears only when this deployment’s Timbro signs DGII portal documents, the certification binding exists, and the caller confirms as itself: a person or an admin key, not an agent. run_test_set appears under the same conditions when this deployment’s Timbro runs certification test sets.

Array

progress

required

Any of:

BusinessCertificationProgress

The latest DGII step the business declared. Earlier steps count as done for sequencing and stay user-reported; a declaration never verifies a step or grants Live access.

object

dgiiStep

required

Any of:

number

number

Allowed value: 1

number

number

Allowed value: 2

number

number

Allowed value: 3

number

number

Allowed value: 4

number

number

Allowed value: 5

number

number

Allowed value: 6

number

number

Allowed value: 7

number

number

Allowed value: 8

number

number

Allowed value: 9

number

number

Allowed value: 10

number

number

Allowed value: 11

number

number

Allowed value: 12

number

number

Allowed value: 13

number

number

Allowed value: 14

number

number

Allowed value: 15

postulationSoftware

required

Any of:

object

The software the business named in its DGII postulation. name is accepted only with kind other.

object

kind

required

Any of:

string

string

Allowed value: timbro

string

string

Allowed value: other

string

string

Allowed value: unknown

name

string

>= 1 characters <= 80 characters /^[^\p{C}]*$/

null

null

reportedAt

required

string format: date-time

null

null

entryKit

required

Array<object>

<= 5 items

One thing the current step needs from the business, with the action that completes it. service_urls_in_dgii asks for the receiver host in DGII’s boxes at step 1, from step 7, and from step 12, and is done only after the business reports that step through Timbro. postulation_provider asks the business of an external_software certification to enter INDEXA SRL as the DGII provider in its postulation.

object

code

required

Any of:

string

string

Allowed value: signing_certificate

string

string

Allowed value: service_urls

string

string

Allowed value: service_urls_in_dgii

string

string

Allowed value: postulation_software

string

string

Allowed value: postulation_provider

state

required

Any of:

string

string

Allowed value: done

string

string

Allowed value: todo

string

string

Allowed value: not_needed

action

required

Any of:

unknown

Any of:

string

string

Allowed value: import_certificate

string

string

Allowed value: copy_service_urls

string

string

Allowed value: enter_service_urls_in_dgii

string

string

Allowed value: confirm_software_with_dgii

string

string

Allowed value: enter_postulation_provider_in_dgii

null

null

steps

required

Array<object>

>= 15 items <= 15 items

One official DGII step. basis names the source of its status: declared_progress for a step below the declared DGII step, business_report for a reported outcome, and null when nothing is recorded.

object

number

required

Any of:

number

number

Allowed value: 1

number

number

Allowed value: 2

number

number

Allowed value: 3

number

number

Allowed value: 4

number

number

Allowed value: 5

number

number

Allowed value: 6

number

number

Allowed value: 7

number

number

Allowed value: 8

number

number

Allowed value: 9

number

number

Allowed value: 10

number

number

Allowed value: 11

number

number

Allowed value: 12

number

number

Allowed value: 13

number

number

Allowed value: 14

number

number

Allowed value: 15

code

required

string

>= 1 characters

title

required

string

>= 1 characters

actor

required

Any of:

string

string

Allowed value: merchant

string

string

Allowed value: dgii

string

string

Allowed value: timbro

status

required

Any of:

string

string

Allowed value: blocked

string

string

Allowed value: action_required

string

string

Allowed value: awaiting_dgii

string

string

Allowed value: reported

string

string

Allowed value: verified

basis

required

Any of:

unknown

Any of:

string

string

Allowed value: timbro_executed

string

string

Allowed value: declared_progress

string

string

Allowed value: business_report

string

string

Allowed value: service_observed

null

null

evidence

required

Array<object>

A business-reported DGII outcome. It stays user-reported: only a DGII answer Timbro observes can verify a step.

object

id

required

string

>= 1 characters

outcome

required

Any of:

string

string

Allowed value: submitted

string

string

Allowed value: approved

string

string

Allowed value: rejected

string

string

Allowed value: needs_correction

verification

required

Any of:

string

string

Allowed value: user_reported

reference

required

Any of:

string

string

<= 255 characters

null

null

createdAt

required

string format: date-time

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_revision_conflict idempotency_key_reused idempotency_request_in_progress idempotency_key_expired

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.

Retry-After

string

/^[0-9]+$/

Seconds to wait before repeating this request or reading the resource again.

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.