API mantida por Fintera

Webhooks (Webhook)

O Financeiro possui um sistema de notificação via webhooks. Ele possibilita que você receba notificações em um endpoint especificado por você (uma URL do seu sistema).

Este endpoint precisa estar ativo e respondendo para o webhook com HTTP 200 Ok. O Financeiro fará no máximo 5 tentativas de notificação. Após a 5ª tentativa sem sucesso, o administrador da conta será notificado via e-mail e o endpoint deste webhook será marcado como "Com erro".

Lista de eventos:


Contas a pagar

  • payable_accounts.created
  • payable_accounts.updated
  • payable_accounts.destroyed
  • payable_accounts.paid
  • payable_accounts.payment_undone
  • payable_accounts.reconciled

Contas a receber

  • receivable_accounts.created
  • receivable_accounts.updated
  • receivable_accounts.destroyed
  • receivable_accounts.received
  • receivable_accounts.receivement_undone
  • receivable_accounts.reconciled

Contas bancárias

  • deposit_accounts.created
  • deposit_accounts.updated
  • deposit_accounts.destroyed
  • deposit_accounts.archived
  • deposit_accounts.unarchived

Lançamentos

  • financial_transactions.created
  • financial_transactions.updated
  • financial_transactions.destroyed
  • financial_transactions.reconciled

Extratos

  • bank_statements.created
  • bank_statements.imported
  • bank_statements.import_failed

Cartões de crédito

  • credit_cards.created
  • credit_cards.updated
  • credit_cards.destroyed
  • credit_cards.archived
  • credit_cards.unarchived

Lançamentos de Cartões de crédito

  • credit_card_transactions.created
  • credit_card_transactions.updated
  • credit_card_transactions.destroyed
  • credit_card_transactions.moved

Categorias

  • categories.created
  • categories.updated
  • categories.destroyed

Clientes / Fornecedores

  • people.created
  • people.updated
  • people.destroyed

Centro de custos / receitas

  • classification_centers.created
  • classification_centers.updated
  • classification_centers.destroyed

Anexos

  • attachments.created
  • attachments.updated
  • attachments.destroyed

Recebível

  • sales.created
  • sales.updated
  • sales.destroyed
  • sales.financial_transaction_associated
  • sales.financial_transaction_disassociated

Conta de Recebível

  • sale_accounts.created
  • sale_accounts.updated
  • sale_accounts.destroyed

Regra de Recebível

  • sale_rules.created
  • sale_rules.updated
  • sale_rules.destroyed

Permissão

Somente o administrador da conta pode usar os endpoints a seguir. Qualquer token que não seja do Administrador receberá um erro 403 Forbidden.

Headers de segurança:

Quando um evento é notificado, são utilizados 2 headers de segurança que permitem garantir a autenticidade de quem enviou a requisição e o conteúdo da mensagem.

O header X-Myfinance-RequestId é um identificador único e randômico da requisição. Com este identificador podemos garantir que um atacante não irá efetuar um replay attack, uma vez que esse identificador não poderá se repetir.

O header X-Myfinance-Signature é a assinatura da requisição composta por:

  • O segredo informado quando do cadastro da integração;
  • O identificador único da requisição (X-Myfinance-RequestId);
  • O corpo da requisição.

A assinatura é formada concatenando-se o conteúdo de X-Myfinance-RequestId + o corpo da requisição. Ao resultado disso deve ser aplicado um HMAC digest SHA1, conforme examplo abaixo:

SHA1(X-Myfinance-RequestId + request_body)


Exemplo de Requisição

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 30 Sep 2015 17:40:36 GMT
X-Myfinance-RequestId: d12c56319826262a371989930be7d0b2
X-Myfinance-Signature: b09209a810d67b382193680a0342896c2cb042a8
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <event>classification_centers.destroyed</event>
  <timestamp>2015-09-30T18:01:42Z</timestamp>
  <classification-center>
    <id type="integer">10</id>
    <_links>
      <rel>self</rel>
      <method>GET</method>
      <url>https://financeiro.fintera.com.br/classification_centers/10</url>
    </_links>
  </classification-center>
</hash>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 30 Sep 2015 17:40:36 GMT
X-Myfinance-RequestId: d12c56319826262a371989930be7d0b2
X-Myfinance-Signature: b09209a810d67b382193680a0342896c2cb042a8
{
  "event": "classification_centers.destroyed",
  "timestamp": "2015-09-30T17:40:36Z",
  "classification_center": {
    "id": 10,
    "_links": {
      "rel": "self",
      "method": "GET",
      "url": "https://financeiro.fintera.com.br/classification_centers/10"
    }
  }
}

Listar webhooks 

GET /integrations/webhooks

Retorna uma lista de todas os webhooks da Account.

Exemplo de Resposta

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT
<?xml version="1.0" encoding="UTF-8"?>
<webhooks type="array">
  <webhook>
    <account-id type="integer">2</account-id>
    <created-at type="dateTime">2015-09-21T15:41:05-03:00</created-at>
    <description>Webhook edit 2</description>
    <entity-id type="integer">3</entity-id>
    <healthy-check-code>200</healthy-check-code>
    <id type="integer">22</id>
    <updated-at type="dateTime">2015-09-21T16:08:48-03:00</updated-at>
    <url>http://requestb.in/yl4vfwyl</url>
  </webhook>
  <webhook>
    <account-id type="integer">2</account-id>
    <created-at type="dateTime">2015-09-21T16:15:22-03:00</created-at>
    <description>Webhook edit 1</description>
    <entity-id type="integer">3</entity-id>
    <healthy-check-code>200</healthy-check-code>
    <id type="integer">23</id>
    <updated-at type="dateTime">2015-09-21T16:15:35-03:00</updated-at>
    <url>http://requestb.in/o31a9qo3</url>
  </webhook>
</webhooks>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT
[
  {
    "webhook":
      {
        "account_id":2,
        "created_at":"2015-09-21T15:41:05-03:00",
        "description":"Webhook edit 2",
        "entity_id":3,
        "healthy_check_code":"200",
        "id":22,
        "updated_at":"2015-09-21T16:08:48-03:00",
        "url":"http://requestb.in/yl4vfwyl"
      }
  },
  {
    "webhook":
      {
        "account_id":2,
        "created_at":"2015-09-21T16:15:22-03:00",
        "description":"Webhook edit 1",
        "entity_id":3,
        "healthy_check_code":"200",
        "id":23,
        "updated_at":"2015-09-21T16:15:35-03:00",
        "url":"http://requestb.in/o31a9qo3"
      }
  }
]

Exibir um webhook

GET /integrations/webhooks/:id

Retorna os atributos do webhook especificado com uma resposta 200 Ok.

Exemplo de Resposta

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT
<?xml version="1.0" encoding="UTF-8"?>
<webhook>
  <account-id type="integer">2</account-id>
  <created-at type="dateTime">2015-09-21T15:41:05-03:00</created-at>
  <description>Webhook edit 2</description>
  <entity-id type="integer">3</entity-id>
  <healthy-check-code>200</healthy-check-code>
  <id type="integer">22</id>
  <updated-at type="dateTime">2015-09-21T16:08:48-03:00</updated-at>
  <url>http://requestb.in/yl4vfwyl</url>
</webhook>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:11:23 GMT
{
  "webhook":
    {
      "account_id":2,
      "created_at":"2015-09-21T15:41:05-03:00",
      "description":"Webhook edit 2",
      "entity_id":3,
      "healthy_check_code":"200",
      "id":22,
      "updated_at":"2015-09-21T16:08:48-03:00",
      "url":"http://requestb.in/yl4vfwyl"
    }
}

Criar um webhook

POST /integrations/webhooks

Cria um novo webhook com os parâmetros informados. Em caso de sucesso, retorna 201 Created, juntamente com a URI do webhook criado no cabeçalho Location da resposta HTTP. Em caso de falha, retorna 422 Unprocessable entity juntamente com a descrição dos erros.

Você pode configurar o webhook de forma que o corpo da requisição seja um json ou um xml, basta informar o campo format ao cadastrar um webhook.

Exemplo de Requisição

{
  "webhook": {
    "entity_id": 3,
    "description": "Webhook test",
    "url": "http://requestb.in/xssmudxs"
    "format": "json"
  }
}
<webhook>
  <entity-id>3</entity-id>
  <description>Webhook test</description>
  <url>http://requestb.in/xssmudxs<url>
  <format>xml</format>
</webhook>

Exemplo de Resposta

HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/integrations/webhooks/24
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT
{
  "webhook":
    {
      "account_id":2,
      "created_at":"2015-09-23T11:27:14-03:00",
      "description":null,
      "entity_id":3,
      "healthy_check_code":200,
      "id":24,
      "updated_at":"2015-09-23T11:27:14-03:00",
      "url":"http://requestb.in/xssmudxs"
      "format":"json"
    }
}
HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/integrations/webhooks/24
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT
<?xml version="1.0" encoding="UTF-8"?>
<webhook>
  <account-id type="integer">2</account-id>
  <created-at type="dateTime">2015-09-23T11:40:06-03:00</created-at>
  <description nil="true"/>
  <entity-id type="integer">3</entity-id>
  <healthy-check-code type="integer">200</healthy-check-code>
  <id type="integer">24</id>
  <updated-at type="dateTime">2015-09-23T11:40:06-03:00</updated-at>
  <url>http://requestb.in/xssmudxs</url>
  <format>xml</format>
</webhook>

Requisição de teste


Ao cadastrar um novo webhook, o Financeiro fará uma requisição do tipo POST de teste para garantir o funcionamento do endpoint informado. Esta requisição deve retornar 200 Ok, caso contrário, não será possível cadastrar webhook e a API retornará o seguinte erro: A URL não respondeu à requisição de teste.

Exemplo da requisição de teste enviada pelo Financeiro

HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/integrations/webhooks/24
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT
{
  "test": true
}
HTTP/1.1 201 Created
Location: https://financeiro.fintera.com.br/integrations/webhooks/24
Content-Type: application/xml; charset=utf-8
Date: Wed, 26 Jan 2011 13:27:00 GMT
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <test type="boolean">true</test>
</hash>

Alterar um webhook

PUT /integrations/webhooks/:id

Altera os dados do webhook especificado. Só pode alterar o campo description. Retorna uma resposta vazia com status 200 OK.

Em caso de erro, retorna os erros que impediram de alterar o webhook.

Exemplo de Requisição

{
  "webhook":
    {
      "account_id":2,
      "created_at":"2015-09-23T11:27:14-03:00",
      "description":"Descrição",
      "entity_id":3,
      "healthy_check_code":200,
      "id":24,
      "updated_at":"2015-09-23T11:27:14-03:00",
      "url":"http://requestb.in/xssmudxs"
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<webhook>
  <account-id type="integer">2</account-id>
  <created-at type="dateTime">2015-09-23T11:40:06-03:00</created-at>
  <description>Descrição</description>
  <entity-id type="integer">3</entity-id>
  <healthy-check-code type="integer">200</healthy-check-code>
  <id type="integer">24</id>
  <updated-at type="dateTime">2015-09-23T11:40:06-03:00</updated-at>
  <url>http://requestb.in/xssmudxs</url>
</webhook>

Valida o estado do webhook

PUT /integrations/webhooks/:id/verify_status

Retorna os dados do webhook depois de verififcado. Se necessário marcar como ativo, o retorno é com 200 OK.

Em caso de erro, retorna os erros que impediram de alterar o webhook.

Exemplo de Requisição

{
  "webhook":
    {
      "account_id":2,
      "created_at":"2015-09-23T11:27:14-03:00",
      "description":"Descrição",
      "entity_id":3,
      "healthy_check_code":200,
      "id":24,
      "updated_at":"2015-09-23T11:27:14-03:00",
      "url":"http://requestb.in/xssmudxs"
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<webhook>
  <account-id type="integer">2</account-id>
  <created-at type="dateTime">2015-09-23T11:40:06-03:00</created-at>
  <description>Descrição</description>
  <entity-id type="integer">3</entity-id>
  <healthy-check-code type="integer">200</healthy-check-code>
  <id type="integer">24</id>
  <updated-at type="dateTime">2015-09-23T11:40:06-03:00</updated-at>
  <url>http://requestb.in/xssmudxs</url>
</webhook>

Apagar um webhook

Exemplo de Requisição

DELETE /integrations/webhooks/:id

Apaga o webhook especificado. Retorna uma resposta vazia com status 200 OK.