Documentação da API¶

Classes Principais¶

Toda a funcionalidade do Conector pode ser acessada através dessas duas classes.

Client¶

class rapconector.client.Client(base_url, email=None, password=None)¶

Cliente da API.

Parâmetros

base_url (str) – URL do conector.
email (str, optional) – E-mail para autenticação.
password (str, optional) – Senha para autenticação.

Retorna

Instância da classe.

Tipo de retorno

Client

with_document_id(document_id)¶

Retorna uma instância de Document com somente o campo document_id preenchido. Útil para evitar requisições adicionais. Por exemplo:

# 2 requisições: uma para get_document() e outra para get_receipt()
receipt = conector.get_document(372).get_receipt()

# 1 única requisição, pois `with_document_id` cria um objeto vazio
receipt = conector.with_document_id(372).get_receipt()

Parâmetros: document_id (int) – Identificador do documento.
Tipo de retorno: Document

get_group(group_id)¶

Exibe as informações básicas de um grupo de documentos, incluindo os slots ocupados e disponíveis para a inserção de novos documentos.

IMPORTANTE:: Novos documentos só devem ser inseridos em grupos parcialmente ocupados caso o documento seja do tipo do slot disponível e que contenha dados complementares aos demais documentos.

Parâmetros: group_id (str) – Identificador do grupo de documentos.
Retorna: O documento especificado, caso exista. None caso contrário.
Tipo de retorno: Document

list_groups(page=None, limit=None)¶

Lista todos os grupos de documentos, incluindo seus slots ocupados e disponíveis para a inserção de novos documentos.

IMPORTANTE:: Novos documentos só devem ser inseridos em grupos parcialmente ocupados caso o documento seja do tipo do slot disponível e que contenha dados complementares aos demais documentos.

Parâmetros

page (int, optional) – Número da página utilizada na paginação dos resultados.
limit (int, optional) – Quantos items retornar por página.

Retorna

Lista de grupos de documentos.

Tipo de retorno

list(DocumentGroup)

delete_group(group_id)¶

Deleta um grupo de documentos da base de dados do Conector, incluindo todos os documentos nele contidos.

IMPORTANTE:: Essa operação apaga apenas os documentos do registro local, de forma que não deleta os documentos preservados no registro do Serviço RAP. Para a remoção dos documentos do registro do RAP é necessário revogá-los antes deletar os dados no Conector.

Parâmetros: group_id (str) – Identificador do grupo de documentos a ser removido.
Retorna: Número de documentos removidos.
Tipo de retorno: int

get_document(id_or_security_code)¶

Exibe as informações básicas de um documento, incluindo o código de segurança que se torna disponível após o documento ser gerado e o recibo após o documento ser registrado.

Cada documento possui um código de segurança baseado no seu contexto. No caso do Diploma Digital esse código de segurança é o Código de Validação do Diploma.

Parâmetros: id_or_security_code (int or str) – Identificador ou código de segurança do documento.
Retorna: O documento especificado.
Tipo de retorno: Document

list_documents(state=None, document_type=None, page=None, limit=None)¶

Lista todos os documentos processados pelo RAP Conector, indicando para cada documento o seu estado atual.

Parâmetros

state (DocumentStateCode) – Código de estado para utilizar como filtro. O retorno incluirá todos os documentos que já passaram pelo estado especificado. Nesse contexto, currentState representa o estado corrente da consulta e não o estado atual do documento.
document_type (DocumentType) – Tipo de documento, para utilizar como filtro.
page (int, optional) – Número da página utilizada na paginação dos resultados.
limit (int, optional) – Quantos items retornar por página.

Retorna

Lista de documentos.

Tipo de retorno

list(Document)

insert_document(document_type, document_data, document_file=None)¶

Insere um novo documento ou um lote de documentos.

IMPORTANTE: As etapas de processamento dos documentos possuem uma ordem lógica bem definida que deve ser respeitada. Inicialmente deve ser gerada, assinada e registrada a Documentação Acadêmica. Após isso, deve ser gerado, assinado e registrado o Diploma Digital associado. Por último (opcionalmente) pode ser processada a Representação Visual do Diploma.

IMPORTANTE: Os arquivos PDF anexados em base64 no JSON da Documentação Acadêmica ou inseridos no campo document_file para a Representação Visual, devem estar preferencialmente no formato de preservação PDF/A (www.pdfa.org). Caso algum arquivo esteja no formato PDF comum, o Conector tentará a conversão automática que se for malsucedida, fará com que o documento entre no estado de erro de geração.

Parâmetros

document_type (DocumentType) – Código do tipo do documento.
document_data (str) – Dados e metadados do documento, em formato JSON. No caso da inserção em lote, o JSON esperado é um array onde cada item representa (e obedece o schema) da inserção de um único documento. Caso o lote seja do tipo DocumentType.VISUAL_REP_DEGREE, deve ser adicionado nos metadados de cada documento o atributo attachment contendo o nome e a extensão do arquivo utilizado no parâmetro document_file para que a representação visual do diploma seja associada ao documento correspondente.
document_file (tuple or list(tuple), optional) – Arquivo(s) do documento, onde um arquivo é uma tupla name (str), file (IOBase), mime_type (str).

Retorna

O identificador do documento inserido, ou uma lista de identificadores no caso da inserção em lote.

Tipo de retorno

int or list(int)

retrieve_file(document_type, client_id, your_number)¶

Recupera o arquivo de um documento diretamente do Serviço de Preservação usando os metadados do documento preservado.

Parâmetros

document_type (DocumentType) – Código do tipo do documento.
client_id (string) – Identificador da instituição cliente.
your_number (string) – Identificador do documento no contexto do cliente.

Retorna

Um objeto requests.Response, com a propriedade stream setada para True. Para exemplos de como realizar o download do arquivo de forma eficiente, ver https://stackoverflow.com/a/39217788 e https://2.python-requests.org/en/master/user/quickstart/#raw-response-content.

Tipo de retorno

requests.Response

authenticate_document(document_type, document_file)¶

Verifica a autenticidade de um documento no contexto do registro do Serviço RAP.

Parâmetros

document_type (DocumentType) – Código do tipo do documento.
document_file (tuple or list(tuple), optional) – Arquivo para verificar, onde um arquivo é uma tupla (name (str), file (IOBase), mime_type (str)).

Tipo de retorno

DocumentAuthenticityResult

healthcheck()¶

Retorna dados sobre a saúde do serviço. Por exemplo:

{
    "status": "pass",
    "version": "1",
    "releaseId": "0.7.8",
    "checks": {
        "conector": [
            {
                "status": "pass",
                "version": "0.7.8"
            }
        ],
        "RAP": [
            {
                "status": "pass",
                "version": "1.0.0"
            }
        ],
        "database": [
            {
                "status": "pass"
            }
        ]
    }
}

Retorna: Objeto JSON contendo informações sobre o estado do serviço.
Tipo de retorno: dict

Document¶

class rapconector.document.Document(client, json)¶

Representação de um documento no Conector.

document_id¶: Identificador do documento.

document_type¶: Tipo do documento. Possivelmente nulo. Ver DocumentType.

group_id¶: Identificador do grupo ao qual o documento pertence. Possivelmente nulo.

your_number¶: Identificador do documento no contexto do cliente. Possivelmente nulo.

current_state¶: Código de estado atual do documento. Possivelmente nulo. Ver DocumentStateCode.

security_code¶: Código de segurança do documento. Possivelmente nulo.

receipt¶: Recibo do documento. Possivelmente nulo.

update(document_type=None, document_data=None, document_file=None, update_description=None)¶

Atualiza o dados de um documento, quais sejam: tipo, JSON com dados e/ou arquivo gerado.

Após atualização, o documento retorna ao estado inicial reniciando sua geração/processamento. Documentos com estado de registro válido não são afetados por essa operação.

Nos casos em que um documento já está em estado válido de registro (estado 10) ou suspenso, é necessário revogar todo o seu respectivo grupo de documentos e reiniciar o processo de registro fazendo a inserção de novos documentos na ordem correta.

Parâmetros

document_type (int, optional) – Código do tipo do documento.
document_data (str, optional) – Metadados do documento (string JSON).
document_file (tuple or list(tuple), optional) – Arquivo(s) do documento, onde um arquivo é uma tupla (name (str), file (IOBase), mime_type (str))
update_description (str, optional) – Mensagem de atualização.

Retorna

O identificador do documento atualizado.

Tipo de retorno

int

delete(cascade=False)¶

Deleta este documento da base de dados do RAP Conector.

ATENÇÃO: Essa operação apaga os registros apenas no Conector local, de forma que não deleta documentos preservados no contexto do Serviço RAP. Para remoção do(s) documento(s) no contexto do RAP é necessário revogá-lo(s) antes de ter seus dados deletados do Conector local.

Parâmetros: cascade (bool, optional) – Se deve ocorrer remoção em cascata de documentos dependentes.
Retorna: Número de documentos removidos.
Tipo de retorno: int

get_state()¶

Exibe o estado atual do documento.

Em caso de erro, suspensão, re-ativação ou revogação de documento, o campo aditionalInfo indicará a razão de entrada em cada estado.

As informações de suspensão, ativação e revogação podem ser utilizadas para mapear o histórico do documento conforme previsão na nota técnica referente a diplomas digitais: ver item 7.12 da Nota Técnica No. 13/2019/DIFES/SESU/SESU.

Tipo de retorno: DocumentState

get_history()¶

Retorna o histórico de processamento do documento.

Tipo de retorno: list(DocumentStateChange)

get_receipt()¶

Retorna o recibo do documento. Por exemplo:

{
    "raw_signatures": [
        "string"
    ],
    "doc_type": "string",
    "status": "string",
    "dlt_id": "string",
    "group_id": "string",
    "client_id": "string",
    "mime_type": "string",
    "our_number": "string",
    "your_number": "string",
    "client_signature": "string",
    "data": {},
    "register_path": [],
    "created_at": "string",
    "updated_at": "string",
    "__v": int,
    "doc_hash": "string",
    "register_root": "string",
    "tx_date": "string",
    "tx_receipt": "string",
    "UUID": "string",
    "status_detail": "string",
}

Tipo de retorno: dict

download_file(version)¶

Faz download de uma versão específica do arquivo do documento em formato XML.

Caso seja indicado DocumentVersion.SIGNED, o serviço irá retornar o estado atual do documento assinado. Caso a coleta de assinaturas ainda não tenha sido finalizada, esse documento pode ainda não representar o documento final assinado. Recomenda-se seu download quando o documento alcançar o status registrado no serviço (estado DocumentStateCode.VALID).

A chamada desse método com parâmetro version contendo DocumentVersion.REGISTERED faz o Conector realizar o download do arquivo diretamente do Serviço de Preservação. Esse arquivo só existe após o registro do documento no Serviço (estado DocumentStateCode.VALID). O acesso ao arquivo do Serviço de Preservação pode ser útil nos casos em que a cópia local foi corrompida. Caso a instituição escolha não enviar os documentos para registro, a versão de registro do arquivo não existirá.

Parâmetros: version (DocumentVersion) – Versão desejada do documento.
Retorna: Um objeto requests.Response, com a propriedade stream setada para True. Para exemplos de como realizar o download do arquivo de forma eficiente, ver https://stackoverflow.com/a/39217788 e https://2.python-requests.org/en/master/user/quickstart/#raw-response-content.
Tipo de retorno: requests.Response

suspend(reason)¶

Suspende o documento.

Parâmetros: reason (str) – Motivo da suspensão do documento.
Retorna: Se o documento foi suspenso.
Tipo de retorno: bool

activate(reason)¶

Ativa o documento.

Parâmetros: reason (str) – Motivo da re-ativação do documento.
Retorna: Se o documento foi re-ativado.
Tipo de retorno: bool

revoke(reason)¶

Revoga um documento no contexto do Conector e no contexto do Serviço RAP.

Parâmetros: reason (str) – Motivo da revogação do documento.
Retorna: Se o documento foi marcado como “irá ser revogado”.
Tipo de retorno: bool

retry_processing(step=None)¶

Caso o documento esteja em um estado de falha, tenta reiniciar a etapa desejada do processamento.

Parâmetros: step (DocumentProcessingStep, optional) – Qual etapa para re-executar. Caso omitido, a etapa tentará ser inferida a partir do current_state do documento.
Retorna: True em caso de sucesso.
Tipo de retorno: bool

Tipos de retorno¶

As classes abaixo representam os tipos de objetos que são retornados pelo Conector.

DocumentAuthenticityResult¶

class rapconector.document.DocumentAuthenticityResult(json)¶

Resultado da autenticação de um documento.

Observação: o único campo que tem garantia de estar preenchido é o campo valid os outros campos podem ou não estar preenchidos, de acordo com a validade do documento.

dlt_id¶: Identificador da blockchain em que o documento está registrado.

tx_receipt¶: Código do recibo da transação de registro do documento na blockchain escolhida.

doc_hash¶: Hash do documento registrado na blockchain.

valid¶: Booleano que indica se o status do documento é válido no serviço RAP.

register_root¶: Raiz da estrutura de dados utilizada para registro do documento na blockchain.

client_id¶: Identificador da instituição no serviço RAP.

your_number¶: Identificador único do documento no serviço RAP.

register_date¶: Data e hora de registro do documento na blockchain (timestamp Unix).

confirmations¶: Número de confirmações da transação de registro do documento na blockchain.

revocation_date¶: Data e hora da revogação do documento na blockchain (timestamp Unix).

DocumentGroup¶

class rapconector.document.DocumentGroup(json)¶

Representação de um grupo de documentos.

group_id¶: String de identificação do grupo.

document_stubs¶: Documentos pertencentes ao grupo, representados por uma lista de dicionários contendo as chaves document_id e document_type.

DocumentSignature¶

class rapconector.document.DocumentSignature(json)¶

Representação de uma assinatura em um documento.

signer¶: Nome do assinante.

tag¶: Tag da assinatura.

state¶: Estado da assinatura. Ver DocumentSignatureState.

archiving_signature¶: Se a assinatura é uma assinatura de arquivamento.

substitute_signer¶: Nome do assinante substituto, caso exista.

substitute_signature_state¶: Estado da assinatura substituta, caso exista. Ver DocumentSignatureState.

DocumentState¶

class rapconector.document.DocumentState(current_state, description, additional_info, signatures)¶

Representação do estado atual do processamento de um documento.

current_state¶: Código de estado atual do documento. Ver DocumentStateCode.

description¶: Descrição textual do estado atual do documento.

additional_info¶: Informações adicionais sobre o estado atual do documento.

signatures¶: Assinaturas do documento. Ver DocumentSignature.

DocumentStateChange¶

class rapconector.document.DocumentStateChange(previous_state, current_state, description, timestamp, additional_info)¶

Representação do histórico de processamento de um documento.

previous_state¶: Código de estado anterior do documento. Ver DocumentStateCode.

current_state¶: Código de estado atual do documento. Ver DocumentStateCode.

timestamp¶: Timestamp (str) referente à mudança de estado do documento.

description¶: Descrição textual do estado do documento.

additional_info¶: Informações adicionais sobre o estado do documento.

Enumerações¶

Enums para facilitar o tratamento de strings e constantes númericas comumente utilizadas e retornadas pelo Conector.

DocumentProcessingStep¶

class rapconector.document.DocumentProcessingStep¶

Enumeração das possíveis etapas de processamento para re-executar.

PROCESSING = 'restart-processing'¶: Para re-executar o processamento de um documento.

GENERATION = 'retry-generation'¶: Para re-executar o processo de geração de um documento.

SIGNATURE = 'retry-signature'¶: Para re-executar o processo de assinatura de um documento.

REVOCATION = 'retry-revocation'¶: Para re-executar o processo de revogação de um documento.

REGISTRATION = 'retry-registration'¶: Para re-executar o processo de registro de um documento.

DocumentSignatureState¶

class rapconector.document.DocumentSignatureState¶

Enumeração dos possíveis estados de uma DocumentSignature.

NOT_SIGNED = 0¶: Não assinado.

PROCESSING = 1¶: Assinatura em processamento, no caso da assinatura principal.

SUBSTITUTE_PROCESSING = 1¶: Assinatura substituta concluída.

SIGNED = 2¶: Assinatura concluída.

DocumentStateCode¶

class rapconector.document.DocumentStateCode¶

Enumeração dos possíveis estados de um Document.

UNKNOWN = 0¶: Desconhecido

READY_TO_CREATE = 1¶: Pronto para gerar

CREATED = 2¶: Gerado

SIGNING_STARTING = 3¶: Iniciando assinatura

SIGNING_STARTED = 4¶: Assinatura iniciada

SIGNING_IN_PROGRESS = 5¶: Assinando documento

SIGNED = 6¶: Documento assinado

READY_FOR_REGISTRATION = 7¶: Pronto para registrar

REGISTRATION_STARTED = 8¶: Registro iniciado

REGISTRATION_FINISHED = 9¶: Processo finalizado

VALID = 10¶: Documento válido

SUSPENDED = 11¶: Documento suspenso

REVOCATION_STARTED = 12¶: Iniciando revogação

REVOCATION_IN_PROGRESS = 13¶: Revogando

REVOKED = 14¶: Documento revogado

ERROR_DURING_CREATION_PREPARATION = 500¶: Erro ao preparar a geração

ERROR_DURING_CREATION = 501¶: Erro na geração

ERROR_DURING_SIGNING_STARTING = 502¶: Erro ao iniciar a assinatura

ERROR_DURING_SIGNING = 503¶: Erro ao assinar o documento

ERROR_DURING_REGISTRATION = 504¶: Erro ao iniciar o registro

ERROR_FINISHING_REGISTRATION = 505¶: Erro ao finalizar o registro

ERROR_DURING_REVOCATION = 506¶: Erro na revogação

DocumentType¶

class rapconector.document.DocumentType¶

Enumeração dos possíveis tipos de um Document.

DIGITAL_DEGREE = 2¶: Diploma digital. Equivalente a digital_degree.

ACADEMIC_DOC_MEC_DEGREE = 4¶: Documentação acadêmica. Equivalente a academic_doc_mec_degree.

VISUAL_REP_DEGREE = 5¶: Representação visual. Equivalente a visual_rep_degree.

DocumentVersion¶

class rapconector.document.DocumentVersion¶

Enumeração das possíveis versões de um arquivo.

GENERATED = 'generatedDocument'¶: Versão gerada do documento.

SIGNED = 'signedDocument'¶: Versão assinada do documento.

REGISTERED = 'registeredDocument'¶: Versão registrada do documento.

Exceções¶

Exceções que podem ser levantadas pelos métodos das classes principais.

AuthenticationError¶

class rapconector.errors.AuthenticationError¶: Credenciais de autenticação incorretas fornecidas ao Conector.

NotFoundError¶

class rapconector.errors.NotFoundError¶: Objeto não encontrado no Conector.

ServerError¶

class rapconector.errors.ServerError¶: Erro inesperado no servidor do Conector.