Business

Retrieve the business certification process

GET

/v1/business/certification

const url = 'https://api.timbro.do/v1/business/certification';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.timbro.do/v1/business/certification \
  --header 'Authorization: Bearer <token>'

Returns the authenticated business’s DGII certification path, prerequisites, the declared DGII step, all 15 official steps with the source of each status, reported evidence, and what the current step needs. A reported or declared step is never verified and never grants Live access.

Authentication

secretKey
adminKey

Responses

200

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

application/json

Response fields and codes

discriminator: status

BusinessCertificationNotStarted
BusinessCertificationInProgress

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

Allowed value: invoices_not_requested

owner

required

Any of:

string

Allowed value: merchant

blocks

required

Array

<= 4 items

field

string

availablePaths

required

Array

>= 1 items

recommendedPath

required

Any of:

string
string

string

Allowed value: own_software

actions

required

Array

<= 1 items

object

object

required

string

Allowed value: business_certification

required

string

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

revision

required

integer

>= 1

status

required

string

Allowed value: in_progress

path

required

Any of:

string
string

string

Allowed value: own_software

software

required

object

name

required

string

>= 1 characters <= 128 characters

version

required

string

>= 1 characters <= 64 characters

dgiiProvider

required

Any of:

object
null

object

rnc

required

string

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

name

required

string

>= 1 characters <= 128 characters

phase

required

Any of:

string

Allowed value: preparation

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>

object

code

required

Any of:

string

Allowed value: invoices_not_requested

owner

required

Any of:

string

Allowed value: merchant

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
null

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

Allowed value: 1

postulationSoftware

required

Any of:

object
null

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

object

kind

required

Any of:

string

Allowed value: timbro

name

string

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

reportedAt

required

string format: date-time

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

Allowed value: signing_certificate

state

required

Any of:

string

Allowed value: done

action

required

Any of:

unknown
null

Any of:

string

Allowed value: import_certificate

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

Allowed value: 1

code

required

string

>= 1 characters

title

required

string

>= 1 characters

actor

required

Any of:

string

Allowed value: merchant

status

required

Any of:

string

Allowed value: blocked

basis

required

Any of:

unknown
null

Any of:

string

Allowed value: timbro_executed

evidence

required

Array<object>

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

object

required

string

>= 1 characters

outcome

required

Any of:

string

Allowed value: submitted

verification

required

Any of:

string

string

Allowed value: user_reported

reference

required

Any of:

string
null

string

<= 255 characters

createdAt

required

string format: date-time

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

400

The request could not be understood.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The request could not be understood.",
  "status": 400,
  "code": "parameter_invalid",
  "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_invalid

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

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

application/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>

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

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

application/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>

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

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

application/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>

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

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

application/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>

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.