Constancias

Emitir constancia NOM-151

POST /constancias

Emite una Constancia de Conservación NOM-151 a partir del hash SHA-256 de tu documento. Tu documento nunca sale de tu infraestructura. No es una restricción nuestra: la NOM-151-SCFI-2016 lo ordena. Apéndice Normativo A, numeral A.2.4 — «el Prestador de Servicios de Certificación únicamente recibirá la huella digital electrónica del mensaje de datos». Usa este endpoint si ya firmas por tu cuenta (e.firma del SAT, tu propio flujo) y solo necesitas la prueba legal del momento en que el documento existió. El hash va en hexadecimal minúsculas de 64 caracteres — exactamente lo que produce sha256sum archivo.pdf. Se aceptan mayúsculas y se normalizan; no se acepta base64 ni prefijos tipo sha256:. Idempotency-Key es obligatoria. Este endpoint cobra y llama a un PSC externo: sin la key, un timeout de red te deja sin forma segura de reintentar. Reintentar con la misma key devuelve la primera respuesta, nunca emite dos veces. externalId es tu propia referencia (el folio de tu expediente). Te sirve para recuperar la constancia después sin haber guardado nuestro id, y como segunda red contra el doble cobro. Reusar un externalId con el mismo hash devuelve la constancia ya emitida; reusarlo con otro hash devuelve 409 — la referencia ya está tomada por otro documento, y devolverte la constancia equivocada sería peor que fallar. Facturación y entornos. En live consume créditos y llama al PSC. Con una API key test o dev no cobra, no contacta al PSC y devuelve un artefacto sin validez legal, marcado con sandbox: true y livemode: false. Requiere contrato. El addon se activa por tenant tras firmar el contrato de prestación de servicio; sin él, live responde 403 CONTRACT_REQUIRED.

Parámetros

• Idempotency-Key string header requerido

  Clave única (UUID v4) que vuelve idempotente el POST: un reintento con la misma clave repite la respuesta original en lugar de volver a crear, cobrar o notificar.

• AllSign-Version enum header

  Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 UNSUPPORTED_API_VERSION.

  Valores: 2026-07-11

Cuerpo de la petición

application/json

• hashSha256 string requerido

  SHA-256 hex del documento.

  de 64 a 64 caracteres

• externalId string puede ser null

  máx. 255 caracteres

• label string puede ser null

  máx. 255 caracteres

Devuelve

201 Constancia emitida. El artefacto viene inline en base64 en constancia. — el objeto ConstanciaResponse

Errores posibles (problem+json): 400 401 402 403 409 422 429 503

Recuperar una constancia

GET /constancias/{constancia_id}

Devuelve una constancia que emitimos, con el artefacto inline en base64 — así que basta con haber guardado el id (o tu externalId) para recuperarla meses después. Archiva constancia, no downloadUrl. La URL de descarga es una conveniencia con caducidad (downloadUrlExpiresAt); si guardas el JSON con la URL y vuelves después, te queda un enlace muerto. El base64 es la fuente de verdad y no expira. Los campos sealedAt, serialNumber, policyOid y tsaName se extraen del interior del token, donde están cubiertos por la firma — no del JSON que envuelve la respuesta del PSC. sealedAt es el genTime del sello: el instante con valor legal. Con Accept: application/pkcs7-mime la misma ruta devuelve el DER crudo en vez del JSON, listo para pasárselo a openssl sin decodificar nada.

Parámetros

• constancia_id string ruta requerido
• AllSign-Version enum header

  Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 UNSUPPORTED_API_VERSION.

  Valores: 2026-07-11

Devuelve

200 La constancia, con el artefacto inline. — el objeto ConstanciaResponse

Errores posibles (problem+json): 400 401 403 404 422 429

Listar constancias

GET /constancias

Lista las constancias del tenant, más recientes primero, con paginación por cursor. El listado NO trae el artefacto. Devolver el base64 de hasta 100 constancias por página significaría descargarlas todas de nuestro almacenamiento en cada petición. Para el artefacto usa GET /v3/constancias/{constanciaId}, que trae uno. Sirve para conciliar: filtra por tu externalId para encontrar el expediente que buscas, o pagina el periodo completo para cuadrar lo emitido contra lo cobrado. Paginación: manda startingAfter con el nextCursor de la respuesta anterior. hasMore te dice si vale la pena pedir otra página. El listado está acotado al entorno de tu API key: una key test no ve las constancias live del tenant, ni al revés.

Parámetros

• limit integer query

  default 20 · entre 1 y 100

• startingAfter string query
• externalId string query
• AllSign-Version enum header

  Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 UNSUPPORTED_API_VERSION.

  Valores: 2026-07-11

Devuelve

200 Página de constancias (sin el artefacto — ver la nota arriba).

Ver los 5 atributos de la respuesta

• object string, siempre "list"

  Siempre "list".

• data array de objetos requerido
  Ver 14 atributos hijos

  • data[].livemode boolean requerido

    true en entorno live, false en test/dev (marca de agua, sin validez legal).

  • data[].object string, siempre "constancia"

    Siempre "constancia".

  • data[].id string requerido
  • data[].hashSha256 string requerido
  • data[].externalId string puede ser null
  • data[].label string puede ser null
  • data[].constanciaSha256 string puede ser null
  • data[].serialNumber string puede ser null
  • data[].sealedAt string (fecha-hora ISO 8601) puede ser null
  • data[].policyOid string puede ser null
  • data[].tsaName string puede ser null
  • data[].environment string requerido
  • data[].sandbox boolean requerido
  • data[].createdAt string (fecha-hora ISO 8601) requerido
• hasMore boolean requerido
• limit integer requerido
• nextCursor string puede ser null

Errores posibles (problem+json): 400 401 403 422 429

Verificar una constancia

POST /constancias/verify

Corre los cuatro checks criptográficos sobre una constancia y devuelve el resultado por criterio. | Check | Qué prueba | |---|---| | integrity | El hash sellado dentro del token es el de tu documento | | chainOfTrust | El certificado firmante encadena a la raíz de Secretaría de Economía | | cmsSignature | La firma CMS del token es válida (RFC 5652) | | certValidity | El certificado estaba vigente al momento del sellado | Los cuatro son necesarios y ninguno implica a otro: un imprint correcto no dice nada de quién firmó, y una firma válida de un emisor cualquiera no acredita nada. status es tri-estado, no un booleano (ETSI EN 319 102-1): - VALID — los cuatro checks pasaron. - INVALID — afirmación fuerte: el artefacto está mal (el documento no es el que se selló, o el emisor no es acreditado). - INDETERMINATE — no pudimos concluir. Token ilegible, o un check que no se pudo completar. No significa que la constancia sea falsa. Esa distinción importa: colapsar INDETERMINATE en INVALID te haría reportar «tu constancia es falsa» cuando el problema es de nuestro lado. > Esto es una conveniencia, no una autoridad. AllSign no es PSC acreditado, y preguntarle al emisor si su propio artefacto es válido no constituye prueba ante un tercero. Para eso está la verificación independiente: baja la raíz en /v3/constancias/certchain y verifica con openssl por tu cuenta. El valor de este endpoint es que valida el certificado del PSC contra la raíz correcta, que es el paso que se suele equivocar. Puedes mandar constancia (base64) + hashSha256, o solo constanciaId si la emitimos nosotros — en ese caso el hash sale de nuestro registro.

Parámetros

• AllSign-Version enum header

  Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 UNSUPPORTED_API_VERSION.

  Valores: 2026-07-11

Cuerpo de la petición

application/json

• hashSha256 string puede ser null

  de 64 a 64 caracteres

• constancia string puede ser null
• constanciaId string puede ser null

Devuelve

200 Resultado de la verificación. Revisa status y checks; un INDETERMINATE con errors te dice qué no se pudo comprobar.

Ver los 12 atributos de la respuesta

• status enum requerido

  Valores: VALID INDETERMINATE INVALID

• reason string requerido
• hashSha256 string puede ser null
• checks objeto puede ser null

  Resultado POR CRITERIO. Los cuatro checks son independientes. Se publican por separado a propósito: un INVALID sin desglose no le dice al cliente si el documento fue alterado (integridad) o si el emisor no está acreditado (cadena) — son problemas distintos con remedios distintos.

  Ver 4 atributos hijos

  • checks.integrity boolean requerido
  • checks.chainOfTrust boolean requerido
  • checks.cmsSignature boolean requerido
  • checks.certValidity boolean requerido
• sealedHash string puede ser null
• sealedAt string puede ser null
• serialNumber string puede ser null
• policyOid string puede ser null
• tsaName string puede ser null
• signerSubject string puede ser null
• signerIssuer string puede ser null
• errors array de string

Errores posibles (problem+json): 401 403 404 422 429

Raíz de confianza para verificar offline

GET /constancias/certchain

Devuelve en PEM el certificado raíz de la Autoridad Certificadora Raíz Segunda de Secretaría de Economía — el -CAfile que necesitas para verificar una constancia sin depender de AllSign. ⚠️ openssl ts -verify rechaza una constancia NOM-151 con la invocación normal. No es que la constancia esté mal: el certificado firmante no lleva el Extended Key Usage Time Stamping (solo Digital Signature, Non Repudiation), porque una constancia de conservación no es un sello de tiempo puro. Sin el flag correcto verás unsuitable certificate purpose y concluirás, equivocadamente, que la constancia es inválida. El flag es -purpose any. Y como SeguriData entrega un token CMS pelado (no un TimeStampResp), hace falta además -token_in. Si tu versión de openssl aun así se niega, openssl cms -verify -purpose any comprueba firma y cadena — pero no compara el message imprint, así que en ese camino tienes que extraer el TSTInfo y comparar el hash tú mismo. > Servimos esta raíz por conveniencia, no como autoridad: no somos PSC acreditado. La fuente autoritativa es la Secretaría de Economía; si tu proceso requiere rigor, bájala de ahí y compara. El archivo que servimos se valida contra su fingerprint SHA-256 antes de entregarse.

Parámetros

• AllSign-Version enum header

  Fecha del contrato contra la que quieres resolver la petición. Si la omites se sirve la versión vigente; una fecha desconocida responde 400 UNSUPPORTED_API_VERSION.

  Valores: 2026-07-11

Devuelve

200 El certificado raíz en PEM.

Errores posibles (problem+json): 401 403 422 429 503