Documentação API
  • Introdução
  • Setup
  • Autenticação
  • Autenticação simplificada
  • Caraterísticas dos pedidos
  • API-v1
    • Introdução à API v1
    • Documentos de venda
    • Recibos
    • Documentos de compra
    • Pagamentos
  • API-v0
    • Documentos de venda
    • Clientes e Moradas
    • Fornecedores
    • Produtos e serviços
    • Recibos
    • Documentos de compra
    • Pagamentos
    • Descarregar PDF documentos
    • Envio de documentos e recibos por email
    • Anexar ficheiros
    • Comunicação de documentos à AT
Powered by GitBook
On this page
  1. API-v1

Pagamentos

PreviousDocumentos de compraNextDocumentos de venda

Last updated 1 year ago

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.

post
Body
all ofOptional
Responses
200
OK
application/json
Responseall of
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

OK

{
  "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
    }
  ]
}
delete
Path parameters
idintegerRequired

id of the payment line to delete

Responses
200
OK
delete
DELETE /v1/commercial_purchases_payment_lines/{id} HTTP/1.1
Host: 
Accept: */*
200

OK

No content

get
Path parameters
idintegerRequired

id of the payment to get the information of

Responses
200
OK
application/json
get
GET /v1/commercial_purchases_payments/{id} HTTP/1.1
Host: 
Accept: */*
200

OK

{
  "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
        }
      }
    }
  }
}
  • Criação de cabeçalhos e linhas
  • POST/v1/commercial_purchases_payments
  • Finalização do documento
  • Anulação de um documento (Caso seja preciso)
  • DELETE/v1/commercial_purchases_payments/{id}
  • Edição do documento, após criação
  • PATCH/v1/commercial_purchases_payments/{id}
  • Adição de linhas
  • POST/v1/commercial_purchases_payment_lines/{id}
  • Remoção de linhas
  • DELETE/v1/commercial_purchases_payment_lines/{id}
  • Consultar documento
  • GET/v1/commercial_purchases_payments/{id}
delete
Path parameters
idintegerRequired

id of the payment line to delete

Body
voided_reasonstringRequiredExample: Texto descritivo do motivo de anulação
Responses
200
OK
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

OK

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
Responses
200
OK
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

OK

No content

post
Path parameters
idintegerRequired

id of the payment to add the line to

Body
Responses
200
OK
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

OK

No content