Pagamentos

Os pagamentos seguem a mesma estrutura anteriormente definida: São compostos por um cabeçalho, e linhas. Nesta nova versão, é possível criar ambas as componentes num só pedido, descrito de seguida.

Criação de cabeçalhos e linhas

Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL.

Este pedido permite criar um pagamento, e respetivas linhas, em simultâneo.

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>/v1/commercial_purchases_payments'

Neste, o payload JSON deverá vir no seguinte formato

{
    "date": "2017-06-01",                                 // Data do pagamento
    "payment_mechanism": "MO|CH|DC|CC|TR|DDA|MB|OU|...",  // Por omissão, MO. Modo de pagamento: MO (numerário), CH (cheque), DC (cartão de débito), CC (cartão de crédito), TR (transferência), DDA (débito directo), MB (referência MB), OU (outro)
    "document_series_id": 1,                              // Associação à série de pagamentos. Pode ser omitida, se for para usar a série por omissão. Este id pode ser obtido por um GET /commercial_document_series?filter[document_type]=PF&filter[prefix]=2020|ou outro qualquer...
    "bank_account_id": 2,                                 // SÓ NECESSÁRIO se o meio de pagamento for DC,CC,TR,CH, e se for para indicar uma conta bancária específica. Associação à conta bancária da empresa de onde o pagamento foi feito. // Este id pode ser obtido por um GET /company_bank_accounts?filter[iban]=<IBAN da conta>, ou GET /company_bank_accounts?filter[name]=<nome da conta>
    "cash_account_id": 2,                                 // SÓ NECESSÁRIO se o meio de pagamento for MO, e se for para indicar uma conta de caixa específica. Associação à conta de caixa da empresa de onde o pagamento foi feito. Este id pode ser obtido por um GET /cash_accounts?filter[name]=<nome da conta de caixa>
    "lines": [
        {
            "payable_type": "Purchases::Document",
            "payable_id": "<id do documento de compra a pagar>",
            "paid_value": 50, // Valor total a pagar (não é necessário pagar a totalidade do documento, ou pode pagar-se mais do que um documento)
            // Indicar o atributo seguinte apenas se existir desconto no pagamento (3%, neste exemplo)
            "settlement_percentage": 3,
            "commercial_purchases_document_id": 2 //id do documento de compra a pagar
        }
    ]
}

Finalização do documento

Não é necessário. Os pagamentos são sempre fechados.

Anulação de um documento (Caso seja preciso)

Edição do documento, após criação

O seguinte pedido pode ser realizado, após a criação do documento, e permite alterar informações sobre o documento. A estrutura do payload é a mesma do POST de criação. Neste, deverá enviar no id do pedido o id do documento a alterar. Os atributos enviados no body irão substituir os guardados no momento, e cada linha enviada dentro de lines irá substituir os dados guardados na linha com id especificado em payment_line_id

Adição de linhas

Caso pretenda adicionar novas linhas ao documento, após a sua criação, pode utilizar a seguinte rota, que utiliza o mesmo payload das lines do pedido POST de criação. Neste, o id a enviar no path é o do documento ao qual pretende adicionar a linha

Remoção de linhas

Do mesmo modo, caso pretenda remover linhas de um documento, pode utilizar a seguinte rota, onde apenas tem de indicar o id da linha a remover, no path.

Consultar documento

Por fim, se pretender obter informações sobre um dado documento, pode utilizar a seguinte rota, onde deverá especificar o id do documento a analisar no path.

PreviousDocumentos de compra NextDocumentos de venda

Last updated 1 year ago

Criação de cabeçalhos e linhas

Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL.

Este pedido permite criar um pagamento, e respetivas linhas, em simultâneo.

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>/v1/commercial_purchases_payments'

Neste, o payload JSON deverá vir no seguinte formato

{
    "date": "2017-06-01",                                 // Data do pagamento
    "payment_mechanism": "MO|CH|DC|CC|TR|DDA|MB|OU|...",  // Por omissão, MO. Modo de pagamento: MO (numerário), CH (cheque), DC (cartão de débito), CC (cartão de crédito), TR (transferência), DDA (débito directo), MB (referência MB), OU (outro)
    "document_series_id": 1,                              // Associação à série de pagamentos. Pode ser omitida, se for para usar a série por omissão. Este id pode ser obtido por um GET /commercial_document_series?filter[document_type]=PF&filter[prefix]=2020|ou outro qualquer...
    "bank_account_id": 2,                                 // SÓ NECESSÁRIO se o meio de pagamento for DC,CC,TR,CH, e se for para indicar uma conta bancária específica. Associação à conta bancária da empresa de onde o pagamento foi feito. // Este id pode ser obtido por um GET /company_bank_accounts?filter[iban]=<IBAN da conta>, ou GET /company_bank_accounts?filter[name]=<nome da conta>
    "cash_account_id": 2,                                 // SÓ NECESSÁRIO se o meio de pagamento for MO, e se for para indicar uma conta de caixa específica. Associação à conta de caixa da empresa de onde o pagamento foi feito. Este id pode ser obtido por um GET /cash_accounts?filter[name]=<nome da conta de caixa>
    "lines": [
        {
            "payable_type": "Purchases::Document",
            "payable_id": "<id do documento de compra a pagar>",
            "paid_value": 50, // Valor total a pagar (não é necessário pagar a totalidade do documento, ou pode pagar-se mais do que um documento)
            // Indicar o atributo seguinte apenas se existir desconto no pagamento (3%, neste exemplo)
            "settlement_percentage": 3,
            "commercial_purchases_document_id": 2 //id do documento de compra a pagar
        }
    ]
}

Finalização do documento

Não é necessário. Os pagamentos são sempre fechados.

Anulação de um documento (Caso seja preciso)

Edição do documento, após criação

Adição de linhas

Remoção de linhas

Do mesmo modo, caso pretenda remover linhas de um documento, pode utilizar a seguinte rota, onde apenas tem de indicar o id da linha a remover, no path.

Consultar documento

Por fim, se pretender obter informações sobre um dado documento, pode utilizar a seguinte rota, onde deverá especificar o id do documento a analisar no path.

delete

Path parameters

idintegerRequired

id of the payment line to delete

Responses

delete

DELETE /v1/commercial_purchases_payment_lines/{id} HTTP/1.1
Host: 
Accept: */*

200

No content

get

Path parameters

idintegerRequired

id of the payment to get the information of

Responses

application/json

objectOptional

get

GET /v1/commercial_purchases_payments/{id} HTTP/1.1
Host: 
Accept: */*

200

{
  "data": {
    "id": 1,
    "attributes": {
      "date": "text",
      "document_no": "text",
      "document_series_id": 1,
      "payment_mechanism": "text",
      "gross_total": 1,
      "net_total": 1,
      "third_party_type": "text",
      "third_party_id": 1,
      "check_number": true,
      "currency_conversion_rate": 1,
      "internal_observations": "text",
      "observations": "text",
      "standalone": true,
      "deleted": true
    },
    "relationships": {
      "bank_accounts": {
        "data": {
          "resource": "bank_accounts"
        }
      },
      "cash_accounts": {
        "data": {
          "resource": "cash_accounts"
        }
      },
      "company": {
        "data": {
          "resource": "current_company"
        }
      },
      "commercial_document_series": {
        "data": {
          "resource": "commercial_document_series"
        }
      },
      "country": {
        "data": {
          "resource": "countries"
        }
      },
      "supplier": {
        "data": {
          "table": "payments",
          "resource": "suppliers"
        }
      },
      "employee": {
        "data": {
          "table": "payments",
          "resource": "current_company_users"
        }
      },
      "currency": {
        "data": {
          "resource": "currencies"
        }
      },
      "user": {
        "data": {
          "resource": "current_company_users"
        }
      },
      "lines": {
        "data": {
          "type": "commercial_purchases_payment_lines",
          "id": 1
        }
      }
    }
  }
}

delete

Path parameters

idintegerRequired

id of the payment line to delete

Body

voided_reasonstringRequiredExample: Texto descritivo do motivo de anulação

Responses

delete

DELETE /v1/commercial_purchases_payments/{id} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "voided_reason": "Texto descritivo do motivo de anulação"
}

200

No content

patch

Path parameters

idintegerRequired

id of the payment to edit the information of

Body

datestringRequiredExample: 15-7-2022

payment_mechanismstringRequiredExample: MO|CH|DC|CC|TR|DDA|MB|OU|...

commercial_document_series_idintegerOptional

bank_account_idintegerOptional

cash_account_idintegerOptional

linesobject[]Optional

Responses

patch

PATCH /v1/commercial_purchases_payments/{id} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 255

{
  "date": "15-7-2022",
  "payment_mechanism": "MO|CH|DC|CC|TR|DDA|MB|OU|...",
  "commercial_document_series_id": 1,
  "bank_account_id": 1,
  "cash_account_id": 1,
  "lines": [
    {
      "payment_line_id": 1,
      "payable_id": 1,
      "payable_type": "text",
      "paid_value": 1,
      "settlement_percentage": 1
    }
  ]
}

200

No content

post

Path parameters

idintegerRequired

id of the payment to add the line to

Body

linesobject[]Optional

Responses

post

POST /v1/commercial_purchases_payment_lines/{id} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 108

{
  "lines": [
    {
      "payable_type": "Purchases::Document",
      "payable_id": 1,
      "paid_value": 1,
      "settlement_percentage": "5"
    }
  ]
}

200

No content

post

Body

all ofOptional

Responses

application/json

all ofOptional

post

POST /commercial_purchases_payments HTTP/1.1
Host: v1
Content-Type: application/json
Accept: */*
Content-Length: 285

{
  "date": "2023-01-01",
  "payment_mechanism": "MO|CH|DC|CC|TR|DDA|MB|OU|...",
  "document_series_id": 1,
  "bank_account_id": 1,
  "cash_account_id": 1,
  "return_pdf": true,
  "lines": [
    {
      "payable_type": "Purchases::Document|Purchases::DocumentLine",
      "payable_id": 1,
      "paid_value": 9.99,
      "settlement_percentage": 5
    }
  ]
}

200

{
  "id": 1,
  "date": "2023-01-01",
  "payment_mechanism": "MO|CH|DC|CC|TR|DDA|MB|OU|...",
  "document_series_id": 1,
  "bank_account_id": 1,
  "cash_account_id": 1,
  "url": "https://app.cloudware.pt/path_to_file",
  "lines": [
    {
      "id": 1,
      "payable_type": "Purchases::Document|Purchases::DocumentLine",
      "payable_id": 1,
      "paid_value": 9.99,
      "settlement_percentage": 5
    }
  ]
}