Correct a rejected fiscal document

POST

/fiscal_documents/{fiscalDocumentId}/corrections

const url = 'https://api.timbro.dev/v1/fiscal_documents/example/corrections';
const options = {
  method: 'POST',
  headers: {
    'idempotency-key': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"kind":"consumer","merchantInvoiceNumber":"example","merchantOrderNumber":"example","lines":[{"sourceLineId":"example","description":"example","quantity":"example","measurementUnit":"unit","unitPriceMinorUnits":1,"itemKind":"good","taxTreatment":"itbis_18","isLegalTipApplicable":true,"group":"example"}],"buyer":{"identityKind":"domestic","taxId":"example"},"governmentEligibility":{"entityKind":"central_government","authorityReference":"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.dev/v1/fiscal_documents/example/corrections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: example' \
  --data '{ "kind": "consumer", "merchantInvoiceNumber": "example", "merchantOrderNumber": "example", "lines": [ { "sourceLineId": "example", "description": "example", "quantity": "example", "measurementUnit": "unit", "unitPriceMinorUnits": 1, "itemKind": "good", "taxTreatment": "itbis_18", "isLegalTipApplicable": true, "group": "example" } ], "buyer": { "identityKind": "domestic", "taxId": "example" }, "governmentEligibility": { "entityKind": "central_government", "authorityReference": "example" } }'

Authorizations

merchantSecretKey

Parameters

Path Parameters

fiscalDocumentId

required

string

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

Rejected fiscal document to correct.

Header Parameters

idempotency-key

required

string

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

Request Body^required

Merchant-authored replacement revision for a rejected fiscal document.

application/json

FiscalDocumentCorrectionRequest

Merchant-authored replacement revision for a rejected fiscal document.

object

kind

required

string

Allowed values: consumer fiscal_credit government

merchantInvoiceNumber

required

string

>= 1 characters <= 20 characters

merchantOrderNumber

required

string

>= 1 characters <= 20 characters /^[0-9]+$/

lines

required

Array<object>

>= 1 items

FiscalLine

object

sourceLineId

required

string

>= 1 characters <= 128 characters

description

required

string

>= 1 characters <= 80 characters

quantity

required

string

/^(?=[0-9.]*[1-9])[0-9]{1,16}(\.[0-9]{1,2})?$/

measurementUnit

required

string

Allowed values: unit kilogram litre metre piece

unitPriceMinorUnits

required

integer

itemKind

required

string

Allowed values: good service

taxTreatment

required

string

Allowed values: itbis_18 itbis_16 zero_rated exempt non_billable

isLegalTipApplicable

required

Whether this line belongs to the merchant's mandatory legal-tip base. Non-billable lines cannot be eligible.

boolean

group

string

>= 1 characters <= 64 characters

buyer

Any of:

object
object

object

identityKind

required

string

Allowed value: domestic

taxId

required

string

>= 1 characters <= 64 characters

governmentEligibility

Any of:

object

entityKind

required

string

Allowed value: central_government

authorityReference

required

string

>= 1 characters <= 128 characters

Responses

200

Read-only fiscal document projection inline on Payment.

application/json

One of: discriminator: status

RequestedFiscalDocument

object

required

Fiscal document identifier.

string

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

object

required

string

Allowed value: fiscal_document

paymentId

required

Payment that requested the fiscal document.

string

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

kind

required

string

Allowed values: consumer fiscal_credit government

issuanceMode

required

Whether fiscal issuance is required before Checkout presents the purchase as complete or may finish after the paid receipt is shown.

string

Allowed values: required deferred

merchantInvoiceNumber

required

string

>= 1 characters <= 20 characters

merchantOrderNumber

required

string

>= 1 characters <= 20 characters /^[0-9]+$/

revision

required

integer

>= 1

buyer

FiscalBuyer

object

identityKind

required

string

Allowed values: domestic foreign

taxId

required

Any of:

string
null

string

/^\d{9}$|^\d{11}$/

foreignId

required

Any of:

string
null

string

>= 1 characters <= 20 characters /^[A-Za-z0-9][A-Za-z0-9._/-]{0,19}$/

legalName

required

string

>= 1 characters <= 256 characters

address

string

>= 1 characters <= 100 characters

contactName

string

>= 1 characters <= 80 characters

email

string format: email

<= 80 characters

governmentEligibility

Any of:

object

entityKind

required

string

Allowed value: central_government

authorityReference

required

string

>= 1 characters <= 128 characters

lines

required

Array<object>

>= 1 items

FiscalLine

object

sourceLineId

required

string

>= 1 characters <= 128 characters

description

required

string

>= 1 characters <= 80 characters

quantity

required

string

/^(?=[0-9.]*[1-9])[0-9]{1,16}(\.[0-9]{1,2})?$/

measurementUnit

required

string

Allowed values: unit kilogram litre metre piece

unitPriceMinorUnits

required

integer

itemKind

required

string

Allowed values: good service

taxTreatment

required

string

Allowed values: itbis_18 itbis_16 zero_rated exempt non_billable

isLegalTipApplicable

required

Whether this line belongs to the merchant's mandatory legal-tip base. Non-billable lines cannot be eligible.

boolean

group

string

>= 1 characters <= 64 characters

delivery

required

Any of:

FiscalDelivery
null

One of: discriminator: status

WaitingFiscalDelivery

object

email

required

string format: email

<= 320 characters

status

required

string

Allowed value: waiting_for_document

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

status

required

string

Allowed value: requested

Example

{
  "object": "fiscal_document",
  "kind": "consumer",
  "issuanceMode": "required",
  "buyer": {
    "identityKind": "domestic"
  },
  "governmentEligibility": {
    "entityKind": "central_government"
  },
  "lines": [
    {
      "measurementUnit": "unit",
      "itemKind": "good",
      "taxTreatment": "itbis_18"
    }
  ],
  "delivery": {
    "status": "waiting_for_document"
  },
  "status": "requested"
}

400

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

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

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

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

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

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

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

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

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

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

Default Response

application/json

Any of:

UnprocessableRequestError
TaxpayerUnprocessableError

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,}$/

TaxpayerUnprocessableError

The taxpayer cannot be used for this fiscal operation.

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: taxpayer_unregistered taxpayer_inactive

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

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

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

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

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

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

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

503

A required Gateway dependency is temporarily unavailable. The request is safe to retry.

application/json

TaxpayerDirectoryUnavailableError

A required Gateway dependency is temporarily unavailable. The request is safe to retry.

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: taxpayer_directory_unavailable

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": "taxpayer_directory_unavailable"
  }
}

Correct a rejected fiscal document

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

500

Example

502

Example

503

Example

Request Body^required