Redeem a purchase code (validate identity)

POST

/certificate_request

curl --request POST \
  --url https://dev-api.tsp.cl/firma_digital/dev/api/partners/v1/certificate_request \
  --header 'Content-Type: application/json' \
  --header 'x-gw: <x-gw>' \
  --data '{ "pCode": "example", "referenceId": "example", "dni": "18925910-7", "email": "hello@example.com", "pin": "example", "serialNumber": "example", "names": "example", "fLastname": "example", "mLastname": "example", "phone": "+56911111111", "claveUnica": "example", "dniFront": "example", "dniBack": "example", "partnerCopy": "hello@example.com", "fechaVencimiento": "21/09/2034" }'

• Development
• Production

Validates the identity of the holder of a purchase code already issued (via POST /pcode on the partner-pcode Worker). It does not deliver the certificate in this call — that’s what certificate_claim is for — unless the partner is configured in B2B mode, in which case the certificate is generated and delivered automatically (webhook and/or email to the partner) in this same call, with no separate claim step for the end user.

Which fields are required depends on partner_config.require_cedula_serie, not on this call: a partner with the reduced flow (require_cedula_serie=1) must not send names/fLastname/phone (names come from the civil registry) but must send serialNumber; a partner with the full flow must send names/fLastname/phone and additionally validates against Clave Única.

Authorizations

• PartnerApiKey

Request Body^required

Media typeapplication/json

object

pCode

required

Purchase code previously generated for this partner.

string

referenceId

required

The partner’s own identifier for this transaction.

string

dni

required

Holder’s RUT (Chilean national ID), with check digit.

string

Example

18925910-7

email

required

string format: email

pin

required

4 digits — doubles as the resulting PFX’s password.

string

/^\d{4}$/

serialNumber

ID card serial number. Required if the partner has the reduced flow (require_cedula_serie=1).

string

names

Holder’s first name(s). Required only in the full flow.

string

fLastname

Paternal last name. Required only in the full flow.

string

mLastname

string

phone

Required only in the full flow.

string

Example

+56911111111

claveUnica

Clave Única token, if the partner’s flow requires it.

string

dniFront

string

dniBack

string

partnerCopy

Extra email address to CC the certificate to (full flow).

string format: email

fechaVencimiento

ID card expiration date as entered by the user, YYYY-MM-DD or DD-MM-YYYY/DD/MM/YYYY (day first). Compared against the real civil registry date if the partner has validate_vencimiento=1.

string

Example

21/09/2034

Responses

200

Identity validated. status indicates whether the certificate still needs to be claimed (VALIDATED, B2C flow) or was already issued and delivered (EMITTED, B2B flow).

Media typeapplication/json

object

success

boolean

data

object

p_code

string

referenceId

string

status

string

Allowed values: VALIDATED EMITTED

titular

object

rut

string

nombreCompleto

string

email

string format: email

certificate

Only present when status is EMITTED (B2B partner).

object

serialNumber

string

validFrom

string format: date-time

validTo

string format: date-time

pfxFileName

string

Example

{
  "success": true,
  "data": {
    "status": "VALIDATED",
    "titular": {
      "rut": "18925910-7",
      "nombreCompleto": "FABIAN JESUS AGUILAR ALISTE"
    }
  }
}

400

Missing required field or invalid format.

Media typeapplication/json

object

success

boolean

error

string

message

string

Example

{
  "success": false,
  "error": "VALIDATION_ERROR"
}

401

Invalid or missing API Key.

404

The purchase code does not exist.

406

Business rejection: required serial number missing, RUT does not match the purchase code, email already used by another holder, another purchase code has an ongoing validation, ID card does not match the civil registry, or expiration date does not match.

Media typeapplication/json

object

success

boolean

error

string

message

string

Example

{
  "success": false,
  "error": "VALIDATION_ERROR"
}

423

The purchase code is permanently blocked.

429

ID validation attempt limit reached (security lock), or the emission rate limit was exceeded (10 requests/minute per partner).