Business

Import a signing certificate

POST

/v1/business/import-signing-certificate

const url = 'https://api.timbro.do/v1/business/import-signing-certificate';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"certificateP12Base64":"example","password":"example"}'
};

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

curl --request POST \
  --url https://api.timbro.do/v1/business/import-signing-certificate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "certificateP12Base64": "example", "password": "example" }'

Hands the business’s PKCS#12 archive and its password to Timbro’s custody once. Timbro uses the certificate for test, live, and DGII certification invoicing, including an environment the business binds later. When the business already has a certificate, importing a different valid one replaces it in every environment at once; the same certificate is a replay. A certificate from another signer than the one an environment enrolled is refused as certificate_signer_mismatch, and an import that collides with another one in progress as business_certificate_conflict, which the caller repeats. The import does not assert DGII production qualification.

Authentication

adminKey

Request body^required

application/json

Example^generated

{
  "certificateP12Base64": "example",
  "password": "example"
}

object

certificateP12Base64

required

string

>= 24 characters <= 200000 characters

password

required

string

>= 1 characters <= 256 characters

Responses

200

Default Response

application/json

Response fields and codes

The business the credential selects, its capabilities, and the requirements that remain.

object

object

required

string

Allowed value: business

required

string

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

rnc

required

string

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

legalName

required

string

>= 1 characters

economicActivity

required

Any of:

string
null

string

>= 1 characters <= 512 characters

revision

required

integer

capabilities

required

Invoices live.status is active only when the live signing certificate is active and at least one e-CF type in invoicing.live.documentTypes is ready. An empty or unreadable list is never active; requirements with mode: "live" name what is missing.

object

payments

required

object

requested

required

boolean

test

required

object

status

required

Any of:

string

Allowed value: active

live

required

object

status

required

Any of:

string

Allowed value: active

invoices

required

object

requested

required

boolean

test

required

object

status

required

Any of:

string

Allowed value: active

live

required

object

status

required

Any of:

string

Allowed value: active

fiscalDetails

required

object

commercialName

required

Any of:

string
null

string

address

required

Any of:

string
null

string

location

required

Any of:

object
null

object

placeId

required

string

/^place_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/

catalogReleaseId

required

string

/^dr_[A-Za-z0-9._-]+$/

municipalityCode

required

Any of:

string
null

string

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

name

required

string

>= 1 characters <= 160 characters

kind

required

Any of:

string

Allowed value: country

qualityStatus

required

Any of:

string

Allowed value: verified

ancestors

required

The places that contain the selected one, outermost first.

Array<object>

<= 32 items

object

placeId

required

string

/^place_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/

name

required

string

>= 1 characters <= 160 characters

kind

required

Any of:

string

Allowed value: country

qualityStatus

required

Any of:

string

Allowed value: verified

phone

required

Any of:

string
null

string

email

required

Any of:

string
null

string

defaultIncomeType

required

Any of:

string
null

string

paymentsProfile

required

Any of:

MerchantPaymentsProfile
null

Payer-facing support, address, and delivery terms. The legal name and RNC are the business’s.

object

displayName

required

string

>= 2 characters <= 80 characters /^(?=[\s\S]*\p{L})(?=\s*\S(?:[\s\S]*\S){1})(?!\s*(\S)\1*\s*$)[\s\S]+$/

statementDescriptor

required

string

>= 2 characters <= 22 characters /^(?=[\s\S]*\p{L})(?=\s*\S(?:[\s\S]*\S){1})(?!\s*(\S)\1*\s*$)[\s\S]+$/

permanentAddress

required

The selling merchant’s permanent business address.

object

line1

required

string

>= 3 characters <= 160 characters /^(?=[\s\S]*\p{L})(?=\s*\S(?:[\s\S]*\S){2})(?!\s*(\S)\1*\s*$)[\s\S]+$/

city

required

string

>= 2 characters <= 80 characters /^(?=[\s\S]*\p{L})(?=\s*\S(?:[\s\S]*\S){1})(?!\s*(\S)\1*\s*$)[\s\S]+$/

countryCode

required

string

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

line2

string

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

province

string

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

postalCode

string

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

supportEmail

required

string format: email

<= 254 characters

supportPhone

required

string

/^\+[1-9][0-9]{7,14}$/

deliveryPolicy

required

discriminator: kind

DeliveryNotOffered
MerchantManagedDelivery

object

kind

required

string

Allowed value: not_offered

paymentsProfileOrigin

required

Any of:

unknown
null

Any of:

string
string

string

Allowed value: derived

invoicing

required

object

test

required

Any of:

BusinessFiscalSetupUnavailable
BusinessFiscalSetupAvailable

object

status

required

string

Allowed value: unavailable

cause

required

string

Allowed value: timbro_unreachable

object

status

required

string

Allowed value: available

binding

required

discriminator: status

object

status

required

string

Allowed value: unbound

legalIssuer

required

discriminator: status

object

status

required

string

Allowed value: missing

signingCertificate

required

discriminator: status

BusinessSigningCertificateMissing
BusinessSigningCertificateActive

object

status

required

string

Allowed value: missing

testFiscalDocument

required

discriminator: status

object

status

required

string

Allowed value: not_sent

documentTypes

required

Any of:

Array
null

Array

discriminator: status

DocumentTypeReadyToIssue
DocumentTypeActionRequired

object

type

required

Any of:

string

Allowed value: E31

status

required

string

Allowed value: ready

numbering

required

The range Timbro assigns the next fiscal number of this type from.

object

remaining

required

Fiscal numbers left in the selected range.

integer

>= 1 <= 9999999999

confirmation

required

Any of:

string
string

string

Allowed value: confirmed

expiresOn

required

Any of:

string
null

The sequence expiry, or null for a type without one (E32 and E34).

string format: date

object

type

required

Any of:

string

Allowed value: E31

status

required

string

Allowed value: actionRequired

reasons

required

Every condition that blocks this type: issuer, then certificate, then numbering.

Array

>= 1 items

numbering

required

Any of:

NumberingRange
null

The range Timbro assigns the next fiscal number of this type from.

object

remaining

required

Fiscal numbers left in the selected range.

integer

>= 1 <= 9999999999

confirmation

required

Any of:

string
string

string

Allowed value: confirmed

expiresOn

required

Any of:

string
null

The sequence expiry, or null for a type without one (E32 and E34).

string format: date

live

required

Any of:

BusinessFiscalSetupUnavailable
BusinessLiveFiscalSetupAvailable

object

status

required

string

Allowed value: unavailable

cause

required

string

Allowed value: timbro_unreachable

object

status

required

string

Allowed value: available

binding

required

discriminator: status

object

status

required

string

Allowed value: unbound

legalIssuer

required

discriminator: status

object

status

required

string

Allowed value: missing

signingCertificate

required

discriminator: status

BusinessSigningCertificateMissing
BusinessSigningCertificateActive

object

status

required

string

Allowed value: missing

documentTypes

required

Any of:

Array
null

Array

discriminator: status

DocumentTypeReadyToIssue
DocumentTypeActionRequired

object

type

required

Any of:

string

Allowed value: E31

status

required

string

Allowed value: ready

numbering

required

The range Timbro assigns the next fiscal number of this type from.

object

remaining

required

Fiscal numbers left in the selected range.

integer

>= 1 <= 9999999999

confirmation

required

Any of:

string
string

string

Allowed value: confirmed

expiresOn

required

Any of:

string
null

The sequence expiry, or null for a type without one (E32 and E34).

string format: date

object

type

required

Any of:

string

Allowed value: E31

status

required

string

Allowed value: actionRequired

reasons

required

Every condition that blocks this type: issuer, then certificate, then numbering.

Array

>= 1 items

numbering

required

Any of:

NumberingRange
null

The range Timbro assigns the next fiscal number of this type from.

object

remaining

required

Fiscal numbers left in the selected range.

integer

>= 1 <= 9999999999

confirmation

required

Any of:

string
string

string

Allowed value: confirmed

expiresOn

required

Any of:

string
null

The sequence expiry, or null for a type without one (E32 and E34).

string format: date

sequences

required

Any of:

Array<object>
null

Array<object>

An e-NCF sequence the business recorded from DGII’s Oficina Virtual, as recorded. DGII’s answers confirm it; documentTypes[].numbering.confirmation and sequence_rejected_by_dgii report that.

object

documentType

required

Any of:

string

Allowed value: E31

firstNumber

required

The first number DGII granted.

integer

>= 1 <= 9999999999

lastNumber

required

The last number DGII granted.

integer

>= 1 <= 9999999999

nextNumber

required

Any of:

integer
null

The next number that was unused when the business recorded the sequence, or null once every number is used. Timbro moves on from there as it issues; documentTypes reports how many numbers remain.

integer

>= 1 <= 9999999999

expiresOn

required

Any of:

string
null

The day the sequence expires, or null for E32 and E34, which never expire.

string format: date

requirements

required

Array<object>

One thing that must happen before a capability is active, and who acts on it. While a capability is active, a requirement it would otherwise block blocks nothing and is a warning. Live invoicing lists at most one requirement per reason class (legal_issuer_profile_required, signing_certificate_required, sequence_required, sequence_confirmation_pending), each with the e-CF documentTypes it affects. When Timbro refused the live Legal issuer profile, the first entry is fiscal_details_rejected instead, with field /fiscalDetails. The merchant owns all but sequence_confirmation_pending, which waits on dgii. default_income_type_required is deprecated and no longer returned: an invoicing business without a stored income type reads 01.

object

code

required

Any of:

string

Allowed value: capabilities_required

owner

required

Any of:

string

Allowed value: merchant

blocks

required

Array

<= 2 items

mode

Any of:

string
string

string

Allowed value: test

documentTypes

The e-CF types this requirement keeps from being issued, in type order. Absent when it applies to the whole environment.

Array

>= 1 items

field

JSON Pointer into this representation the requirement names.

string

errors

Array<object>

>= 1 items

object

code

required

string

message

required

string

onboardingUrl

required

string format: uri

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.

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_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

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.

409

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

application/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_fiscal_setup_incomplete",
  "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_fiscal_setup_incomplete business_certificate_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>

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

The request body is larger than this endpoint accepts.

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

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

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

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

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.

422

The request is well-formed but cannot be carried out.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The request is well-formed but cannot be carried out.",
  "status": 422,
  "code": "certificate_p12_password_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: certificate_p12_password_invalid certificate_pkcs12_invalid certificate_expired certificate_not_yet_valid certificate_archive_not_supported certificate_not_supported certificate_signer_mismatch

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 422

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.

503

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

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

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.

Import a signing certificate

Authentication

Request bodyrequired

Examplegenerated

Responses

200

Headers

400

Example

Headers

401

Example

Headers

403

Example

Headers

404

Example

Headers

409

Example

Headers

413

Example

Headers

415

Example

Headers

422

Example

Headers

500

Example

Headers

503

Example

Headers

Request body^required

Example^generated