Documentación

API en línea

Flujo que recorre toda la estructura de la API de Certillion, desde los pasos iniciales de la solicitud hasta la entrega de la respuesta.

Documentación

API en línea

Descripción completa, parámetros y códigos de retorno de todos los métodos API Certillion.

authorize

/css/restful/application/oauth/authorize

El primer paso a seguir es crear una solicitud de autorización que contenga los parámetros necesario para que el PSC identifique la aplicación del cliente. A continuación, es importante solicitar autorización al usuario, según el permiso de uso solicitado. Oauth2 Standard

Se realiza la solicitud de autorización, incluidos parámetros como tipo de respuesta, ID de aplicación, desafío de código, método de desafío, PSC, URI de redireccionamiento, alcance y otros opcionales. Si tiene éxito, la respuesta incluye un código de autorización.

Método: GET

PARAMETROS

code_challengeValor utilizado para proteger el otorgamiento del código de autorización, asegurando que quien inició la solicitud será quien intercambie el código de autorización por el token de acceso.
code_challenge_method

valor fijo “S256”

Valor correspondiente al método utilizado en la clave de prueba (code_verifier) para derivar el desafío (code_challenge) ).

manager_idToken que identifica la aplicación que quiere utilizar la API (Proporcionada por e-Sec)

psc

[opcional]

PSC que se utilizará.
response_typeValor fijo «código»

vida útil

[opcional]

Indica la vida útil deseada para el token que se generará. Entero, en segundos.

login_hint

[opcional]

Identificador de usuario

redirect_uri

[opcional]

Debe tener el URI para redirigir al usuario a la aplicación de origen .

estado

[opcional]

Código para identificar el estado de la solicitud.

alcance

[opcional]

Valores disponibles: single_signature, multi_signature, Signature_session

Códigos de error:

Código HTTPDescripciónAcción sugerida
404 (NOT_FOUND)Se devolvió cuando la API de Certillion no pudo comunicarse con el PSC.En primer lugar, es necesario rehacer el pedido; Además, es fundamental asegurarse de que las credenciales sean correctas.

En este método, usted Es necesario proporcionar un code_challenge. code_challenge es un hash SHA256 de code_verifier, codificado en URL Base64.En primer lugar, code_verifier se almacena en la aplicación para su uso posterior, mientras que code_challenge se envía junto con la solicitud de autorización. Para obtener más información, consulte PKCE RFC< /a> .

Por ejemplo, para la plataforma Java, esto La información se puede generar usando el siguiente código, o equivalente:

var crypto = require('crypto')
función base64URLEncode(str) {
return str.toString('base64') .reemplazar(/\+/g, '-') .replace(/\//g, ' _') .replace(/=/g, '');
} var verificador = base64URLEncode(crypto.randomBytes(32)); console.log("verificador: " + verificador); función sha256(búfer) { return crypto.createHash('sha256').update(buffer).digest(); < span style="font-weight: 400;">} var desafío = base64URLEncode(sha256(verificador) ); console.log("challenge: " + desafío);

descubrimiento-certificado

/css/restful/application/certificate -discovery

Recupera el certificado autorizado por el usuario para realizar una firma digital.

Método: GET

Los parámetros devueltos por la solicitud son:

ParámetroDescripción
Estado< /b>Objeto que contiene el código de estado de la solicitud , nombre y detalles
Certificados Matriz que contiene los certificados encontrados, contiene los campos número de serie, dn_sujeto, dn_emisor, not_before, not_after, alias, estado, certificado, certificado_emisor

Códigos de error:

Código HTTPCódigo de errorDescripciónAcción sugerida
401 (NO AUTORIZADO)

249 (TOKEN_VALIDITY_INVALID)

250 (INVALID_ACCESS_TOKEN)

209 (BAD_AUTHENTICATION)

 

Se devuelve cuando el campo Autorización pasado es incorrecto o ha caducado.Rehacer la solicitud asegurándose de que la Autorización sea correcta.
401 (NO AUTORIZADO)

218 (USERS_EXCEEDED_MAXIMUM_ALLOWED)

Se devuelve cuando se ha agotado el acceso contratado al PSC en cuestión.Comprueba el estado de tu cuenta con el PSC.
400 ( BAD_REQUEST)

205

(REQUEST_BAD_DATA)

Rehacer la solicitud después de revisarla, asegurándose de que cumple con lo esperado por el método.
404 ( NOT_FOUND)620 (CERTIFICATE_NOT_FOUND )

Devuelto cuando:

– No hay ningún certificado en la ranura PSC;

– El Alias proporcionado no coincide con ningún certificado en la ranura PSC.

Rehaga la solicitud proporcionando un alias correcto.
500 (INTERNAL_SERVER_ERROR)

224

(ERROR_DURING_AUTHENTICATION)

Se devuelve cuando hay un error inesperado al procesar la solicitud.

Rehacer el solicitud después de revisarla, asegurándose de que está de acuerdo con lo esperado por el método.

< p>Si el error persiste, comuníquese con Certillion soporte.

504 (GATEWAY_TIMEOUT)Se devuelve cuando hay un tiempo de espera en comunicación con el PSC. Puede deberse a alguna falta de disponibilidad o lentitud por parte del PSC.Espera unos minutos y rehace la solicitud.< /span>< /td>

ENCABEZADOS

AutorizaciónRecibe el valor del access_token generado por la llamada del token 2.2.

client_maintenance

/css/restful/application/oauth/client_maintenance

El método permite el mantenimiento de información de una aplicación. Los desarrolladores pueden registrar o actualizar datos esenciales, como nombres y direcciones de devolución de llamadas, utilizando tokens proporcionados por e-Sec. El servidor responde con códigos apropiados en casos de autorización incorrecta o solicitud mal formada. Esencial para la administración efectiva de aplicaciones en Certillion, el método facilita una integración segura y confiable.

Método: POST

Descripción del parámetro:

Parámetro Descripción
client_idToken que identifica la aplicación utilizando la API (Proporcionado por e-Sec)
client_secretToken secreto de aplicación (proporcionado por e-Sec)
comentariosComentarios generales sobre el uso de la aplicación estando registrado
correo electrónicoCorreo electrónico de soporte en caso de indisponibilidad, cambio de versión, entre otros
nombreNombre/descripción de la aplicación
redirect_urisServidor de aplicaciones Redirect_uris al que la API de Certillion debe llamar cuando la firma completo

Posibles errores devueltos por el servidor:

Códigos HTTP Descripción Acción sugerida
401 (NO AUTORIZADO)Se devuelve cuando el campo de autorización pasado es incorrecto o ha caducado.Es necesario rehacer el solicitud asegurándose de que la autorización sea correcta.
400 (BAD_REQUEST)Se devuelve cuando la solicitud JSON enviada tiene un formato incorrecto.Se requiere, primero, rehacer la solicitud después de revisarla, asegurándose de que, además, que su formato sea acorde a lo esperado por el método.
500 (INTERNAL_SERVER_ERROR)

Se devuelve cuando hay un error inesperado en el procesamiento de la solicitud.

Revisar la solicitud enviada asegurándose de que su estructura sea correcta. Si el error persiste, comuníquese con el soporte de Certillion.


HEADERS :

Autorización

{{token}}

Recibe el valor de access_token que puede haber sido generado por la llamada client_token 1.1 o la llamada token 2.2.

Contenido- Escriba

application/json

El contenido del cuerpo de la solicitud debe estar en formato JSON.


BODY:

{ 
 "client_id": "{CLIENT_ID}",
“client_secret”: "{CLIENT_SECRET}", “nombre”: "{NAME}", “comentarios”: "{COMMENTS} ", “redirect_uris”: [ “{REDIRECT_URIS} ] , "email": "{EMAIL}"
}

client_token

/css/restful/application/oauth/client_token

El método se utiliza para obtener un token de cliente, esencial para consultar a los usuarios y preparar las firmas que realizará el firmante. La respuesta a la solicitud incluye el token de acceso, necesario para utilizar otros recursos del sistema, junto con la validez del token (expires_in), el tipo de token (token_type – fijado en ‘Portador’) y una indicación de la vida útil deseada para el token generado (vida en segundos), permitiendo una interacción segura y autorizada con otros recursos del sistema.

Método: POST

La respuesta a la solicitud contiene los siguientes datos:

Parámetro

Descripción
access_tokenToken de acceso necesario para utilizar otros recursos del sistema
expires_inValidez del token devuelto
token_typeTipo de token, valor fijo ‘Portador’
vida útilIndica la vida útil deseada para el elemento generado simbólico. Entero, en segundos.

Códigos de error:

Código HTTPDescripción Acción sugerida
401 (NO AUTORIZADO)Se devuelve cuando las credenciales pasadas son incorrectas (client_id y/o client_secret)Rehacer la solicitud asegurándose de que las credenciales sean correctas.
500 (INTERNAL_SERVER_ERROR)Se devuelve cuando hay un error inesperado en el procesamiento de la solicitud.

Rehaga la solicitud después de revisarla, asegurándose de que su formato esté de acuerdo con lo esperado por el método.

Caso Si el error persiste, comuníquese con el soporte de Certillion.

ENCABEZADOS

Tipo de contenido

application/x-www-form-urlencoded

El cuerpo de la solicitud cuando se envía tiene el formato de una cadena de consulta separada por &.

CUERPO

{
“client_id”: "{CLIENT_ID}",
“client_secret”: "{CLIENT_SECRET}",
" Grant_type": "{GRANT_TYPE}",
 “lifetime”: "{LIFETIME}" 
}

documento (descargar)

/css/restful/application/oauth/document/{transaction}

Este método de la API de Certillion se utiliza para descargar la firma en formato adjunto. El id de transacción que se devolvió en la llamada debe ser informado en la llamada/ firma para descargar el archivo firmado.

Si la operación es exitosa, la solicitud devuelve un byte[].

Método: GET

ENCABEZADOS

AutorizaciónRecibe el valor de access_token que podría haber sido generado por la llamada 1.1 client_token o la llamada 2.2 token.

Códigos de error:

HTTP CódigoDescripciónAcción sugerida
401 (NO AUTORIZADO)Se devuelve cuando el campo Autorización pasado es incorrecto o caducado.Rehaga la solicitud asegurándose de que la autorización sea correcta.
404 (NOT_FOUND)

Devuelto cuando :

– No hay ninguna transacción asociada con el ID de transacción pasado;

 Transacción nno pertenece a la empresa que realizó la solicitud;

Rehaga la solicitud asegurándose de que la identificación de la transacción pasada sea válida y que está vinculado a una transacción en su empresa.
400 (BAD_REQUEST)

Devuelto cuando:

– No existe una firma válida para realizar la descarga;

– El patrón de firma utilizado en la transacción no acepta la descarga;

Rehaga la solicitud utilizando otra identificación de transacción.
Se devuelve cuando hay un error inesperado en el procesamiento de la solicitud.

Rehaga la solicitud después de revisarla, asegurándose de que esté de acuerdo con lo esperado por el método.

Si el error persiste, comuníquese con el soporte técnico de Certillion.

documento (cargar)

/css/restful/application/oauth/document

Este método le permite solicitar la firma de un lote de documentos a la API de Certillion, requiriendo primero la carga de todos los archivos que componen el lote . Al enviar archivos al servidor, la llamada devuelve el estado de la operación, incluyendo el código, nombre y detalles en el campo de estado, así como el hash del documento enviado.

Si se producen errores, como problemas al leer el archivo, el servidor devuelve los códigos HTTP correspondientes con descripciones específicas, sugiriendo acciones para corregir el errores identificados, como garantizar la exactitud de la autorización o revisar y reenviar la solicitud.

Método: POST

Parámetros devueltos por la solicitud:

Descripción

Parámetro
document_hashcadena codificada en Base64 de hash de documento
archivoDebe recibir como valor el documento o documentos que se enviarán a la API de Certillion para su firma.
statusEstado de la operación, objeto que contiene los pares de código, nombre y detalle.

Códigos de error:

Código HTTPDescripciónAcción sugerida
401 (NO AUTORIZADO)Devuelto cuando el campo Autorización pasado es incorrecto o ha caducado.Rehaga la solicitud asegurándose de que la autorización sea correcta.
400 (BAD_REQUEST)Se devuelve cuando hay un problema al leer el archivo enviado.Rehaga la solicitud asegurándose de que el archivo no esté dañado. 
500 (INTERNAL_SERVER_ERROR)Se devuelve cuando hay un error inesperado en el procesamiento de la solicitud. Posiblemente causado por no completar la autorización o por intentar cargar un archivo vacío.

Rehacer la solicitud después de revisarla garantiza que cumple con lo esperado por el método.

Si el error persiste, comuníquese con el soporte de Certillion.

ENCABEZADOS

Aceptarapplication/json
AutorizaciónRecibe el valor del access_token que puede haber sido generado por tanto la llamada client_token 1.1 como la llamada token 2.2.

Content-Type

multipart/form-data

Permite enviar grandes cantidades de datos binarios, útil para enviar grandes lotes de archivos

buscar cuentas-psc

/css/restful/application/oauth/find-psc-accounts

Método API de Certillion que encuentra cuentas PSC por identificador legal, puede ser un CPF o CNPJ.

Método: POST

Descripción de los parámetros presentes en el cuerpo de la solicitud:

ParámetroDescripción
client_idToken que identifica la aplicación que quiere utilizar la API (Proporcionada por e-Sec)
client_secretToken secreto de aplicación (Proporcionado por e-Sec)
user_cpf_cnpj

Debe completarse según la investigación, CPF para la investigación CPF y CNPJ para la investigación CNPJ

val_cpf_cnpjNúmero del CPF o CNPJ para buscar

Códigos de error:

Código HTTPDescripciónAcción sugerid
401 (NO AUTORIZADO)Se devuelve cuando el campo Autorización pasado es incorrecto o ha caducado.Rehaga la solicitud asegurándose de que la Autorización es correcto.
400 (BAD_REQUEST)Se devuelve cuando el campo val_cpf_cnpj no está completo.Rehaga la solicitud después de revisarla él, asegurando que cumple con lo esperado por el método.
500 ( INTERNAL_SERVER_ERROR)Se devuelve cuando hay un error inesperado en el procesamiento de la solicitud.

Rehaga la solicitud después de revisarla, asegurándose de que esté de acuerdo con lo esperado por el método.

Si el error persiste, comuníquese con el soporte de Certillion.

504 (GATEWAY_TIMEOUT)Se devuelve cuando hay un tiempo de espera en la comunicación con el PSC. Puede deberse a alguna falta de disponibilidad o lentitud por parte del PSC.Espera unos minutos y rehace la solicitud.

ENCABEZADOS

Recibe el valor access_token generado por la llamada 1.1 client_token .

BODY

{
  “client_id”: “{CLIENT_ID}”,
  “client_secret”: “ {CLIENT_SECRET}” ,
  “user_cpf_cnpj”: "{CPF}",
“val_cpf_cnpj": "{USERNAME}" }

psc-info

/css/restful/application/oauth/psc-info

Método API de Certillion que permite Consultar Proveedores de Servicios de Certificación (PSC) aceptados por Certillion. Los usuarios pueden obtener una lista completa de PSC que la aplicación reconoce y acepta para los procesos de autenticación y certificación digital, lo que garantiza que los usuarios puedan identificar y utilizar fácilmente los servicios de certificación digital compatibles con Certillion.

Método: GET

Descripción del parámetro:

PasoDescripción
Llamada que recupera todos los PSC compatibles con API de Certillion

otp_authorize

/css /restful /application/oauth/otp_authorize

Método API de Certillion para solicitar la generación de un token de acceso al sistema basado en el uso del certificado OTP proporcionado por Aplicación Certillion (disponible para MacOS, Windows, Linux, Androide iOS).

Método: POST

Descripción de los parámetros presentes en el cuerpo de la solicitud:

ParámetroDescripción
client_id Token que identifica la aplicación que quiere utilizar la API (Proporcionado por e-Sec)
client_secret Token secreto de aplicación (proporcionado por e-Sec)
Tiempo de vencimiento deseado para el token de acceso solicitado, en segundos.
otpCódigo OTP para utilizar el certificado proporcionado por la aplicación Certillion
alcance«signature_session»
nombre de usuarioCPF o CNPJ del destinatario

Códigos de error:

HTTP CódigoDescripciónAcción sugerida
401 (NO AUTORIZADO)

Devuelto cuando: >p>

– Las credenciales pasadas son incorrectas;

– No hay OTP para el usuario;

– La OTP pasada no es válida.

Vuelva a enviar la solicitud asegurándose de que la OTP y las credenciales de autorización sean correctas.
500 (INTERNAL_SERVER_ERROR)Se devuelve cuando hay una falla inesperada en procesando la solicitud.

Rehaga la solicitud después de revisarla y asegurarse de que esté de acuerdo con lo esperado por el método. .

Si el error persiste, comuníquese con el soporte técnico de Certillion.

ENCABEZADOS

Tipo de contenido

aplicación/json

El contenido del cuerpo de la solicitud debe estar en formato JSON.

CUERPO

{
  “client_id”: "{CLIENT_ID}",
“client_secret”: "{CLIENT_SECRET}", “nombre de usuario”: "{USERNAME}", “otp”: "{OTP}", “alcance”: "{SCOPE}" , “vida”: "{LIFETIME}"
}

pwd_authorize

/css/restful/application/oauth/pwd_authorize

Método de la API de Certillion que solicita la La generación de un token de acceso al sistema no es compatible con todos los PSC.

Método: POST

Descripción de los parámetros presentes en el cuerpo de la solicitud:

Valores disponibles: single_signature, multi_signature, Signature_session

Códigos de error:

ParámetroDescripción

client_id

Token que identifica la aplicación que quiere utilizar la API (Proporcionada por e-Sec)
client_secretToken secreto de aplicación (proporcionado por e-Sec)
lifetimeTiempo de vencimiento deseado para el token de acceso solicitado, en segundos
contraseña Código OTP del destinatario

psc_id[opcional]

Identificador del solicitante proporcionado por PSC.

psc_secret

[opcional]

Contraseña del solicitante para acceder a PSC

psc

[opcional]

Nombre del psc deseado por el solicitante
alcance
nombre de usuarioCPF o CNPJ del destinatario

Rehaga la solicitud usando otro PSC.

Código HTTPDescripciónAcción sugerida
400 (BAD_REQUEST)

Devuelto cuando:

– El PSC que desea utilizar está deshabilitado;

– El patrón de firma utilizado en la transacción no acepta la descarga;

Rehacer la solicitud usando otro id de transacción.
401 (NO AUTORIZADO)Se devuelve cuando las credenciales pasadas son incorrectas.Rehaga la solicitud asegurándose de que la autorización las credenciales (tanto de empresa como de usuario) son correctas.

500 (INTERNAL_SERVER_ERROR)

Se devuelve cuando hay un error inesperado en el procesamiento de la solicitud.

Rehaga la solicitud después de revisarla, asegurándose de que esté de acuerdo con lo esperado por el método.

Si el error persiste, comuníquese con el soporte de Certillion.

501 (NOT_IMPLEMENTED; )Se devuelve cuando el método pwd_authorize no es compatible con el PSC;
504 (GATEWAY_TIMEOUTSe devuelve cuando hay un tiempo de espera en la comunicación con el PSC. Puede deberse a alguna falta de disponibilidad o lentitud por parte del PSC.Espera unos minutos y rehace la solicitud.

ENCABEZADOS

aplicación /json

El contenido del cuerpo de la solicitud debe estar en formato JSON.

CUERPO

{
“client_id”: «{ CLIENT_ID}»,
“client_secret”: «{CLIENT_SECRET}»,
“nombre de usuario”: «{USERNAME}»,
“contraseña”: «{PASSWORD}»,
“alcance”: «{SCOPE} «,
“lifetime”:»{LIFETIME}»,
“psc»: «{PSC}»
}

firma

/css/restful/application/oauth/signature

Método API de Certillion utilizado para firmar un lote de documentos (uno o más). De esta forma, el usuario podrá firmar todos los documentos en un solo paso, aportando sus credenciales una sola vez. Es necesario subir los archivos a firmar con antelación. Este método es ideal para firmar documentos de gran tamaño en formatos PDF (simple y PAdES), XML, DOC, entre otros.

Método: POST

Descripción de los parámetros presentes en el cuerpo de la solicitud. Los valores en negrita son los predeterminados:

ParámetroDescripción

alias_certificado

[opcional]

Identificador del certificado correspondiente a la clave utilizada en la firma .
separadoverdadero para separado o falso para adjunto
hashesHashes de documentos cargados previamente al servidor Certillion, cada documento tiene una identificación, un alias, un hash calculado, un algoritmo hash [opcional] que define el tipo de generación de hash y, finalmente, opciones_estándar_firma [opcional] que define más opciones de firma (detalladas en el tabla siguiente)
pki_nameICP_BR
signature_policyAD-RB, AD-RT, AD-RV, AD-RC o AD-RA
PADES, PADES_ICP_BR, CADES o XADES

Nota: PADES Signature_standard no requiere Signature_policy.

Parámetros Signature_standard_options:

Parámetro
digest_methodSHA1, SHA512, SHA256 (predeterminado)
pdf_optionsDefine parámetros para la firma visible en PDF.
Define parámetros para la firma xml.

parámetros de pdf_options:

Propiedad no visible en la firma. Motivo de la firma.

ParámetroDescripción
contact_infoPropiedad no visible en la firma. Información de contacto del firmante.
ubicaciónPropiedad no visible en la firma. Especifica el nombre del servidor o la ubicación física donde se firmó el documento PDF.
nombre Propiedad no visible en la firma. Define el nombre de la persona o autoridad que firmó el documento PDF. Esta propiedad se obtiene del certificado.
reason

visible_signature_font_size

[obsoleto]

Tamaño de fuente del texto.

visible_signature_height

[obsoleto]

Altura del campo visible.
opciones_de_firma_visible Propiedades de firma visual de PDF.

visible_signature_page

[obsoleto]

Página PDF donde se encuentra el texto se insertará.

visible_signature_pos_x

[obsoleto]

Coordenada x (horizontal) para firma visible.

visible_signature_pos_y

[obsoleto]
Coordenada (vertical) para firma visible .

visible_signature_width

[obsoleto]
Ancho de campo visible.

visible_signature_zoom

[obsoleto]

Aumenta o disminuye proporcionalmente el tamaño de todos los elementos en el campo visible; 50 = 150%; -30 = 70%; 0 = 100%.

text_visible

[obsoleto]

Texto que se insertará en el PDF.

parámetros visible_signature_options:

ParámetroDescripción
weight: distance_x

Posición en el eje x desde el margen izquierdo

Predeterminado: 0

font-distance_y

Posición en el eje y desde abajo margen .

Predeterminado: 0

altura

Altura del campo de firma.

Predeterminado: 100

image_dataImagen de firma codificada en Base64. Si no se proporciona una imagen, la información pasada en los campos image_zoom e image_position no se tendrá en cuenta.
image_position

Posición de la imagen de la firma en la página del documento PDF. Valores posibles: IZQUIERDA, DERECHA, ARRIBA, ABAJO, FONDO

Predeterminado: IZQUIERDA

image_zoom

Aumenta o disminuye el tamaño de la imagen de la firma.

Predeterminado 1.0

número de página

Página donde se insertará la firma visual.

Predeterminado: 1

position_on_page

Posición de la firma en la página.

Valores posibles: TOP_LEFT, TOP_CENTER

ARRIBA_DERECHA, CENTRO_IZQUIERDA, MEDIO, CENTRO_DERECHA, ABAJO_IZQUIERDA, ABAJO_CENTRO, ABAJO_DERECHA.

Valor predeterminado: TOP_LEFT

signature_field_nameNombre del campo PDF donde se insertará la firma visible. Si se completa esta propiedad, se ignorarán todos los campos que aparecen encima en esta tabla.
text Texto de firma. Si esta propiedad no se completa, todas las demás propiedades de esta tabla no se tendrán en cuenta.
text_alignment

Alineación del texto de la firma.

Valores posibles: IZQUIERDA, DERECHA, CENTRO.

Predeterminado: IZQUIERDA

text_font

Fuente que se utilizará en el texto de la firma.

Valores posibles: HELVETICA, TIMES_ROMAN, COURIER.

Predeterminado: HELVETICA

text_font_size

Tamaño de fuente utilizado en el texto de la firma.< /p>

Predeterminado: 10

text_padding

Relleno de texto de firma.

Predeterminado: 0

visual_rotation

Ángulo de rotación de la firma. Valores posibles: NINGUNO, ROTATION_90 , ROTATION_180 , ROTATION_270

Predeterminado: NINGUNO

ancho

Ancho del campo de firma.

Predeterminado: 200

parámetros xml_options:

ParámetroDescripción

add_key_val

 true/false: para agregar un valor clave.
add_subject_nametrue/false – Para agregar un asunto.
attribute_id_nameNombre del atributo ID, por ejemplo id, Id o ID (mutuamente excluyentes con elements_id
elements_idLista de ID de elementos a firmar.
elements_name Lista de nombres de elementos que se van a firmar (usados junto con atributo_id_name)

multiple_signatures

true/false: indica si se debe aplicar una transformación adicional.
true/false: eliminar firma.

Parámetros devueltos por la solicitud:

ParámetroDescripción
policy_idID de política utilizado en la firma
firmasMatriz que contiene los detalles de las firmas realizadas
signer_certificateObjeto que contiene detalles del certificado utilizado en las firmas
signer_indentifierCPF o CNPJ del suscriptor
statusObjeto que contiene el código de estado devuelto por la solicitud, el nombre y los detalles< /td>

Códigos de error:

Se devuelve cuando hay un error inesperado en el procesamiento de la solicitud.

Código HTTPCódigo de error

Descripción 

Acción sugerida

401 (NO AUTORIZADO< /td>

249 (TOKEN_VALIDITY_INVALID)

250 (INVALID_ACCESS_TOKEN )

209 (BAD_AUTHENTICATION)

807 (INVALID_CREDENTIALS)

Se devuelve cuando el campo Autorización pasado es incorrecto o ha caducado.Rehacer la solicitud asegurándose de que la Autorización sea correcta.
401 (NO AUTORIZADO)218 (USERS_EXCEEDED_MAXIMUM_ALLOWED)Se devuelve cuando se han agotado los accesos contratados al PSC en cuestión.Comprueba el estado de tu cuenta con el PSC.
400 (BAD_REQUEST ) 620 (CERTIFICATE_NOT_FOUND)Se devuelve cuando no hay ningún certificado válido para usar en la firma.Rehaga la solicitud usando un PSC que tenga un certificado válido.
400 (BAD_REQUEST)711 (DOCUMENT_NOT_FOUND)Se devuelve cuando no se encuentra el documento. Posiblemente causado por el hecho de que el documento no se cargó anteriormente.Vuelva a cargar el documento y rehaga la solicitud de firma .
400 (BAD_REQUEST)713 (WRONG_DOCUMENT_TYPE)

Devuelto cuando el tipo de documento enviado no coincide con el patrón de firma solicitado

ej: documento tipo XML enviado a una firma PAdES que requiere PDF.

Rehaga la solicitud utilizando el tipo de documento apropiado para el patrón de firma solicitado.
400 (BAD_REQUEST)

600 (CERTIFICATE_INVALID )

Se devuelve cuando el certificado utilizado no es compatible con la política de firma o su cadena no es válida.

Vuelva a realizar la solicitud utilizando un certificado válido para la política solicitada.

nota : Las políticas ICP-Br solo aceptan certificados ICP-Br

400 (BAD_REQUEST) 702 (ERROR_ON_PREPARE_SIGNATURE)Se devuelve cuando hay un problema con el hash del documento.Rehaga la solicitud después de comprobar si el hash del documento que se pasa como parámetro es correcto
400 (BAD_REQUEST)200 (REQUEST_MISSING_PARAM)Se devuelve cuando algún parámetro obligatorio está vacío.Rehacer la solicitud completando los parámetros obligatorios.
500 (INTERNAL_SERVER_ERROR)

224

(ERROR_DURING_AUTHENTICATION)

Rehacer la solicitud después de revisarla, asegurándose de que esté de acuerdo con lo esperado por el método.

Si el error persiste, ingrese Contactar al soporte de Certillion.

504 (GATEWAY_TIMEOUT)301 (TIEMPO DE ESPERA) Devuelto cuando hay un tiempo de espera en la comunicación con el PSC. Puede deberse a alguna falta de disponibilidad o lentitud por parte del PSC.Espera unos minutos y rehace la solicitud.< /span>< /td>

Por último, cabe destacar que, además, para que el documento sea descargable se debe pasar el valor del campo transacción a la URL de la solicitud de descarga del documento.

HEADERS

CUERPO

Autorización

{{token}}

Recibir el valor access_token que podría haber sido generado por la llamada client_token 1.1 o la llamada token 2.2.

Tipo de contenido

aplicación/json

El contenido del cuerpo de la solicitud debe estar en formato JSON.

 {
  “signature_standard”: “SIGNATURE_STANDARD”,
“signature_policy”: “SIGNATURE_POLICY”, “pki_name”: “{PKI_NAME}”, “separado”: {DETACHED }, "hashes": [ { "id": "{ID} ", “alias”: "{ALIAS}",
"hash": "{DOCUMENTO_HASH}" } ] }

token

/css/restful/application/oauth/token

Segunda etapa de Oauth2 . Solicitud de una aplicación para obtener un token de acceso.

El código del paso 1 se intercambia por un token de acceso a través de una solicitud POST a la URL /oauth/token. La respuesta contiene el token de acceso, su tiempo de vencimiento, alcance, tipo de identificación autorizada y posibles mensajes de error asociados con los códigos HTTP, proporcionando así la base para una autenticación y autorización seguras en un sistema, con soporte opcional para diferentes alcances de operación.

Método: POST

Los parámetros devueltos por la llamada son los siguientes:

Valor correspondiente al CPF o CNPJ asociado al titular del certificado

ParámetroDescripción
access_tokenAcceso al token de acceso necesario para su uso otros recursos del sistema
identificación_autorizada
tipo_identificación_autorizadaDebe contener «CPF» para una persona física o «CNPJ» para una entidad jurídica
errorRepresenta el código de error. Valores posibles para el parámetro Código de error de estado HTTP: invalid_request,invalid_grant<. /span> ,cliente_inválido, unsupported_grant_type,server_error
error_descriptionDescripción del error

error_uri< /td>

URI de la documentación que describe el error
expires_inValidez del token devuelto
alcanceValores disponibles: single_signature(Signos solo 1 documento), multi_signature(Firma más de 1 documento), Signature_session(Crea una sesión de firma. Durante el período en que esté abierta la sesión, todas las firmas se realizarán sin requerir nueva autorización)

A continuación se muestra un ejemplo de una respuesta a una solicitud de token:

Códigos de error:

Código HTTPErrorDescripción Acción sugerida
400 (BAD_REQUEST )SERVER_ERROR

Devuelto cuando:

– El PSC ingresado no es válido;

– El PSC informado está deshabilitado.

Rehacer la solicitud luego de revisarlo, asegurando que está acorde con lo esperado por el método.
400 (BAD_REQUEST) INVALID_REQUESTEl parámetro O manager_secret no puede estar vacío.

Rehacer la solicitud completando correctamente el código o el parámetro manager_secret.

Si no tiene una URL de devolución de llamada registrada, comuníquese con el soporte de Certillion.

400 (BAD_REQUEST)INVALID_GRANT

Devuelto cuando:

– El parámetro de código es incorrecto;

– El parámetro manager_id no es válido;< /p>

– La empresa no tiene una URL de devolución de llamada previamente registrada;

Rehacer la solicitud correctamente completando el código o parámetro manager_secret.

En caso de no hacerlo tiene una URL de devolución de llamada registrada, comuníquese con el soporte de Certillion.

400 (BAD_REQUEST)INVALID_REQUEST

Devuelto cuando:

– El parámetro manager_id, code o code_verifier está vacío;

– El PSC no dispone de un certificado válido para utilizar en una firma;

Rehacer la solicitud completando el parámetro que falta.

En el caso de PSC no tiene un certificado válido, deberá comunicarse con el PSC para obtener un nuevo certificado.

500 (INTERNAL_SERVER_ERROR)SERVER_ERRORSe devuelve cuando hay un error inesperado en el procesamiento de la solicitud o cuando no se envía un parámetro obligatorio de la solicitud.

Rehaga la solicitud después de revisarla, asegurándose de que esté de acuerdo con lo esperado por el método.

Si el error persiste, comuníquese con el soporte de Certillion.

ENCABEZADOS

Tipo de contenidoapplication/x-www-form-urlencoded

BODY< /span>

{
“client_secret”: "{CLIENT_SECRET}", “client_id”: "{CLIENT_ID}", “code”: "{CODE}", “code_verifier”: "{CODE_VERIFIER}",
“grant_type": "{GRANT_TYPE}", “manager_id”: "{MANAGER_ID}", “manager_secret": "{MANAGER_SECRET} ", “psc”: "{PSC}"
}

En este método API de Certillion, es necesario proporcionar un code_verifier.

Por ejemplo, para la plataforma Java, esta información se puede generar usando el siguiente código o, alternativamente, un equivalente:

var crypto = require('crypto')
función base64URLEncode(str) {
   return str.toString('base64')
        .replace(/\+/g, '-')< br class="xliff-newline" />        .replace(/\//g, '_')
        .replace(/=/g, '');
} var verificador = base64URLEncode(crypto.randomBytes(32)); console.log("verificador: " + verificador); función sha256(buffer) { return crypto.createHash('sha256').update(buffer).digest( ); } var desafío = base64URLEncode(sha256(verificador)); console.log ("desafío: " + desafío);

comando-token

/css/restful/application/oauth/token-command

Método API de Certillion que le permite gestionar la tokenización (creación, consulta de estado y revocación).

Método: POST

Descripción de los parámetros pasados en el cuerpo de la solicitud:

ParámetroDescripción 
vida útilTiempo de vencimiento deseado para el token de acceso solicitado
operación
operaciónOperación que se pasará al servidor
PSCPSC en el que desea realizar la operación, actualmente admite los siguientes PSC: VAULTID y BIRDID
alcanceValores disponibles: single_signature, multi_signature, Signature_session
user_idCNPJ del solicitante
user_secretSolicitar contraseña

Códigos de error

Código HTTP

Código de error

DescripciónAcción sugerida
401 (NO AUTORIZADO)

250 (INVALID_ACCESS_TOKEN)

209 (BAD_AUTHENTICATION)

Devuelto cuando el El campo de autorización pasado es incorrecto o ha caducado.Rehaga la solicitud asegurándose de que la autorización sea correcta.
401 (NO AUTORIZADO)218 (USERS_EXCEEDED_MAXIMUM_ALLOWED)Se devuelve cuando se ha agotado el acceso contratado al PSC en cuestión.Compruebe el estado de su cuenta con el PSC.
400 (BAD_REQUEST)

205

(REQUEST_BAD_DATA)

Se devuelve cuando hay un problema al ejecutar el comando token.

Rehaga la solicitud después de revisarla, asegurándose de que esté de acuerdo con lo esperado por el método.

500 (INTERNAL_SERVER_ERROR)

224

(ERROR_DURING_AUTHENTICATION)

Se devuelve cuando hay un error inesperado en el procesamiento de la solicitud.

Rehaga la solicitud después de revisarla, asegurándose de que esté de acuerdo con lo esperado por el método.

Si el error persiste, comuníquese con el soporte técnico de Certillion.

HEADERS

Autorización

{{token}}

Recibe el valor del access_token que puede haber sido generado por cualquiera de los 1.1 llamada client_token o mediante la llamada 2.2 token.

Content-Type

application/json

El contenido del cuerpo de la solicitud debe estar en formato JSON.

CUERPO :

{
“user_id”: "{USER_ID}", “user_secret”: "{USER_SECRET}", “ vida”: "{LIFETIME} " , “alcance”: "{SCOPE}",
“operación": "{OPERATION}", “psc": "{PSC}" }

descubrimiento de usuario

/css/restful/application /oauth/user-discovery

Este método API de Certillion consulta el servicio API de Certillion para verificar la existencia de un certificado asociado a un CPF o CNPJ.

Método: POST

Descripción de los parámetros del cuerpo de la solicitud:

ParámetroDescripción
client_idToken que identifica la aplicación que quiere utilizar la API (Proporcionada por e-Sec)
client_secret Token secreto de aplicación (proporcionado por e-Sec)
pscPSC que desea buscar por CPF /CNPJ, los PSC admitidos son: VAULTID, BIRDID, REMOTEID, NEOID, SAFEID, VIDAAS
user_cpf_cnpjDebe completarse según la búsqueda, CPF para la búsqueda de Personas Físicas y CNPJ para la búsqueda de Personas Jurídicas
val_cpf_cnpjNúmero CPF o CNPJ a buscar

Códigos de error:

Acción sugerida

Código HTTPDescripción
401 (NO AUTORIZADO)Se devuelve cuando el campo de autorización pasado es incorrecto o ha caducado.Rehacer el solicitud asegurándose de que la autorización sea correcta.
400 (BAD_REQUEST)Se devuelve cuando el PSC está deshabilitado o cuando se utiliza un PSC no válido.Rehaga la solicitud utilizando un PSC válido.
500 (INTERNAL_SERVER_ERROR )Se devuelve cuando hay un error inesperado en el procesamiento de la solicitud. Posiblemente motivado por la falta de finalización de un parámetro obligatorio o su ausencia en la solicitud.

Rehacer la solicitud después de la revisión . asegurando quesu formato es el esperado por el método.

Si el error persiste, comuníquese con el soporte de Certillion.

HEADERS

Contenido -Tipo

aplicación/json

El contenido del cuerpo de la solicitud debe estar en formato JSON.

BODY

{ 
  “client_id”: "{CLIENT_ID}",
< span style="font-weight: 400;"> “client_secret”: "{CLIENT_SECRET}", “user_cpf_cnpj": "{CPF}", “val_cpf_cnpj": " {USERNAME}", “psc”: "{PSC}"
}

validar

/css/restful/application/signature/validate

Este método API de Certillion valida las firmas CAdES y PAdES realizadas por otro sistema (las firmas devueltas por Certillion son siempre válidas), incluyendo controles según las especificaciones de los estándares ICP-Brasil y PKIX. La validación es integral y cubre la cadena de certificación, las listas de revocación de certificados (LCR o CRL) y el protocolo de estado de certificados en línea (OCSP).

Para validar una firma PDF es necesario enviar el archivo PDF firmado en el campo «firma» (en base64) sin el necesidad de enviar contenido y document_hash. Alternativamente, el hash del archivo PDF que se guarda en el servidor se puede enviar en el mismo campo «firma».

Para firmas del tipo Si el archivo no es PDF deberá enviar el archivo en base64 en el campo «firma».

En el caso de firmas del tipo desprendidas, la firma debe estar en el campo «firma». En esta llamada, el archivo que se firmó puede estar en el campo de contenido (base64) o guardado en el servidor y su hash enviado en el campo «document_hash».

El encabezado debe contener el token de acceso generado por las llamadas de token 1.1 client_token o 2.2, y el cuerpo debe estar en formato JSON y contener los parámetros necesarios para la validación.

Método: POST

Código HTTPCódigo de errorDescripciónAcción sugerida
401 (NO AUTORIZADO)

250 (INVALID_ACCESS_TOKEN )

209 (BAD_AUTHENTICATION)

Se devuelve cuando el campo Autorización pasado es incorrecto o ha caducado.Rehaga la solicitud asegurándose de que La autorización es correcta.
401 (NO AUTORIZADO)218 (USERS_EXCEEDED_MAXIMUM_ALLOWED)Devuelve cuando el contratado accede al PSC en La pregunta se ha agotado.Comprueba el estado de tu cuenta con el PSC.
400 (BAD_REQUEST)

205

(REQUEST_BAD_DATA)

Devuelto cuando:

– La cadena de certificados está incompleta;

– El la cadena de certificados no es válida;

– Hay un error criptográfico en la firma;

– Hay un error en la codificación de la firma;

– El algoritmo utilizado para realizar la firma no es compatible con Certillion;

– El formato de archivo no es compatible;

– Error en la verificación de firma;

– Error al verificar la política de firma;

Revisar la firma enviada según el error devuelto.
400 (BAD_REQUEST)711 (DOCUMENT_NOT_FOUND)Devuelto cuando la API de Certillion no pudo localizar el documento original para validar la firma.Enviar la firma en formato adjunto.
500 (INTERNAL_SERVER_ERROR)

205

(REQUEST_BAD_DATA)

Devuelto cuando hay un error inesperado en el procesamiento de la solicitud.

Vuelva a realizar la solicitud después de revisarla y asegurarse de que cumple con lo esperado por el método. .

Si el error persiste, comuníquese con el soporte técnico de Certillion.

ENCABEZADOS

Autorización

{{token} }

< p>Recibe el valor de access_token que podría haber sido generado por la llamada 1.1 client_token o la llamada 2.2 token.

Tipo de contenido

application/json

El contenido del cuerpo de la solicitud debe estar en formato JSON.

CUERPO:

{
  “ firma”: "{SIGNATURE}",
  “contenido”: " {CONTENT}",
  “document_hash”: "{DOCUMENTO_HASH}",
“pki_name”: "{PKI_NAME}" }

Códigos de estado devueltos por llamadas de Certillion

Códigos de error:

NombreCódigoDescripción
REQUEST_OK100Solicitud aceptada por el receptor .
TRANSACTION_IN_PROGRESS110El mensaje ha sido recibido y aún se está procesando.
REGISTRATION_VALID120Estás registrado en el sistema.
CERTIFICATE_VALID130El certificado es válido.
CSR_VALID131El CSR es válido.
REVOCATION_ACCEPTED132El certificado se marca como revocado, luego se informará al usuario final.
SIGNATURE_VALID140La firma es válida
USER_ACTIVE

150

Cuenta de usuario lista para firma.
DEVICE_READY151
REQUEST_MISSING_PARAM200Falta un argumento en la solicitud: %S
REQUEST_WRONG_PARAM201Error entre los argumentos de la solicitud.
REQUEST_WRONG_LENGTH202El mensaje es demasiado grande o uno de sus argumentos tiene una longitud incorrecta.
REQUEST_BAD_FORMATNo se puede manejar el tipo MIME o estilo de codificación dado.
REQUEST_BAD_PROFILE204El AP solicitó un tipo de clave, uso de clave o firma política que los MSS hacenno es compatible.
REQUEST_BAD_DATA205El equipo móvil del usuario final no puede manejar este tipo de datos.
REQUEST_DUPLICADO206La solicitud o sus parámetros están duplicados.

ACCOUNT_NO_BANDWIDTH td>

210Ancho de banda insuficiente restante para realizar la transacción.
ACCOUNT_MAX_TRIES211Se superó el número máximo de intentos.
ACCOUNT_NO_CREDIT212El usuario debe pagar por el uso del certificado, pero se ha quedado sin crédito.
ACCESS_NOT_AUTHORIZED220El AP es desconocido o la autenticación es incorrecta.
ACCESS_NO_HANDSHAKE221El MSS quiere antes de negociar con el AP el uso de firmas XML en los mensajes.

 

NombreCódigoDescripción
ACCESS_NO_SPECIFIED222No se especificó el mecanismo de autenticación.
TRANSACTION_NOT_AUTHORIZED223La transacción no fue autorizada. El motivo específico se informa detalladamente.
NETWORK_ERROR300El MSS no pudo contactar con el equipo móvil del usuario final.
td>
Esta transacción es desconocida.310Esta transacción es desconocida.< /td>
IDENTIFIER_NOT_FOUND311Este usuario final es desconocido.

SERVICE_NOT_FOUND< /td>

312
MOBILE_SIGNATURE_ERROR320Error durante el proceso de firma en el equipo Móvil.
MOBILE_CERTIFICATE_ERROR321Error durante la generación del certificado en el móvil equipo.
400El cliente ha cancelado la transacción.
MESSAGE_BAD_INTEGRITY410400

td>

La verificación de integridad falló.
MESSAGE_BAD_AUTHENTICATION411La autenticación falló.
MESSAGE_BAD_ENCRYPTION412El descifrado del mensaje falló.
MESSAGE_BAD_ENCODING413El mensaje no se pudo descodificar.
MESSAGE_EXPIRED414El mensaje ha caducado.
MESSAGE_WRONG_VERSION420La versión del mensaje no es apropiada para el receptor.
MESSAGE_MISSING_KEY421El receptor esperaba una clave simétrica.
MESSAGE_UNEXPECTED_KEY422El El receptor no esperaba una clave simétrica.
MESSAGE_UNEXPECTED423Se supone que este mensaje no debe recibirse en este momento.
KEY_EXPIRED424La clave de autenticación ha caducado.
KEY_REJECTED425La nueva clave no es aceptable.
MESSAGE_NOT_FOUND430Este mensaje no existe en el equipo móvil o ha sido eliminado.
USER_NOT_FOUND431No hay usuario móvil con este ID.
INTERNAL_ERROR440Error interno.
SERVICE_CANT_ACTIVATE450Este servicio adicional no se puede activar para este móvil o esta empresa.
SERVICE_CANT_USE451Este servicio adicional no está permitido o no es compatible.
SERVICE_WAS_ACTIVATED452
PLATFORM_NOT_FOUND500
TOKEN_WRONG501El token es incorrecto.
IDENTIFIER_INVALID502El identificador único no es válido.
IDENTIFIER_DUPLICated503Identificador único ya registrado.< /td>
CERTIFICATE_INVALID600El certificado no es válido, no hay más detalles.
601La CSR no es válida, no hay más detalles.
CRL_INVALID602La CRL no es válida, no hay más detalles.

< /tr>

td>

< td>El certificado está revocado.

< td>El PIN de la tarjeta inteligente ha sido bloqueado.

< td>701

NombreCódigoDescripción
CERTIFICATE_MALFORMED603No se pudo construir un certificado X509.
CERTIFICATE_REVOKED604
CERTIFICATE_EXPIRED605El certificado está caducado.
CERTIFICATE_NOT_IN_EFFECT606La fecha actual precede a la del campo NOT_BEFORE del certificado.
CERTIFICATE_BLOCKED607El certificado está bloqueado o en uno de los estados de operación pendiente.
CERTIFICATE_NOT_TRUSTED608El certificado fue emitido por una CA desconocida o que no es de confianza.
KEY_SIZE_INVALID609El certificado utiliza un tamaño de clave que no es compatible.
CRL_UNAVAILABLE

610< /td>

La CRL no estaba disponible en el momento en que se intentó descargar.
CERTIFICATE_NOT_FOUND620No se ha encontrado ningún certificado.
CHAIN_NOT_FOUND621Cadena de confianza no encontrada.
KEY_NOT_FOUND622No se ha encontrado la clave privada de este certificado.

CARD_ERROR td>

630La tarjeta inteligente encontró un error durante la operación.
CARD_PIN_BLOCKED631
CARD_BLOCKED632La tarjeta inteligente está bloqueada y nunca podrá ya no podrá utilizarse.
CARD_NOT_PRESENT633La tarjeta inteligente no está conectada al equipo móvil.
PIN_WRONG640El PIN es incorrecto.
CERTIFICATE_CANT_REVOKE650Este certificado no se puede revocar.
CERTIFICADO_DUPLICADO660Este certificado ya existe en la base de datos del servidor y no se puede duplicar.
CERTIFICATE_WRONG_SUBJECT661El usuario no es el propietario del certificado.< /td
KEY_MISMATCH662La clave pública en este certificado es diferente de la clave pública contenida en la CSR.
SIGNATURE_INVALID700La firma no es válida.
SIGNATURE_CANT_VALIDATELos parámetros de seguridad (certificado, políticas, TSA) están dañados o son incorrectos.
TEMPLATE_NOT_FOUND710La plantilla no existe.

< td> 711

< td>XMLDSIG_ELEMENTS_WITHOUT_ATRIBUTE_ID

td>

< td>DUPLICATED_ACCOUNT

Nombre

CódigoDescripción
DOCUMENT_NOT_FOUNDEl documento no se puede encontrar en el almacenamiento interno.
WRONG_DOCUMENT_HASH712El documento descargado en la URL tiene otro hash.
WRONG_DOCUMENT_TYPE713El tipo de documento no coincide con el estándar solicitado (XML o PDF)
XMLDSIG_EMPTY_ELEMENT_LIST720Lista de elementos vacía en XMLDSig
721Etiquetas de elemento sin ID de atributo en XMLDSig
XMLDSIG_SAME_ID_FOR_MULTIPLE_ELEMENTS722Mismo ID en múltiples elementos en XMLDSig
XMLDSIG_NO_ELEMENT_FOUND723Sin etiqueta de elemento en XMLDSig
CONTRACT_NOT_FOUND800No se pudo encontrar el contrato.
801El usuario CPF ya existe en esta lista
MAX_ACCOUNTS_REACHED

802

El contrato alcanzó el número máximo de cuentas disponibles.
ACCOUNT_NOT_REGISTERED803La cuenta no está registrada en el contrato de la empresa.< /td>< /tr>

 

Shopping Basket