POST /v1/invoices/inbound/{id}/status

POST

/v1/invoices/inbound/{id}/status

curl --request POST \
  --url https://api.asap.cool/v1/invoices/inbound/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/status \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "action": "approve", "reason": "example", "reason_code": "TX_TVA_ERR" }'

• Production

Authorizations

• api_key
  invoice:write
• session

Parameters

Path Parameters

id

required

string format: uuid

Inbound record identifier.

Request Body^required

Media typeapplication/json

Body of POST /v1/invoices/inbound/{id}/status.

object

action

required

The decision.

string

Allowed values: approve refuse dispute paid

reason

Motive, mandatory for refuse and dispute (at most 1000 characters); ignored for the other actions.

string | null

<= 1000 characters

reason_code

One of:

null

null

string

Coded motive (MDT-113), mandatory for refuse and dispute (the platform rejects those statuses without it); ignored for the other actions.

string

Allowed values: TX_TVA_ERR MONTANTTOTAL_ERR CALCUL_ERR NON_CONFORME DOUBLON DEST_INC DEST_ERR TRANSAC_INC EMMET_INC CONTRAT_TERM DOUBLE_FACT CMD_ERR ADR_ERR REF_CT_ABSENT

Responses

200

Decision recorded; its submission to the platform is queued.

Media typeapplication/json

Public projection of an [InboundRecord].

Light by design: the structured CII XML and the integrity digest are not surfaced; the readable PDF is referenced by its object-store key.

object

byte_size

Size in bytes of the stored object, when known.

integer | null format: int64

created_at

required

RFC3339 creation timestamp.

string

currency

Invoice currency code (BT-5), when parsed.

string | null

due_date

Payment due date as ISO YYYY-MM-DD (BT-9), when parsed.

string | null

id

required

Stable identifier.

string format: uuid

imported_at

RFC3339 import timestamp, when set.

string | null

invoice_number

Invoice number extracted from the CII (BT-1), when parsed.

string | null

issue_date

Issue date as ISO YYYY-MM-DD (BT-2), when parsed.

string | null

parse_status

required

CII parse outcome: 'parsed', 'parse_failed', 'pdf_only' (a PDF with no embedded CII) or 'pending'.

string

pdf_origin

required

Origin of the PDF the /pdf route serves.

string

Allowed values: received rendered none

pdf_storage_key

Object-store key of the readable PDF, when stored.

string | null

received_at

RFC3339 reception timestamp (as reported by the PA), when known.

string | null

received_lifecycle

required

What the org decided about the invoice.

string

Allowed values: received approved refused disputed paid

refusal_reason

Motive of a refusal or dispute.

string | null

refusal_reason_code

Coded motive (MDT-113, AFNOR XP Z12-012) of a refusal or dispute; absent on decisions taken before the code was required.

string | null

seller_name

Seller name extracted from the CII (BT-27), when parsed.

string | null

sender_siren

SIREN of the sender, when provided.

string | null

submission_error

Failure code when submission_state is error: not_connected, rejected or enqueue_failed.

string | null

submission_state

required

Whether the decision has reached the platform.

string

Allowed values: none pending sent error

submitted_at

RFC3339 time the platform accepted the decision.

string | null

total_ht

Total amount without VAT in cents (BT-109), when parsed.

integer | null format: int64

total_ttc

Grand total with VAT in cents (BT-112), when parsed.

integer | null format: int64

total_vat

Total VAT amount in cents (BT-110), when parsed.

integer | null format: int64

transmission_id

required

PA-assigned transmission id.

string

Example

{
  "pdf_origin": "received",
  "received_lifecycle": "received",
  "submission_state": "none"
}

401

No active org.

Media typeapplication/json

Generic error body returned by API handlers when they fail. code is a stable machine-readable token; message is human-friendly and meant for surfacing to end users.

object

code

required

Stable machine token (e.g. invalid_credentials).

string

field

Offending request field for validation errors, when known.

string | null

message

required

Human-readable message.

string

Example ^generated

{
  "code": "example",
  "field": "example",
  "message": "example"
}

403

Missing invoice:write scope.

Media typeapplication/json

Generic error body returned by API handlers when they fail. code is a stable machine-readable token; message is human-friendly and meant for surfacing to end users.

object

code

required

Stable machine token (e.g. invalid_credentials).

string

field

Offending request field for validation errors, when known.

string | null

message

required

Human-readable message.

string

Example ^generated

{
  "code": "example",
  "field": "example",
  "message": "example"
}

404

Not found or cross-org.

Media typeapplication/json

Generic error body returned by API handlers when they fail. code is a stable machine-readable token; message is human-friendly and meant for surfacing to end users.

object

code

required

Stable machine token (e.g. invalid_credentials).

string

field

Offending request field for validation errors, when known.

string | null

message

required

Human-readable message.

string

Example ^generated

{
  "code": "example",
  "field": "example",
  "message": "example"
}

409

The action does not follow from the invoice’s state, or the previous decision is still being sent.

Media typeapplication/json

Generic error body returned by API handlers when they fail. code is a stable machine-readable token; message is human-friendly and meant for surfacing to end users.

object

code

required

Stable machine token (e.g. invalid_credentials).

string

field

Offending request field for validation errors, when known.

string | null

message

required

Human-readable message.

string

Example ^generated

{
  "code": "example",
  "field": "example",
  "message": "example"
}

422

Missing or oversized reason, or missing reason code.

Media typeapplication/json

Generic error body returned by API handlers when they fail. code is a stable machine-readable token; message is human-friendly and meant for surfacing to end users.

object

code

required

Stable machine token (e.g. invalid_credentials).

string

field

Offending request field for validation errors, when known.

string | null

message

required

Human-readable message.

string

Example ^generated

{
  "code": "example",
  "field": "example",
  "message": "example"
}