Introdução
==========

Instalação
----------

O cliente é distribuído como um pacote pip. Para instalar::

    $ python -m pip install rap-conector-client

Exemplos de uso
---------------

Uso básico do cliente
~~~~~~~~~~~~~~~~~~~~~

O ponto de partida para o uso da API é a classe
:class:`Client <rapconector.client.Client>`. A partir dela, é possível
receber instâncias da classe :class:`Document <rapconector.document.Document>`::

    >>> import rapconector
    >>> conector = rapconector.Client('{{ URL_DO_CONECTOR }}/api')
    >>> doc = conector.get_document(25)
    >>> doc.current_state
    503

A partir dessa instância, é possível interagir com o documento no Conector::

    >>> receipt = doc.get_receipt()
    >>> receipt['status']
    'preserved'
    >>> receipt['group_id']
    '350'

Caso deseje interagir com um documento sem precisar antes fazer uma requisição
para pegar o objeto do documento, é possível utilizar a função
:class:`with_document_id() <rapconector.client.Client.with_document_id>` da
classe principal::

    >>> conector.with_document_id(39).suspend('Suspendendo o documento com id 39.')
    True

Além disso, também são disponibilizadas algumas
:ref:`classes de enumeração <enumeracoes>` para melhorar a legibilidade do
código::

    >>> from rapconector.document import DocumentStateCode
    >>> doc.current_state == DocumentStateCode.ERROR_DURING_SIGNING
    True

Download e validação de um arquivo
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Por questões de performance, os métodos que interagem com arquivos do Conector
não fornecem suporte a parâmetros do tipo string. Sendo assim, é
necessário passar *file handles* abertos para os métodos que fazem upload, e os
métodos que fazem download de arquivos retornam um objeto
:class:`requests.Response` com a propriedade ``stream=True``, para que a
aplicação tenha controle total sobre o processo de download::

    >>> from rapconector.document import DocumentType, DocumentVersion
    >>>
    >>> res = conector.with_document_id(17).download_file(DocumentVersion.SIGNED)
    >>> with open('diploma.xml', 'wb') as f:
    >>>     for chunk in res.iter_content(chunk_size=4096):
    >>>         f.write(chunk)
    >>>
    >>> with open('diploma.xml', 'r') as f:
    >>>     authenticity = conector.authenticate_document(
    >>>         DocumentType.ACADEMIC_DOC_MEC_DEGREE,
    >>>             ('diploma.xml', f, 'application/xml'))
    >>>
    >>> authenticity.valid
    True