Recibos de Venda

Criar Cabeçalho Recibo de Venda

Criar Cabeçalho Recibo de Venda

Criar Cabeçalho Recibo de Venda

POST{{base_url}}/api/v1/commercial_sales_receipts

Body

application/json

cash_account_idnumber

Example: 2

check_numbernullable any

company_idnumber

Example: 800000046

country_idnumber

Example: 1

created_atstring

Example: "2024-02-23 11:49:25.209661"

currency_conversion_ratenumber

Example: 1

currency_idnumber

Example: 1

customer_idnumber

Example: 57

datestring

Example: "2024-02-24"

deletedboolean

Example: true

gross_totalnumber

Example: 10.69

internal_observationsstring

Example: ""

linesarray of object

manual_registration_numbernullable any

manual_registration_seriesnullable any

manual_registration_typenullable any

net_totalnumber

Example: 9.25

observationsstring

Example: ""

payment_mechanismstring

Example: "MO"

saft_import_idnullable any

standaloneboolean

Example: true

third_party_idnullable any

third_party_typenullable any

updated_atstring

Example: "2024-02-28 14:04:52.678033"

user_idnumber

Example: 800000863

Response

200

Request

JavaScriptCurlPython

const response = await fetch('{{base_url}}/api/v1/commercial_sales_receipts', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "cash_account_id": 2,
      "check_number": null,
      "company_id": 800000046,
      "country_id": 1,
      "created_at": "2024-02-23 11:49:25.209661",
      "currency_conversion_rate": 1,
      "currency_id": 1,
      "customer_id": 57,
      "date": "2024-02-24",
      "deleted": true,
      "gross_total": 10.69,
      "internal_observations": "",
      "lines": [
        {
          "cashed_vat_amount": null,
          "gross_total": 11.38,
          "net_total": 9.25,
          "receivable_id": 12,
          "receivable_type": "Document",
          "received_value": 10.69,
          "retention_total": 0.69,
          "settlement_amount": 0,
          "settlement_percentage": 0
        }
      ],
      "manual_registration_number": null,
      "manual_registration_series": null,
      "manual_registration_type": null,
      "net_total": 9.25,
      "observations": "",
      "payment_mechanism": "MO",
      "saft_import_id": null,
      "standalone": true,
      "third_party_id": null,
      "third_party_type": null,
      "updated_at": "2024-02-28 14:04:52.678033",
      "user_id": 800000863
    }),
});
const data = await response.json();

{ 
    "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.
    "commercial_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",                              // [OBRIGATÓRIO]
            "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]=o tipo de documento> &filter[prefix]=<o prefixo da série> &filter[number]=<o numero da série>

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

GET /company_bank_accounts?filter[iban]= <IBAN da conta> 
ou 
GET /company_bank_accounts?filter[name]= <nome da conta> 

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

GET /cash_accounts?filter[name]= <nome da conta>

Criar Linhas de Recibo de Venda

Adicionar Linha a Recibo de Venda

Adicionar Linha a Recibo de Venda

POST{{base_url}}/api/commercial_sales_receipt_lines

Body

application/json

dataobject

Response

200

Request

JavaScriptCurlPython

const response = await fetch('{{base_url}}/api/commercial_sales_receipt_lines', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "data": {
        "attributes": {
          "cashed_vat_amount": null,
          "gross_total": 10.69,
          "net_total": 9.27,
          "receipt_id": 13,
          "receivable_id": 12,
          "receivable_type": "Document",
          "received_value": 10.69,
          "retention_total": 0.72,
          "settlement_amount": 0,
          "settlement_percentage": 0
        },
        "type": "commercial_sales_receipt_lines"
      }
    }),
});
const data = await response.json();

Anular Recibo de Venda

Anular Recibo de Venda

Anular Recibo de Venda

PATCH{{base_url}}/api/v1/commercial_sales_receipts/{salesReceiptId}/void

Path parameters

salesReceiptId*string

Response

200

Request

JavaScriptCurlPython

const response = await fetch('{{base_url}}/api/v1/commercial_sales_receipts/{salesReceiptId}/void', {
    method: 'PATCH',
    headers: {},
});
const data = await response.json();

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 /api/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

Atualizar Recibo de Venda

Atualizar Recibo de Venda

PATCH{{base_url}}/api/v1/commercial_sales_receipts/{salesReceiptId}

Path parameters

salesReceiptId*string

Body

application/json

cash_account_idnumber

Example: 2

check_numbernullable any

company_idnumber

Example: 800000046

country_idnumber

Example: 1

created_atstring

Example: "2024-02-23 11:49:25.209661"

currency_conversion_ratenumber

Example: 1

currency_idnumber

Example: 1

customer_idnumber

Example: 57

datestring

Example: "2024-02-24"

deletedboolean

Example: true

document_nostring

Example: "RC 2023/1"

document_series_idnumber

Example: 66

gross_totalnumber

Example: 10.69

idnumber

Example: 2

internal_observationsstring

Example: ""

linesarray of object

manual_registration_numbernullable any

manual_registration_seriesnullable any

manual_registration_typenullable any

net_totalnumber

Example: 9.25

observationsstring

Example: ""

payment_mechanismstring

Example: "MO"

saft_import_idnullable any

standaloneboolean

Example: true

third_party_idnullable any

third_party_typenullable any

updated_atstring

Example: "2024-02-27 11:19:15.761393"

user_idnumber

Example: 800000863

Response

200

Request

JavaScriptCurlPython

const response = await fetch('{{base_url}}/api/v1/commercial_sales_receipts/{salesReceiptId}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "cash_account_id": 2,
      "check_number": null,
      "company_id": 800000046,
      "country_id": 1,
      "created_at": "2024-02-23 11:49:25.209661",
      "currency_conversion_rate": 1,
      "currency_id": 1,
      "customer_id": 57,
      "date": "2024-02-24",
      "deleted": true,
      "document_no": "RC 2023/1",
      "document_series_id": 66,
      "gross_total": 10.69,
      "id": 2,
      "internal_observations": "",
      "lines": [
        {
          "cashed_vat_amount": null,
          "gross_total": 11.38,
          "id": 2,
          "net_total": 9.25,
          "receipt_id": 2,
          "receivable_id": 12,
          "receivable_type": "Document",
          "received_value": 10.69,
          "retention_total": 0.69,
          "settlement_amount": 0,
          "settlement_percentage": 0
        }
      ],
      "manual_registration_number": null,
      "manual_registration_series": null,
      "manual_registration_type": null,
      "net_total": 9.25,
      "observations": "",
      "payment_mechanism": "MO",
      "saft_import_id": null,
      "standalone": true,
      "third_party_id": null,
      "third_party_type": null,
      "updated_at": "2024-02-27 11:19:15.761393",
      "user_id": 800000863
    }),
});
const data = await response.json();

Exemplo:

Payload

Exemplo de Payload

{
    "date": "2024-02-24",
    "document_no": "RC 2023/1",
    "document_series_id": 66,
    "payment_mechanism": "MO",
    "gross_total": 10.69,
    "net_total": 9.25,
    "third_party_type": null,
    "third_party_id": null,
    "check_number": null,
    "currency_conversion_rate": 1,
    "internal_observations": "",
    "observations": "",
    "standalone": true,
    "saft_import_id": null,
    "deleted": true,
    "manual_registration_type": null,
    "manual_registration_series": null,
    "manual_registration_number": null,
    "created_at": "2024-02-23 11:49:25.209661",
    "updated_at": "2024-02-27 11:19:15.761393",
    "id": 2,
    "cash_account_id": 2,
    "company_id": 800000046,
    "country_id": 1,
    "currency_id": 1,
    "customer_id": 57,
    "user_id": 800000863,
    "lines": [
        {
            "receipt_id": 2,
            "receivable_type": "Document",
            "receivable_id": 12,
            "received_value": 10.69,
            "settlement_percentage": 0,
            "cashed_vat_amount": null,
            "gross_total": 11.38,
            "settlement_amount": 0.0,
            "net_total": 9.25,
            "retention_total": 0.69,
            "id": 2
        }
    ]
}

Response

Exemplo de Response

{
    "date": "2024-02-24",
    "document_no": "RC 2023/1",
    "document_series_id": 66,
    "payment_mechanism": "MO",
    "gross_total": 10.69,
    "net_total": 9.25,
    "third_party_type": null,
    "third_party_id": null,
    "check_number": null,
    "currency_conversion_rate": 1,
    "internal_observations": "",
    "observations": "",
    "standalone": true,
    "saft_import_id": null,
    "deleted": true,
    "manual_registration_type": null,
    "manual_registration_series": null,
    "manual_registration_number": null,
    "created_at": "2024-02-23 11:49:25.209661",
    "updated_at": "2024-02-27 14:03:24.085399",
    "id": 2,
    "cash_account_id": 2,
    "company_id": 800000046,
    "country_id": 1,
    "currency_id": 1,
    "customer_id": 57,
    "user_id": 800000863,
    "lines": [
        {
            "receipt_id": 2,
            "receivable_type": "Document",
            "receivable_id": 12,
            "received_value": 10.69,
            "settlement_percentage": 0,
            "cashed_vat_amount": null,
            "gross_total": 11.38,
            "settlement_amount": 0.0,
            "net_total": 9.25,
            "retention_total": 0.69,
            "id": 2
        }
    ]
}

Adição de Linha em Documento de Recibo de Venda

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.

Adicionar Linha a Recibo de Venda

Adicionar Linha a Recibo de Venda

POST{{base_url}}/api/commercial_sales_receipt_lines

Body

application/json

dataobject

Response

200

Request

JavaScriptCurlPython

const response = await fetch('{{base_url}}/api/commercial_sales_receipt_lines', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "data": {
        "attributes": {
          "cashed_vat_amount": null,
          "gross_total": 10.69,
          "net_total": 9.27,
          "receipt_id": 13,
          "receivable_id": 12,
          "receivable_type": "Document",
          "received_value": 10.69,
          "retention_total": 0.72,
          "settlement_amount": 0,
          "settlement_percentage": 0
        },
        "type": "commercial_sales_receipt_lines"
      }
    }),
});
const data = await response.json();

No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o <payload JSON> deverá ter o seguinte formato

Payload

{
  "data": {
    "type": "commercial_sales_receipt_lines",                     // [OBRIGATÓRIO]
    "attributes": {
      "receivable_type": "Document",                              // [OBRIGATÓRIO]
      "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"
      "receipt_id" : "<id do recibo>"                            // [OBRIGATÓRIO] Recibo a que esta linha pertence. Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima
    }
  }
}

Nota 1: O "id" interno do documento (fatura, nota) a receber deve ser obtido por um

GET /commercial_sales_documents?filter[document_no]=<o número do documento, ex. FT 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)

Remover Linha do Recibo de Venda

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.

DELETE /v1/commercial_sales_receipt_lines/{id}

Path Parameters

Name	Type	Description
id*	Integer	id of the receipt line to delete

200: OK OK

Obter Recibo de Venda por ID

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.

GET /v1/commercial_sales_receipts/{id}

Path Parameters

Name	Type	Description
id*	integer	id of the receipt to get the information of

200: OK OK