API mantida por Fintera

Anexos (Attachment)

Listar Anexos

GET /entities/:entity_id/attachments

Retorna uma lista (paginada) de todos os Anexos da Entity que usuários possui acesso. Para designar o número de registros por página, passar o parâmetro per_page no endpoint. Caso o parâmetro não seja passado, o default de 50 será utilizado. O limite superior é de 500 registros por página. Para navegar entre as diferentes páginas, basta usar o parâmetro page. Exemplo:

GET /entities/:entity_id/attachments?per_page=15&page=3

O endpoint acima irá retornar a terceira página da listagem de Anexos com 15 registros em cada.

Exemplo de Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Links: <http://financeiro.fintera.com.br/entities/1/attachments.json?page=1&per_page=50>;rel="first",
       <http://financeiro.fintera.com.br/entities/1/attachments.json?page=3&per_page=50>;rel="last",
       <http://financeiro.fintera.com.br/entities/1/attachments.json?page=3&per_page=50>;rel="next",
       <http://financeiro.fintera.com.br/entities/1/attachments.json?page=1&per_page=50>;rel="prev"
[
    {
        "attachment": {
            "id": 12,
            "entity_id": 1,
            "title": "",
            "attachment_file_name": "extratoPoup.ofx",
            "attachment_content_type": "application/octet-stream",
            "attachment_file_size": 5517,
            "created_at": "2011-11-10T15:52:59-02:00",
            "updated_at": "2011-11-10T15:52:59-02:00",
            "download_url": "https://financeiro.fintera.com.br/entities/1/attachments/12/download"
            "attachables": [],
            "links": [
                {
                    "rel": "self",
                    "href": "https://financeiro.fintera.com.br/entities/1/attachments/12",
                    "method": "get"
                },
                {
                    "rel": "download",
                    "href": "https://financeiro.fintera.com.br/entities/1/attachments/12/download"
                    "method": "get"
                }
            ]
        }
    }
]
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Links: <http://financeiro.fintera.com.br/entities/1/attachments.xml?page=1&per_page=50>;rel="first",
       <http://financeiro.fintera.com.br/entities/1/attachments.xml?page=3&per_page=50>;rel="last",
       <http://financeiro.fintera.com.br/entities/1/attachments.xml?page=3&per_page=50>;rel="next",
       <http://financeiro.fintera.com.br/entities/1/attachments.xml?page=1&per_page=50>;rel="prev"
<?xml version="1.0" encoding="UTF-8"?>
<attachments type="array">
  <attachment>
    <id type="integer">12</id>
    <entity_id type="integer">1</id>
    <title></title>
    <attachment-file-name>extratoPoup.ofx</attachment-file-name>
    <attachment-content-type>application/octet-stream</attachment-content-type>
    <attachment-file-size type="integer">5517</attachment-file-size>
    <created-at type="dateTime">2011-11-10T15:21:54-02:00</created-at>
    <updated-at type="dateTime">2011-11-10T15:21:54-02:00</updated-at>
    <download-url>https://financeiro.fintera.com.br/entities/1/attachments/12/download</expiring-url>
    <attachables type="array"/>
    <links type="array">
      <link>
        <rel>self</rel>
        <href>https://financeiro.fintera.com.br/entities/1/attachments/1</href>
        <method>get</method>
      </link>
      <link>
        <rel>download</rel>
        <href>https://financeiro.fintera.com.br/entities/1/attachments/12/download</href>
        <method>get</method>
      </link>
    </links>
  </attachment>
  <attachment>
</attachments>

Exibir modelo de novo Anexo

GET /entities/:entity_id/attachments/new

Retorna os atributos de um novo anexo, com os valores default. Use como modelo para criar novos anexos.

Exemplo de Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "attachment": {
        "title": null,
        "entity_id": 1,
        "attachment_file_name": null,
        "attachment_content_type": null,
        "attachment_file_size": null,
        "created_at": null,
        "updated_at": null
    }
}
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<attachment>
  <title nil="true"></title>
  <entity_id type="integer">1</id>
  <attachment-file-name nil="true"></attachment-file-name>
  <attachment-content-type nil="true"></attachment-content-type>
  <attachment-file-size nil="true"></attachment-file-size>
  <created-at nil="true"></created-at>
  <updated-at nil="true"></updated-at>
</attachment>

Exibir um Anexo

GET /entities/:entity_id/attachments/:id

Retorna 200 OK e os dados do anexo solicitado.

Exemplo de Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "attachment": {
        "id": 12,
        "entity_id": 1,
        "title": "",
        "attachment_file_name": "extratoPoup.ofx",
        "attachment_content_type": "application/octet-stream",
        "attachment_file_size": 5517,
        "created_at": "2011-11-10T15:52:59-02:00",
        "updated_at": "2011-11-10T15:52:59-02:00",
        "download_url": "https://financeiro.fintera.com.br/entities/1/attachments/12/download"
        "attachables": [],
        "links": [
            {
                "rel": "self",
                "href": "https://financeiro.fintera.com.br/entities/1/attachments/12",
                "method": "get"
            },
            {
                "rel": "download",
                "href": "https://financeiro.fintera.com.br/entities/1/attachments/12/download"
                "method": "get"
            }
        ]
    }
}
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Fri, 19 Aug 2011 15:29:58 GMT
<?xml version="1.0" encoding="UTF-8"?>
<attachment>
  <id type="integer">12</id>
  <entity_id type="integer">1</id>
  <title></title>
  <attachment-file-name>extratoPoup.ofx</attachment-file-name>
  <attachment-content-type>application/octet-stream</attachment-content-type>
  <attachment-file-size type="integer">5517</attachment-file-size>
  <created-at type="dateTime">2011-11-10T15:52:59-02:00</created-at>
  <updated-at type="dateTime">2011-11-10T15:52:59-02:00</updated-at>
  <download-url>https://financeiro.fintera.com.br/entities/1/attachments/12/download</expiring-url>
  <attachables type="array"/>
  <links type="array">
    <link>
      <rel>self</rel>
      <href>https://financeiro.fintera.com.br/entities/1/attachments/12</href>
      <method>get</method>
    </link>
    <link>
      <rel>download</rel>
      <href>https://financeiro.fintera.com.br/entities/1/attachments/12/download</href>
      <method>get</method>
    </link>
  </links>
</attachment>

Baixar um anexo

GET /entities/:entity_id/attachments/:id/download

Retorna um redirect (302 Moved Temporaroly) para a URL do arquivo enviado. Se seu cliente API segue redirects automaticamente, será redirecionado para o arquivo. Caso contrário, busque a URL real de download do arquivo no cabeçalho Location da resposta.

Os arquivos dos anexos são armazenados no Amazon S3 de maneira privada. Assim sendo, ao solicitar a visualização de um arquivo, nosso sistema gera uma URL com os devidos parâmetros de autorização para que apenas agentes autorizados possam visualizar o arquivo. Estes parâmetros têm uma expiração default de 1 hora. Assim sendo, recomendamos que você armazene em seus sitemas apenas a URL para download do arquivo no Financeiro (ou seja, algo como https://financeiro.fintera.com.br/entities/1/attachments/12/download) e use-a para consultar a URL autorizada do Amazon S3 quando for necessário baixar o arquivo.

Exemplo de Resposta

HTTP/1.1 302 Moved Temporarily
Location: https://s3.amazonaws.com/fintera_financeiro_uploads/attachments/12/extratoPoup.ofx?AWSAccessKeyId=AKIAICEZUAFW5S23SUGA&Expires=1340725938&Signature=e4BXtcvjF4hWu9cyf9mvzf0Jweg%3D
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache, private
Date: Tue, 26 Jun 2012 14:52:18 GMT
{"redirect_to": "https://s3.amazonaws.com/fintera_financeiro_uploads/attachments/12/extratoPoup.ofx?AWSAccessKeyId=AKIAICEZUAFW5S23SUGA&Expires=1340725938&Signature=e4BXtcvjF4hWu9cyf9mvzf0Jweg%3D"}
HTTP/1.1 302 Moved Temporarily
Location: https://s3.amazonaws.com/fintera_financeiro_uploads/attachments/12/extratoPoup.ofx?AWSAccessKeyId=AKIAICEZUAFW5S23SUGA&Expires=1340725938&Signature=e4BXtcvjF4hWu9cyf9mvzf0Jweg%3D
Content-Type: application/xml; charset=utf-8
Cache-Control: no-cache, private
Date: Tue, 26 Jun 2012 14:52:18 GMT
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <redirect-to>https://s3.amazonaws.com/fintera_financeiro_uploads/attachments/1/extrato_com_erro.qif?AWSAccessKeyId=AKIAICEZUAFW5S23SUGA&amp;Expires=1340727185&amp;Signature=86rsXHMPCFUCkNvSf7J3NbgXzRk%3D</redirect-to>
</hash>

Criar um Anexo

POST /entities/:entity_id/attachments

Para enviar arquvos será necessário usar o "Content-Type: multipart/form-data" e passar os arquivos corretamente. Segue um exemplo completo de requisição usando o curl.

Em caso de sucesso, retorna 201 Created mais o caminho para o objeto criado no header Location, além dos dados do objeto criado. Em caso de erro, retorna 422 Unprocessable Entity e as mensagens de erro informando porque o objeto não pôde ser criado. O formato da resposta será de acordo com o informado no Header "Accept".

Exemplo de Requisição

curl -i --request POST \
--header "Accept: application/json" \
--header "Content-type: multipart/form-data" \
--form "attachment[attachments][]=@./extratoPoup.ofx" \
--form "attachment[associated_financial_transaction_ids][]=1" \
--form "attachment[associated_financial_transaction_ids][]=2" \
--form "attachment[associated_financial_account_ids][]=1" \
--form "attachment[associated_financial_account_ids][]=2" \
--form "attachment[titles][]"="Meu arquivo" \
--basic --user "your-auth-token-here:x" \
https://financeiro.fintera.com.br/entities/1/attachments
curl -i --request POST \
--header "Accept: application/xml" \
--header "Content-type: multipart/form-data" \
--form "attachment[attachments][]=@./extratoPoup.ofx" \
--form "attachment[associated_financial_transaction_ids][]=1" \
--form "attachment[associated_financial_transaction_ids][]=2" \
--form "attachment[associated_financial_account_ids][]=1" \
--form "attachment[associated_financial_account_ids][]=2" \
--form "attachment[titles][]"="Meu arquivo" \
--basic --user "your-auth-token-here:x" \
https://financeiro.fintera.com.br/entities/1/attachments

Exemplo de Resposta

HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/entities/1/attachments/12
Content-Type: application/json; charset=utf-8
[
  {
    "attachment": {
        "id": 12,
        "entity_id": 1,
        "title": "",
        "attachment_file_name": "extratoPoup.ofx",
        "attachment_content_type": "application/octet-stream",
        "attachment_file_size": 5517,
        "created_at": "2011-11-10T15:52:59-02:00",
        "updated_at": "2011-11-10T15:52:59-02:00",
        "download_url": "https://financeiro.fintera.com.br/entities/1/attachments/12/download"
        "attachables": [],
        "links": [
            {
                "rel": "self",
                "href": "https://financeiro.fintera.com.br/entities/1/attachments/12",
                "method": "get"
            },
            {
                "rel": "download",
                "href": "https://financeiro.fintera.com.br/entities/1/attachments/12/download"
                "method": "get"
            }
        ]
    }
  }
]
HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/entities/1/attachments/12
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<attachments type="array">
  <attachment>
    <id type="integer">12</id>
    <entity_id type="integer">1</id>
    <title></title>
    <attachment-file-name>extratoPoup.ofx</attachment-file-name>
    <attachment-content-type>application/octet-stream</attachment-content-type>
    <attachment-file-size type="integer">5517</attachment-file-size>
    <created-at type="dateTime">2011-11-10T15:52:59-02:00</created-at>
    <updated-at type="dateTime">2011-11-10T15:52:59-02:00</updated-at>
    <download-url>https://financeiro.fintera.com.br/entities/1/attachments/12/download</expiring-url>
    <attachables type="array"/>
    <links type="array">
      <link>
        <rel>self</rel>
        <href>https://financeiro.fintera.com.br/entities/1/attachments/12</href>
        <method>get</method>
      </link>
      <link>
        <rel>download</rel>
        <href>https://financeiro.fintera.com.br/entities/1/attachments/12/download</href>
        <method>get</method>
      </link>
    </links>
  </attachment>
</attachments>

Alterar um Anexo

Requisição

PUT /entities/:entity_id/attachments/:id

Enviar os parâmetros para alteração do objeto como XML ou JSON (conforme o formato escolhido) no corpo da requisição HTTP.

Em caso de sucesso, retorna 200 OK e uma representação do objeto, como é mostrado no exemplo de resposta em "Exibir um Anexo". Em caso de erro, retorna 422 Unprocessable Entity e as mensagens de erro informando porque o objeto não pôde ser criado.

Exemplo de Requisição

"attachment": {
  "title": "Meu arquivo"
}
<?xml version="1.0" encoding="UTF-8"?>
  <attachment>
    <title>Meu arquivo</title>
  </attachment>

Apagar um Anexo

Exemplo de Requisição

DELETE /entities/:entity_id/attachments/:id

Retorna 200 OK.