Endpoints de la API

Catálogo de rutas disponibles en la API pública de Acreditta, agrupadas por lo que necesitas lograr. Todas requieren el header Authorization: Bearer <idToken> que obtienes en Empezar con la API, salvo donde se indique lo contrario.

🔎 Fíjate en: esta tabla resume el propósito de cada ruta. Los parámetros exactos, el cuerpo de la petición y los códigos de respuesta completos están en Swagger: https://public-api.acreditta.com/swagger/#/.

Emitir credenciales

Ruta Método Uso
/credential/issue POST Emite una credencial individual.
/credential/batch/create POST Crea un lote de emisión.
/credential/batch/close/{batchId} PATCH Cierra un lote de emisión ya creado.

Emitir una credencial individual

POST /credential/issue recibe los siguientes campos en el cuerpo:

Campo Tipo Obligatorio Notas
credentialTemplateId string Sí ID de la plantilla de credencial a emitir.
firstName string Sí Nombre del acreditado.
lastName string No Apellido del acreditado.
email string (email) Sí Correo del acreditado — recibe la notificación si sendNotification es true.
phoneNumber string No Con código de país, ej. +573203133677.
identification string No Número de identificación del acreditado.
awardedAt string (fecha) Sí Fecha de otorgamiento de la credencial.
expiresAt string (fecha) No Fecha de expiración, si la credencial la tiene.
creditHours integer No Horas de crédito asociadas, si la plantilla las usa.
licenseNumber string No Número de licencia, si la plantilla lo requiere.
result string No Resultado o calificación obtenida.
programStartDate / programEndDate string (fecha) No Fechas de inicio y fin del programa cursado.
degreeCertificate string No Número o identificador del certificado/diploma.
book / sheet string No Libro y folio de registro, si tu institución los usa.
evidences array (máx. 5 elementos) No Evidencias del logro. Cada elemento admite name (obligatorio), description y url.
evidenceAnnexe object No Anexo adicional: annexe (contenido) y type (markdown o url).
issuingTags array de string No Etiquetas libres para clasificar la emisión.
sendNotification boolean No Si se le notifica por correo al acreditado apenas se emita.
overwriteRecord object No Sobrescribe, solo para esta emisión, el diseño (recordDesign), los textos (texts) o las imágenes (images) de la constancia.
updateCredential boolean No true para actualizar una credencial ya emitida en vez de crear una nueva. Por defecto false.
credentialUUID string No Obligatorio solo cuando updateCredential es true — identifica la credencial a actualizar.

Además, POST /credential/issue admite el parámetro de consulta batch_id (integer, opcional): si lo envías, la credencial se agrega al lote de emisión indicado en vez de emitirse suelta (ver Emitir credenciales en lote).

La respuesta incluye credentialId, transactionBlock, acceptanceLink y rejectionLink.

{
  "credentialTemplateId": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "user@example.com",
  "awardedAt": "2026-09-07",
  "evidences": [
    { "name": "string", "description": "string", "url": "string" }
  ],
  "sendNotification": true
}

🔎 Fíjate en: para actualizar una credencial ya emitida en vez de crear una nueva, envía updateCredential: true junto con credentialUUID.

Emitir credenciales en lote

Para emitir a muchos acreditados: crea el lote con POST /credential/batch/create (indicando credentialTemplateId), emite las credenciales individuales dentro de ese lote pasando el batch_id como parámetro de consulta en POST /credential/issue, y cuando termines, ciérralo con PATCH /credential/batch/close/{batchId}.

Consultar credenciales

Ruta Método Uso
/credential/list GET Lista credenciales de tu organización.
/credential/{credentialId} GET Consulta una credencial puntual.
/credential/record/{credentialId} GET Obtiene el registro/constancia de una credencial.
/report/credential/status GET Reporte de estatus de credenciales.

🔎 Fíjate en: /credential/record/{credentialId} es la única ruta de credenciales que no requiere un plan con API habilitada — se mantiene abierta para no romper integraciones antiguas de PDF/constancias. El resto sí exige el feature de API activo en tu plan (ver Planes y límites).

Gestionar credenciales

Ruta Método Uso
/credential/revoke/{credentialId} PATCH Revoca una credencial.

Plantillas y flujos

Ruta Método Uso
/template/list GET Lista las plantillas de tu organización.
/template/validate-user GET Valida si un correo tiene acceso a una plantilla (parámetros credentialTemplateId, email).
/flows GET Lista los flujos configurados en tu organización.
/get-organization GET Devuelve los metadatos de tu organización.

Códigos de respuesta que debes manejar

Código Cuándo aparece
200 La petición se procesó correctamente.
401 Token inválido, expirado, o el JWT no corresponde a un usuario de API (profile=developer). Revisa tu login.
402 Tu organización no tiene el plan que habilita el acceso a la API. Ver Planes y límites.
406 La petición no pasó la validación (por ejemplo, un campo requerido faltante o mal formado). Revisa el cuerpo contra el esquema en Swagger.

Siguiente paso


CONTENIDO

Powered By EazyDocs