Flujo que recorre toda la estructura de la API de Certillion, desde los pasos iniciales de la solicitud hasta la entrega de la respuesta.
Descripción completa, parámetros y códigos de retorno de todos los métodos API Certillion.
/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_challenge | Valor 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_id | Token que identifica la aplicación que quiere utilizar la API (Proporcionada por e-Sec) |
psc [opcional] | PSC que se utilizará. |
response_type | Valor 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 HTTP | Descripción | Acció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) { |
/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ámetro | Descripció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 HTTP | Código de error | Descripción | Acció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ón | Recibe el valor del access_token generado por la llamada del token 2.2. |
/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_id | Token que identifica la aplicación utilizando la API (Proporcionado por e-Sec) |
client_secret | Token secreto de aplicación (proporcionado por e-Sec) |
comentarios | Comentarios generales sobre el uso de la aplicación estando registrado |
correo electrónico | Correo electrónico de soporte en caso de indisponibilidad, cambio de versión, entre otros |
nombre | Nombre/descripción de la aplicación |
redirect_uris | Servidor 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}", |
/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_token | Token de acceso necesario para utilizar otros recursos del sistema |
expires_in | Validez del token devuelto |
token_type | Tipo de token, valor fijo ‘Portador’ |
vida útil | Indica la vida útil deseada para el elemento generado simbólico. Entero, en segundos. |
Códigos de error:
Código HTTP | Descripció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}" } |
/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ón | 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. |
Códigos de error:
HTTP Código | Descripción | Acció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. |
/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_hash | cadena codificada en Base64 de hash de documento |
archivo | Debe recibir como valor el documento o documentos que se enviarán a la API de Certillion para su firma. |
status | Estado de la operación, objeto que contiene los pares de código, nombre y detalle. |
Códigos de error:
Código HTTP | Descripción | Acció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
Aceptar | application/json |
Autorización | Recibe 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 |
/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ámetro | Descripción |
client_id | Token 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) |
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_cnpj | Número del CPF o CNPJ para buscar |
Códigos de error:
Código HTTP | Descripción | Acció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}", |
/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:
Paso | Descripción |
Llamada que recupera todos los PSC compatibles con API de Certillion |
/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ámetro | Descripció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. | |
otp | Código OTP para utilizar el certificado proporcionado por la aplicación Certillion |
alcance | «signature_session» |
nombre de usuario | CPF o CNPJ del destinatario |
Códigos de error:
HTTP Código | Descripción | Acció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}", |
/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ámetro | Descripción |
client_id | Token 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) |
lifetime | Tiempo 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 usuario | CPF o CNPJ del destinatario |
Rehaga la solicitud usando otro PSC.
Código HTTP | Descripción | Acció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_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
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}» } |
/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ámetro | Descripción |
alias_certificado [opcional] | Identificador del certificado correspondiente a la clave utilizada en la firma . |
separado | verdadero para separado o falso para adjunto |
hashes | Hashes 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_name | ICP_BR |
signature_policy | AD-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_method | SHA1, SHA512, SHA256 (predeterminado) |
pdf_options | Define 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ámetro | Descripción |
contact_info | Propiedad no visible en la firma. Información de contacto del firmante. |
ubicación | Propiedad 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ámetro | Descripció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_data | Imagen 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_name | Nombre 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ámetro | Descripción | |
add_key_val | true/false: para agregar un valor clave. | |
add_subject_name | true/false – Para agregar un asunto. | |
attribute_id_name | Nombre del atributo ID, por ejemplo id, Id o ID (mutuamente excluyentes con elements_id | |
elements_id | Lista 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ámetro | Descripción |
policy_id | ID de política utilizado en la firma |
firmas | Matriz que contiene los detalles de las firmas realizadas |
signer_certificate | Objeto que contiene detalles del certificado utilizado en las firmas |
signer_indentifier | CPF o CNPJ del suscriptor |
status | Objeto 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 HTTP | Có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”, |
/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ámetro | Descripción |
access_token | Acceso al token de acceso necesario para su uso otros recursos del sistema |
identificación_autorizada | |
tipo_identificación_autorizada | Debe contener «CPF» para una persona física o «CNPJ» para una entidad jurídica |
error | Representa 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_description | Descripción del error |
error_uri< /td> | URI de la documentación que describe el error |
expires_in | Validez del token devuelto |
alcance | Valores 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 HTTP | Error | Descripció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_REQUEST | El 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_ERROR | Se 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 contenido | application/x-www-form-urlencoded |
BODY< /span>
{ |
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, ''); |
/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ámetro | Descripción |
vida útil | Tiempo de vencimiento deseado para el token de acceso solicitado |
operación | |
operación | Operación que se pasará al servidor |
PSC | PSC en el que desea realizar la operación, actualmente admite los siguientes PSC: VAULTID y BIRDID |
alcance | Valores disponibles: single_signature, multi_signature, Signature_session |
user_id | CNPJ del solicitante |
user_secret | Solicitar contraseña |
Códigos de error
Código HTTP | Código de error | Descripción | Acció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 :
{ |
/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ámetro | Descripción |
client_id | Token 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) |
psc | PSC que desea buscar por CPF /CNPJ, los PSC admitidos son: VAULTID, BIRDID, REMOTEID, NEOID, SAFEID, VIDAAS |
user_cpf_cnpj | Debe 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_cnpj | Número CPF o CNPJ a buscar |
Códigos de error:
Acción sugerida
Código HTTP | Descripció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}", |
/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 HTTP | Código de error | Descripción | Acció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}", |
Códigos de error:
Nombre | Código | Descripción |
REQUEST_OK | 100 | Solicitud aceptada por el receptor . |
TRANSACTION_IN_PROGRESS | 110 | El mensaje ha sido recibido y aún se está procesando. |
REGISTRATION_VALID | 120 | Estás registrado en el sistema. |
CERTIFICATE_VALID | 130 | El certificado es válido. |
CSR_VALID | 131 | El CSR es válido. |
REVOCATION_ACCEPTED | 132 | El certificado se marca como revocado, luego se informará al usuario final. |
SIGNATURE_VALID | 140 | La firma es válida |
USER_ACTIVE | 150 | Cuenta de usuario lista para firma. |
DEVICE_READY | 151 | |
REQUEST_MISSING_PARAM | 200 | Falta un argumento en la solicitud: %S |
REQUEST_WRONG_PARAM | 201 | Error entre los argumentos de la solicitud. |
REQUEST_WRONG_LENGTH | 202 | El mensaje es demasiado grande o uno de sus argumentos tiene una longitud incorrecta. |
REQUEST_BAD_FORMAT | No se puede manejar el tipo MIME o estilo de codificación dado. | |
REQUEST_BAD_PROFILE | 204 | El AP solicitó un tipo de clave, uso de clave o firma política que los MSS hacenno es compatible. |
REQUEST_BAD_DATA | 205 | El equipo móvil del usuario final no puede manejar este tipo de datos. |
REQUEST_DUPLICADO | 206 | La solicitud o sus parámetros están duplicados. |
ACCOUNT_NO_BANDWIDTH td> | 210 | Ancho de banda insuficiente restante para realizar la transacción. |
ACCOUNT_MAX_TRIES | 211 | Se superó el número máximo de intentos. |
ACCOUNT_NO_CREDIT | 212 | El usuario debe pagar por el uso del certificado, pero se ha quedado sin crédito. |
ACCESS_NOT_AUTHORIZED | 220 | El AP es desconocido o la autenticación es incorrecta. |
ACCESS_NO_HANDSHAKE | 221 | El MSS quiere antes de negociar con el AP el uso de firmas XML en los mensajes. |
Nombre | Código | Descripción | ||
ACCESS_NO_SPECIFIED | 222 | No se especificó el mecanismo de autenticación. | ||
TRANSACTION_NOT_AUTHORIZED | 223 | La transacción no fue autorizada. El motivo específico se informa detalladamente. | ||
NETWORK_ERROR | 300 | El MSS no pudo contactar con el equipo móvil del usuario final. | ||
td> | ||||
Esta transacción es desconocida. | 310 | Esta transacción es desconocida.< /td> | ||
IDENTIFIER_NOT_FOUND | 311 | Este usuario final es desconocido. | ||
SERVICE_NOT_FOUND< /td> | 312 | |||
MOBILE_SIGNATURE_ERROR | 320 | Error durante el proceso de firma en el equipo Móvil. | ||
MOBILE_CERTIFICATE_ERROR | 321 | Error durante la generación del certificado en el móvil equipo. | ||
400 | El cliente ha cancelado la transacción. | |||
MESSAGE_BAD_INTEGRITY | 410 | 400 | td> | La verificación de integridad falló. |
MESSAGE_BAD_AUTHENTICATION | 411 | La autenticación falló. | ||
MESSAGE_BAD_ENCRYPTION | 412 | El descifrado del mensaje falló. | ||
MESSAGE_BAD_ENCODING | 413 | El mensaje no se pudo descodificar. | ||
MESSAGE_EXPIRED | 414 | El mensaje ha caducado. | ||
MESSAGE_WRONG_VERSION | 420 | La versión del mensaje no es apropiada para el receptor. | ||
MESSAGE_MISSING_KEY | 421 | El receptor esperaba una clave simétrica. | ||
MESSAGE_UNEXPECTED_KEY | 422 | El El receptor no esperaba una clave simétrica. | ||
MESSAGE_UNEXPECTED | 423 | Se supone que este mensaje no debe recibirse en este momento. | ||
KEY_EXPIRED | 424 | La clave de autenticación ha caducado. | ||
KEY_REJECTED | 425 | La nueva clave no es aceptable. | ||
MESSAGE_NOT_FOUND | 430 | Este mensaje no existe en el equipo móvil o ha sido eliminado. | ||
USER_NOT_FOUND | 431 | No hay usuario móvil con este ID. | ||
INTERNAL_ERROR | 440 | Error interno. | ||
SERVICE_CANT_ACTIVATE | 450 | Este servicio adicional no se puede activar para este móvil o esta empresa. | ||
SERVICE_CANT_USE | 451 | Este servicio adicional no está permitido o no es compatible. | ||
SERVICE_WAS_ACTIVATED | 452 | |||
PLATFORM_NOT_FOUND | 500 | |||
TOKEN_WRONG | 501 | El token es incorrecto. | ||
IDENTIFIER_INVALID | 502 | El identificador único no es válido. | ||
IDENTIFIER_DUPLICated | 503 | Identificador único ya registrado.< /td> | ||
CERTIFICATE_INVALID | 600 | El certificado no es válido, no hay más detalles. | ||
601 | La CSR no es válida, no hay más detalles. | |||
CRL_INVALID | 602 | La 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.
Nombre | Código | Descripción |
CERTIFICATE_MALFORMED | 603 | No se pudo construir un certificado X509. |
CERTIFICATE_REVOKED | 604 | |
CERTIFICATE_EXPIRED | 605 | El certificado está caducado. |
CERTIFICATE_NOT_IN_EFFECT | 606 | La fecha actual precede a la del campo NOT_BEFORE del certificado. |
CERTIFICATE_BLOCKED | 607 | El certificado está bloqueado o en uno de los estados de operación pendiente. |
CERTIFICATE_NOT_TRUSTED | 608 | El certificado fue emitido por una CA desconocida o que no es de confianza. |
KEY_SIZE_INVALID | 609 | El 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_FOUND | 620 | No se ha encontrado ningún certificado. |
CHAIN_NOT_FOUND | 621 | Cadena de confianza no encontrada. |
KEY_NOT_FOUND | 622 | No se ha encontrado la clave privada de este certificado. |
CARD_ERROR td> | 630 | La tarjeta inteligente encontró un error durante la operación. |
CARD_PIN_BLOCKED | 631 | |
CARD_BLOCKED | 632 | La tarjeta inteligente está bloqueada y nunca podrá ya no podrá utilizarse. |
CARD_NOT_PRESENT | 633 | La tarjeta inteligente no está conectada al equipo móvil. |
PIN_WRONG | 640 | El PIN es incorrecto. |
CERTIFICATE_CANT_REVOKE | 650 | Este certificado no se puede revocar. |
CERTIFICADO_DUPLICADO | 660 | Este certificado ya existe en la base de datos del servidor y no se puede duplicar. |
CERTIFICATE_WRONG_SUBJECT | 661 | El usuario no es el propietario del certificado.< /td |
KEY_MISMATCH | 662 | La clave pública en este certificado es diferente de la clave pública contenida en la CSR. |
SIGNATURE_INVALID | 700 | La firma no es válida. |
SIGNATURE_CANT_VALIDATE | Los parámetros de seguridad (certificado, políticas, TSA) están dañados o son incorrectos. | |
TEMPLATE_NOT_FOUND | 710 | La plantilla no existe. |
< td> 711
< td>XMLDSIG_ELEMENTS_WITHOUT_ATRIBUTE_ID
td>
Nombre | Código | Descripción |
DOCUMENT_NOT_FOUND | El documento no se puede encontrar en el almacenamiento interno. | |
WRONG_DOCUMENT_HASH | 712 | El documento descargado en la URL tiene otro hash. |
WRONG_DOCUMENT_TYPE | 713 | El tipo de documento no coincide con el estándar solicitado (XML o PDF) |
XMLDSIG_EMPTY_ELEMENT_LIST | 720 | Lista de elementos vacía en XMLDSig |
721 | Etiquetas de elemento sin ID de atributo en XMLDSig | |
XMLDSIG_SAME_ID_FOR_MULTIPLE_ELEMENTS | 722 | Mismo ID en múltiples elementos en XMLDSig |
XMLDSIG_NO_ELEMENT_FOUND | 723 | Sin etiqueta de elemento en XMLDSig |
CONTRACT_NOT_FOUND | 800 | No se pudo encontrar el contrato. |
801 | El usuario CPF ya existe en esta lista | |
MAX_ACCOUNTS_REACHED | 802 | El contrato alcanzó el número máximo de cuentas disponibles. |
ACCOUNT_NOT_REGISTERED | 803 | La cuenta no está registrada en el contrato de la empresa.< /td>< /tr> |