Clave numérica

La clave numérica identifica un comprobante electrónico de forma única ante Hacienda. Tiene 50 caracteres, va en el XML firmado y es lo que Hacienda usa para responder. En la API de Aster aparece como document_key y sirve para consultar el comprobante con GET /electronic-documents/{clave}.

Estructura

Posición	Largo	Campo	Valores
1–3	3	País	506 (Costa Rica)
4–5	2	Día de emisión	01–31
6–7	2	Mes de emisión	01–12
8–9	2	Año de emisión	Últimos dos dígitos del año
10–21	12	Identificación del emisor	Cédula rellenada con ceros a la izquierda
22–41	20	Número consecutivo	Ver consecutivo
42	1	Situación	1 normal, 2 contingencia, 3 sin internet
43–50	8	Código de seguridad	Número aleatorio

Ejemplo desglosado

La clave 50608102600310165432100100001010000001042147201936 corresponde a una Factura Electrónica de Ferretería La Sabana S.A. emitida el 8 de octubre de 2026:

Segmento	Valor	Significado
País	506	Costa Rica
Día	08	Día 8
Mes	10	Octubre
Año	26	2026
Emisor	003101654321	Cédula jurídica 3101654321 con dos ceros a la izquierda
Consecutivo	00100001010000001042	Sucursal 001, terminal 00001, tipo 01 (Factura Electrónica), número 0000001042
Situación	1	Normal
Código de seguridad	47201936	Aleatorio

Quién la genera

Aster la genera por vos. Si no enviás document.clave, Aster arma la clave con la fecha de emisión, la identificación del emisor, el consecutivo que asigna y un código de seguridad aleatorio, y la devuelve en document_key en la respuesta 201.

También podés enviarla ya generada, si tu sistema numera por su cuenta. En ese caso enviá document.clave y document.consecutive_number juntos; uno sin el otro responde 422 invalid_clave_consecutive.

{
  "document": {
    "document_type": "01",
    "date": "2026-10-08T10:20:00-06:00",
    "clave": "50608102600310165432100100001010000001042147201936",
    "consecutive_number": "00100001010000001042"
  }
}

Validaciones

Cuando enviás tu propia clave, Aster la revisa antes de firmar:

Regla	Error de Aster	Error de Hacienda que evita
Exactamente 50 caracteres	422 invalid_clave_format
El consecutivo tiene exactamente 20 dígitos	422 invalid_consecutive_format
La fecha de las posiciones 4–9 coincide con document.date en hora de Costa Rica	422 clave_date_mismatch	-405
En una Factura Electrónica de Compra (08), las posiciones 10–21 llevan la identificación del receptor, que es quien firma	422 fec_clave_id_mismatch	-60
La clave no se usó antes	409 duplicate_clave	-99
El consecutivo no se usó antes en ese ambiente	409 duplicate_consecutive

La clave admite letras mayúsculas en el segmento del emisor (posiciones 10–21). Desde 2026 el Registro Nacional asigna cédulas jurídicas alfanuméricas, como 3101A00001, que en la clave queda como 003101A00001. El resto de la clave es numérico.

Una clave no se reutiliza

Una clave identifica un único comprobante para siempre, aunque Hacienda lo haya rechazado. Para reemplazar un comprobante rechazado se emite uno nuevo, con clave y consecutivo nuevos. Ver consecutivo.