Skip to content
TimbroTimbroTimbro

Create a fiscal delivery

POST
/fiscal_documents/{fiscalDocumentId}/deliveries
curl --request POST \
  --url https://api.timbro.dev/v1/fiscal_documents/example/deliveries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: example' \
  --data '{ "recipientEmail": "hello@example.com" }'

Queues delivery of a fiscal document; delivery remains pending until the document is ready.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
fiscalDocumentId
required
string
/^fiscal_document_[0-9a-hjkmnp-tv-z]{24,}$/

Fiscal document whose delivery is requested.

Header Parameters

Section titled “Header Parameters”
idempotency-key
required
string
>= 1 characters <= 255 characters /^[\x20-\x7e]+$/

Request Bodyrequired

Section titled “Request Bodyrequired”

Request delivery of an already issued fiscal document.

Media typeapplication/json
FiscalDeliveryRequest

Request delivery of an already issued fiscal document.

object
recipientEmail
required
string format: email
<= 254 characters
Examplegenerated
{
  "recipientEmail": "hello@example.com"
}

Responses

Section titled “Responses”

200

Section titled “200”

Default Response

Media typeapplication/json
object
email
required
string format: email
<= 320 characters
status
required
Any of:
string
Allowed value: waiting_for_document
Example
{
  "status": "waiting_for_document"
}

400

Section titled “400”

The request could not be understood or is not valid for this merchant account.

Media typeapplication/json
InvalidRequestError

The request could not be understood or is not valid for this merchant account.

object
error
required
object
type
required
string
Allowed value: invalid_request
code
required

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

string
Allowed values: parameter_missing parameter_invalid provider_not_available currency_not_supported amount_below_minimum amount_above_maximum checkout_reference_invalid checkout_reference_expired fiscal_buyer_tax_id_invalid fiscal_line_total_invalid fiscal_lines_required payment_split_invalid
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "invalid_request",
    "code": "parameter_missing"
  }
}

401

Section titled “401”

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

Media typeapplication/json
AuthenticationError

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

object
error
required
object
type
required
string
Allowed value: authentication_error
code
required

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

string
Allowed values: api_key_missing api_key_invalid checkout_token_invalid checkout_token_expired
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_missing"
  }
}

403

Section titled “403”

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

Media typeapplication/json
PermissionError

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

object
error
required
object
type
required
string
Allowed value: permission_error
code
required

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

string
Allowed values: merchant_account_not_owned merchant_account_admin_required operation_not_permitted_for_checkout_token live_mode_not_enabled
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "permission_error",
    "code": "merchant_account_not_owned"
  }
}

404

Section titled “404”

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

Media typeapplication/json
NotFoundError

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

object
error
required
object
type
required
string
Allowed value: invalid_request
code
required

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

string
Allowed values: endpoint_not_found payment_not_found fiscal_document_not_found merchant_account_not_found merchant_profile_not_found payment_split_not_found payment_part_not_found
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "invalid_request",
    "code": "endpoint_not_found"
  }
}

409

Section titled “409”

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

Media typeapplication/json
ConflictError

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

object
error
required
object
type
required
string
Allowed value: conflict_error
code
required

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

string
Allowed values: idempotency_key_reused idempotency_request_in_progress idempotency_key_expired payment_method_already_in_progress payment_awaiting_verification decline_not_retryable checkout_window_closed fiscal_preset_locked payment_not_editable fiscal_buyer_required fiscal_correction_not_allowed payment_split_not_allowed payment_split_exists payment_split_locked payment_split_not_capturable payment_split_not_expired payment_split_not_renewable payment_split_complete payment_split_part_required payment_part_not_payable fiscal_artifact_not_ready
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_key_reused"
  }
}

422

Section titled “422”

The request is well-formed but cannot be carried out for this payment or this merchant account.

Media typeapplication/json
UnprocessableRequestError

The request is well-formed but cannot be carried out for this payment or this merchant account.

object
error
required
object
type
required
string
Allowed value: invalid_request
code
required

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

string
Allowed values: merchant_account_not_ready merchant_profile_incomplete payment_description_required merchant_account_provider_mismatch credential_storage_unavailable provider_not_eligible no_eligible_provider currency_not_supported_by_provider currency_not_supported_for_fiscal_document fiscal_total_mismatch fiscal_line_total_invalid fiscal_line_legal_tip_invalid fiscal_document_kind_not_allowed fiscal_document_kind_unsupported fiscal_government_eligibility_required fiscal_government_eligibility_not_allowed
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "invalid_request",
    "code": "merchant_account_not_ready"
  }
}

429

Section titled “429”

Too many requests. Retry after the interval in the Retry-After header.

Media typeapplication/json
RateLimitError

Too many requests. Retry after the interval in the Retry-After header.

object
error
required
object
type
required
string
Allowed value: rate_limit_error
code
required

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

string
Allowed values: rate_limit_exceeded
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

500

Section titled “500”

The gateway failed before reaching a payment outcome. Retry with the same Idempotency-Key.

Media typeapplication/json
ApiError

The gateway failed before reaching a payment outcome. Retry with the same Idempotency-Key.

object
error
required
object
type
required
string
Allowed value: api_error
code
required

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

string
Allowed values: internal_error
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "api_error",
    "code": "internal_error"
  }
}

502

Section titled “502”

The payment provider rejected the request or could not be reached before anything was submitted. Safe to retry with the same Idempotency-Key.

Media typeapplication/json
ProviderError

The payment provider rejected the request or could not be reached before anything was submitted. Safe to retry with the same Idempotency-Key.

object
error
required
object
type
required
string
Allowed value: provider_error
code
required

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

string
Allowed values: provider_unavailable provider_rejected_request
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "provider_error",
    "code": "provider_unavailable"
  }
}