Recibos

Os recibos 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.

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_sales_receipts'

{ 
    "date": "2020-06-01",                          // [OPCIONAL] Data do recibo; por omissão, a data do pedido
    "payment_mechanism": "MO",                     // [OPCIONAL] Por omissão, "MO". Meios de pagamento aceites: "MO": Numerário, "CH": Cheque, "DC": Cartão de débito, "CC": Cartão de crédito, "TR": Transferência bancária, "DDA": Débito direto autorizado, "MB": Referências de pagamento Multibanco.                                             
    // [OPCIONAL] Recursos associados ao recibo. Caso nenhum seja indicado, os restantes devem atributos devem ser omitidos. Caso contrário, todos os atributos devem ser preenchidos.
    "document_series_id": 1,                       // [OBRIGATÓRIO] Série de recibos associada. Não precisa de ser indicada; por omissão o recibo é criado na série por omissão associada ao tipo de documento. Vd. NOTA 1
    "bank_account_id": 2,                          // [OBRIGATÓRIO] Conta bancária da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento é "DC", "CC", "TR" ou "DDA", e apenas se for necessário indicar uma conta bancária específica. Vd. NOTA 2
    "cash_account_id": 3,                          // [OBRIGATÓRIO] Conta de caixa da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento é "MO", e apenas se for necessário indicar uma conta de caixa específica. Vd. NOTA 3
    "lines": [
        {
            "receivable_type": "Document|DocumentLine",                 // [OBRIGATÓRIO] "Document" para receber faturas ou notas, "DocumentLine" para receber uma linha de um SI
            "receivable_id": "<id do documento a liquidar>",            // [OBRIGATÓRIO] Vd. NOTA 1
            "received_value": 50,                                       // [OBRIGATÓRIO] Valor total a receber (não é necessário receber a totalidade do documento, pode fazer-se um recebimento parcial)
            "settlement_percentage": "3"                                // [OPCIONAL] Desconto de pagamento, em percentagem; são suportados descontos compostos, como "3+5"
        }
    ]
}

NOTA 1: A série associada ao recibo tem já que existir, e o seu "id" interno deve ser obtido por um

GET /commercial_document_series?filter[document_type]=RC&filter[prefix]=2020|<o prefixo da série a usar>

NOTA 2: O "id" interno da conta bancária da empresa deve ser obtido por um

GET /company_bank_accounts?filter[iban]=
ou
GET /company_bank_accounts?filter[name]=

NOTA 3: O "id" interno da conta de caixa da empresa deve ser obtido por um

 GET /cash_accounts?filter[name]=ACCOUNT_NAME

Anulação de um recibo (Caso seja preciso):

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

curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' '<API_URL>/v1/commercial_sales_receipts/<id do recibo>'

No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth

NOTA 1: O "id" interno do recibo a anular deve ser obtido por um

GET /commercial_sales_receipts?filter[document_no]=<o número do recibo, ex. RC 2020/1>

É na linha do recibo que se indica qual o documento (FT, ou outro) que foi pago.

Se necessário, pode criar-se mais do que uma linha (e nesse caso o recibo é emitido de uma só vez para todos os documentos referenciados)

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

O seguinte pedido pode ser realizado, após a criação do recibo, e permite alterar informações sobre o mesmo. A estrutura do payload é a mesma do POST de criação. Neste, deverá enviar no id do pedido o id do recibo 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 receipt_line_id

Adição de linhas

Caso pretenda adicionar novas linhas ao recibo, 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 recibo ao qual pretende adicionar a linha

Remoção de linhas

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

Consultar recibo

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

PreviousDocumentos de venda NextDocumentos de compra

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.

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_sales_receipts'

{ 
    "date": "2020-06-01",                          // [OPCIONAL] Data do recibo; por omissão, a data do pedido
    "payment_mechanism": "MO",                     // [OPCIONAL] Por omissão, "MO". Meios de pagamento aceites: "MO": Numerário, "CH": Cheque, "DC": Cartão de débito, "CC": Cartão de crédito, "TR": Transferência bancária, "DDA": Débito direto autorizado, "MB": Referências de pagamento Multibanco.                                             
    // [OPCIONAL] Recursos associados ao recibo. Caso nenhum seja indicado, os restantes devem atributos devem ser omitidos. Caso contrário, todos os atributos devem ser preenchidos.
    "document_series_id": 1,                       // [OBRIGATÓRIO] Série de recibos associada. Não precisa de ser indicada; por omissão o recibo é criado na série por omissão associada ao tipo de documento. Vd. NOTA 1
    "bank_account_id": 2,                          // [OBRIGATÓRIO] Conta bancária da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento é "DC", "CC", "TR" ou "DDA", e apenas se for necessário indicar uma conta bancária específica. Vd. NOTA 2
    "cash_account_id": 3,                          // [OBRIGATÓRIO] Conta de caixa da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento é "MO", e apenas se for necessário indicar uma conta de caixa específica. Vd. NOTA 3
    "lines": [
        {
            "receivable_type": "Document|DocumentLine",                 // [OBRIGATÓRIO] "Document" para receber faturas ou notas, "DocumentLine" para receber uma linha de um SI
            "receivable_id": "<id do documento a liquidar>",            // [OBRIGATÓRIO] Vd. NOTA 1
            "received_value": 50,                                       // [OBRIGATÓRIO] Valor total a receber (não é necessário receber a totalidade do documento, pode fazer-se um recebimento parcial)
            "settlement_percentage": "3"                                // [OPCIONAL] Desconto de pagamento, em percentagem; são suportados descontos compostos, como "3+5"
        }
    ]
}

NOTA 1: A série associada ao recibo tem já que existir, e o seu "id" interno deve ser obtido por um

GET /commercial_document_series?filter[document_type]=RC&filter[prefix]=2020|<o prefixo da série a usar>

NOTA 2: O "id" interno da conta bancária da empresa deve ser obtido por um

GET /company_bank_accounts?filter[iban]=
ou
GET /company_bank_accounts?filter[name]=

NOTA 3: O "id" interno da conta de caixa da empresa deve ser obtido por um

 GET /cash_accounts?filter[name]=ACCOUNT_NAME

Anulação de um recibo (Caso seja preciso):

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

curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' '<API_URL>/v1/commercial_sales_receipts/<id do recibo>'

No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth

NOTA 1: O "id" interno do recibo a anular deve ser obtido por um

GET /commercial_sales_receipts?filter[document_no]=<o número do recibo, ex. RC 2020/1>

É na linha do recibo que se indica qual o documento (FT, ou outro) que foi pago.

Se necessário, pode criar-se mais do que uma linha (e nesse caso o recibo é emitido de uma só vez para todos os documentos referenciados)

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

Adição de linhas

Remoção de linhas

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

Consultar recibo

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

post

Body

all ofOptional

Responses

application/json

all ofOptional

post

POST /commercial_sales_receipts HTTP/1.1
Host: v1
Content-Type: application/json
Accept: */*
Content-Length: 259

{
  "date": "2023-01-01",
  "payment_mechanism": "MO|CH|DC|...",
  "document_series_id": 1,
  "bank_account_id": 1,
  "cash_account_id": 1,
  "return_pdf": true,
  "lines": [
    {
      "receivable_type": "Document|DocumentLine",
      "receivable_id": 1,
      "received_value": 9.99,
      "settlement_percentage": "5"
    }
  ]
}

200

{
  "id": 1,
  "date": "2023-01-01",
  "payment_mechanism": "MO|CH|DC|...",
  "document_series_id": 1,
  "bank_account_id": 1,
  "cash_account_id": 1,
  "url": "https://app.cloudware.pt/path_to_file",
  "lines": [
    {
      "id": 1,
      "receivable_type": "Document|DocumentLine",
      "receivable_id": 1,
      "received_value": 9.99,
      "settlement_percentage": 5
    }
  ]
}

delete

Path parameters

idintegerRequired

id of the receipt line to delete

Responses

delete

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

200

No content

delete

Path parameters

idintegerRequired

id of the receipt line to delete

Responses

delete

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

200

No content

get

Path parameters

idintegerRequired

id of the receipt to get the information of

Responses

application/json

objectOptional

get

GET /v1/commercial_sales_receipts/{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
        }
      }
    }
  }
}

patch

Path parameters

idintegerRequired

id of the receipt to edit the information of

Body

datestringOptionalExample: 15-07-2022

payment_mechanismstringOptionalExample: MO|CH|DC|...

commercial_document_series_idintegerRequired

bank_account_idintegerRequired

cash_account_idintegerRequired

linesobject[]Optional

Responses

patch

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

{
  "date": "15-07-2022",
  "payment_mechanism": "MO|CH|DC|...",
  "commercial_document_series_id": 1,
  "bank_account_id": 1,
  "cash_account_id": 1,
  "lines": [
    {
      "receipt_line_id": 1,
      "receivable_type": "Document",
      "receivable_id": 1,
      "received_value": 1,
      "settlement_percentage": "5"
    }
  ]
}

200

No content

post

Path parameters

idintegerRequired

id of the receipt to add the line to

Body

linesobject[]Optional

Responses

post

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

{
  "lines": [
    {
      "receivable_type": "Document",
      "receivable_id": 1,
      "received_value": 1,
      "settlement_percentage": "5"
    }
  ]
}

200

No content