Contabilização

As rotas aqui descritas permitem gerir os lançamentos no módulo de contabilidade. Nota: para se poder usar rotas de contabilidade é necessário que esteja seleccionado um exercício fiscal como descrito no passo 2.4 da autenticação.

1. Consulta de lançamentos

A consulta de lançamentos, pode ser efetuada usando os parâmetros de filtragem e paginação da v0, que devolve uma coleção de lançamentos. Por omissão são devolvidas todas as relações incluindo não só as linhas de cada lançamento, mas também as outras relações, podendo-se definir qual a informação a incluir nos parâmetros.

Sendo a consulta de um lançamento específico efetuada de forma individual usando o identificador interno do lançamento:

Também é possível consultar apenas linhas de lançamento, usando os critérios de filtragem e paginação referidos:

Sendo também possível efetuar a consulta de uma linha de lançamento específica efetuada de forma individual usando o identificador interno da linha do lançamento:

2. Relação com outros recursos / rotas

2.1. Controlo de terceiros

Quando existe controlo de terceiros, ou seja, o "third_party_control_id" tem o valor "CLIENTE" ou "FORNECEDOR", o campo "third_party_entity_id" é o identificador interno de clientes ou fornecedores, que pode ser obtido através do NIF usando um dos pedidos seguintes:

GET /customers?filter[tax_registration_number]=999999990|<NIF do cliente>

ou

GET /suppliers?filter[tax_registration_number]=999999990|<NIF do fornecedor>

2.2. Moeda do lançamento

Por omissão, a moeda do lançamento, "currency", é o mesmo tipo de moeda usado no exercício fiscal, ou seja euros (EUR). No entanto, é possível definir que o lançamento é noutra moeda, usando o identificador interno de moeda no campo "currency", que pode ser obtido através do código ISO num pedido:

GET /currencies?filter[iso_code]=USD|<código ISO da moeda>

Quando se define uma moeda de lançamento distinta da do exercício deve ser definida a taxa de câmbio,"currency_conversion_rate", para converter os valores das linhas do lançamento em euros.

2.3. Rubricas

Nos exercícios fiscais que suportam rubricas, estas devem ser configuradas nas linhas do lançamento usando o seu identificador interno. A consulta dos identificadores internos das rubricas deve ser efectuada da seguinte forma:

2.4. Centros de custos

A consulta dos identificadores internos dos centros de custo deve ser efectuada da seguinte forma:

2.5. Fluxos de caixa

A consulta dos identificadores internos dos fluxos de caixa deve ser efectuada da seguinte forma:

3. Criação de lançamentos

Os lançamentos, semelhantes aos documentos comerciais, são constituídos por:

1. Um cabeçalho

2. Duas ou mais linhas

3.1. Criação do lançamento (cabeçalho)

De modo a criar um lançamento, deverá ser efetuado um pedido com informação do cabeçalho do mesmo. No momento de criação do lançamento é automaticamente adicionada uma linha, que se não for utilizada e estiver vazia quando o lançamento for finalizado, será automaticamente removida durante a finalização do lançamento. Para este efeito, deverá realizar o seguinte pedido:

curl -v -X POST \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '<payload JSON>' '<API_URL>/accounting_transaction'

No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth. O pedido de criação do lançamento deve ser feito de acordo com a seguinte especificação:

3.2. Criação de linha de lançamento

De modo a adicionar uma linha a um lançamento, deverá realizar o seguinte pedido:

curl -v -X POST \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '<payload JSON>' '<API_URL>/accounting_transaction_lines'

No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth. O pedido de criação de uma linha de lançamento deve ser feito de acordo com a seguinte especificação:

3.3. Criação de sugestão para documento comercial

Os documentos comerciais podem ter lançamentos de contabilidade associados através da funcionalidade de sugestão de lançamentos, disponível na rota /set_suggestions_for_document_on_fiscal_year. Para gerar uma sugestão de lançamento de um documento finalizado deve ser passada o parâmetro operation=create e para lançamentos anulados o parâmetro operation=destroy.

3.4. Duplicação de lançamento

Qualquer lançamento pode ser duplicado fazendo um pedido à rota /duplicate_transaction , que tem a seguinte especificação:

3.5. Criação de estorno

Se for necessário criar um estorno para um lançamento finalizado, é possível utilizar a API fazendo um pedido à rota /reverse_transaction que executa essa ação, tendo o pedido a seguinte especificação:

4. Alteração de lançamentos

4.1. Alteração do cabeçalho de um lançamento

Um determinado lançamento pode ser alterado da seguinte forma:

4.2. Alteração de uma linha de lançamento

Uma linha de lançamento pode ser alterada da seguinte forma:

4.3. Eliminar linha de lançamento

Uma linha de lançamento pode ser eliminada da seguinte forma:

4.4. Finalizar ou reabrir lançamento

Para finalizar ou reabrir um lançamento, deverá ser efetuado um pedido de alteração, sendo indicado o "status" de deleted ou draft, respectivamente.

5. Eliminação de lançamentos

Um lançamento só pode ser realmente eliminado se nunca tiver sido finalizado, ou seja, se ainda não tiver sido atribuída a entrada no diário, nem um número de documento: Se for necessário eliminar um lançamento que já estiver numerado poderá ser alterado com estado de eliminado, ou ser criado um estorno.

6. Lançamentos com analítica

As rotas aqui descritas permitem gerir a distribuição por centros de custos das linhas de lançamentos em exercícios com contabilidade analítica.

Para haver linhas de distribuição por centro de custos de uma linha de lançamento, é necessário que essa linha de lançamento esteja configurada com uma rubrica. Esta configuração aparece em duplicado no recurso "accounting_transaction_lines", podendo ser configurada ou consultada através do atributo "cost_dimension_id" ou da relação "cost_dimension". A distribuição do montante, a débito ou a crédito, de uma linha de lançamento associada a uma rubrica, é efetuada usando a rota /transaction_line_costs.

6.1. Consulta de linhas de centro de custos

A consulta de várias linhas, usando ou não filtros, pode ser efetuada com um pedido:

Sendo a consulta de uma linha de custos específica efetuada de forma individual usando o identificador interno da linha de custos associada a uma linha de lançamento:

6.2. Criação de linhas de custos

6.3. Alteração de linhas de custos

6.4. Eliminação de linhas de custos

7. Lançamentos com fluxos de caixa

As rotas aqui descritas permitem gerir a distribuição por fluxos nos lançamentos em exercícios que usam fluxos de caixa.

7.1. Consulta de linhas de fluxos de caixa

A consulta de várias linhas, usando ou não filtros, pode ser efetuada com um pedido:

Sendo a consulta de uma linha de fluxos específica efetuada de forma individual usando o identificador interno da linha de fluxos de caixa associada a uma linha de lançamento:

7.2. Criação de linhas de fluxos de caixa

7.3. Alteração de linhas de fluxos de caixa

7.4. Eliminação de linhas de fluxos de caixa

8. Pedidos com várias operações

Relembramos que é possível utilizar a extensão JSON Patch para realizar num só pedido várias operações sobre lançamentos, de acordo com a nossa implementação da API v0.

Operações sobre linhas de lançamentos

Exemplo: adicionar 2 linhas no mesmo lançamento:

[
    {
        "op": "add",
        "path": "/-",
        "value": {
            "type": "accounting_transaction_lines",
            "attributes": {
                "transaction_id": 1,
                "seqno": 0,
                "account_id": "11001",
                "debit_amount": 10
            }
        }
    },
    {
        "op": "add",
        "path": "/-",
        "value": {
            "type": "accounting_transaction_lines",
            "attributes": {
                "transaction_id": 1,
                "seqno": 1,
                "account_id": "12001",
                "credit_amount": 10
            }
        }
    }
]

Operações sobre recursos distintos

Para efetuar pedidos sobre recursos distintos, deve-se fazer o pedido PATCH sobre o <API_URL>/ e especificar o path em cada operação.

Exemplo: adicionar linhas e finalizar lançamento

[
    {
        "op": "replace",
        "path": "/accounting_transaction_lines/23/account_id",
        "value": "11001"
    },
    {
        "op": "replace",
        "path": "/accounting_transaction_lines/23/debit_amount",
        "value": "10"
    },
    {
        "op": "add",
        "path": "/accounting_transaction_lines",
        "value": {
            "type": "accounting_transaction_lines",
            "attributes": {
                "transaction_id": 4,
                "account_id": "12001",
                "credit_amount": 10
            }
        }
    },
    {
        "op": "replace",
        "path": "/accounting_transactions/4/status",
        "value": "finalized"
    }
]